Begins an asynchronous read from the System.Net.Sockets.NetworkStream.
- 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.
An IAsyncResult that represents the asynchronous call.
Type Reason 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.ObjectDisposedException The current instance has been disposed.
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.
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.