connect() [1/4]

template<typename end_point_t >

void xtd::net::sockets::socket::connect ( const end_point_t &  remote_end_point )

inline

Establishes a connection to a remote host.

Parameters

remote_end_point

An xtd::net::end_point that represents the remote device.

Exceptions

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

If you are using a connection-oriented protocol such as TCP, the xtd::net::sockets::socket::connect method synchronously establishes a network connection between xtd::net::sockets::socket::local_end_point and the specified remote endpoint. If you are using a connectionless protocol, xtd::net::sockets::socket::connect establishes a default remote host. After you call xtd::net::sockets::socket::connect, you can send data to the remote device with the xtd::net::sockets::socket::send method, or receive data from the remote device with the xtd::net::sockets::socket::receive method.

If you are using a connectionless protocol such as UDP, you do not have to call xtd::net::sockets::socket::connect before sending and receiving data. You can use xtd::net::sockets::socket::send_to and xtd::net::sockets::socket::receive_from to synchronously communicate with a remote host. If you do call xtd::net::sockets::socket::connect, any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the xtd::net::sockets::socket::set_socket_option method and set the socket option to xtd::net::sockets::socket::socket_option_name::broadcast, or xtd::net::sockets::socket::connect will throw a xtd::net::sockets::socket_exception. 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 for a detailed description of the error.

The xtd::net::sockets::socket::connect method will block, unless you specifically set the xtd::net::sockets::socket::blocking property to false prior to calling xtd::net::sockets::socket::connect. If you are using a connection-oriented protocol like TCP and you do disable blocking, xtd::net::sockets::socket::connect will throw a xtd::net::sockets::socket_exception because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use xtd::net::sockets::socket_exception::error_code to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented xtd::net::sockets::socket, but has not yet completed successfully. Use the Poll method to determine when the xtd::net::sockets::socket is finished connecting.

Note

If you are using a connection-oriented protocol and did not call xtd::net::sockets::socket::bind before calling xtd::net::sockets::socket::connect, the underlying service provider will assign the 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 complete a send or receive operation. If you want to change the default remote host, call xtd::net::sockets::socket::connect again with the desired endpoint.

If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous xtd::net::sockets::socket::begin_connect methods to reconnect. This is a limitation of the underlying provider.

Examples

socket_tcp_ip_v4.cpp, and socket_tcp_ip_v6.cpp.