begin_connect() [1/4]

template<typename end_point_t >

xtd::sptr< xtd::iasync_result > xtd::net::sockets::socket::begin_connect ( const end_point_t &  remote_end_point, xtd::async_callback  callback, const std::any &  state  )

inline

Begins an asynchronous request for a remote host connection.

Parameters

remote_end_point	An xtd::net::end_point that represents the remote host.
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::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

If you are using a connection-oriented protocol, the xtd::net::sockets::socket::begin_connect method starts an asynchronous request for a connection to the remote_end_point parameter. If you are using a connectionless protocol, xtd::net::sockets::socket::begin_connect establishes a default remote host. Connecting or setting the default remote host asynchronously gives you the ability to send and 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_connect method. At the very minimum, you must pass the xtd::net::sockets::socket::socket to xtd::net::sockets::socket::begin_connect through the state parameter. 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_connect method through the state parameter.

Your callback method should invoke the xtd::net::sockets::socket::end_connect method. When your application calls xtd::net::sockets::socket::begin_connect, the system will use a separate thread to execute the specified callback method, and will block on xtd::net::sockets::socket::end_connect until the xtd::net::sockets::socket::socket connects successfully or throws an exception. If you want the original thread to block after you call the xtd::net::sockets::socket::begin_connect 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.

If you are using a connectionless protocol such as UDP, you do not have to call xtd::net::sockets::socket::begin_connect before sending and receiving data. You can use xtd::net::sockets::socket::begin_send_to and xtd::net::sockets::socket::begin_receive_from to communicate with a remote host. If you do call xtd::net::sockets::socket::begin_connect, any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call xtd::net::sockets::socket::set_socket_option and set xtd::net::sockets::socket::socket_option_name::broadcast to true. If you cannot, xtd::net::sockets::socket::begin_connect will throw a xtd::net::sockets::socket_exception.

If you are using a connection-oriented protocol and do not call xtd::net::sockets::socket::bind before calling xtd::net::sockets::socket::begin_connect, the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the xtd::net::sockets::socket::begin_send or xtd::net::sockets::socket::receive_from method. If you want to change the default remote host, call the xtd::net::sockets::socket::begin_connect method again with the desired endpoint.

To cancel a pending call to the xtd::net::sockets::socket::begin_connect method, close the xtd::net::sockets::socket::socket. When the xtd::net::sockets::socket::socket::close method is called while an asynchronous operation is in progress, the callback provided to the xtd::net::sockets::socket::begin_connect method is called. A subsequent call to the xtd::net::sockets::socket::end_connect method will throw an xtd::object_closed_exception to indicate that the operation has been cancelled.

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.

If this socket has previously been disconnected, then xtd::net::sockets::socket::begin_connect must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider.

Examples

socket_tcp_ip_v4_without_thread.cpp.