Skip to content

Commit bde04cc

Browse files
Rob-HagueRob-Hague
committed
docs
1 parent 342a842 commit bde04cc

File tree

2 files changed

+44
-100
lines changed

2 files changed

+44
-100
lines changed

‎src/Renci.SshNet/ISftpClient.cs‎

Lines changed: 38 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -556,40 +556,34 @@ public interface ISftpClient : IBaseClient
556556
Task DeleteFileAsync(string path, CancellationToken cancellationToken);
557557

558558
/// <summary>
559-
/// Downloads remote file specified by the path into the stream.
559+
/// Downloads a remote file into a <see cref="Stream"/>.
560560
/// </summary>
561-
/// <param name="path">File to download.</param>
562-
/// <param name="output">Stream to write the file into.</param>
561+
/// <param name="path">The path to the remote file.</param>
562+
/// <param name="output">The <see cref="Stream"/> to write the file into.</param>
563563
/// <param name="downloadCallback">The download callback.</param>
564-
/// <exception cref="ArgumentNullException"><paramref name="output" /> is <see langword="null"/>.</exception>
565-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
564+
/// <exception cref="ArgumentNullException"><paramref name="output"/> or <paramref name="path"/> is <see langword="null"/>.</exception>
565+
/// <exception cref="ArgumentException"><paramref name="path"/> is empty or contains only whitespace characters.</exception>
566566
/// <exception cref="SshConnectionException">Client is not connected.</exception>
567-
/// <exception cref="SftpPermissionDeniedException">Permission to perform the operation was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
568-
/// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>///
569-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
567+
/// <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>
568+
/// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>
569+
/// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
570570
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
571-
/// <remarks>
572-
/// Method calls made by this method to <paramref name="output" />, may under certain conditions result in exceptions thrown by the stream.
573-
/// </remarks>
574571
void DownloadFile(string path, Stream output, Action<ulong>? downloadCallback = null);
575572

576573
/// <summary>
577-
/// Asynchronously downloads remote file specified by the path into the stream.
574+
/// Asynchronously downloads a remote file into a <see cref="Stream"/>.
578575
/// </summary>
579-
/// <param name="path">File to download.</param>
580-
/// <param name="output">Stream to write the file into.</param>
576+
/// <param name="path">The path to the remote file.</param>
577+
/// <param name="output">The <see cref="Stream"/> to write the file into.</param>
581578
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to observe.</param>
582579
/// <returns>A <see cref="Task"/> that represents the asynchronous download operation.</returns>
583-
/// <exception cref="ArgumentNullException"><paramref name="output" /> is <see langword="null"/>.</exception>
584-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
580+
/// <exception cref="ArgumentNullException"><paramref name="output"/> or <paramref name="path"/> is <see langword="null"/>.</exception>
581+
/// <exception cref="ArgumentException"><paramref name="path"/> is empty or contains only whitespace characters.</exception>
585582
/// <exception cref="SshConnectionException">Client is not connected.</exception>
586-
/// <exception cref="SftpPermissionDeniedException">Permission to perform the operation was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
587-
/// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>///
588-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
583+
/// <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>
584+
/// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>
585+
/// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
589586
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
590-
/// <remarks>
591-
/// Method calls made by this method to <paramref name="output" />, may under certain conditions result in exceptions thrown by the stream.
592-
/// </remarks>
593587
Task DownloadFileAsync(string path, Stream output, CancellationToken cancellationToken = default);
594588

595589
/// <summary>
@@ -1089,52 +1083,46 @@ public interface ISftpClient : IBaseClient
10891083
IEnumerable<FileInfo> SynchronizeDirectories(string sourcePath, string destinationPath, string searchPattern);
10901084

10911085
/// <summary>
1092-
/// Uploads stream into remote file.
1086+
/// Uploads a <see cref="Stream"/> to a remote file path.
10931087
/// </summary>
1094-
/// <param name="input">Data input stream.</param>
1095-
/// <param name="path">Remote file path.</param>
1088+
/// <param name="input">The <see cref="Stream"/> to write to the remote path.</param>
1089+
/// <param name="path">The remote file path to write to.</param>
10961090
/// <param name="uploadCallback">The upload callback.</param>
1097-
/// <exception cref="ArgumentNullException"><paramref name="input" /> is <see langword="null"/>.</exception>
1098-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
1091+
/// <exception cref="ArgumentNullException"><paramref name="input" /> or <paramref name="path" /> is <see langword="null"/>.</exception>
1092+
/// <exception cref="ArgumentException"><paramref name="path" /> is empty or contains only whitespace characters.</exception>
10991093
/// <exception cref="SshConnectionException">Client is not connected.</exception>
1100-
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
1101-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
1094+
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> An SSH command was denied by the server.</exception>
1095+
/// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
11021096
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
1103-
/// <remarks>
1104-
/// Method calls made by this method to <paramref name="input" />, may under certain conditions result in exceptions thrown by the stream.
1105-
/// </remarks>
11061097
void UploadFile(Stream input, string path, Action<ulong>? uploadCallback = null);
11071098

11081099
/// <summary>
1109-
/// Uploads stream into remote file.
1100+
/// Uploads a <see cref="Stream"/> to a remote file path.
11101101
/// </summary>
1111-
/// <param name="input">Data input stream.</param>
1112-
/// <param name="path">Remote file path.</param>
1113-
/// <param name="canOverride">if set to <see langword="true"/> then existing file will be overwritten.</param>
1102+
/// <param name="input">The <see cref="Stream"/> to write to the remote path.</param>
1103+
/// <param name="path">The remote file path to write to.</param>
1104+
/// <param name="canOverride">Whether the remote file can be overwritten if it already exists.</param>
11141105
/// <param name="uploadCallback">The upload callback.</param>
1115-
/// <exception cref="ArgumentNullException"><paramref name="input" /> is <see langword="null"/>.</exception>
1116-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
1106+
/// <exception cref="ArgumentNullException"><paramref name="input" /> or <paramref name="path" /> is <see langword="null"/>.</exception>
1107+
/// <exception cref="ArgumentException"><paramref name="path" /> is empty or contains only whitespace characters.</exception>
11171108
/// <exception cref="SshConnectionException">Client is not connected.</exception>
1118-
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
1119-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
1109+
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> An SSH command was denied by the server.</exception>
1110+
/// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
11201111
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
1121-
/// <remarks>
1122-
/// Method calls made by this method to <paramref name="input" />, may under certain conditions result in exceptions thrown by the stream.
1123-
/// </remarks>
11241112
void UploadFile(Stream input, string path, bool canOverride, Action<ulong>? uploadCallback = null);
11251113

11261114
/// <summary>
1127-
/// Asynchronously uploads stream into remote file.
1115+
/// Asynchronously uploads a <see cref="Stream"/> to a remote file path.
11281116
/// </summary>
1129-
/// <param name="input">Data input stream.</param>
1130-
/// <param name="path">Remote file path.</param>
1117+
/// <param name="input">The <see cref="Stream"/> to write to the remote path.</param>
1118+
/// <param name="path">The remote file path to write to.</param>
11311119
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to observe.</param>
11321120
/// <returns>A <see cref="Task"/> that represents the asynchronous upload operation.</returns>
1133-
/// <exception cref="ArgumentNullException"><paramref name="input" /> is <see langword="null"/>.</exception>
1134-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
1121+
/// <exception cref="ArgumentNullException"><paramref name="input"/> or <paramref name="path"/> is <see langword="null"/>.</exception>
1122+
/// <exception cref="ArgumentException"><paramref name="path" /> is empty or contains only whitespace characters.</exception>
11351123
/// <exception cref="SshConnectionException">Client is not connected.</exception>
1136-
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
1137-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
1124+
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> An SSH command was denied by the server.</exception>
1125+
/// <exception cref="SshException">An SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
11381126
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
11391127
Task UploadFileAsync(Stream input, string path, CancellationToken cancellationToken = default);
11401128

‎src/Renci.SshNet/SftpClient.cs‎

Lines changed: 6 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -893,22 +893,7 @@ public async Task<bool> ExistsAsync(string path, CancellationToken cancellationT
893893
}
894894
}
895895

896-
/// <summary>
897-
/// Downloads remote file specified by the path into the stream.
898-
/// </summary>
899-
/// <param name="path">File to download.</param>
900-
/// <param name="output">Stream to write the file into.</param>
901-
/// <param name="downloadCallback">The download callback.</param>
902-
/// <exception cref="ArgumentNullException"><paramref name="output" /> is <see langword="null"/>.</exception>
903-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
904-
/// <exception cref="SshConnectionException">Client is not connected.</exception>
905-
/// <exception cref="SftpPermissionDeniedException">Permission to perform the operation was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
906-
/// <exception cref="SftpPathNotFoundException"><paramref name="path"/> was not found on the remote host.</exception>///
907-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
908-
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
909-
/// <remarks>
910-
/// Method calls made by this method to <paramref name="output" />, may under certain conditions result in exceptions thrown by the stream.
911-
/// </remarks>
896+
/// <inheritdoc />
912897
public void DownloadFile(string path, Stream output, Action<ulong>? downloadCallback = null)
913898
{
914899
CheckDisposed();
@@ -1031,42 +1016,13 @@ public void EndDownloadFile(IAsyncResult asyncResult)
10311016
ar.EndInvoke();
10321017
}
10331018

1034-
/// <summary>
1035-
/// Uploads stream into remote file.
1036-
/// </summary>
1037-
/// <param name="input">Data input stream.</param>
1038-
/// <param name="path">Remote file path.</param>
1039-
/// <param name="uploadCallback">The upload callback.</param>
1040-
/// <exception cref="ArgumentNullException"><paramref name="input" /> is <see langword="null"/>.</exception>
1041-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
1042-
/// <exception cref="SshConnectionException">Client is not connected.</exception>
1043-
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
1044-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
1045-
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
1046-
/// <remarks>
1047-
/// Method calls made by this method to <paramref name="input" />, may under certain conditions result in exceptions thrown by the stream.
1048-
/// </remarks>
1019+
/// <inheritdoc/>
10491020
public void UploadFile(Stream input, string path, Action<ulong>? uploadCallback = null)
10501021
{
10511022
UploadFile(input, path, canOverride: true, uploadCallback);
10521023
}
10531024

1054-
/// <summary>
1055-
/// Uploads stream into remote file.
1056-
/// </summary>
1057-
/// <param name="input">Data input stream.</param>
1058-
/// <param name="path">Remote file path.</param>
1059-
/// <param name="canOverride">if set to <see langword="true"/> then existing file will be overwritten.</param>
1060-
/// <param name="uploadCallback">The upload callback.</param>
1061-
/// <exception cref="ArgumentNullException"><paramref name="input" /> is <see langword="null"/>.</exception>
1062-
/// <exception cref="ArgumentException"><paramref name="path" /> is <see langword="null"/> or contains only whitespace characters.</exception>
1063-
/// <exception cref="SshConnectionException">Client is not connected.</exception>
1064-
/// <exception cref="SftpPermissionDeniedException">Permission to upload the file was denied by the remote host. <para>-or-</para> A SSH command was denied by the server.</exception>
1065-
/// <exception cref="SshException">A SSH error where <see cref="Exception.Message" /> is the message from the remote host.</exception>
1066-
/// <exception cref="ObjectDisposedException">The method was called after the client was disposed.</exception>
1067-
/// <remarks>
1068-
/// Method calls made by this method to <paramref name="input" />, may under certain conditions result in exceptions thrown by the stream.
1069-
/// </remarks>
1025+
/// <inheritdoc/>
10701026
public void UploadFile(Stream input, string path, bool canOverride, Action<ulong>? uploadCallback = null)
10711027
{
10721028
CheckDisposed();
@@ -1090,7 +1046,7 @@ public Task UploadFileAsync(Stream input, string path, CancellationToken cancell
10901046
{
10911047
CheckDisposed();
10921048

1093-
return InternalUploadFileAsync(input, path, FileMode.Create, cancellationToken);
1049+
return InternalUploadFileAsync(input, path, cancellationToken);
10941050
}
10951051

10961052
/// <summary>
@@ -2552,7 +2508,7 @@ private void InternalUploadFile(Stream input, string path, Flags flags, SftpUplo
25522508
responseReceivedWaitHandle.Dispose();
25532509
}
25542510

2555-
private async Task InternalUploadFileAsync(Stream input, string path, FileMode fileMode, CancellationToken cancellationToken)
2511+
private async Task InternalUploadFileAsync(Stream input, string path, CancellationToken cancellationToken)
25562512
{
25572513
ThrowHelper.ThrowIfNull(input);
25582514
ThrowHelper.ThrowIfNullOrWhiteSpace(path);
@@ -2565,7 +2521,7 @@ private async Task InternalUploadFileAsync(Stream input, string path, FileMode f
25652521
cancellationToken.ThrowIfCancellationRequested();
25662522

25672523
var fullPath = await _sftpSession.GetCanonicalPathAsync(path, cancellationToken).ConfigureAwait(false);
2568-
var openStreamTask = SftpFileStream.OpenAsync(_sftpSession, fullPath, fileMode, FileAccess.Write, (int)_bufferSize, cancellationToken);
2524+
var openStreamTask = SftpFileStream.OpenAsync(_sftpSession, fullPath, FileMode.Create, FileAccess.Write, (int)_bufferSize, cancellationToken);
25692525

25702526
using (var output = await openStreamTask.ConfigureAwait(false))
25712527
{

0 commit comments

Comments
 (0)