begin_send() [1/2]

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

Sends data asynchronously to a connected xtd::net::sockets::socket::socket.

Parameters

buffer	An array of type xtd::byte that contains the data to send.
offset	The zero-based position in the buffer parameter at which to begin sending data.
size	The number of bytes to send.
socket_flags	A bitwise combination of the xtd::net::sockets::socket_flags values.
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_send method starts an asynchronous send operation to the remote host established in the xtd::net::sockets::socket::connect, xtd::net::sockets::socket::begin_connect, xtd::net::sockets::socket::accept, or xtd::net::sockets::socket::begin_accept method. xtd::net::sockets::socket::begin_send will throw an exception if you do not first call xtd::net::sockets::socket::accept, xtd::net::sockets::socket::begin_accept, xtd::net::sockets::socket::connect, or xtd::net::sockets::socket::begin_connect. Calling the xtd::net::sockets::socket::begin_send method gives you the ability to send 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_send 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 or structure 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_send method through the state parameter.

Your callback method should invoke the xtd::net::sockets::socket::end_send method. When your application calls xtd::net::sockets::socket::begin_send, the system will use a separate thread to execute the specified callback method, and will block on xtd::net::sockets::socket::end_send until the xtd::net::sockets::socket::socket sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the xtd::net::sockets::socket::begin_send method, use the xtd::threading::mutex::wait_one method. 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.

Although intended for connection-oriented protocols, xtd::net::sockets::socket::begin_send also works for connectionless protocols, provided that you first call the xtd::net::sockets::socket::connect or xtd::net::sockets::socket::begin_connect method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use xtd::net::sockets::socket::begin_send_to. It is okay to use xtd::net::sockets::socket::begin_send_to even after you have established a default remote host with xtd::net::sockets::socket::connect. You can also change the default remote host prior to calling xtd::net::sockets::socket::begin_send by making another call to xtd::net::sockets::socket::connect or xtd::net::sockets::socket::begin_connect. With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and xtd::net::sockets::socket::begin_send will throw a xtd::net::sockets::socket_exception.

If you specify the xtd::net::sockets::socket_flags::dont_route flag as the socketflags parameter, the data you are sending will not be routed.

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.

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.

state is an instantiation of a user-defined class.

The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode.