This documentation is archived and is not being maintained.

NetworkStream.BeginWrite Method

Begins an asynchronous write to a stream.

[Visual Basic]
Overrides Public Function BeginWrite( _
   ByVal buffer() As Byte, _
   ByVal offset As Integer, _
   ByVal size As Integer, _
   ByVal callback As AsyncCallback, _
   ByVal state As Object _
) As IAsyncResult
[C#]
public override IAsyncResult BeginWrite(
 byte[] buffer,
 int offset,
 int size,
 AsyncCallback callback,
 object state
);
[C++]
public: IAsyncResult* BeginWrite(
 unsigned char buffer __gc[],
 int offset,
 int size,
 AsyncCallback* callback,
 Object* state
);
[JScript]
public override function BeginWrite(
   buffer : Byte[],
 offset : int,
 size : int,
 callback : AsyncCallback,
 state : Object
) : IAsyncResult;

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 containing any additional user defined data.

Return Value

An IAsyncResult representing the asynchronous call.

Exceptions

Exception Type Condition
ArgumentNullException buffer is a null reference (Nothing in Visual Basic).
ArgumentOutOfRangeException offset is less than 0.

-or-

offset is greater than the length of buffer.

-or-

size is less than 0.

-or-

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

IOException The underlying Socket is closed.

-or-

There is a failure while writing to the network.

ObjectDisposedException The NetworkStream is closed.
IOException An error occurred when accessing the socket. See the Remarks section for more information.

Remarks

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 acallback 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 will use a separate thread to execute the specified callback method, and will block 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 WaitOne. Call Set in the callback method when you want the original thread to continue executing. For additional information on writing callback methods, see Callback Sample.

Note   If you receive a IOException check the InnerException property to determine if it was caused by a SocketException. If so, use ErrorCode to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Socket Version 2 API error code documentation in MSDN for a detailed description of the error.

Example

[Visual Basic, C#, C++] The following example uses BeginWrite to write data asynchronously to a network stream. The method m yWriteCallBack implements the AsyncCallback delegate and will be called by the system when BeginWrite returns.

[Visual Basic] 
' Check to see if this NetworkStream is writable.
If myNetworkStream.CanWrite Then
   
   Dim myWriteBuffer As Byte() = Encoding.ASCII.GetBytes("Are you receiving this message?")
   myNetworkStream.BeginWrite(myWriteBuffer, 0, myWriteBuffer.Length, New AsyncCallback(AddressOf NetworkStream_ASync_Send_Receive.myWriteCallBack), myNetworkStream)
   allDone.WaitOne()
Else
   Console.WriteLine("Sorry.  You cannot write to this NetworkStream.")
End If


[C#] 

 // 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.");  
 }


[C++] 

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

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

NetworkStream Class | NetworkStream Members | System.Net.Sockets Namespace | EndWrite | Including Asynchronous Calls

Show: