Skip to content

Commit

Permalink
fixes dotnet#10895
Browse files Browse the repository at this point in the history
  • Loading branch information
@gewarren
gewarren committed Feb 4, 2025
1 parent 2c0d1a4 commit b79650a
Showing 1 changed file with 9 additions and 14 deletions.
23 changes: 9 additions & 14 deletions xml/System.Net.Sockets/NetworkStream.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -422,13 +422,13 @@
## Remarks
> [!IMPORTANT]
> This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
> This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
You can pass a callback that implements <xref:System.AsyncCallback> to <xref:System.Net.Sockets.NetworkStream.BeginRead%2A> in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to <xref:System.Net.Sockets.NetworkStream.BeginRead%2A>. In this case, the <xref:System.IAsyncResult.CompletedSynchronously%2A> property on the returned <xref:System.IAsyncResult> will be set to `true` to indicate that the method completed synchronously. Use the <xref:System.IAsyncResult.AsyncState%2A> property of the <xref:System.IAsyncResult> to obtain the state object passed to the <xref:System.Net.Sockets.NetworkStream.BeginRead%2A> method.
The <xref:System.Net.Sockets.NetworkStream.BeginRead%2A> operation must be completed by calling the <xref:System.Net.Sockets.NetworkStream.EndRead%2A> method. Typically, the method is invoked by the provided <xref:System.AsyncCallback> delegate. <xref:System.Net.Sockets.NetworkStream.EndRead%2A> will block the calling thread until the operation is completed.
The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter.
The operation reads as much data as is available, up to the number of bytes specified by the `count` parameter.
> [!NOTE]
> If you receive an <xref:System.IO.IOException>, check the <xref:System.Exception.InnerException%2A> property to determine if it was caused by a <xref:System.Net.Sockets.SocketException>. If so, use the <xref:System.Net.Sockets.SocketException.ErrorCode%2A> property to obtain the specific error code.
Expand Down Expand Up @@ -540,7 +540,7 @@
## Remarks
> [!IMPORTANT]
> This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
> This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
You can pass a callback that implements <xref:System.AsyncCallback> to <xref:System.Net.Sockets.NetworkStream.BeginWrite%2A> in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to <xref:System.Net.Sockets.NetworkStream.BeginWrite%2A>. In this case, the <xref:System.IAsyncResult.CompletedSynchronously%2A> property on the returned <xref:System.IAsyncResult> will be set to `true` to indicate that the method completed synchronously. Use the <xref:System.IAsyncResult.AsyncState%2A> property of the <xref:System.IAsyncResult> to obtain the state object passed to the <xref:System.Net.Sockets.NetworkStream.BeginWrite%2A> method.
Expand Down Expand Up @@ -1113,12 +1113,10 @@ The Close method frees both unmanaged and managed resources associated with the
## Remarks
> [!IMPORTANT]
> This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
> This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
The <xref:System.Net.Sockets.NetworkStream.EndRead%2A> method completes the read operation started by the <xref:System.Net.Sockets.NetworkStream.BeginRead%2A> method. You need to pass the <xref:System.IAsyncResult> created by the matching <xref:System.Net.Sockets.NetworkStream.BeginRead%2A> call. <xref:System.Net.Sockets.NetworkStream.EndRead%2A> will block the calling thread until the operation is completed.
The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter.
> [!NOTE]
> If you receive an <xref:System.IO.IOException>, check the <xref:System.Exception.InnerException%2A> property to determine if it was caused by a <xref:System.Net.Sockets.SocketException>. If so, use the <xref:System.Net.Sockets.SocketException.ErrorCode%2A> property to obtain the specific error code.
Expand Down Expand Up @@ -1179,12 +1177,10 @@ The Close method frees both unmanaged and managed resources associated with the
## Remarks
> [!IMPORTANT]
> This is a compatibility API, we don't recommend to use the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
> This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents.
The <xref:System.Net.Sockets.NetworkStream.EndWrite%2A> method completes the read operation started by the <xref:System.Net.Sockets.NetworkStream.BeginWrite%2A> method. You need to pass the <xref:System.IAsyncResult> created by the matching <xref:System.Net.Sockets.NetworkStream.BeginWrite%2A> call. <xref:System.Net.Sockets.NetworkStream.EndWrite%2A> will block the calling thread until the operation is completed.
The operation reads as much data as is available, up to the number of bytes specified by the `size` parameter.
> [!NOTE]
> If you receive an <xref:System.IO.IOException>, check the <xref:System.Exception.InnerException%2A> property to determine if it was caused by a <xref:System.Net.Sockets.SocketException>. If so, use the <xref:System.Net.Sockets.SocketException.ErrorCode%2A> property to obtain the specific error code.
Expand Down Expand Up @@ -1552,15 +1548,14 @@ There is a failure reading from the network.</exception>
<format type="text/markdown"><![CDATA[
## Remarks
This method reads data into `buffer` and returns the number of bytes successfully read. The `Read` operation reads as much data as is available, up to the number of bytes specified by the `size` parameter.
This method reads data into `buffer` and returns the number of bytes successfully read. The `Read` operation reads as much data as is available, up to the number of bytes specified by the `count` parameter.
> [!NOTE]
> Check to see if the <xref:System.Net.Sockets.NetworkStream> is readable by calling the <xref:System.Net.Sockets.NetworkStream.CanRead> property. If you attempt to read from a <xref:System.Net.Sockets.NetworkStream> that is not readable, you will get an <xref:System.InvalidOperationException>.
> [!NOTE]
> If you receive an <xref:System.IO.IOException>, check the <xref:System.Exception.InnerException> property to determine if it was caused by a <xref:System.Net.Sockets.SocketException>. If so, use the <xref:System.Net.Sockets.SocketException.ErrorCode> property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error.
## Examples
The following code example reads data from the <xref:System.Net.Sockets.NetworkStream> into a buffer. If data is available, it continues reading until the end of the stream is reached, appending the received data to a <xref:System.Text.StringBuilder>.
:::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Overview/source.cs" id="Snippet4":::
Expand Down Expand Up @@ -1776,7 +1771,7 @@ There is a failure reading from the network.</exception>
<format type="text/markdown"><![CDATA[
## Remarks
This method reads data into `buffer` and returns the number of bytes successfully read. The `ReadAsync` operation reads as much data as is available, up to the number of bytes specified by the `size` parameter.
This method reads data into `buffer` and returns the number of bytes successfully read. The `ReadAsync` operation reads as much data as is available, up to the number of bytes specified by the `count` parameter.
> [!NOTE]
> Check to see if the <xref:System.Net.Sockets.NetworkStream> is readable by calling the <xref:System.Net.Sockets.NetworkStream.CanRead> property. If you attempt to read from a <xref:System.Net.Sockets.NetworkStream> that is not readable, you will get an <xref:System.InvalidOperationException>.
Expand Down Expand Up @@ -2218,7 +2213,7 @@ There was a failure while writing to the network.</exception>
<format type="text/markdown"><![CDATA[
## Remarks
This method starts at the specified `offset` and sends `size` bytes from the contents of `buffer` to the network. The `Write` method blocks until the requested number of bytes is sent or a <xref:System.Net.Sockets.SocketException> is thrown.
This method starts at the specified `offset` and sends `count` bytes from the contents of `buffer` to the network. The `Write` method blocks until the requested number of bytes is sent or a <xref:System.Net.Sockets.SocketException> is thrown.
> [!NOTE]
> Check to see if the <xref:System.Net.Sockets.NetworkStream> is writable by calling the <xref:System.Net.Sockets.NetworkStream.CanWrite> property. If you attempt to write to a <xref:System.Net.Sockets.NetworkStream> that is not writable, you will get an <xref:System.InvalidOperationException>.
Expand Down Expand Up @@ -2438,7 +2433,7 @@ There was a failure while writing to the network.</exception>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method starts at the specified `offset` and sends `size` bytes from the contents of `buffer` to the network.
This method starts at the specified `offset` and sends `count` bytes from the contents of `buffer` to the network.
> [!NOTE]
> Check to see if the <xref:System.Net.Sockets.NetworkStream> is writable by calling the <xref:System.Net.Sockets.NetworkStream.CanWrite> property. If you attempt to write to a <xref:System.Net.Sockets.NetworkStream> that is not writable, you will get an <xref:System.InvalidOperationException>.
Expand Down

0 comments on commit b79650a

Please sign in to comment.