Merge pull request #418 from konstantingross/master

Shell API adapted to Electron 9.0.0

Author: GregorBiswanger

ElectronNET.API/Entities/Error.cs

@@ -1,16 +1,22 @@
-using System.ComponentModel;
+using System;
+using System.ComponentModel;
 
 namespace ElectronNET.API.Entities
 {
     /// <summary>
-    /// 
+    /// Controls the behavior of OpenExternal.
     /// </summary>
     public class OpenExternalOptions
     {
         /// <summary>
-        /// true to bring the opened application to the foreground. The default is true.
+        /// <see langword="true"/> to bring the opened application to the foreground. The default is <see langword="true"/>.
         /// </summary>
         [DefaultValue(true)]
         public bool Activate { get; set; } = true;
+
+        /// <summary>
+        /// The working directory.
+        /// </summary>
+        public string WorkingDirectory { get; set; }
     }
 }

ElectronNET.API/Entities/OpenExternalOptions.cs

@@ -1,38 +1,38 @@
-namespace ElectronNET.API
+namespace ElectronNET.API.Entities
 {
     /// <summary>
-    /// 
+    /// Structure of a shortcut.
     /// </summary>
     public class ShortcutDetails
     {
         /// <summary>
-        /// The Application User Model ID. Default is empty.
+        /// The Application User Model ID. Default is <see cref="string.Empty"/>.
         /// </summary>
         public string AppUserModelId { get; set; }
 
         /// <summary>
-        /// The arguments to be applied to target when launching from this shortcut. Default is empty.
+        /// The arguments to be applied to <see cref="Target"/> when launching from this shortcut. Default is <see cref="string.Empty"/>.
         /// </summary>
         public string Args { get; set; }
 
         /// <summary>
-        /// The working directory. Default is empty.
+        /// The working directory. Default is <see cref="string.Empty"/>.
         /// </summary>
         public string Cwd { get; set; }
 
         /// <summary>
-        /// The description of the shortcut. Default is empty.
+        /// The description of the shortcut. Default is <see cref="string.Empty"/>.
         /// </summary>
         public string Description { get; set; }
 
         /// <summary>
-        /// The path to the icon, can be a DLL or EXE. icon and iconIndex have to be set
-        /// together.Default is empty, which uses the target's icon.
+        /// The path to the icon, can be a DLL or EXE. <see cref="Icon"/> and <see cref="IconIndex"/> have to be set
+        /// together. Default is <see cref="string.Empty"/>, which uses the target's icon.
         /// </summary>
         public string Icon { get; set; }
 
         /// <summary>
-        /// The resource ID of icon when icon is a DLL or EXE. Default is 0.
+        /// The resource ID of icon when <see cref="Icon"/> is a DLL or EXE. Default is 0.
         /// </summary>
         public int IconIndex { get; set; }
 

ElectronNET.API/Entities/ShortcutDetails.cs

@@ -1,23 +1,28 @@
-namespace ElectronNET.API
+using System.ComponentModel;
+
+namespace ElectronNET.API.Entities
 {
     /// <summary>
-    /// 
+    /// Defines the ShortcutLinkOperation enumeration.
     /// </summary>
     public enum ShortcutLinkOperation
     {
         /// <summary>
         /// Creates a new shortcut, overwriting if necessary.
         /// </summary>
-        create,
+        [Description("create")]
+        Create,
 
         /// <summary>
         /// Updates specified properties only on an existing shortcut.
         /// </summary>
-        update,
+        [Description("update")]
+        Update,
 
         /// <summary>
-        /// Overwrites an existing shortcut, fails if the shortcut doesn’t exist.
+        /// Overwrites an existing shortcut, fails if the shortcut doesn't exist.
         /// </summary>
-        replace
+        [Description("replace")]
+        Replace
     }
-}
+}

ElectronNET.API/Entities/ShortcutLinkOperation.cs

@@ -2,9 +2,8 @@
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 using Newtonsoft.Json.Serialization;
-using System;
-using System.Collections.Generic;
 using System.Threading.Tasks;
+using ElectronNET.API.Extensions;
 
 namespace ElectronNET.API
 {
@@ -40,17 +39,14 @@ internal static Shell Instance
         /// <summary>
         /// Show the given file in a file manager. If possible, select the file.
         /// </summary>
-        /// <param name="fullPath"></param>
-        /// <returns>Whether the item was successfully shown.</returns>
-        public Task<bool> ShowItemInFolderAsync(string fullPath)
+        /// <param name="fullPath">The full path to the directory / file.</param>
+        public Task ShowItemInFolderAsync(string fullPath)
         {
-            var taskCompletionSource = new TaskCompletionSource<bool>();
+            var taskCompletionSource = new TaskCompletionSource<object>();
 
-            BridgeConnector.Socket.On("shell-showItemInFolderCompleted", (success) =>
+            BridgeConnector.Socket.On("shell-showItemInFolderCompleted", () =>
             {
                 BridgeConnector.Socket.Off("shell-showItemInFolderCompleted");
-
-                taskCompletionSource.SetResult((bool)success);
             });
 
             BridgeConnector.Socket.Emit("shell-showItemInFolder", fullPath);
@@ -61,17 +57,17 @@ public Task<bool> ShowItemInFolderAsync(string fullPath)
         /// <summary>
         /// Open the given file in the desktop's default manner.
         /// </summary>
-        /// <param name="path">The path to the file.</param>
+        /// <param name="path">The path to the directory / file.</param>
         /// <returns>The error message corresponding to the failure if a failure occurred, otherwise <see cref="string.Empty"/>.</returns>
         public Task<string> OpenPathAsync(string path)
         {
             var taskCompletionSource = new TaskCompletionSource<string>();
 
-            BridgeConnector.Socket.On("shell-openPathCompleted", (success) =>
+            BridgeConnector.Socket.On("shell-openPathCompleted", (errorMessage) =>
             {
                 BridgeConnector.Socket.Off("shell-openPathCompleted");
 
-                taskCompletionSource.SetResult((string) success);
+                taskCompletionSource.SetResult((string) errorMessage);
             });
 
             BridgeConnector.Socket.Emit("shell-openPath", path);
@@ -83,106 +79,61 @@ public Task<string> OpenPathAsync(string path)
         /// Open the given external protocol URL in the desktop’s default manner. 
         /// (For example, mailto: URLs in the user’s default mail agent).
         /// </summary>
-        /// <param name="url"></param>
-        /// <returns>Whether an application was available to open the URL. 
-        /// If callback is specified, always returns true.</returns>
-        public Task<bool> OpenExternalAsync(string url)
+        /// <param name="url">Max 2081 characters on windows.</param>
+        /// <returns>The error message corresponding to the failure if a failure occurred, otherwise <see cref="string.Empty"/>.</returns>
+        public Task<string> OpenExternalAsync(string url)
         {
-            var taskCompletionSource = new TaskCompletionSource<bool>();
-
-            BridgeConnector.Socket.On("shell-openExternalCompleted", (success) =>
-            {
-                BridgeConnector.Socket.Off("shell-openExternalCompleted");
-
-                taskCompletionSource.SetResult((bool)success);
-            });
-
-            BridgeConnector.Socket.Emit("shell-openExternal", url);
-
-            return taskCompletionSource.Task;
+            return OpenExternalAsync(url, null);
         }
 
         /// <summary>
         /// Open the given external protocol URL in the desktop’s default manner. 
         /// (For example, mailto: URLs in the user’s default mail agent).
         /// </summary>
-        /// <param name="url"></param>
-        /// <param name="options">macOS only</param>
-        /// <returns>Whether an application was available to open the URL. 
-        /// If callback is specified, always returns true.</returns>
-        public Task<bool> OpenExternalAsync(string url, OpenExternalOptions options)
+        /// <param name="url">Max 2081 characters on windows.</param>
+        /// <param name="options">Controls the behavior of OpenExternal.</param>
+        /// <returns>The error message corresponding to the failure if a failure occurred, otherwise <see cref="string.Empty"/>.</returns>
+        public Task<string> OpenExternalAsync(string url, OpenExternalOptions options)
         {
-            var taskCompletionSource = new TaskCompletionSource<bool>();
+            var taskCompletionSource = new TaskCompletionSource<string>();
 
-            BridgeConnector.Socket.On("shell-openExternalCompleted", (success) =>
+            BridgeConnector.Socket.On("shell-openExternalCompleted", (error) =>
             {
                 BridgeConnector.Socket.Off("shell-openExternalCompleted");
 
-                taskCompletionSource.SetResult((bool)success);
+                taskCompletionSource.SetResult((string) error);
             });
 
-            BridgeConnector.Socket.Emit("shell-openExternal", url, JObject.FromObject(options, _jsonSerializer));
-
-            return taskCompletionSource.Task;
-        }
-
-        /// <summary>
-        /// Open the given external protocol URL in the desktop’s default manner. 
-        /// (For example, mailto: URLs in the user’s default mail agent).
-        /// </summary>
-        /// <param name="url"></param>
-        /// <param name="options">macOS only</param>
-        /// <param name="errorAction">Action to get the error message.</param>
-        /// <returns>Whether an application was available to open the URL. 
-        /// If callback is specified, always returns true.</returns>
-        public Task<bool> OpenExternalAsync(string url, OpenExternalOptions options, Action<Error> errorAction)
-        {
-            var taskCompletionSource = new TaskCompletionSource<bool>();
-
-            BridgeConnector.Socket.On("shell-openExternalCompleted", (success) =>
+            if (options == null)
             {
-                BridgeConnector.Socket.Off("shell-openExternalCompleted");
-
-                taskCompletionSource.SetResult((bool)success);
-            });
-
-            BridgeConnector.Socket.Off("shell-openExternalCallback");
-            BridgeConnector.Socket.On("shell-openExternalCallback", (args) => {
-                var urlKey = ((JArray)args).First.ToString();
-                var error = ((JArray)args).Last.ToObject<Error>();
-
-                if(_openExternalCallbacks.ContainsKey(urlKey))
-                {
-                    _openExternalCallbacks[urlKey](error);
-                }
-            });
-
-            _openExternalCallbacks.Add(url, errorAction);
-
-            BridgeConnector.Socket.Emit("shell-openExternal", url, JObject.FromObject(options, _jsonSerializer), true);
+                BridgeConnector.Socket.Emit("shell-openExternal", url);
+            }
+            else
+            {
+                BridgeConnector.Socket.Emit("shell-openExternal", url, JObject.FromObject(options, _jsonSerializer));
+            }
 
             return taskCompletionSource.Task;
         }
 
-        private Dictionary<string, Action<Error>> _openExternalCallbacks = new Dictionary<string, Action<Error>>();
-
         /// <summary>
-        /// Move the given file to trash and returns a boolean status for the operation.
+        /// Move the given file to trash and returns a <see cref="bool"/> status for the operation.
         /// </summary>
-        /// <param name="fullPath"></param>
+        /// <param name="fullPath">The full path to the directory / file.</param>
+        /// <param name="deleteOnFail">Whether or not to unilaterally remove the item if the Trash is disabled or unsupported on the volume.</param>
         /// <returns> Whether the item was successfully moved to the trash.</returns>
-        public Task<bool> MoveItemToTrashAsync(string fullPath)
+        public Task<bool> MoveItemToTrashAsync(string fullPath, bool deleteOnFail)
         {
             var taskCompletionSource = new TaskCompletionSource<bool>();
 
             BridgeConnector.Socket.On("shell-moveItemToTrashCompleted", (success) =>
             {
                 BridgeConnector.Socket.Off("shell-moveItemToTrashCompleted");
 
-                taskCompletionSource.SetResult((bool)success);
+                taskCompletionSource.SetResult((bool) success);
             });
 
-            BridgeConnector.Socket.Emit("shell-moveItemToTrash", fullPath);
+            BridgeConnector.Socket.Emit("shell-moveItemToTrash", fullPath, deleteOnFail);
 
             return taskCompletionSource.Task;
         }
@@ -198,9 +149,9 @@ public void Beep()
         /// <summary>
         /// Creates or updates a shortcut link at shortcutPath.
         /// </summary>
-        /// <param name="shortcutPath"></param>
-        /// <param name="operation"></param>
-        /// <param name="options"></param>
+        /// <param name="shortcutPath">The path to the shortcut.</param>
+        /// <param name="operation">Default is <see cref="ShortcutLinkOperation.Create"/></param>
+        /// <param name="options">Structure of a shortcut.</param>
         /// <returns>Whether the shortcut was created successfully.</returns>
         public Task<bool> WriteShortcutLinkAsync(string shortcutPath, ShortcutLinkOperation operation, ShortcutDetails options)
         {
@@ -210,21 +161,20 @@ public Task<bool> WriteShortcutLinkAsync(string shortcutPath, ShortcutLinkOperat
             {
                 BridgeConnector.Socket.Off("shell-writeShortcutLinkCompleted");
 
-                taskCompletionSource.SetResult((bool)success);
+                taskCompletionSource.SetResult((bool) success);
             });
 
-            BridgeConnector.Socket.Emit("shell-writeShortcutLink", shortcutPath, operation.ToString(), JObject.FromObject(options, _jsonSerializer));
+            BridgeConnector.Socket.Emit("shell-writeShortcutLink", shortcutPath, operation.GetDescription(), JObject.FromObject(options, _jsonSerializer));
 
             return taskCompletionSource.Task;
         }
 
         /// <summary>
         /// Resolves the shortcut link at shortcutPath.
-        /// 
         /// An exception will be thrown when any error happens.
         /// </summary>
-        /// <param name="shortcutPath"></param>
-        /// <returns></returns>
+        /// <param name="shortcutPath">The path tot the shortcut.</param>
+        /// <returns><see cref="ShortcutDetails"/> of the shortcut.</returns>
         public Task<ShortcutDetails> ReadShortcutLinkAsync(string shortcutPath)
         {
             var taskCompletionSource = new TaskCompletionSource<ShortcutDetails>();
@@ -233,19 +183,22 @@ public Task<ShortcutDetails> ReadShortcutLinkAsync(string shortcutPath)
             {
                 BridgeConnector.Socket.Off("shell-readShortcutLinkCompleted");
 
-                taskCompletionSource.SetResult((ShortcutDetails)shortcutDetails);
+                var shortcutObject = shortcutDetails as JObject;
+                var details = shortcutObject?.ToObject<ShortcutDetails>();
+
+                taskCompletionSource.SetResult(details);
             });
 
             BridgeConnector.Socket.Emit("shell-readShortcutLink", shortcutPath);
 
             return taskCompletionSource.Task;
         }
 
-        private JsonSerializer _jsonSerializer = new JsonSerializer()
+        private readonly JsonSerializer _jsonSerializer = new JsonSerializer()
         {
             ContractResolver = new CamelCasePropertyNamesContractResolver(),
             NullValueHandling = NullValueHandling.Ignore,
             DefaultValueHandling = DefaultValueHandling.Ignore
         };
     }
-}
+}