Skip to content

Added documentation for System.Net.Security APIs targeted for 3.0 #2788

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 24, 2019
Merged

Added documentation for System.Net.Security APIs targeted for 3.0 #2788

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e7da70c
Added documentation for System.Net.Sockets APIs targeted for 3.0
jozkee Jul 21, 2019
941cba7
Apply suggestions from code review
jozkee Jul 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions xml/System.Net.Security/AuthenticatedStream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,9 +182,20 @@ The following example demonstrates displaying the properties of an authenticated
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.AuthenticatedStream" />.</summary>
<returns>A task that represents the asynchronous dispose operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method enables you to perform a resource-intensive dispose operation without blocking the main thread.

This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`, otherwise, the inner stream is just flushed.

Calling `DisposeAsync` allows the resources used by the <xref:System.Net.Security.AuthenticatedStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="InnerStream">
Expand Down
18 changes: 15 additions & 3 deletions xml/System.Net.Security/NegotiateStream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2629,9 +2629,21 @@ The following method is called when the operation completes.
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.NegotiateStream" />.</summary>
<returns>A task that represents the asynchronous dispose operation.</returns>
<remarks>
<format type="text/markdown">
<![CDATA[

## Remarks
This method enables you to perform a resource-intensive dispose operation without blocking the main thread.

This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`, otherwise, the inner stream is just flushed.

Calling `DisposeAsync` allows the resources used by the <xref:System.Net.Security.NegotiateStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="EndAuthenticateAsClient">
Expand Down
161 changes: 131 additions & 30 deletions xml/System.Net.Security/SslStream.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2451,9 +2451,21 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.SsslStream" />.</summary>
<returns>A task that represents the asynchronous dispose operation.</returns>
<remarks>
<format type="text/markdown">
<![CDATA[

## Remarks
This method enables you to perform a resource-intensive dispose operation without blocking the main thread.

This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`, otherwise, the inner stream is just flushed.

Calling `DisposeAsync` allows the resources used by the <xref:System.Net.Security.SslStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="EndAuthenticateAsClient">
Expand Down Expand Up @@ -3597,11 +3609,26 @@ Authentication has not occurred.</exception>
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="buffer">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="buffer">The buffer that receives the bytes read from this stream.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Asynchronously reads data from this stream and stores it in the specified memory range.</summary>
<returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.ValueTask`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" />. When there is no more data to be read, returns 0.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This method reads as much data as is available into the `buffer`.

You cannot perform multiple simultaneous read operations.

You cannot call this method until you have successfully authenticated.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if present to determine the cause of the failure.</exception>
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="ReadAsync">
Expand Down Expand Up @@ -3631,13 +3658,38 @@ Authentication has not occurred.</exception>
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="buffer">To be added.</param>
<param name="offset">To be added.</param>
<param name="count">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="buffer">The buffer that receives the bytes read from this stream.</param>
<param name="offset">The zero-based location in <paramref name="buffer" /> at which to begin storing the data read from this stream.</param>
<param name="count">The maximum number of bytes to read from this stream.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Asynchronously reads data from this stream and stores it in the specified range of a byte array.</summary>
<returns>A task that represents the asynchronous read operation. The value of its <see cref="P:System.Threading.Tasks.Task`1.Result" /> property contains the total number of bytes read into <paramref name="buffer" />. When there is no more data to be read, returns 0.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The method reads a maximum of `count` bytes from the stream and stores them in `buffer` beginning at `offset`.

You cannot perform multiple simultaneous read operations.

You cannot call this method until you have successfully authenticated.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="buffer" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="offset" /> is less than 0.

-or-

<paramref name="count" /> is less than 0.

-or-

<paramref name="count" /> is greater than the length of <paramref name="buffer" /> minus <paramref name="offset" />.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if present to determine the cause of the failure.</exception>
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="ReadByte">
Expand All @@ -3663,9 +3715,22 @@ Authentication has not occurred.</exception>
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Reads a byte from the <see cref="T:System.Net.Security.SslStream" /> and advances the position within the stream by one byte, or returns -1 if at the end of the stream.</summary>
<returns>The unsigned byte cast to an <see langword="Int32"/>, or -1 if at the end of the stream.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
You cannot perform multiple simultaneous read operations.

You cannot call this method until you have successfully authenticated.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if present to determine the cause of the failure.</exception>
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="ReadTimeout">
Expand Down Expand Up @@ -4161,11 +4226,24 @@ Authentication has not occurred.</exception>
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="buffer">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="buffer">The data to write to the underlying stream.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Asynchronously writes data to the underlying stream from a read-only byte memory range.</summary>
<returns>A task that represents the asynchronous write operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
You cannot call this method until you have successfully authenticated.

The <xref:System.Net.Security.SslStream> class does not support multiple simultaneous write operations.

]]></format>
</remarks>
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
<exception cref="T:System.IO.IOException">The write operation failed.</exception>
<exception cref="T:System.NotSupportedException">There is already a write operation in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="WriteAsync">
Expand Down Expand Up @@ -4195,13 +4273,36 @@ Authentication has not occurred.</exception>
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="buffer">To be added.</param>
<param name="offset">To be added.</param>
<param name="count">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="buffer">The data to write to the underlying stream.</param>
<param name="offset">The location in <paramref name="buffer" /> from which to start writing data.</param>
<param name="count">The number of bytes to write to the underlying stream.</param>
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
<summary>Asynchronously writes data to the underlying stream from the specified range of a byte array.</summary>
<returns>A task that represents the asynchronous write operation.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
You cannot call this method until you have successfully authenticated.

The <xref:System.Net.Security.SslStream> class does not support multiple simultaneous write operations.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException"><paramref name="buffer" /> is <see langword="null" />.</exception>
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="offset" /> is less than 0.

-or-

<paramref name="count" /> is less than 0.

-or-

<paramref name="count" /> is greater than the length of <paramref name="buffer" /> minus <paramref name="offset" />.</exception>
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
<exception cref="T:System.IO.IOException">The write operation failed.</exception>
<exception cref="T:System.NotSupportedException">There is already a write operation in progress.</exception>
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
</Docs>
</Member>
<Member MemberName="WriteTimeout">
Expand Down