feat: IMaaAgentClient.IsAlive & SetTimeout()

- Implement Cancel() and CancelWith() to trigger SetTimeout(0) for operation cancellation and restore the original timeout after completion.

MaaXYZ/MaaFramework#671

Update Test_IMaaAgentClient.cs

Update Test_IMaaAgentClient.cs

Update Test_IMaaAgentClient.cs

Author: moomiji

src/MaaFramework.Binding.Native/MaaAgentClient.cs

@@ -13,13 +13,14 @@ namespace MaaFramework.Binding;
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
 public class MaaAgentClient : MaaDisposableHandle<MaaAgentClientHandle>, IMaaAgentClient<MaaAgentClientHandle>
 {
+    private long _timeout = -1;
     private Process? _agentServerProcess;
 
     [ExcludeFromCodeCoverage(Justification = "Debugger display.")]
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private string DebuggerDisplay => IsInvalid
         ? $"Invalid {GetType().Name}"
-        : $"{GetType().Name} {{ {nameof(Id)} = {Id ?? "<null>"}, {nameof(IsConnected)} = {IsConnected} }}";
+        : $"{GetType().Name} {{ {nameof(Id)} = {Id ?? "<null>"}, {nameof(IsConnected)} = {IsConnected}, {nameof(IsAlive)} = {IsAlive}, Timeout = {_timeout} }}";
 
     /// <summary>
     ///     Creates a <see cref="MaaAgentClient"/> instance.
@@ -162,11 +163,11 @@ public async Task<bool> LinkStartUnlessProcessExit(Process process, Cancellation
 
         try
         {
+            _ = Cancel(waitTask: linkStartTask);
             cts.Token.ThrowIfCancellationRequested();
-            if (completedTask == serverExitTask)
-                return false;
 
-            return linkStartTask.Result;
+            return completedTask != serverExitTask
+                && linkStartTask.Result;
         }
         finally
         {
@@ -178,36 +179,106 @@ public async Task<bool> LinkStartUnlessProcessExit(Process process, Cancellation
         }
     }
 
-    private int _stopping;
-
     /// <inheritdoc/>
     /// <remarks>
     ///     Wrapper of <see cref="MaaAgentClientDisconnect"/>.
     /// </remarks>
     public bool LinkStop()
+        => MaaAgentClientDisconnect(Handle);
+
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaAgentClientConnect"/>.
+    /// </remarks>
+    public bool IsConnected => MaaAgentClientConnected(Handle);
+
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaAgentClientAlive"/>.
+    /// </remarks>
+    public bool IsAlive => MaaAgentClientAlive(Handle);
+
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaAgentClientSetTimeout"/>.
+    /// </remarks>
+    public bool SetTimeout(long millisecondsDelay)
+    {
+        _timeout = millisecondsDelay;
+        return MaaAgentClientSetTimeout(Handle, _timeout);
+    }
+
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaAgentClientSetTimeout"/>.
+    /// </remarks>
+    public bool SetTimeout(TimeSpan delay)
+        => SetTimeout((long)delay.TotalMilliseconds);
+
+    private static bool NeedToCancel(Func<bool>? waitFunc, Task<bool>? waitTask, MaaJob? waitJob)
+    {
+        if (waitFunc is not null)
+            return true;
+        if (waitTask is not null && !waitTask.IsCompleted)
+            return true;
+        if (waitJob is not null && !waitJob.Status.IsDone())
+            return true;
+
+        return false;
+    }
+
+    private static bool WaitForCancellation(Func<bool>? waitFunc = null, Task<bool>? waitTask = null, MaaJob? waitJob = null)
+    {
+        var ret = true;
+        if (waitFunc is not null)
+            ret &= waitFunc.Invoke();
+        if (waitTask is not null)
+            ret &= waitTask.GetAwaiter().GetResult();
+        if (waitJob is not null)
+            ret &= waitJob.Wait().IsSucceeded();
+        return ret;
+    }
+
+    /// <inheritdoc/>
+    /// <remarks>
+    ///     Wrapper of <see cref="MaaAgentClientSetTimeout"/>.
+    /// </remarks>
+    public bool CancelWith(CancellationToken cancellationToken, Func<bool>? waitFunc = null, Task<bool>? waitTask = null, MaaJob? waitJob = null)
     {
-        if (IsConnected && Interlocked.CompareExchange(ref _stopping, 1, 0) == 0)
+        if (!NeedToCancel(waitFunc, waitTask, waitJob))
+            return true;
+
+        var ctr = cancellationToken.Register(() => SetTimeout(0));
+        try
         {
-            return MaaAgentClientDisconnect(Handle);
-#pragma warning disable CS0162 // 检测到无法访问的代码
-            try
-            {
-                return MaaAgentClientDisconnect(Handle);
-            }
-            finally
-            {
-                _stopping = 0;
-            }
-#pragma warning restore CS0162 // 检测到无法访问的代码
+            return WaitForCancellation(waitFunc, waitTask, waitJob);
+        }
+        finally
+        {
+            ctr.Dispose();
+            _ = SetTimeout(_timeout).ThrowIfFalse();
         }
-        return true;
     }
 
     /// <inheritdoc/>
     /// <remarks>
-    ///     Wrapper of <see cref="MaaAgentClientConnect"/>.
+    ///     Wrapper of <see cref="MaaAgentClientSetTimeout"/>.
     /// </remarks>
-    public bool IsConnected => MaaAgentClientConnected(Handle);
+    public bool Cancel(Func<bool>? waitFunc = null, Task<bool>? waitTask = null, MaaJob? waitJob = null)
+    {
+        if (!NeedToCancel(waitFunc, waitTask, waitJob))
+            return true;
+
+        _ = SetTimeout(0).ThrowIfFalse();
+        try
+        {
+            return WaitForCancellation(waitFunc, waitTask, waitJob);
+        }
+        finally
+        {
+            _ = SetTimeout(_timeout).ThrowIfFalse();
+        }
+    }
 
     /// <inheritdoc/>
     public Process AgentServerProcess => _agentServerProcess

src/MaaFramework.Binding.UnitTests/Test_IMaaAgentClient.cs

@@ -58,12 +58,21 @@ public void Interface_Id_Resource(MaaTypes type, IMaaAgentClient maaAgentClient)
 
     [TestMethod]
     [MaaData(MaaTypes.All, nameof(Data))]
-    public void Interface_LinkStart_LinkStop_AgentServerProcess(MaaTypes type, IMaaAgentClient maaAgentClient)
+    public void Interface_LinkStart_LinkStop_AgentServerProcess_IsConnected_IsAlive_SetTimeout(MaaTypes type, IMaaAgentClient maaAgentClient)
     {
         _ = Assert.ThrowsExactly<InvalidOperationException>(() =>
             maaAgentClient.AgentServerProcess);
+        Assert.IsFalse(
+            maaAgentClient.IsConnected);
+        Assert.IsFalse(
+            maaAgentClient.IsAlive);
+
         Assert.IsTrue(
-            maaAgentClient.IsConnected);    // IsConnected 的值有问题，先改了一下LinkStop()实现，记得改回来
+            maaAgentClient.SetTimeout(TimeSpan.MaxValue));
+        Assert.IsTrue(
+            maaAgentClient.SetTimeout(TimeSpan.MinValue));
+        Assert.IsTrue(
+            maaAgentClient.SetTimeout(TimeSpan.FromMinutes(2)));
 
         var ret = maaAgentClient.LinkStart(StartupAgentServer);
         Assert.IsTrue(
@@ -74,6 +83,8 @@ public void Interface_LinkStart_LinkStop_AgentServerProcess(MaaTypes type, IMaaA
             maaAgentClient.AgentServerProcess.HasExited);
         Assert.IsTrue(
             maaAgentClient.IsConnected);
+        Assert.IsTrue(
+            maaAgentClient.IsAlive);
 
         Assert.IsTrue(
             maaAgentClient.LinkStop());
@@ -82,25 +93,63 @@ public void Interface_LinkStart_LinkStop_AgentServerProcess(MaaTypes type, IMaaA
         Task.Delay(100).Wait(); // wait for process exit
         Assert.IsTrue(
             maaAgentClient.AgentServerProcess.HasExited);
-        Assert.IsTrue(
+        Assert.IsFalse(
             maaAgentClient.IsConnected);
+        Assert.IsFalse(
+            maaAgentClient.IsAlive);
+    }
+
+    [TestMethod]
+    [MaaData(MaaTypes.All, nameof(Data))]
+    public void Interface_Cancel_CancelWith(MaaTypes type, IMaaAgentClient maaAgentClient)
+    {
+        using var res = new MaaResource();
+        using var agent = MaaAgentClient.Create(res);
+        var ct = new CancellationToken(true);
+        var job = new MaaJob(0, res);
+        Assert.AreEqual(MaaJobStatus.Invalid, job.Wait());
+
+        Assert.IsFalse(
+            agent.Cancel(waitFunc: agent.LinkStart));
+        Assert.IsFalse(
+            agent.Cancel(waitTask: Task.Run(agent.LinkStart)));
+        Assert.IsFalse(
+            agent.Cancel(waitJob: job));
+
+        Assert.IsFalse(
+            agent.CancelWith(ct, waitFunc: agent.LinkStart));
+        Assert.IsFalse(
+            agent.CancelWith(ct, waitTask: Task.Run(agent.LinkStart)));
+        Assert.IsFalse(
+            agent.CancelWith(ct, waitJob: job));
     }
 
     [TestMethod]
     [MaaData(MaaTypes.All, nameof(Data))]
-    public void RunTask(MaaTypes type, IMaaAgentClient maaAgentClient)
+    public void Case_RunTask(MaaTypes type, IMaaAgentClient maaAgentClient)
     {
-        using var maa = new MaaTasker
+        using var maa = type switch
         {
-            Controller = new MaaAdbController(Common.AdbPath, Common.Address, AdbScreencapMethods.Encode, AdbInputMethods.AdbShell, Common.AdbConfig, Common.AgentPath),
-            Resource = new MaaResource(),
-            DisposeOptions = DisposeOptions.All,
+#if MAA_NATIVE
+            MaaTypes.Native => new MaaTasker
+            {
+                Controller = new MaaAdbController(Common.AdbPath, Common.Address, AdbScreencapMethods.Encode, AdbInputMethods.AdbShell, Common.AdbConfig, Common.AgentPath),
+                Resource = new MaaResource(),
+                DisposeOptions = DisposeOptions.All,
+            },
+#endif
+            _ => throw new NotImplementedException(),
         };
-        Assert.IsTrue(
-            maa.IsInitialized);
+        Assert.IsTrue(maa.IsInitialized);
 
-        using var agent = MaaAgentClient.Create("6CDC213A-085C-40C8-8665-635820D10425", maa.Resource);
-        using (var cts = new CancellationTokenSource(10000))
+        using var agent = type switch
+        {
+#if MAA_NATIVE
+            MaaTypes.Native => MaaAgentClient.Create("6CDC213A-085C-40C8-8665-635820D10425", maa.Resource),
+#endif
+            _ => throw new NotImplementedException(),
+        };
+        using (var cts = new CancellationTokenSource(10 * 1000))
         {
             Assert.IsTrue(
             //  agent.LinkStart());

src/MaaFramework.Binding/IMaaAgentClient.cs

@@ -79,6 +79,39 @@ public interface IMaaAgentClient : IMaaDisposable
     /// <returns><see langword="true"/> if the <see cref="IMaaAgentClient"/> is connected; otherwise, <see langword="false"/>.</returns>
     bool IsConnected { get; }
 
+    /// <summary>
+    ///     Gets whether the connection is alive.
+    /// </summary>
+    /// <returns><see langword="true"/> if the connection is alive; otherwise, <see langword="false"/>.</returns>
+    bool IsAlive { get; }
+
+    /// <summary>
+    ///    Sets the timeout for the agent server to respond.
+    /// </summary>
+    /// <param name="millisecondsDelay">The time span to wait before the agent server response.</param>
+    /// <returns><see langword="true"/> if the timeout was set successfully; otherwise, <see langword="false"/>.</returns>
+    bool SetTimeout(long millisecondsDelay);
+
+    /// <param name="delay">The time span to wait before the agent server response.</param>
+    /// <inheritdoc cref="SetTimeout(long)"/>
+    bool SetTimeout(TimeSpan delay);
+
+    /// <summary>
+    ///   Cancels the agent operation with a specified token.
+    /// </summary>
+    /// <param name="cancellationToken">The token used to cancel the waiting operation.</param>
+    /// <param name="waitFunc">The func that needs to be canceled.</param>
+    /// <param name="waitTask">The task that needs to be canceled.</param>
+    /// <param name="waitJob">The job that needs to be canceled.</param>
+    /// <returns>The return value of <paramref name="waitFunc"/> AND <paramref name="waitTask"/>.Result AND <paramref name="waitJob"/>.IsSucceeded().</returns>
+    bool CancelWith(CancellationToken cancellationToken, Func<bool>? waitFunc = null, Task<bool>? waitTask = null, MaaJob? waitJob = null);
+
+    /// <summary>
+    ///   Cancels the agent operation.
+    /// </summary>
+    /// <inheritdoc cref="CancelWith"/>
+    bool Cancel(Func<bool>? waitFunc = null, Task<bool>? waitTask = null, MaaJob? waitJob = null);
+
     /// <summary>
     ///     Represents a method that starts the agent server process.
     /// </summary>