System.Net.Sockets.NetworkStream.BeginWrite Method

Begins an asynchronous write to a stream.

Syntax

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

Parameters

buffer
An array of type byte that contains the data to write to the System.Net.Sockets.NetworkStream.
offset
The location in buffer to begin sending the data.
size
The number of bytes to write to the System.Net.Sockets.NetworkStream.
callback
The AsyncCallback delegate that is executed when NetworkStream.BeginWrite(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.BeginSend(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.BeginWrite(Byte[], int, int, AsyncCallback, object) method starts an asynchronous send operation to the remote host. Calling the NetworkStream.BeginWrite(Byte[], int, int, AsyncCallback, object) method gives you the ability to send data within a separate execution thread.

You must create a callback method that implements the AsyncCallback delegate and pass its name to the NetworkStream.BeginWrite(Byte[], int, int, AsyncCallback, object) method. At the very minimum, your state parameter must contain the System.Net.Sockets.NetworkStream. If your callback needs more information, you can create a small class or structure to hold the System.Net.Sockets.NetworkStream and the other required information. Pass the structure or class instance to the NetworkStream.BeginWrite(Byte[], int, int, AsyncCallback, object) method through the state parameter.

Your callback method should implement the NetworkStream.EndWrite(IAsyncResult) method. When your application calls NetworkStream.BeginWrite(Byte[], int, int, AsyncCallback, object), the system uses a separate thread to execute the specified callback method, and blocks on NetworkStream.EndWrite(IAsyncResult) until the System.Net.Sockets.NetworkStream sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the NetworkStream.BeginWrite(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.

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