System.Net.Sockets.NetworkStream.BeginRead Method

Begins an asynchronous read from the System.Net.Sockets.NetworkStream.

Syntax

public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback callback, object state)

Parameters

buffer
An array of type byte that is the location in memory to store data read from the System.Net.Sockets.NetworkStream.
offset
The location in buffer to begin storing the data.
size
The number of bytes to read from the System.Net.Sockets.NetworkStream.
callback
The AsyncCallback delegate that is executed when NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) completes.
state
An object that contains any additional user-defined data.

Returns

An IAsyncResult that represents the asynchronous call.

Exceptions

TypeReason
ArgumentNullException buffer is null.
ArgumentOutOfRangeException

offset < 0.

-or-

offset > buffer.Length.

-or-

size < 0.

-or-

size > buffer.Length - offset.

System.IO.IOException

An error occurred while accessing the underlying socket.

Note: Any exception thrown by the Socket.BeginReceive(Byte[], int, int, SocketFlags, AsyncCallback, object) method is caught and rethrown as an IOException with the original exception stored in the Exception.InnerException property.

ObjectDisposedExceptionThe current instance has been disposed.

Remarks

The NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method starts asynchronously reading data from the incoming network buffers. Calling the NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method gives you the ability to receive data within a separate execution thread.

You must create a callback method that implements the AsyncCallback delegate and pass its name to the NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method. At the very minimum, your state parameter must contain the System.Net.Sockets.NetworkStream. Because you will want to obtain the received data within your callback method, you should create a small class or structure to hold a read buffer and any other useful information. Pass the structure or class instance to the NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method through the state parameter.

Your callback method should call the NetworkStream.EndRead(IAsyncResult) method. When your application calls NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object), the system will wait until data is received or an error occurs, and then the system will use a separate thread to execute the specified callback method, and blocks on NetworkStream.EndRead(IAsyncResult) until the provided System.Net.Sockets.NetworkStream reads data or throws an exception. If you want the original thread to block after you call the NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method, use the System.Threading.WaitHandle.WaitOne(int, bool) method. Call System.Threading.EventWaitHandle.Set in the callback method when you want the original thread to continue executing. For additional information about writing callback methods, see Callback Sample.

The NetworkStream.BeginRead(Byte[], int, int, AsyncCallback, object) method reads as much data as is available, up to the number of bytes specified by the size parameter.

Note:

If you receive an System.IO.IOException, check the Exception.InnerException property to determine if it was caused by a System.Net.Sockets.SocketException. If so, use the SocketException.ErrorCode property to obtain the specific error code, and refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error.

Read and write operations can be performed simultaneously on an instance of the System.Net.Sockets.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.

Example

For an outline of an asynchronous operation, see the Socket.BeginAccept(AsyncCallback, object) method. For the complete example, see the System.Net.Sockets.Socket class overview.

Requirements

Namespace: System.Net.Sockets
Assembly: System (in System.dll)
Assembly Versions: 1.0.5000.0, 2.0.0.0, 4.0.0.0