SftpClient: add DownloadFileAsync overload with downloadCallback

fixes #1765

Author: mus65

src/Renci.SshNet/ISftpClient.cs

@@ -578,6 +578,23 @@ public interface ISftpClient : IBaseClient
         /// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
         Task DownloadFileAsync(string path, Stream output, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Asynchronously downloads a remote file into a <see cref="Stream"/>.
+        /// </summary>
+        /// <param name="path">The path to the remote file.</param>
+        /// <param name="output">The <see cref="Stream"/> to write the file into.</param>
+        /// <param name="downloadCallback">The download callback.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to observe.</param>
+        /// <returns>A <see cref="Task"/> that represents the asynchronous download operation.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="output"/> or <paramref name="path"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException"><paramref name="path"/> is empty or contains only whitespace characters.</exception>
+        /// <exception cref="SshConnectionException">Client is not connected.</exception>
+        /// <exception cref="SftpPermissionDeniedException">Permission to perform the operation was denied by the remote host. <para>-or-</para> An SSH command was denied by the server.</exception>
+        /// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>
+        /// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
+        /// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
+        Task DownloadFileAsync(string path, Stream output, Action<ulong>? downloadCallback, CancellationToken cancellationToken = default);
+
         /// <summary>
         /// Ends an asynchronous file downloading into the stream.
         /// </summary>

src/Renci.SshNet/SftpClient.cs

@@ -912,6 +912,12 @@ public void DownloadFile(string path, Stream output, Action<ulong>? downloadCall
 
         /// <inheritdoc />
         public Task DownloadFileAsync(string path, Stream output, CancellationToken cancellationToken = default)
+        {
+            return DownloadFileAsync(path, output, downloadCallback: null, cancellationToken);
+        }
+
+        /// <inheritdoc />
+        public Task DownloadFileAsync(string path, Stream output, Action<ulong>? downloadCallback, CancellationToken cancellationToken = default)
         {
             ArgumentException.ThrowIfNullOrWhiteSpace(path);
             ArgumentNullException.ThrowIfNull(output);
@@ -921,7 +927,7 @@ public Task DownloadFileAsync(string path, Stream output, CancellationToken canc
                 path,
                 output,
                 asyncResult: null,
-                downloadCallback: null,
+                downloadCallback: downloadCallback,
                 isAsync: true,
                 cancellationToken);
         }

test/Renci.SshNet.IntegrationTests/OldIntegrationTests/SftpClientTest.Download.cs

@@ -124,5 +124,34 @@ public void Test_Sftp_EndDownloadFile_Invalid_Async_Handle()
                 Assert.ThrowsExactly<ArgumentException>(() => sftp.EndDownloadFile(async1));
             }
         }
+
+        [TestMethod]
+        [TestCategory("Sftp")]
+        public async Task Test_Sftp_DownloadFileAsync_DownloadCallback()
+        {
+            using (var sftp = new SftpClient(SshServerHostName, SshServerPort, User.UserName, User.Password))
+            {
+                await sftp.ConnectAsync(CancellationToken.None);
+                var filename = Path.GetTempFileName();
+                int testFileSizeMB = 1;
+                CreateTestFile(filename, testFileSizeMB);
+                await sftp.UploadFileAsync(File.OpenRead(filename), "test123");
+                using ManualResetEventSlim finalCallbackCalledEvent = new();
+
+                void Callback(ulong totalBytesRead)
+                {
+                    if ((int)totalBytesRead == testFileSizeMB * 1024 * 1024)
+                    {
+                        finalCallbackCalledEvent.Set();
+                    }
+                }
+
+                await sftp.DownloadFileAsync("test123", new MemoryStream(), Callback, CancellationToken.None);
+
+                // since the callback is queued to the thread pool, wait for the event.
+                bool callbackCalled = finalCallbackCalledEvent.Wait(5000);
+                Assert.IsTrue(callbackCalled);
+            }
+        }
     }
 }