end_receive() [1/2]

size_t xtd::net::sockets::socket::end_receive

(

xtd::sptr< xtd::iasync_result >

async_result

)

Ends a pending asynchronous read.

Parameters

async_result

An xtd::iasync_result that stores state information for this asynchronous operation as well as any user defined data.

Returns

The number of bytes received.

Exceptions

argument_exception	asyncResult was not returned by a call to the xtd::net::sockets::socket::begin_receive method.
xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::socket::end_receive method completes the asynchronous read operation started in the xtd::net::sockets::socket::begin_receive method.

Before calling xtd::net::sockets::socket::begin_receive, you need to create a callback method that implements the xtd::async_callback delegate. This callback method executes in a separate thread and is called by the system after xtd::net::sockets::socket::begin_receive returns. The callback method must accept the xtd::iasync_result returned by the xtd::net::sockets::socket::begin_receive method as a parameter.

Within the callback method, call the xtd::iasync_result::async_state method of the xtd::iasync_result to obtain the state object passed to the xtd::net::sockets::socket::begin_receive method. Extract the receiving xtd::net::sockets::socket::socket from this state object. After obtaining the xtd::net::sockets::socket::socket, you can call the xtd::net::sockets::socket::end_receive method to successfully complete the read operation and return the number of bytes read.

The xtd::net::sockets::socket::end_receive method will block until data is available. If you are using a connectionless protocol, xtd::net::sockets::socket::end_receive will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the xtd::net::sockets::socket::end_receive method will read as much data as is available up to the number of bytes you specified in the size parameter of the xtd::net::sockets::socket::begin_receive method. If the remote host shuts down the xtd::net::sockets::socket::socket connection with the Shutdown method, and all available data has been received, the xtd::net::sockets::socket::end_receive method will complete immediately and return zero bytes.

To obtain the received data, call the xtd::iasync_result::async_state method of the xtd::iasync_result, and extract the buffer contained in the resulting state object.

To cancel a pending xtd::net::sockets::socket::begin_receive, call the xtd::net::sockets::socket::socket::close method.

Note

If you receive a xtd::net::sockets::socket_exception, use the xtd::net::sockets::socket_exception::error_code property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error.

All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes.