NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) Method

Definition

Begins an asynchronous read from the NetworkStream.

public:
 override IAsyncResult ^ BeginRead(cli::array <System::Byte> ^ buffer, int offset, int size, AsyncCallback ^ callback, System::Object ^ state);
public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback callback, object state);
override this.BeginRead : byte[] * int * int * AsyncCallback * obj -> IAsyncResult
Public Overrides Function BeginRead (buffer As Byte(), offset As Integer, size As Integer, callback As AsyncCallback, state As Object) As IAsyncResult
Parameters
buffer
Byte[]

An array of type Byte that is the location in memory to store data read from the NetworkStream.

offset
Int32 Int32 Int32 Int32

The location in buffer to begin storing the data.

size
Int32 Int32 Int32 Int32

The number of bytes to read from the NetworkStream.

state
Object Object Object Object

An object that contains any additional user-defined data.

Returns

An IAsyncResult that represents the asynchronous call.

Exceptions

The offset parameter is less than 0.

-or-

The offset parameter is greater than the length of the buffer paramater.

-or-

The size is less than 0.

-or-

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

The underlying Socket is closed.

-or-

There was a failure while reading from the network.

-or-

An error occurred when accessing the socket.

Examples

The following code example uses BeginRead to read data asynchronously from the network stream. The myReadCallBack method implements the AsyncCallback delegate and is called by the system when BeginRead returns.

// Example of CanRead, and BeginRead.
// Check to see if this NetworkStream is readable.
if ( myNetworkStream->CanRead )
{
   array<Byte>^myReadBuffer = gcnew array<Byte>(1024);
   myNetworkStream->BeginRead( myReadBuffer, 0, myReadBuffer->Length, gcnew AsyncCallback( &MyNetworkStreamClass::myReadCallBack ), myNetworkStream );
   allDone->WaitOne();
}
else
{
   Console::WriteLine( "Sorry.  You cannot read from this NetworkStream." );
}
// Example of CanRead, and BeginRead.

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

' Example of CanRead, and BeginRead.
' 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

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 a callback 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. 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 BeginRead method through the state parameter.

Your callback method should call the EndRead method. When your application calls BeginRead, 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 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 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 Marshaling a Delegate as a Callback Method.

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

Note

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 for a detailed description of the error.

Read and write operations can be performed simultaneously on an instance of the 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.

Applies to

See Also