Share via

  • Article

Socket.ReceiveAsync Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Begins an asynchronous request to receive data from a connected Socket object.

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

Syntax

'Declaration
Public Function ReceiveAsync ( _
    e As SocketAsyncEventArgs _
) As Boolean

public bool ReceiveAsync(
    SocketAsyncEventArgs e
)

Parameters

Return Value

Type: System.Boolean
Returns true if the I/O operation is pending. The SocketAsyncEventArgs.Completed event on the System.Net.Sockets.SocketAsyncEventArgs object passed in the e parameter will be raised upon completion of the operation.
Returns false if the I/O operation completed synchronously. In this case, The SocketAsyncEventArgs.Completed event on the System.Net.Sockets.SocketAsyncEventArgs object passed in the e parameter will not be raised. The System.Net.Sockets.SocketAsyncEventArgs object in the e parameter may be examined immediately after the method call returns to retrieve the result of the operation.

Exceptions

Exception Condition
ArgumentException

An argument was invalid. The SocketAsyncEventArgs.Buffer or SocketAsyncEventArgs.BufferList properties on the System.Net.Sockets.SocketAsyncEventArgs object passed in the e parameter must reference valid buffers. One or the other of these properties may be set, but not both at the same time.
ArgumentOutOfRangeException

The value for an internal socket option associated with the Socket was incorrect.
InvalidOperationException

A socket operation was already in progress using the System.Net.Sockets.SocketAsyncEventArgs object passed in the e parameter.
NotSupportedException

Windows XP or later is required for this method.
ObjectDisposedException

The Socket has been closed.
SocketException

An error occurred when attempting to access the socket. See the Remarks section for more information.

Remarks

The ReceiveAsync method is used on connected sockets and is used to read incoming data.

To be notified of completion, you must create a callback method that implements the EventHandler<SocketAsyncEventArgs> delegate and attach the callback to the SocketAsyncEventArgs.Completed event.

The following properties and events on the System.Net.Sockets.SocketAsyncEventArgs object are required to successfully call this method:

The caller may set the SocketAsyncEventArgs.UserToken property to any user state object desired before calling the ReceiveAsync method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members.

A connection to the remote host using the Socket must be established before any data can be received by the ReceiveAsync method.

For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted.

For connection-oriented sockets, the ReceiveAsync method can indicate the graceful termination of the virtual circuit. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. In any case, a SocketException with the SocketAsyncEventArgs.SocketError set to the native Winsock WSAECONNRESET error code (10054) indicates an abortive close has occurred.

NoteNote:

If you receive a SocketException when calling this method, use the SocketException.ErrorCode property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets Error Codes documentation in the MSDN library for a detailed description of the error.

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.