Add Fluent DownloadHandler (#3576)

* Core - Add Fluent DownloadHandler implementation and IFrame.DownloadUrlAsync

Resolves #3550

Author: amaitland

CefSharp.Core/CefSharp.Core.csproj

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="..\packages\GitLink.3.1.0\build\GitLink.props" Condition="Exists('..\packages\GitLink.3.1.0\build\GitLink.props')" />
   <Import Project="..\packages\Microsoft.Net.Compilers.2.4.0\build\Microsoft.Net.Compilers.props" Condition="Exists('..\packages\Microsoft.Net.Compilers.2.4.0\build\Microsoft.Net.Compilers.props')" />
@@ -55,6 +55,10 @@
     <Compile Include="Cef.cs" />
     <Compile Include="CefSettingsBase.cs" />
     <Compile Include="DragData.cs" />
+    <Compile Include="Fluent\DownloadHandler.cs" />
+    <Compile Include="Fluent\DownloadHandlerBuilder.cs" />
+    <Compile Include="Fluent\UrlRequestClient.cs" />
+    <Compile Include="Fluent\UrlRequestClientBuilder.cs" />
     <Compile Include="ManagedCefBrowserAdapter.cs" />
     <Compile Include="NativeMethodWrapper.cs" />
     <Compile Include="PostData.cs" />
@@ -85,4 +89,4 @@
   <ItemGroup />
   <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
   <Import Project="..\packages\GitLink.3.1.0\build\GitLink.targets" Condition="Exists('..\packages\GitLink.3.1.0\build\GitLink.targets')" />
-</Project>
+</Project>

CefSharp.Core/Fluent/DownloadHandler.cs

@@ -0,0 +1,119 @@
+// Copyright © 2021 The CefSharp Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
+
+using System.IO;
+
+namespace CefSharp.Fluent
+{
+    /// <summary>
+    /// Called before a download begins.
+    /// </summary>
+    /// <param name="chromiumWebBrowser">the ChromiumWebBrowser control</param>
+    /// <param name="browser">The browser instance</param>
+    /// <param name="downloadItem">Represents the file being downloaded.</param>
+    /// <param name="callback">Callback interface used to asynchronously continue a download.</param>
+    public delegate void OnBeforeDownloadDelegate(IWebBrowser chromiumWebBrowser, IBrowser browser, DownloadItem downloadItem, IBeforeDownloadCallback callback);
+
+    /// <summary>
+    /// Called when a download's status or progress information has been updated. This may be called multiple times before and after <see cref="OnBeforeDownload"/>.
+    /// </summary>
+    /// <param name="chromiumWebBrowser">the ChromiumWebBrowser control</param>
+    /// <param name="browser">The browser instance</param>
+    /// <param name="downloadItem">Represents the file being downloaded.</param>
+    /// <param name="callback">The callback used to Cancel/Pause/Resume the process</param>
+    public delegate void OnDownloadUpdatedDelegate(IWebBrowser chromiumWebBrowser, IBrowser browser, DownloadItem downloadItem, IDownloadItemCallback callback);
+
+    /// <summary>
+    /// A <see cref="IDownloadHandler"/> implementation used by <see cref="DownloadHandlerBuilder"/>
+    /// to provide a fluent means of creating a <see cref="IDownloadHandler"/>.
+    /// </summary>
+    public class DownloadHandler : Handler.DownloadHandler
+    {
+        private OnBeforeDownloadDelegate onBeforeDownload;
+        private OnDownloadUpdatedDelegate onDownloadUpdated;
+
+        /// <summary>
+        /// Create a new DownloadHandler Builder
+        /// </summary>
+        /// <returns>Fluent DownloadHandler Builder</returns>
+        public static DownloadHandlerBuilder Create()
+        {
+            return new DownloadHandlerBuilder();
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="IDownloadHandler"/> instances
+        /// where all downloads are automatically downloaded to the specified folder.
+        /// No dialog is dispolayed to the user.
+        /// </summary>
+        /// <param name="folder">folder where files are download.</param>
+        /// <param name="downloadUpdated">optional delegate for download updates, track progress, completion etc.</param>
+        /// <returns><see cref="IDownloadHandler"/> instance.</returns>
+        public static IDownloadHandler UseFolder(string folder, OnDownloadUpdatedDelegate downloadUpdated = null)
+        {
+            return Create()
+                .OnBeforeDownload((chromiumWebBrowser, browser, item, callback) =>
+                {
+                    using (callback)
+                    {
+                        var path = Path.Combine(folder, item.SuggestedFileName);
+                        
+                        callback.Continue(path, showDialog: false);
+                    }
+                })
+                .OnDownloadUpdated(downloadUpdated)
+                .Build();
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="IDownloadHandler"/> instances
+        /// where a default "Save As" dialog is displayed to the user.
+        /// </summary>
+        /// <param name="downloadUpdated">optional delegate for download updates, track progress, completion etc.</param>
+        /// <returns><see cref="IDownloadHandler"/> instance.</returns>
+        public static IDownloadHandler AskUser(OnDownloadUpdatedDelegate downloadUpdated = null)
+        {
+            return Create()
+                .OnBeforeDownload((chromiumWebBrowser, browser, item, callback) =>
+                {
+                    using (callback)
+                    {
+                        callback.Continue("", showDialog: true);
+                    }
+                })
+                .OnDownloadUpdated(downloadUpdated)
+                .Build();
+        }
+
+        /// <summary>
+        /// Use <see cref="Create"/> to create a new instance of the fluent builder
+        /// </summary>
+        internal DownloadHandler()
+        {
+
+        }
+
+        internal void SetOnBeforeDownload(OnBeforeDownloadDelegate action)
+        {
+            onBeforeDownload = action;
+        }
+
+        internal void SetOnDownloadUpdated(OnDownloadUpdatedDelegate action)
+        {
+            onDownloadUpdated = action;
+        }
+
+        /// <inheritdoc/>
+        protected override void OnBeforeDownload(IWebBrowser chromiumWebBrowser, IBrowser browser, DownloadItem downloadItem, IBeforeDownloadCallback callback)
+        {
+            onBeforeDownload?.Invoke(chromiumWebBrowser, browser, downloadItem, callback);
+        }
+
+        /// <inheritdoc/>
+        protected override void OnDownloadUpdated(IWebBrowser chromiumWebBrowser, IBrowser browser, DownloadItem downloadItem, IDownloadItemCallback callback)
+        {
+            onDownloadUpdated?.Invoke(chromiumWebBrowser, browser, downloadItem, callback);
+        }
+    }
+}

CefSharp.Core/Fluent/DownloadHandlerBuilder.cs

@@ -0,0 +1,55 @@
+// Copyright © 2021 The CefSharp Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
+
+namespace CefSharp.Fluent
+{
+    /// <summary>
+    /// Fluent DownloadHandler Builder
+    /// </summary>
+    public class DownloadHandlerBuilder
+    {
+        private readonly DownloadHandler handler = new DownloadHandler();
+
+        /// <summary>
+        /// See <see cref="IDownloadHandler.OnBeforeDownload(IWebBrowser, IBrowser, DownloadItem, IBeforeDownloadCallback)"/> for details.
+        /// </summary>
+        /// <param name="action">Action to be executed when <see cref="IDownloadHandler.OnBeforeDownload(IWebBrowser, IBrowser, DownloadItem, IBeforeDownloadCallback)"/>
+        /// is called</param>
+        /// <returns>
+        /// Fluent Builder, call <see cref="Build"/> to create
+        /// a new <see cref="IDownloadHandler"/> instance
+        /// </returns>
+        public DownloadHandlerBuilder OnBeforeDownload(OnBeforeDownloadDelegate action)
+        {
+            handler.SetOnBeforeDownload(action);
+
+            return this;
+        }
+
+        /// <summary>
+        /// See <see cref="IDownloadHandler.OnDownloadUpdated(IWebBrowser, IBrowser, DownloadItem, IDownloadItemCallback)"/> for details.
+        /// </summary>
+        /// <param name="action">Action to be executed when <see cref="IDownloadHandler.OnDownloadUpdated(IWebBrowser, IBrowser, DownloadItem, IDownloadItemCallback)"/>
+        /// is called</param>
+        /// <returns>
+        /// Fluent Builder, call <see cref="DownloadHandlerBuilder.Build"/> to create
+        /// a new <see cref="IDownloadHandler"/> instance
+        /// </returns>
+        public DownloadHandlerBuilder OnDownloadUpdated(OnDownloadUpdatedDelegate action)
+        {
+            handler.SetOnDownloadUpdated(action);
+
+            return this;
+        }
+
+        /// <summary>
+        /// Create a <see cref="IDownloadHandler"/> instance
+        /// </summary>
+        /// <returns> a <see cref="IDownloadHandler"/> instance</returns>
+        public IDownloadHandler Build()
+        {
+            return handler;
+        }
+    }
+}

CefSharp.Core/Fluent/UrlRequestClient.cs

@@ -0,0 +1,142 @@
+// Copyright © 2021 The CefSharp Authors. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
+
+using System.IO;
+
+namespace CefSharp.Fluent
+{
+    /// <summary>
+    /// Called on the CEF IO thread when the browser needs credentials from the user.
+    /// This method will only be called for requests initiated from the browser process. 
+    /// </summary>
+    /// <param name="isProxy">indicates whether the host is a proxy server.</param>
+    /// <param name="host">the hostname.</param>
+    /// <param name="port">the port number.</param>
+    /// <param name="realm">realm</param>
+    /// <param name="scheme">scheme</param>
+    /// <param name="callback">is a callback for authentication information</param>
+    /// <returns>
+    /// Return true to continue the request and call <see cref="IAuthCallback.Continue(string, string)"/> when the authentication information is available.
+    /// If the request has an associated browser/frame then returning false will result in a call to <see cref="IRequestHandler.GetAuthCredentials"/> 
+    /// on the <see cref="IRequestHandler"/> associated with that browser, if any.
+    /// Otherwise, returning false will cancel the request immediately.
+    /// </returns>
+    public delegate bool GetAuthCredentialsDelegate(bool isProxy, string host, int port, string realm, string scheme, IAuthCallback callback);
+
+    /// <summary>
+    /// Called when some part of the response is read. This method will not be called if the <see cref="UrlRequestFlags.NoDownloadData"/> flag is set on the request. 
+    /// </summary>
+    /// <param name="request">request</param>
+    /// <param name="data">A stream containing the bytes received since the last call. Cannot be used outside the scope of this method. </param>
+    public delegate void OnDownloadDataDelegate(IUrlRequest request, Stream data);
+
+    /// <summary>
+    /// Notifies the client of download progress.
+    /// </summary>
+    /// <param name="request">request</param>
+    /// <param name="current">denotes the number of bytes received up to the call </param>
+    /// <param name="total">is the expected total size of the response (or -1 if not determined).</param>
+    public delegate void OnDownloadProgressDelegate(IUrlRequest request, long current, long total);
+
+    /// <summary>
+    /// Notifies the client that the request has completed.
+    /// Use the <see cref="IUrlRequest.RequestStatus"/> property to determine if the
+    /// request was successful or not.
+    /// </summary>
+    /// <param name="request">request</param>
+    public delegate void OnRequestCompleteDelegate(IUrlRequest request);
+
+    /// <summary>
+    /// Notifies the client of upload progress.
+    /// This method will only be called if the UR_FLAG_REPORT_UPLOAD_PROGRESS flag is set on the request.
+    /// </summary>
+    /// <param name="request">request</param>
+    /// <param name="current">denotes the number of bytes sent so far.</param>
+    /// <param name="total">is the total size of uploading data (or -1 if chunked upload is enabled).</param>
+    public delegate void OnUploadProgressDelegate(IUrlRequest request, long current, long total);
+
+    /// <summary>
+    /// Fluent UrlRequestClient
+    /// </summary>
+    public class UrlRequestClient : CefSharp.UrlRequestClient
+    {
+        private GetAuthCredentialsDelegate getAuthCredentials;
+        private OnDownloadDataDelegate onDownloadData;
+        private OnDownloadProgressDelegate onDownloadProgress;
+        private OnRequestCompleteDelegate onRequestComplete;
+        private OnUploadProgressDelegate onUploadProgress;
+
+        /// <summary>
+        /// Create a new UrlRequestClient Builder
+        /// </summary>
+        /// <returns>Fluent UrlRequestClient Builder</returns>
+        public static UrlRequestClientBuilder Create()
+        {
+            return new UrlRequestClientBuilder();
+        }
+
+        /// <summary>
+        /// Use <see cref="Create"/> to create a new instance of the fluent builder
+        /// </summary>
+        internal UrlRequestClient()
+        {
+
+        }
+
+        internal void SetGetAuthCredentials(GetAuthCredentialsDelegate func)
+        {
+            getAuthCredentials = func;
+        }
+
+        internal void SetOnDownloadData(OnDownloadDataDelegate action)
+        {
+            onDownloadData = action;
+        }
+
+        internal void SetOnDownloadProgress(OnDownloadProgressDelegate action)
+        {
+            onDownloadProgress = action;
+        }
+
+        internal void SetOnRequestComplete(OnRequestCompleteDelegate action)
+        {
+            onRequestComplete = action;
+        }
+
+        internal void SetOnUploadProgress(OnUploadProgressDelegate action)
+        {
+            onUploadProgress = action;
+        }
+
+        /// <inheritdoc/>
+        protected override bool GetAuthCredentials(bool isProxy, string host, int port, string realm, string scheme, IAuthCallback callback)
+        {
+            return getAuthCredentials?.Invoke(isProxy, host, port, realm, scheme, callback) ?? false;
+        }
+
+        /// <inheritdoc/>
+        protected override void OnDownloadData(IUrlRequest request, Stream data)
+        {
+            onDownloadData?.Invoke(request, data);
+        }
+
+        /// <inheritdoc/>
+        protected override void OnDownloadProgress(IUrlRequest request, long current, long total)
+        {
+            onDownloadProgress?.Invoke(request, current, total);
+        }
+
+        /// <inheritdoc/>
+        protected override void OnRequestComplete(IUrlRequest request)
+        {
+            onRequestComplete?.Invoke(request);
+        }
+
+        /// <inheritdoc/>
+        protected override void OnUploadProgress(IUrlRequest request, long current, long total)
+        {
+            onUploadProgress?.Invoke(request, current, total);
+        }
+    }
+}