Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Socket.BeginReceive Method

Begins to asynchronously receive data from a connected Socket.

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

Parameters

buffer
An array of type Byte that is the storage location for the received data.
offset
The zero-based position in the buffer parameter at which to store the received data.
size
The number of bytes to receive.
socketFlags
A bitwise combination of the SocketFlags values.
callback
The AsyncCallback delegate.
state
An object containing state information for this request.

Return Value

An IAsyncResult that references the asynchronous read.

Exceptions

Exception Type Condition
ArgumentNullException buffer is a null reference (Nothing in Visual Basic).
SocketException An error occurred when attempting to access the socket. See the Remarks section for more information.
ObjectDisposedException Socket has been closed.
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.

Remarks

The BeginReceive method starts asynchronously reading data from the Socket returned by EndAccept. Calling the BeginReceive method gives you the ability to receive data within a separate execution thread.

You can create acallback method that implements the AsyncCallback delegate and pass its name to the BeginReceive method. To do this, at the very minimum, your state parameter must contain the connected or default Socket being used for communication. 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 BeginReceive method through the state parameter.

Your callback method should implement the EndReceive method. When your application calls BeginReceive, the system will use a separate thread to execute the specified callback method, and will block on EndReceive until the Socket reads data or throws an exception. If you want the original thread to block after you call the BeginReceive method, use WaitHandle.WaitOne. Call ManualResetEvent.Set in the callback method when you want the original thread to continue executing. For additional information on writing callback methods, see Callback Sample.

You can call BeginReceive from both connection-oriented and connectionless sockets. You must call the Connect, BeginConnect, Accept, or BeginAccept method before calling the BeginReceive method, because the BeginReceive method will only read data which arrives from the remote host you specify in one of these methods. If you are using a connectionless protocol, you can also use the BeginReceiveFrom method. BeginReceiveFrom will allow you to receive data arriving from any host.

If you are using a connection-oriented Socket, the BeginReceive method will read as much data as is available, up to the number of bytes specified by the size parameter.

If you are using a connectionless Socket, BeginReceive will read the first enqueued datagram from the destination address you specify in the Connect or BeginConnect method. If the datagram you receive is larger than the size of the buffer parameter, buffer gets filled with the first part of the message, and a SocketException is thrown. With unreliable protocols the excess data is lost; with reliable protocols, the data is retained by the service provider and you can retrieve the rest by calling the BeginReceive method with a large enough buffer.

If you specify the OutOfBand flag as the socketFlags parameter and the Socket is configured for in-line reception of out-of-band (OOB) data (using OutOfBandInline) and OOB data is available, BeginReceive will return only OOB data. The OOB data is a logically independent transmission channel associated with each pair of connected stream sockets. This data is delivered with higher priority and independently of the normal data. If you specify the Peek flag, the available data is copied into the receive buffer but not removed from the system buffer.

Note   If you receive a SocketException, use SocketException.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 begins to asynchronously receive data from a connected Socket.

[Visual Basic] 
allDone.Set()
Dim s As Socket = CType(ar.AsyncState, Socket)
Dim s2 As Socket = s.EndAccept(ar)
Dim so2 As New StateObject()
so2.workSocket = s2
s2.BeginReceive(so2.buffer, 0, StateObject.BUFFER_SIZE, 0, New AsyncCallback(AddressOf Async_Send_Receive.Read_Callback), so2)
   End Sub 'Listen_Callback
   

[C#] 
allDone.Set();
Socket s = (Socket) ar.AsyncState;
Socket s2 = s.EndAccept(ar);
StateObject so2 = new StateObject();
so2.workSocket = s2;
s2.BeginReceive(so2.buffer, 0, StateObject.BUFFER_SIZE,0,
                      new AsyncCallback(Async_Send_Receive.Read_Callback), so2);    

[C++] 
allDone->Set();
Socket* s = __try_cast<Socket*>(ar->AsyncState);
Socket* s2 = s->EndAccept(ar);
StateObject* so2 = new StateObject();
so2->workSocket = s2;
s2->BeginReceive(so2->buffer, 0, StateObject::BUFFER_SIZE, SocketFlags::None,
    new AsyncCallback(0, &Async_Send_Receive::Read_Callback), so2);    

[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

Socket Class | Socket Members | System.Net.Sockets Namespace | Including Asynchronous Calls | EndAccept | AsyncCallback | Callback Sample | Connect | BeginReceiveFrom

Show:
© 2015 Microsoft