begin_receive_from()

xtd::sptr< xtd::iasync_result > xtd::net::sockets::socket::begin_receive_from	(	std::vector< xtd::byte > &	buffer,
		size_t	offset,
		size_t	size,
		xtd::net::sockets::socket_flags	socket_flags,
		xtd::net::end_point &	remote_end_point,
		xtd::async_callback	callback,
		const std::any &	state
	)

Begins to asynchronously receive data from a specified network device.

Parameters

buffer	An array of type xtd::byte that is the storage location for the received data.
offset	The zero-based position in the buffer parameter at which to store the data.
size	The number of bytes to receive.
socket_flags	A bitwise combination of the xtd::net::sockets::socket_flags values.
remote_end_point	An xtd::net::end_point that represents the source of the data.
callback	The xtd::async_callback delegate.
state	An object that contains state information for this request.

Returns

An xtd::iasync_result that references the asynchronous connection.

Exceptions

xtd::argument_out_of_range_exception	size is less than 0 or exceeds the size of the buffer.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.
xtd::invalid_operation_exception	The accepting socket is not listening for connections. You must call xtd::net::sockets::socket::bind and xtd::net::sockets::socket::listen before calling xtd::net::sockets::socket::accept().

Remarks

The xtd::net::sockets::socket::begin_receive_from method starts asynchronously reading connectionless datagrams from a remote host. Calling the xtd::net::sockets::socket::begin_receive_from method gives you the ability to receive data within a separate execution thread.

You can create a callback method that implements the xtd::async_callback delegate and pass its name to the xtd::net::sockets::socket::begin_receive_from method. To do this, at the very minimum, your state parameter must contain the connected or default xtd::net::sockets::socket::socket being used for communication. If your callback needs more information, you can create a small class to hold the xtd::net::sockets::socket::socket and the other required information. Pass an instance of this class to the xtd::net::sockets::socket::begin_receive_from method through the state parameter.

Your callback method should invoke the xtd::net::sockets::socket::end_receive_from method. When your application calls xtd::net::sockets::socket::begin_receive_from, the system will use a separate thread to execute the specified callback method, and it will block on xtd::net::sockets::socket::end_receive_from until the xtd::net::sockets::socket::socket reads data or throws an exception. If you want the original thread to block after you call the xtd::net::sockets::socket::begin_receive_from method, use xtd::threading::mutex::wait_one. Call the xtd::threading::mutex::release_mutex method on a xtd::threading::mutex in the callback method when you want the original thread to continue executing.

Note

Before calling xtd::net::sockets::socket::begin_receive_from, you must explicitly bind the xtd::net::sockets::socket::socket to a local endpoint using the xtd::net::sockets::socket::bind method, or xtd::net::sockets::socket::begin_receive_from will throw a xtd::net::sockets::socket_exception.

Remarks

This method reads data into the buffer parameter, and captures the remote host endpoint from which the data is sent. For information on how to retrieve this endpoint, refer to xtd::net::sockets::socket::end_receive_from. This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. In these cases, xtd::net::sockets::socket::begin_receive_from will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of buffer, the xtd::net::sockets::socket::begin_receive_from method will fill buffer with as much of the message as is possible, and throw a xtd::net::sockets::socket_exception. If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the xtd::net::sockets::socket::begin_receive_from method with a large enough buffer.

To guarantee that the remote host endpoint is always returned, an application should explicitly bind the xtd::net::sockets::socket::socket to a local endpoint using the xtd::net::sockets::socket::bind method and then call the xtd::net::sockets::socket::set_socket_option method with the optionLevel parameter set to IP or IPv6 as appropriate, the option_name parameter set to xtd::net::sockets::socket_option_name::packet_information, and the optionValue parameter to enable this option before calling the xtd::net::sockets::socket::begin_receive_from method. Otherwise, it is possible for the remote host endpoint to not be returned when the sender has sent a number of datagrams before the receiver has called the xtd::net::sockets::socket::begin_receive_from method.

Although xtd::net::sockets::socket::begin_receive_from is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the xtd::net::sockets::socket::connect / xtd::net::sockets::socket::begin_connect method or accept an incoming connection request by calling the xtd::net::sockets::socket::accept or xtd::net::sockets::socket::begin_accept method. If you call the xtd::net::sockets::socket::begin_receive_from method before establishing or accepting a connection, you will get a xtd::net::sockets::socket_exception. You can also establish a default remote host for a connectionless protocol prior to calling the xtd::net::sockets::socket::begin_receive_from method. In either of these cases, the xtd::net::sockets::socket::begin_receive_from method will ignore the remote_end_point parameter and only receive data from the connected or default remote host.

With connection-oriented sockets, xtd::net::sockets::socket::begin_receive_from will read as much data as is available up to the number of bytes specified by the size parameter.

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

Note

If you receive a xtd::net::sockets::socket_exception 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.