Skip to content

Commit da537ea

Browse files
jozkeecarlossanlopRon Petrusha
committed
Added documentation for System.Net.Security APIs targeted for 3.0 (#2788)
* Added documentation for System.Net.Sockets APIs targeted for 3.0 * Apply suggestions from code review Addressing PR suggestions. Co-Authored-By: Carlos Sanchez Lopez <[email protected]> Co-Authored-By: Ron Petrusha <[email protected]>
1 parent 2d8c3bd commit da537ea

File tree

3 files changed

+163
-39
lines changed

3 files changed

+163
-39
lines changed

‎xml/System.Net.Security/AuthenticatedStream.xml

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -182,9 +182,20 @@ The following example demonstrates displaying the properties of an authenticated
182182
</ReturnValue>
183183
<Parameters />
184184
<Docs>
185-
<summary>To be added.</summary>
186-
<returns>To be added.</returns>
187-
<remarks>To be added.</remarks>
185+
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.AuthenticatedStream" />.</summary>
186+
<returns>A task that represents the asynchronous dispose operation.</returns>
187+
<remarks>
188+
<format type="text/markdown"><![CDATA[
189+
190+
## Remarks
191+
This method allows performing resource-intensive dispose operations without blocking the main thread.
192+
193+
This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`; otherwise, the inner stream is just flushed.
194+
195+
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).
196+
197+
]]></format>
198+
</remarks>
188199
</Docs>
189200
</Member>
190201
<Member MemberName="InnerStream">
@@ -536,4 +547,4 @@ The following example demonstrates displaying the value of this property.
536547
</Docs>
537548
</Member>
538549
</Members>
539-
</Type>
550+
</Type>

‎xml/System.Net.Security/NegotiateStream.xml

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2629,9 +2629,21 @@ The following method is called when the operation completes.
26292629
</ReturnValue>
26302630
<Parameters />
26312631
<Docs>
2632-
<summary>To be added.</summary>
2633-
<returns>To be added.</returns>
2634-
<remarks>To be added.</remarks>
2632+
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.NegotiateStream" />.</summary>
2633+
<returns>A task that represents the asynchronous dispose operation.</returns>
2634+
<remarks>
2635+
<format type="text/markdown">
2636+
<![CDATA[
2637+
2638+
## Remarks
2639+
This method enables you to perform a resource-intensive dispose operation without blocking the main thread.
2640+
2641+
This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`; otherwise, the inner stream is just flushed.
2642+
2643+
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).
2644+
2645+
]]></format>
2646+
</remarks>
26352647
</Docs>
26362648
</Member>
26372649
<Member MemberName="EndAuthenticateAsClient">
@@ -3822,4 +3834,4 @@ Authentication has not occurred.</exception>
38223834
</Docs>
38233835
</Member>
38243836
</Members>
3825-
</Type>
3837+
</Type>

‎xml/System.Net.Security/SslStream.xml

Lines changed: 132 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2451,9 +2451,21 @@
24512451
</ReturnValue>
24522452
<Parameters />
24532453
<Docs>
2454-
<summary>To be added.</summary>
2455-
<returns>To be added.</returns>
2456-
<remarks>To be added.</remarks>
2454+
<summary>Asynchronously releases the unmanaged and managed resources used by the <see cref="T:System.Net.Security.SslStream" />.</summary>
2455+
<returns>A task that represents the asynchronous dispose operation.</returns>
2456+
<remarks>
2457+
<format type="text/markdown">
2458+
<![CDATA[
2459+
2460+
## Remarks
2461+
This method enables you to perform a resource-intensive dispose operation without blocking the main thread.
2462+
2463+
This method also disposes the inner stream when <xref:System.Net.Security.AuthenticatedStream.LeaveInnerStreamOpen> is `false`; otherwise, the inner stream is just flushed.
2464+
2465+
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).
2466+
2467+
]]></format>
2468+
</remarks>
24572469
</Docs>
24582470
</Member>
24592471
<Member MemberName="EndAuthenticateAsClient">
@@ -3597,11 +3609,26 @@ Authentication has not occurred.</exception>
35973609
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
35983610
</Parameters>
35993611
<Docs>
3600-
<param name="buffer">To be added.</param>
3601-
<param name="cancellationToken">To be added.</param>
3602-
<summary>To be added.</summary>
3603-
<returns>To be added.</returns>
3604-
<remarks>To be added.</remarks>
3612+
<param name="buffer">The buffer that receives the bytes read from this stream.</param>
3613+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
3614+
<summary>Asynchronously reads data from this stream and stores it in the specified memory range.</summary>
3615+
<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>
3616+
<remarks>
3617+
<format type="text/markdown"><![CDATA[
3618+
3619+
## Remarks
3620+
This method reads as much data as is available into the `buffer`.
3621+
3622+
You cannot perform multiple simultaneous read operations.
3623+
3624+
You cannot call this method until you have successfully authenticated.
3625+
3626+
]]></format>
3627+
</remarks>
3628+
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
3629+
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if it is present, to determine the cause of the failure.</exception>
3630+
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
3631+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
36053632
</Docs>
36063633
</Member>
36073634
<Member MemberName="ReadAsync">
@@ -3631,13 +3658,38 @@ Authentication has not occurred.</exception>
36313658
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="netcore-3.0" />
36323659
</Parameters>
36333660
<Docs>
3634-
<param name="buffer">To be added.</param>
3635-
<param name="offset">To be added.</param>
3636-
<param name="count">To be added.</param>
3637-
<param name="cancellationToken">To be added.</param>
3638-
<summary>To be added.</summary>
3639-
<returns>To be added.</returns>
3640-
<remarks>To be added.</remarks>
3661+
<param name="buffer">The buffer that receives the bytes read from this stream.</param>
3662+
<param name="offset">The zero-based location in <paramref name="buffer" /> at which to begin storing the data read from this stream.</param>
3663+
<param name="count">The maximum number of bytes to read from this stream.</param>
3664+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
3665+
<summary>Asynchronously reads data from this stream and stores it in the specified range of a byte array.</summary>
3666+
<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>
3667+
<remarks>
3668+
<format type="text/markdown"><![CDATA[
3669+
3670+
## Remarks
3671+
The method reads a maximum of `count` bytes from the stream and stores them in `buffer` beginning at `offset`.
3672+
3673+
You cannot perform multiple simultaneous read operations.
3674+
3675+
You cannot call this method until you have successfully authenticated.
3676+
3677+
]]></format>
3678+
</remarks>
3679+
<exception cref="T:System.ArgumentNullException"><paramref name="buffer" /> is <see langword="null" />.</exception>
3680+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="offset" /> is less than 0.
3681+
3682+
-or-
3683+
3684+
<paramref name="count" /> is less than 0.
3685+
3686+
-or-
3687+
3688+
<paramref name="count" /> is greater than the length of <paramref name="buffer" /> minus <paramref name="offset" />.</exception>
3689+
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
3690+
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if it is present, to determine the cause of the failure.</exception>
3691+
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
3692+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
36413693
</Docs>
36423694
</Member>
36433695
<Member MemberName="ReadByte">
@@ -3663,9 +3715,22 @@ Authentication has not occurred.</exception>
36633715
</ReturnValue>
36643716
<Parameters />
36653717
<Docs>
3666-
<summary>To be added.</summary>
3667-
<returns>To be added.</returns>
3668-
<remarks>To be added.</remarks>
3718+
<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>
3719+
<returns>The unsigned byte cast to an <see langword="Int32"/>, or -1 if at the end of the stream.</returns>
3720+
<remarks>
3721+
<format type="text/markdown"><![CDATA[
3722+
3723+
## Remarks
3724+
You cannot perform multiple simultaneous read operations.
3725+
3726+
You cannot call this method until you have successfully authenticated.
3727+
3728+
]]></format>
3729+
</remarks>
3730+
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
3731+
<exception cref="T:System.IO.IOException">The read operation failed. Check the inner exception, if present to determine the cause of the failure.</exception>
3732+
<exception cref="T:System.NotSupportedException">There is already a read operation in progress.</exception>
3733+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
36693734
</Docs>
36703735
</Member>
36713736
<Member MemberName="ReadTimeout">
@@ -4161,11 +4226,24 @@ Authentication has not occurred.</exception>
41614226
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="netcore-3.0" />
41624227
</Parameters>
41634228
<Docs>
4164-
<param name="buffer">To be added.</param>
4165-
<param name="cancellationToken">To be added.</param>
4166-
<summary>To be added.</summary>
4167-
<returns>To be added.</returns>
4168-
<remarks>To be added.</remarks>
4229+
<param name="buffer">The data to write to the underlying stream.</param>
4230+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
4231+
<summary>Asynchronously writes data to the underlying stream from a read-only byte memory range.</summary>
4232+
<returns>A task that represents the asynchronous write operation.</returns>
4233+
<remarks>
4234+
<format type="text/markdown"><![CDATA[
4235+
4236+
## Remarks
4237+
You cannot call this method until you have successfully authenticated.
4238+
4239+
The <xref:System.Net.Security.SslStream> class does not support multiple simultaneous write operations.
4240+
4241+
]]></format>
4242+
</remarks>
4243+
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
4244+
<exception cref="T:System.IO.IOException">The write operation failed.</exception>
4245+
<exception cref="T:System.NotSupportedException">There is already a write operation in progress.</exception>
4246+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
41694247
</Docs>
41704248
</Member>
41714249
<Member MemberName="WriteAsync">
@@ -4195,13 +4273,36 @@ Authentication has not occurred.</exception>
41954273
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="3" FrameworkAlternate="netcore-3.0" />
41964274
</Parameters>
41974275
<Docs>
4198-
<param name="buffer">To be added.</param>
4199-
<param name="offset">To be added.</param>
4200-
<param name="count">To be added.</param>
4201-
<param name="cancellationToken">To be added.</param>
4202-
<summary>To be added.</summary>
4203-
<returns>To be added.</returns>
4204-
<remarks>To be added.</remarks>
4276+
<param name="buffer">The data to write to the underlying stream.</param>
4277+
<param name="offset">The location in <paramref name="buffer" /> from which to start writing data.</param>
4278+
<param name="count">The number of bytes to write to the underlying stream.</param>
4279+
<param name="cancellationToken">The token to monitor for cancellation requests.</param>
4280+
<summary>Asynchronously writes data to the underlying stream from the specified range of a byte array.</summary>
4281+
<returns>A task that represents the asynchronous write operation.</returns>
4282+
<remarks>
4283+
<format type="text/markdown"><![CDATA[
4284+
4285+
## Remarks
4286+
You cannot call this method until you have successfully authenticated.
4287+
4288+
The <xref:System.Net.Security.SslStream> class does not support multiple simultaneous write operations.
4289+
4290+
]]></format>
4291+
</remarks>
4292+
<exception cref="T:System.ArgumentNullException"><paramref name="buffer" /> is <see langword="null" />.</exception>
4293+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="offset" /> is less than 0.
4294+
4295+
-or-
4296+
4297+
<paramref name="count" /> is less than 0.
4298+
4299+
-or-
4300+
4301+
<paramref name="count" /> is greater than the length of <paramref name="buffer" /> minus <paramref name="offset" />.</exception>
4302+
<exception cref="T:System.InvalidOperationException">Authentication has not occurred.</exception>
4303+
<exception cref="T:System.IO.IOException">The write operation failed.</exception>
4304+
<exception cref="T:System.NotSupportedException">There is already a write operation in progress.</exception>
4305+
<exception cref="T:System.ObjectDisposedException">This object has been closed.</exception>
42054306
</Docs>
42064307
</Member>
42074308
<Member MemberName="WriteTimeout">
@@ -4260,4 +4361,4 @@ Authentication has not occurred.</exception>
42604361
</Docs>
42614362
</Member>
42624363
</Members>
4263-
</Type>
4364+
</Type>

0 commit comments

Comments
 (0)