This documentation is archived and is not being maintained.

NetworkStream.BeginRead Method

Begins an asynchronous read from the NetworkStream.

[Visual Basic]
Overrides Public Function BeginRead( _
   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 BeginRead(
 byte[] buffer,
 int offset,
 int size,
 AsyncCallback callback,
 object state
);
[C++]
public: IAsyncResult* BeginRead(
 unsigned char buffer __gc[],
 int offset,
 int size,
 AsyncCallback* callback,
 Object* state
);
[JScript]
public override function BeginRead(
   buffer : Byte[],
 offset : int,
 size : int,
 callback : AsyncCallback,
 state : Object
) : IAsyncResult;

Parameters

buffer
An array of type Byte that is the location in memory to store data read from the NetworkStream.
offset
The location in buffer to begin storing the data.
size
The number of bytes to read from the NetworkStream.
callback
The AsyncCallback delegate that is executed when BeginRead 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 reading from the network.

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

Remarks

The BeginRead method starts asynchronously reading data from the incoming network buffers. Calling the BeginRead method gives you the ability to receive data within a separate execution thread.

You must create acallback method that implements the AsyncCallback delegate and pass its name to the BeginRead method. At the very minimum, your state parameter must contain the NetworkStream. Since 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 BeginRead method through the state parameter.

Your callback method should implement the EndRead method. When your application calls BeginRead, the system will use a separate thread to execute the specified callback method, and will block on EndRead until the provided NetworkStream reads data or throws an exception. If you want the original thread to block after you call the BeginRead 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.

The BeginRead method will read as much data as is available, up to the number of bytes specified by the size parameter.

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 BeginRead to read data asynchronously from the network stream. The method myReadCallBack implements the AsyncCallback delegate and will be called by the system when BeginRead returns.

[Visual Basic] 
' Check to see if this NetworkStream is readable.
If myNetworkStream.CanRead Then
   
   Dim myReadBuffer(1024) As Byte
   myNetworkStream.BeginRead(myReadBuffer, 0, myReadBuffer.Length, New AsyncCallback(AddressOf NetworkStream_ASync_Send_Receive.myReadCallBack), myNetworkStream)
   
   allDone.WaitOne()
Else
   Console.WriteLine("Sorry.  You cannot read from this NetworkStream.")
End If


[C#] 

// Check to see if this NetworkStream is readable.
if(myNetworkStream.CanRead){
    
    byte[] myReadBuffer = new byte[1024];
    myNetworkStream.BeginRead(myReadBuffer, 0, myReadBuffer.Length, 
                                                 new AsyncCallback(NetworkStream_ASync_Send_Receive.myReadCallBack), 
                                                 myNetworkStream);  

    allDone.WaitOne();
}
else{
     Console.WriteLine("Sorry.  You cannot read from this NetworkStream.");
}


[C++] 

// Check to see if this NetworkStream is readable.
if (myNetworkStream->CanRead) {
    Byte myReadBuffer[] = new Byte[1024];
    myNetworkStream->BeginRead(myReadBuffer, 0, myReadBuffer->Length, 
        new AsyncCallback(0, &MyNetworkStreamClass::myReadCallBack), 
        myNetworkStream);  
    allDone->WaitOne();
} else {
    Console::WriteLine(S"Sorry.  You cannot read from 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 | EndRead | Including Asynchronous Calls

Show: