This documentation is archived and is not being maintained.

NetworkStream.BeginWrite Method

Begins an asynchronous write to a stream.

Namespace: System.Net.Sockets
Assembly: System (in system.dll)

public override IAsyncResult BeginWrite (
	byte[] buffer,
	int offset,
	int size,
	AsyncCallback callback,
	Object state
)
public IAsyncResult BeginWrite (
	byte[] buffer, 
	int offset, 
	int size, 
	AsyncCallback callback, 
	Object state
)
public override function BeginWrite (
	buffer : byte[], 
	offset : int, 
	size : int, 
	callback : AsyncCallback, 
	state : Object
) : IAsyncResult
Not applicable.

Parameters

buffer

An array of type Byte that contains the data to write to the NetworkStream.

offset

The location in buffer to begin sending the data.

size

The number of bytes to write to the NetworkStream.

callback

The AsyncCallback delegate that is executed when BeginWrite completes.

state

An object that contains any additional user-defined data.

Return Value

An IAsyncResult that represents the asynchronous call.

Exception typeCondition

ArgumentNullException

The buffer parameter is a null reference (Nothing in Visual Basic).

ArgumentOutOfRangeException

The offset parameter is less than 0.

-or-

The offset parameter is greater than the length of buffer.

-or-

The size parameter is less than 0.

-or-

The size parameter 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 writing to the network.

-or-

An error occurred when accessing the socket. See the Remarks section for more information.

ObjectDisposedException

The NetworkStream is closed.

The BeginWrite method starts an asynchronous send operation to the remote host. Calling the BeginWrite 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 BeginWrite method. At the very minimum, your state parameter must contain the NetworkStream. If your callback needs more information, you can create a small class or structure to hold the NetworkStream and the other required information. Pass the structure or class instance to the BeginWrite method through the state parameter.

Your callback method should implement the EndWrite method. When your application calls BeginWrite, the system uses a separate thread to execute the specified callback method, and blocks on EndWrite until the NetworkStream sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the BeginWrite method, use the WaitOne method. Call Set in the callback method when you want the original thread to continue executing. For additional information about writing callback methods, see Callback Sample.

NoteNote:

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, and refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error.

The following code example uses BeginWrite to write data asynchronously to a network stream. The myWriteCallBack method implements the AsyncCallback delegate and is called by the system when BeginWrite returns.

//Example of CanWrite, and BeginWrite.

 // Check to see if this NetworkStream is writable.
 if (myNetworkStream.CanWrite){
    
      byte[] myWriteBuffer = Encoding.ASCII.GetBytes("Are you receiving this message?");
      myNetworkStream.BeginWrite(myWriteBuffer, 0, myWriteBuffer.Length, 
                                                   new AsyncCallback(NetworkStream_ASync_Send_Receive.myWriteCallBack), 
                                                   myNetworkStream);
      allDone.WaitOne();
 }
 else{
      Console.WriteLine("Sorry.  You cannot write to this NetworkStream.");  
 }


// Example of CanWrite, and BeginWrite.
// Check to see if this NetworkStream is writable.
if (myNetworkStream.get_CanWrite()) {
    ubyte myWriteBuffer[] = Encoding.get_ASCII().
        GetBytes("Are you receiving this message?");
    myNetworkStream.BeginWrite(myWriteBuffer, 0,
        myWriteBuffer.get_Length(), 
        new AsyncCallback(NetworkStreamASyncSendReceive.
        MyWriteCallBack), myNetworkStream);
    allDone.WaitOne();
}
else {
    Console.WriteLine("Sorry.  You cannot write to this "
        + "NetworkStream.");
}

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0
Show: