Edit

NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) Method

  • Reference

Definition

Namespace:
System.Net.Sockets
Assembly:
System.Net.Sockets.dll
Assembly:
System.dll
Assembly:
netstandard.dll
Source:
NetworkStream.cs
Source:
NetworkStream.cs
Source:
NetworkStream.cs

Begins an asynchronous read from the NetworkStream.

public:
 override IAsyncResult ^ BeginRead(cli::array <System::Byte> ^ buffer, int offset, int size, AsyncCallback ^ callback, System::Object ^ state);
public:
 override IAsyncResult ^ BeginRead(cli::array <System::Byte> ^ buffer, int offset, int count, AsyncCallback ^ callback, System::Object ^ state);
public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback? callback, object? state);
public override IAsyncResult BeginRead (byte[] buffer, int offset, int count, AsyncCallback? callback, object? state);
public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback callback, object state);
override this.BeginRead : byte[] * int * int * AsyncCallback * obj -> IAsyncResult
override this.BeginRead : byte[] * int * int * AsyncCallback * obj -> IAsyncResult
Public Overrides Function BeginRead (buffer As Byte(), offset As Integer, size As Integer, callback As AsyncCallback, state As Object) As IAsyncResult
Public Overrides Function BeginRead (buffer As Byte(), offset As Integer, count As Integer, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

buffer
Byte[]

An array of type Byte that is the location in memory to store data read from the NetworkStream.

offset
Int32

The location in buffer to begin storing the data.

sizecount
Int32

The number of bytes to read from the NetworkStream.

callback
AsyncCallback

The AsyncCallback delegate that is executed when BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) completes.

state
Object

An object that contains any additional user-defined data.

Returns

IAsyncResult

An IAsyncResult that represents the asynchronous call.

Exceptions

ArgumentNullException

The buffer parameter is null.

ArgumentOutOfRangeException

The offset parameter is less than 0.

-or-

The offset parameter is greater than the length of the buffer paramater.

-or-

The size is less than 0.

-or-

The size is greater than the length of buffer minus the value of the offset parameter.

IOException

The underlying Socket is closed.

-or-

There was a failure while reading from the network.

-or-

An error occurred when accessing the socket.

ObjectDisposedException

The NetworkStream is closed.

Remarks

Important

This is a compatibility API, we don't recommend to use the APM (Begin / End) methods for new development. Instead, use the Task-based equivalents.

You can pass a callback that implements AsyncCallback to BeginRead 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 BeginRead. In this case, the CompletedSynchronously property on the returned IAsyncResult will be set to true to indicate that the method completed synchronously. Use the AsyncState property of the IAsyncResult to obtain the state object passed to the BeginRead method.

The BeginRead operation must be completed by calling the EndRead method. Typically, the method is invoked by the provided AsyncCallback delegate. EndRead 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 IOException, check the InnerException property to determine if it was caused by a SocketException. If so, use the ErrorCode property to obtain the specific error code.

Read and write operations can be performed simultaneously on an instance of the NetworkStream class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required.

Applies to

See also