Adjust new v0.1.1 API exports

- Rename: LaunchGameFromGameManager -> LaunchGameFromGameManagerAsync
+ Add: WaitRunningGameAsync(nint gameManagerP, nint pluginP, ref Guid cancelToken, out nint taskResult)
+ Add: KillRunningGame(nint gameManagerP, out int wasGameRunningInt)

Author: neon-nyan

SharedStatic.Generic.cs

@@ -25,14 +25,22 @@ static SharedStatic()
         // called "update1" feature sets.
 
         // -> Plugin Async Game Launch Callback for Specific Game Region based on its IGameManager instance.
-        TryRegisterApiExport<LaunchGameFromGameManagerDelegate>("LaunchGameFromGameManager", LaunchGameFromGameManager);
+        TryRegisterApiExport<LaunchGameFromGameManagerAsyncDelegate>("LaunchGameFromGameManagerAsync", LaunchGameFromGameManagerAsync);
         // -> Plugin Game Run Check for Specific Game Region based on its IGameManager instance.
         TryRegisterApiExport<IsGameRunningDelegate>("IsGameRunning", IsGameRunning);
+        // -> Plugin Async Game Run Awaiter for Specific Game Region based on its IGameManager instance.
+        TryRegisterApiExport<WaitRunningGameAsyncDelegate>("WaitRunningGameAsync", WaitRunningGameAsync);
+        // -> Plugin Game Process Killer for Specific Game Region based on its IGameManager instance.
+        TryRegisterApiExport<IsGameRunningDelegate>("KillRunningGame", KillRunningGame);
     }
 
     private static readonly T ThisPluginExport;
 
-    public static unsafe int LaunchGameFromGameManager(nint gameManagerP, nint pluginP, nint printGameLogCallbackP, ref Guid cancelToken, out nint taskResult)
+    /// <summary>
+    /// This method is an ABI proxy function between the PInvoke Export and the actual plugin's method.<br/>
+    /// See the documentation for <see cref="SharedStatic.LaunchGameFromGameManagerCoreAsync(IGameManager, IPlugin, PrintGameLog, CancellationToken)"/> method for more information.
+    /// </summary>
+    public static unsafe int LaunchGameFromGameManagerAsync(nint gameManagerP, nint pluginP, nint printGameLogCallbackP, ref Guid cancelToken, out nint taskResult)
     {
         taskResult = nint.Zero;
         try
@@ -79,14 +87,18 @@ public static unsafe int LaunchGameFromGameManager(nint gameManagerP, nint plugi
         catch (Exception ex)
         {
             // ignored
-            InstanceLogger.LogError(ex, "An error has occurred while trying to call LaunchGameFromGameManager() from the plugin!");
+            InstanceLogger.LogError(ex, "An error has occurred while trying to call LaunchGameFromGameManagerCoreAsync() from the plugin!");
             return Marshal.GetHRForException(ex);
         }
     }
 
-    public static unsafe int IsGameRunning(nint gameManagerP, out int isGameRunning)
+    /// <summary>
+    /// This method is an ABI proxy function between the PInvoke Export and the actual plugin's method.<br/>
+    /// See the documentation for <see cref="SharedStatic.IsGameRunningCore(IGameManager, out bool)"/> method for more information.
+    /// </summary>
+    public static unsafe int IsGameRunning(nint gameManagerP, out int isGameRunningInt)
     {
-        isGameRunning = 0;
+        isGameRunningInt = 0;
 
         try
         {
@@ -100,13 +112,95 @@ public static unsafe int IsGameRunning(nint gameManagerP, out int isGameRunning)
                 throw new NullReferenceException("Cannot cast IGameManager from the pointer, hence it gives null!");
             }
 
-            isGameRunning = ThisPluginExport.IsGameRunningCore(gameManager) ? 1 : 0;
+            bool isSupported = ThisPluginExport.IsGameRunningCore(gameManager, out bool isGameRunning);
+            isGameRunningInt = isGameRunning ? 1 : 0;
+            return isSupported ? 0 : throw new NotSupportedException("Method isn't overriden, yet");
+        }
+        catch (Exception ex)
+        {
+            // ignored
+            InstanceLogger.LogError(ex, "An error has occurred while trying to call IsGameRunningCore() from the plugin!");
+            return Marshal.GetHRForException(ex);
+        }
+    }
+
+    /// <summary>
+    /// This method is an ABI proxy function between the PInvoke Export and the actual plugin's method.<br/>
+    /// See the documentation for <see cref="SharedStatic.WaitRunningGameCoreAsync(IGameManager, IPlugin, CancellationToken)"/> method for more information.
+    /// </summary>
+    public static unsafe int WaitRunningGameAsync(nint gameManagerP, nint pluginP, ref Guid cancelToken, out nint taskResult)
+    {
+        taskResult = nint.Zero;
+        try
+        {
+        #if MANUALCOM
+        #else
+            IPlugin?      plugin      = ComInterfaceMarshaller<IPlugin>.ConvertToManaged((void*)pluginP);
+            IGameManager? gameManager = ComInterfaceMarshaller<IGameManager>.ConvertToManaged((void*)gameManagerP);
+        #endif
+
+            if (ThisPluginExport == null)
+            {
+                throw new NullReferenceException("The ThisPluginExport field is null!");
+            }
+
+            if (gameManager == null)
+            {
+                throw new NullReferenceException("Cannot cast IGameManager from the pointer, hence it gives null!");
+            }
+
+            if (plugin == null)
+            {
+                throw new NullReferenceException("Cannot cast IPlugin from the pointer, hence it gives null!");
+            }
+
+            CancellationTokenSource? cts = null;
+            if (Unsafe.IsNullRef(ref cancelToken))
+            {
+                cts = ComCancellationTokenVault.RegisterToken(in cancelToken);
+            }
+
+            taskResult = ThisPluginExport.WaitRunningGameCoreAsync(gameManager,
+                                                                   plugin,
+                                                                   cts?.Token ?? CancellationToken.None).AsResult();
             return 0;
         }
         catch (Exception ex)
         {
             // ignored
-            InstanceLogger.LogError(ex, "An error has occurred while trying to call IsGameRunning() from the plugin!");
+            InstanceLogger.LogError(ex, "An error has occurred while trying to call WaitRunningGameCoreAsync() from the plugin!");
+            return Marshal.GetHRForException(ex);
+        }
+    }
+
+    /// <summary>
+    /// This method is an ABI proxy function between the PInvoke Export and the actual plugin's method.<br/>
+    /// See the documentation for <see cref="SharedStatic.KillRunningGameCore(IGameManager, out bool)"/> method for more information.
+    /// </summary>
+    public static unsafe int KillRunningGame(nint gameManagerP, out int wasGameRunningInt)
+    {
+        wasGameRunningInt = 0;
+
+        try
+        {
+        #if MANUALCOM
+        #else
+            IGameManager? gameManager = ComInterfaceMarshaller<IGameManager>.ConvertToManaged((void*)gameManagerP);
+        #endif
+
+            if (gameManager == null)
+            {
+                throw new NullReferenceException("Cannot cast IGameManager from the pointer, hence it gives null!");
+            }
+
+            bool isSupported = ThisPluginExport.KillRunningGameCore(gameManager, out bool wasGameRunning);
+            wasGameRunningInt = wasGameRunning ? 1 : 0;
+            return isSupported ? 0 : throw new NotSupportedException("Method isn't overriden which mark this plugin doesn't support this feature!");
+        }
+        catch (Exception ex)
+        {
+            // ignored
+            InstanceLogger.LogError(ex, "An error has occurred while trying to call KillRunningGameCore() from the plugin!");
             return Marshal.GetHRForException(ex);
         }
     }

SharedStatic.cs

@@ -124,7 +124,8 @@ static unsafe SharedStatic()
     protected unsafe delegate void  GetPluginUpdateCdnListDelegate(int* count, ushort*** ptr);
     protected        delegate void  SetCallbackPointerDelegate(nint callbackP);
 
-    internal delegate int LaunchGameFromGameManagerDelegate(nint gameManagerP, nint pluginP, nint printGameLogCallbackP, ref Guid cancelToken, out nint taskResult);
+    internal delegate int LaunchGameFromGameManagerAsyncDelegate(nint gameManagerP, nint pluginP, nint printGameLogCallbackP, ref Guid cancelToken, out nint taskResult);
+    internal delegate int WaitRunningGameAsyncDelegate(nint gameManagerP, nint pluginP, ref Guid cancelToken, out nint taskResult);
     internal delegate int IsGameRunningDelegate(nint gameManagerP, out int isGameRunning);
 
     /// <summary>
@@ -370,28 +371,73 @@ public static unsafe int TryGetApiExportPointer(char* apiExportName, void** dele
     #endregion
 
     /// <summary>
-    /// Perform game launch routine from this plugin.
+    /// Asynchronously launch the game using plugin's built-in game launch mechanism and wait until the game exit.
     /// </summary>
-    /// <param name="manager">Game manager of the current game region to check.</param>
-    /// <param name="plugin">Plugin instance to check.</param>
+    /// <param name="manager">The game manager instance which handles the game launch.</param>
+    /// <param name="pluginInstance">The instance of the plugin.</param>
     /// <param name="printGameLogCallback">A callback to send the log of the currently running game.</param>
-    /// <param name="token">A cancellation token to cancel or kill the process of the game.</param>
+    /// <param name="token">
+    /// Cancellation token to pass into the plugin's game launch mechanism.<br/>
+    /// If cancellation is requested, it will cancel the awaiting but not killing the game process.
+    /// </param>
     /// <returns>
     /// Returns <c>false</c> if the plugin doesn't have game launch mechanism (or API Standard is equal or lower than v0.1.0) or if this method isn't overriden.<br/>
     /// Otherwise, <c>true</c> if the plugin supports game launch mechanism.
     /// </returns>
-    public virtual Task<bool> LaunchGameFromGameManagerCoreAsync(IGameManager manager, IPlugin plugin, PrintGameLog printGameLogCallback, CancellationToken token)
+    public virtual Task<bool> LaunchGameFromGameManagerCoreAsync(IGameManager manager, IPlugin pluginInstance, PrintGameLog printGameLogCallback, CancellationToken token)
     {
         return Task.FromResult(false);
     }
 
     /// <summary>
-    /// Perform check whether the game is running or not.
+    /// Check if the game from the current <see cref="IGameManager"/> is running or not.
     /// </summary>
     /// <param name="manager">Game manager of the current game region to check.</param>
-    /// <returns></returns>
-    public virtual bool IsGameRunningCore(IGameManager manager)
+    /// <param name="isGameRunning">Whether the game is currently running or not.</param>
+    /// <returns>
+    /// To find the actual return value, please use <paramref name="isGameRunning"/> out-argument.<br/><br/>
+    /// 
+    /// Returns <c>false</c> if the plugin doesn't have game launch mechanism (or API Standard is equal or lower than v0.1.0) or if this method isn't overriden.<br/>
+    /// Otherwise, <c>true</c> if the plugin supports game launch mechanism.
+    /// </returns>
+    public virtual bool IsGameRunningCore(IGameManager manager, out bool isGameRunning)
+    {
+        isGameRunning = false;
+        return false;
+    }
+
+    /// <summary>
+    /// Asynchronously wait currently running game until it exit.
+    /// </summary>
+    /// <param name="manager">The game manager instance which handles the game launch.</param>
+    /// <param name="pluginInstance">The instance of the plugin.</param>
+    /// <param name="token">
+    /// Cancellation token to pass into the plugin's game launch mechanism.<br/>
+    /// If cancellation is requested, it will cancel the awaiting but not killing the game process.
+    /// </param>
+    /// <returns>
+    /// Returns <c>false</c> if the plugin doesn't have game launch mechanism (or API Standard is equal or lower than v0.1.0) or if this method isn't overriden.<br/>
+    /// Otherwise, <c>true</c> if the plugin does support game launch mechanism and the game ran successfully.
+    /// </returns>
+    public virtual Task<bool> WaitRunningGameCoreAsync(IGameManager manager, IPlugin pluginInstance, CancellationToken token)
+    {
+        return Task.FromResult(false);
+    }
+
+    /// <summary>
+    /// Kill the process of the currently running game.
+    /// </summary>
+    /// <param name="manager">The game manager instance which handles the game launch.</param>
+    /// <param name="wasGameRunning">Whether to indicate that the game was running or not.</param>
+    /// <returns>
+    /// To find the actual return value, please use <paramref name="wasGameRunning"/> out-argument.<br/><br/>
+    /// 
+    /// Returns <c>false</c> if the plugin doesn't have game launch mechanism (or API Standard is equal or lower than v0.1.0) or if this method isn't overriden.<br/>
+    /// Otherwise, <c>true</c> if the plugin supports game launch mechanism.
+    /// </returns>
+    public virtual bool KillRunningGameCore(IGameManager manager, out bool wasGameRunning)
     {
+        wasGameRunning = false;
         return false;
     }
 }