xtd::net::sockets::tcp_client Class Reference

#include <tcp_client.h>

Definition

Provides client connections for TCP network services.

Namespace

xtd::net::sockets

Library

xtd.core

Remarks

The xtd::net::sockets::tcp_client class provides simple methods for connecting, sending, and receiving stream data over a network in synchronous blocking mode.

In order for xtd::net::sockets::tcp_client to connect and exchange data, a TcpListener or xtd::net::sockets::socket created with the TCP ProtocolType must be listening for incoming connection requests. You can connect to this listener in one of the following two ways:

• Create a xtd::net::sockets::tcp_client and call one of the three available xtd::net::sockets::tcp_client::connect methods.
• Create a xtd::net::sockets::tcp_client using the host name and port number of the remote host. This constructor will automatically attempt a connection.

Note

If you want to send connectionless datagrams in synchronous blocking mode, use the xtd::net::sockets::udp_client class.

Examples

The following example shows how to use IPv4 xtd::net::sockets::tcp_client class with xtd::net::sockets::network_stream, xtd::net::sockets::socket, xtd::io::stream_reader and xtd::io::stream_writer classes.

#include <xtd/xtd>
 
using namespace std;
using namespace std::literals;
using namespace xtd;
using namespace xtd::io;
using namespace xtd::net;
using namespace xtd::net::sockets;
 
int main() {
  auto terminate_app = false;
  
  thread server([&] {
    auto listener = tcp_listener::create(9400);
    listener.start();
    auto stream = listener.accept_tcp_client().get_stream();
    stream_reader reader(stream);
    
    while (!terminate_app)
      if (stream.data_available()) console::write_line(reader.read_line());
  });
  
  thread client([&] {
    tcp_client client;
    client.connect(ip_address::loopback, 9400);
    auto stream = client.get_stream();
    stream_writer writer(stream);
    
    auto counter = 1;
    while (!terminate_app) {
      writer.write_line(ustring::format("counter={}", counter++));
      this_thread::sleep_for(50ms);
    }
  });
  
  console::read_key();
  terminate_app = true;
  server.join();
  client.join();
}
 
// This code produces the following output:
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...

Examples

The following example shows how to use IPv6 xtd::net::sockets::tcp_client class with xtd::net::sockets::network_stream, xtd::net::sockets::socket, xtd::io::stream_reader and xtd::io::stream_writer classes.

#include <xtd/xtd>
 
using namespace std;
using namespace std::literals;
using namespace xtd;
using namespace xtd::io;
using namespace xtd::net;
using namespace xtd::net::sockets;
 
int main() {
  auto terminate_app = false;
  
  thread server([&] {
    tcp_listener listener(ip_end_point(ip_address::ip_v6_any, 9400));
    listener.start();
    auto stream = listener.accept_tcp_client().get_stream();
    stream_reader reader(stream);
    
    while (!terminate_app)
      if (stream.data_available()) console::write_line(reader.read_line());
  });
  
  thread client([&] {
    tcp_client client(address_family::inter_network_v6);
    client.connect(ip_address::ip_v6_loopback, 9400);
    auto stream = client.get_stream();
    stream_writer writer(stream);
    
    auto counter = 1;
    while (!terminate_app) {
      writer.write_line(ustring::format("counter={}", counter++));
      this_thread::sleep_for(50ms);
    }
  });
  
  console::read_key();
  terminate_app = true;
  server.join();
  client.join();
}
 
// This code produces the following output:
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...

Inherits xtd::object.

Public Member Functions
	tcp_client ()
	Initializes a new instance of the xtd::net::sockets::tcp_client class. More...
	tcp_client (const xtd::net::ip_end_point &end_point)
	Initializes a new instance of the xtd::net::sockets::tcp_client class and binds it to the specified local endpoint. More...
	tcp_client (const xtd::ustring &hostname, uint16_t port)
	Initializes a new instance of the xtd::net::sockets::tcp_client class and connects to the specified port on the specified host. More...
	tcp_client (xtd::net::sockets::address_family address_family)
	The xtd::net::sockets::address_family of the IP protocol. More...
size_t	available () const
	Gets the amount of data that has been received from the network and is available to be read. More...
std::shared_ptr< xtd::iasync_result >	begin_connect (const std::vector< xtd::net::ip_address > &addresses, uint16_t port, xtd::async_callback callback, const std::any &state)
	Begins an asynchronous request for a remote host connection. The remote host is specified by an xtd::net::ip_address array and a port number (uint16_t). More...
std::shared_ptr< xtd::iasync_result >	begin_connect (const xtd::net::ip_address &address, uint16_t port, xtd::async_callback callback, const std::any &state)
	Begins an asynchronous request for a remote host connection. The remote host is specified by an xtd::net::ip_address and a port number (uint16_t). More...
std::shared_ptr< xtd::iasync_result >	begin_connect (const xtd::ustring &host, uint16_t port, xtd::async_callback callback, const std::any &state)
	Begins an asynchronous request for a remote host connection. The remote host is specified by a host name (xtd::ustring) and a port number (uint16_t). More...
xtd::net::sockets::socket	client () const noexcept
	Gets the underlying network xtd::net::sockets::socket. More...
tcp_client &	client (const xtd::net::sockets::socket &value) noexcept
	Sets the underlying network xtd::net::sockets::socket. More...
void	close ()
	Disposes this xtd::net::sockets::tcp_client instance and requests that the underlying TCP connection be closed. More...
void	connect (const xtd::net::ip_address &ip_address, uint16_t port)
	Connects the client to a remote TCP host using the specified IP address and port number. More...
void	connect (const xtd::net::ip_end_point &remote_end_point)
	Connects the client to a remote TCP host using the specified remote network endpoint. More...
void	connect (const xtd::ustring &hostname, uint16_t port)
	Connects the client to the specified port on the specified host. More...
bool	connected () const noexcept
	Gets a value indicating whether the underlying xtd::net::sockets::socket for a xtd::net::sockets::tcp_client is connected to a remote host. More...
void	end_connect (std::shared_ptr< xtd::iasync_result > async_result)
	Ends a pending asynchronous connection attempt. More...
bool	exclusive_address_use () const
	Gets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port. More...
tcp_client &	exclusive_address_use (bool value)
	Sets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port. More...
xtd::net::sockets::network_stream	get_stream () const
	Returns the xtd::net::sockets::network_stream used to send and receive data. More...
xtd::net::sockets::linger_option	linger_state () const
	Gets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data. More...
tcp_client &	linger_state (const xtd::net::sockets::linger_option &value)
	Sets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data. More...
bool	no_delay () const
	Gets a value that disables a delay when send or receive buffers are not full. More...
tcp_client &	no_delay (bool value)
	Sets a value that disables a delay when send or receive buffers are not full. More...
size_t	receive_buffer_size () const
	Gets the size of the receive buffer. More...
tcp_client &	receive_buffer_size (size_t value)
	Sets the size of the receive buffer. More...
int32_t	receive_timeout () const
	Gets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated. More...
tcp_client &	receive_timeout (int32_t value)
	Sets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated. More...
size_t	send_buffer_size () const
	Gets the size of the send buffer. More...
tcp_client &	send_buffer_size (size_t value)
	Sets the size of the send buffer. More...
int32_t	send_timeout () const
	Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully. More...
tcp_client &	send_timeout (int32_t value)
	Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully. More...
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const
	Gets the type of the current instance. More...
virtual xtd::ustring	to_string () const noexcept
	Returns a std::string that represents the current object. More...

Protected Member Functions
bool	active () const noexcept
	Gets a value that indicates whether a connection has been made. More...
tcp_client &	active (bool value) noexcept
	Sets a value that indicates whether a connection has been made. More...

Additional Inherited Members
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Constructor & Destructor Documentation

tcp_client() [1/4]

xtd::net::sockets::tcp_client::tcp_client

(

)

Initializes a new instance of the xtd::net::sockets::tcp_client class.

Remarks

This constructor creates a new xtd::net::sockets::tcp_client and allows the underlying service provider to assign the most appropriate local IP address and port number. You must first call the xtd::net::sockets::tcp_client::connect method before sending and receiving data.

Note

This constructor works only with IPv4 address types.

tcp_client() [2/4]

xtd::net::sockets::tcp_client::tcp_client

(

const xtd::net::ip_end_point &

end_point

)

Initializes a new instance of the xtd::net::sockets::tcp_client class and binds it to the specified local endpoint.

Parameters

local_end_point

The xtd::net::ip_end_point to which you bind the TCP xtd::net::sockets::socket.

Remarks

This constructor creates a new xtd::net::sockets::tcp_client and binds it to the xtd::net::ip_end_point specified by the local_end_point parameter. Before you call this constructor, you must create an xtd::net::ip_end_point using the IP address and port number from which you intend to send and receive data. You do not need to specify a local IP address and port number before connecting and communicating. If you create a xtd::net::sockets::tcp_client using any other constructor, the underlying service provider will assign the most appropriate local IP address and port number.

You must call the xtd::net::sockets::tcp_client::connect method before sending and receiving data.

tcp_client() [3/4]

xtd::net::sockets::tcp_client::tcp_client

(

xtd::net::sockets::address_family

address_family

)

The xtd::net::sockets::address_family of the IP protocol.

Exceptions

xtd::argument_exception

The family parameter is not equal to xtd::net::sockets::address_family::inter_network -or- The family parameter is not equal to xtd::net::sockets::address_family::inter_network_v6.

tcp_client() [4/4]

xtd::net::sockets::tcp_client::tcp_client	(	const xtd::ustring &	hostname,
		uint16_t	port
	)

Initializes a new instance of the xtd::net::sockets::tcp_client class and connects to the specified port on the specified host.

Parameters

hostname	The DNS name of the remote host to which you intend to connect.
port	The port number of the remote host to which you intend to connect.

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

This constructor creates a new xtd::net::sockets::tcp_client and makes a synchronous connection attempt to the provided host name and port number. The underlying service provider will assign the most appropriate local IP address and port number. xtd::net::sockets::tcp_client will block until it either connects or fails. This constructor allows you to initialize, resolve the DNS host name, and connect in one convenient step.

If IPv6 is enabled and the xtd::net::sockets::tcp_client method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address.

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.

Member Function Documentation

active() [1/2]

bool xtd::net::sockets::tcp_client::active ( ) const

protectednoexcept

Gets a value that indicates whether a connection has been made.

Returns

true if the connection has been made; otherwise, false.

Remarks

Classes deriving from xtd::net::sockets::tcp_client can use this property to determine if a connection attempt has succeeded. It does not monitor the ongoing connection state of xtd::net::sockets::tcp_client. If the remote host closes the connection, xtd::net::sockets::tcp_client::active will not be updated. If you are deriving from xtd::net::sockets::tcp_client and require closer attention to the connection state, use the xtd::net::sockets::tcp_client::client::connected property of the xtd::net::sockets::socket returned by the xtd::net::sockets::tcp_client::client property.

active() [2/2]

tcp_client& xtd::net::sockets::tcp_client::active ( bool  value )

protectednoexcept

Sets a value that indicates whether a connection has been made.

Parameters

value

true if the connection has been made; otherwise, false.

Returns

This current instance.

Remarks

Classes deriving from xtd::net::sockets::tcp_client can use this property to determine if a connection attempt has succeeded. It does not monitor the ongoing connection state of xtd::net::sockets::tcp_client. If the remote host closes the connection, xtd::net::sockets::tcp_client::active will not be updated. If you are deriving from xtd::net::sockets::tcp_client and require closer attention to the connection state, use the xtd::net::sockets::tcp_client::client::connected property of the xtd::net::sockets::socket returned by the xtd::net::sockets::tcp_client::client property.

available()

size_t xtd::net::sockets::tcp_client::available

(

)

const

Gets the amount of data that has been received from the network and is available to be read.

Returns

The number of bytes of data received from the network and available to be read.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

available is a way to determine whether data is queued for reading. If data is available, call xtd::iostream::read to get the data.

The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, available returns 0.

If the remote host shuts down or closes the connection, available may throw a xtd::net::sockets::socket_exception. If you receive a xtd::net::sockets::socket_exception, use xtd::net::sockets::socket_exception.ErrorCode to obtain the specific error code.

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.

begin_connect() [1/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::tcp_client::begin_connect	(	const std::vector< xtd::net::ip_address > &	addresses,
		uint16_t	port,
		xtd::async_callback	callback,
		const std::any &	state
	)

Begins an asynchronous request for a remote host connection. The remote host is specified by an xtd::net::ip_address array and a port number (uint16_t).

Parameters

addresses	At least one xtd::net::ip_address that designates the remote hosts.
port	The port number of the remote host.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the connect operation. This object is passed to the requestCallback delegate when the operation is complete.

Returns

An xtd::iasync_result object that references the asynchronous connection.

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

The asynchronous xtd::net::sockets::tcp_client::client::begin_connect operation must be completed by calling the xtd::net::sockets::tcp_client::end_connect method. Typically, the method is invoked by the asyncCallback delegate.

This method does not block until the operation completes. To block until the operation completes, use one of the xtd::net::sockets::tcp_client::connect method overloads.

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.

begin_connect() [2/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::tcp_client::begin_connect	(	const xtd::net::ip_address &	address,
		uint16_t	port,
		xtd::async_callback	callback,
		const std::any &	state
	)

Begins an asynchronous request for a remote host connection. The remote host is specified by an xtd::net::ip_address and a port number (uint16_t).

Parameters

address	The xtd::net::ip_address of the remote host.
port	The port number of the remote host.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the connect operation. This object is passed to the callback delegate when the operation is complete.

Returns

An xtd::iasync_result object that references the asynchronous connection.

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

The asynchronous xtd::net::sockets::tcp_client::client::begin_connect operation must be completed by calling the xtd::net::sockets::tcp_client::end_connect method. Typically, the method is invoked by the callback delegate.

This method does not block until the operation completes. To block until the operation completes, use one of the xtd::net::sockets::tcp_client::connect method overloads.

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.

begin_connect() [3/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::tcp_client::begin_connect	(	const xtd::ustring &	host,
		uint16_t	port,
		xtd::async_callback	callback,
		const std::any &	state
	)

Begins an asynchronous request for a remote host connection. The remote host is specified by a host name (xtd::ustring) and a port number (uint16_t).

Parameters

host	The name of the remote host.
port	The port number of the remote host.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the connect operation. This object is passed to the requestCallback delegate when the operation is complete.

Returns

An xtd::iasync_result object that references the asynchronous connection.

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

The asynchronous xtd::net::sockets::tcp_client::client::begin_connect operation must be completed by calling the xtd::net::sockets::tcp_client::end_connect method. Typically, the method is invoked by the asyncCallback delegate.

This method does not block until the operation completes. To block until the operation completes, use one of the xtd::net::sockets::tcp_client::connect method overloads.

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.

client() [1/2]

xtd::net::sockets::socket xtd::net::sockets::tcp_client::client ( ) const

noexcept

Gets the underlying network xtd::net::sockets::socket.

Returns

The underlying network xtd::net::sockets::socket

Remarks

xtd::net::sockets::tcp_client creates a xtd::net::sockets::socket to send and receive data over a network. Classes deriving from xtd::net::sockets::tcp_client can use this property to get or set this xtd::net::sockets::socket.

Use the underlying xtd::net::sockets::socket returned from xtd::net::sockets::tcp_client::client if you require access beyond that which xtd::net::sockets::tcp_client provides.

You can also use xtd::net::sockets::tcp_client::client to set the underlying xtd::net::sockets::socket to an existing xtd::net::sockets::socket. This might be useful if you want to take advantage of the simplicity

of xtd::net::sockets::tcp_client using a pre-existing xtd::net::sockets::socket.

client() [2/2]

tcp_client& xtd::net::sockets::tcp_client::client ( const xtd::net::sockets::socket &  value )

noexcept

Sets the underlying network xtd::net::sockets::socket.

Parameters

value

The underlying network xtd::net::sockets::socket

Returns

This current instance.

Remarks

xtd::net::sockets::tcp_client creates a xtd::net::sockets::socket to send and receive data over a network. Classes deriving from xtd::net::sockets::tcp_client can use this property to get or set this xtd::net::sockets::socket.

Use the underlying xtd::net::sockets::socket returned from xtd::net::sockets::tcp_client::client if you require access beyond that which xtd::net::sockets::tcp_client provides.

You can also use xtd::net::sockets::tcp_client::client to set the underlying xtd::net::sockets::socket to an existing xtd::net::sockets::socket. This might be useful if you want to take advantage of the simplicity

of xtd::net::sockets::tcp_client using a pre-existing xtd::net::sockets::socket.

close()

void xtd::net::sockets::tcp_client::close

(

)

Disposes this xtd::net::sockets::tcp_client instance and requests that the underlying TCP connection be closed.

Remarks

The xtd::net::sockets::tcp_client::close method marks the instance as disposed and requests that the associated xtd::net::sockets::socket close the TCP connection. Based on the xtd::net::sockets::tcp_client::linger_state property,

the TCP connection may stay open for some time after the xtd::net::sockets::tcp_client::close method is called when data remains to be sent. There is no notification provided when

the underlying connection has completed closing.

Calling this method will eventually result in the close of the associated xtd::net::sockets::socket and will also close the associated xtd::net::sockets::network_stream that is used to send and receive data if one was created.

connect() [1/3]

void xtd::net::sockets::tcp_client::connect	(	const xtd::net::ip_address &	ip_address,
		uint16_t	port
	)

Connects the client to a remote TCP host using the specified IP address and port number.

Parameters

ip_address	The xtd::net::ip_address of the remote host to which you intend to send data
port	The port number to which you intend send data

Exceptions

xtd::net::sockets::socket_exception	An error occurred when accessing the socket.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

Call this method to establish a synchronous remote host connection to the specified xtd::net::ip_address and port number.

The xtd::net::sockets::tcp_client::connect method will block until it either connects or fails.

After connecting with the remote host, use the xtd::net::sockets::tcp_client::get_stream method to obtain the underlying xtd::net::sockets::network_stream.

Use this xtd::net::sockets::network_stream to send and receive data.

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.

connect() [2/3]

void xtd::net::sockets::tcp_client::connect

(

const xtd::net::ip_end_point &

remote_end_point

)

Connects the client to a remote TCP host using the specified remote network endpoint.

Parameters

remote_end_point

The xtd::net::ip_end_point to which you intend to connect.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when accessing the socket.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

Call this method to establish a synchronous remote host connection to the specified xtd::net::ip_end_point. Before you call xtd::net::sockets::tcp_client::connect you must create an instance of the xtd::net::ip_end_point class using an IP address and a port number. Use this xtd::net::ip_end_point as the remote_end_point parameter. The xtd::net::sockets::tcp_client::connect method will block until it either connects or fails. After connecting with the remote host, use the xtd::net::sockets::tcp_client::get_stream method to obtain the underlying xtd::net::sockets::network_stream. Use this xtd::net::sockets::network_stream to send and receive data.

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.

connect() [3/3]

void xtd::net::sockets::tcp_client::connect	(	const xtd::ustring &	hostname,
		uint16_t	port
	)

Connects the client to the specified port on the specified host.

Parameters

hostname	The DNS name of the remote host to which you intend to connect.
port	The port number of the remote host to which you intend to connect.

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

This constructor creates a new xtd::net::sockets::tcp_client and makes a synchronous connection attempt to the provided host name and port number. The underlying service provider will assign the most appropriate local IP address and port number. xtd::net::sockets::tcp_client will block until it either connects or fails. This constructor allows you to initialize, resolve the DNS host name, and connect in one convenient step.

If IPv6 is enabled and the xtd::net::sockets::tcp_client(xtd::ustring, uint16_t) method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address.

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.

connected()

bool xtd::net::sockets::tcp_client::connected ( ) const

noexcept

Gets a value indicating whether the underlying xtd::net::sockets::socket for a xtd::net::sockets::tcp_client is connected to a remote host.

Returns

bool true if the xtd::net::sockets::tcp_client::client was connected to a remote resource as of the most recent operation; otherwise, false.

Remarks

The xtd::net::sockets::tcp_client::client::connected property gets the connection state of the xtd::net::sockets::tcp_client::client socket as of the last I/O operation. When it returns false,

the xtd::net::sockets::tcp_client::client socket was either never connected, or is no longer connected.Because the xtd::net::sockets::tcp_client::client::connected property only reflects the state

of the connection as of the most recent operation, you should attempt to send or receive a message to determine the current state.

After the message send fails, this property no longer returns true. Note that this behavior is by design.

You cannot reliably test the state of the connection because, in the time between the test and a send/receive,

the connection could have been lost. Your code should assume the socket is connected, and gracefully handle failed transmissions.

end_connect()

void xtd::net::sockets::tcp_client::end_connect

(

std::shared_ptr< xtd::iasync_result >

async_result

)

Ends a pending asynchronous connection attempt.

Parameters

result

An xtd::iasync_result object returned by a call to xtd::net::sockets::tcp_client::client::begin_connect.

Exceptions

argument_exception	async_result was not returned by a call to the xtd::net::sockets::socket::begin_connect 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

This method blocks until the operation is complete. To perform this operation synchronously, use a xtd::net::sockets::tcp_client::connect 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.

exclusive_address_use() [1/2]

bool xtd::net::sockets::tcp_client::exclusive_address_use

(

)

const

Gets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port.

Returns

bool true if the xtd::net::sockets::tcp_client allows only one client to use a specific port; otherwise, false.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port.

You can use the xtd::net::sockets::tcp_client::client::exclusive_address_use property to prevent multiple clients from using a specific port.

This property must be set before the underlying socket is bound to a client port. If you call xtd::net::sockets::tcp_client::connect, xtd::net::sockets::tcp_client::client::begin_connect, xtd::net::sockets::tcp_client(xtd::net::ip_end_point), or xtd::net::sockets::tcp_client(xtd::ustring, uint16_t), the client port is bound as a side effect of the method, and you cannot subsequently set the xtd::net::sockets::tcp_client::client::exclusive_address_use property.

exclusive_address_use() [2/2]

tcp_client& xtd::net::sockets::tcp_client::exclusive_address_use

(

bool

value

)

Sets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port.

Parameters

value

bool true if the xtd::net::sockets::tcp_client allows only one client to use a specific port; otherwise, false.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port.

You can use the xtd::net::sockets::tcp_client::client::exclusive_address_use property to prevent multiple clients from using a specific port.

This property must be set before the underlying socket is bound to a client port. If you call xtd::net::sockets::tcp_client::connect, xtd::net::sockets::tcp_client::client::begin_connect, xtd::net::sockets::tcp_client(xtd::net::ip_end_point), or xtd::net::sockets::tcp_client(xtd::ustring, uint16_t), the client port is bound as a side effect of the method, and you cannot subsequently set the xtd::net::sockets::tcp_client::client::exclusive_address_use property.

get_stream()

xtd::net::sockets::network_stream xtd::net::sockets::tcp_client::get_stream

(

)

const

Returns the xtd::net::sockets::network_stream used to send and receive data.

Returns

The underlying xtd::net::sockets::network_stream.

Remarks

xtd::net::sockets::tcp_client::get_stream returns a xtd::net::sockets::network_stream that you can use to send and receive data. The xtd::net::sockets::network_stream class inherits from the std::iostream class, which provides a rich collection of methods and properties used to facilitate network communications.You must call the xtd::net::sockets::tcp_client::connect method first, or the xtd::net::sockets::tcp_client::get_stream method will throw an xtd::invalid_operation_exception. After you have obtained the xtd::net::sockets::network_stream, call the std::iostream::write method to send data to the remote host. Call the std::iostream::read method to receive data arriving from the remote host. Both of these methods block until the specified operation is performed. You can avoid blocking on a read operation by checking the xtd::net::sockets::network_stream::data_available property. A true value means that data has arrived from the remote host and is available for reading. In this case, std::iostream::read is guaranteed to complete immediately. If the remote host has shutdown its connection, std::iostream::read will immediately return with zero bytes.

Note

You must close the xtd::net::sockets::network_stream when you are through sending and receiving data. Closing xtd::net::sockets::tcp_client does not release the xtd::net::sockets::network_stream.

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.

linger_state() [1/2]

xtd::net::sockets::linger_option xtd::net::sockets::tcp_client::linger_state

(

)

const

Gets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data.

Returns

A xtd::net::sockets::linger_option that specifies how to linger while closing a socket.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::tcp_client::linger_state property changes the way xtd::net::sockets::tcp_client::close method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior.

This property controls the length of time that the TCP connection will remain open after a call to xtd::net::sockets::tcp_client::close when data remains to be sent. When you call the Write method, data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the xtd::net::sockets::tcp_client::close method drops the connection.

To enable lingering, create a xtd::net::sockets::linger_option instance containing the desired values, and set the xtd::net::sockets::tcp_client::linger_state property to this instance.

The following table describes the behavior of the xtd::net::sockets::tcp_client::close method for the possible values of the xtd::net::sockets::linger_option::enabled property and the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::tcp_client::linger_state property.

xtd::net::sockets::linger_option::enabled	xtd::net::sockets::linger_option::linger_time	Behavior
false (disabled), the default value	The time-out is not applicable, (default).	Attempts to send pending data until the default IP protocol time-out expires.
true (enabled)	A nonzero time-out	Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.
true (enabled)	A zero timeout.	Discards any pending data and Winsock resets the connection.

The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application.

This is the default behavior for a socket when the xtd::net::sockets::tcp_client::linger_state property is not set.

When the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::tcp_client::linger_state property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and virtual.

linger_state() [2/2]

tcp_client& xtd::net::sockets::tcp_client::linger_state

(

const xtd::net::sockets::linger_option &

value

)

Sets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data.

Parameters

value

A xtd::net::sockets::linger_option that specifies how to linger while closing a socket.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::tcp_client::linger_state property changes the way xtd::net::sockets::tcp_client::close method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior.

This property controls the length of time that the TCP connection will remain open after a call to xtd::net::sockets::tcp_client::close when data remains to be sent. When you call the Write method, data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the xtd::net::sockets::tcp_client::close method drops the connection.

To enable lingering, create a xtd::net::sockets::linger_option instance containing the desired values, and set the xtd::net::sockets::tcp_client::linger_state property to this instance.

The following table describes the behavior of the xtd::net::sockets::tcp_client::close method for the possible values of the xtd::net::sockets::linger_option::enabled property and the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::tcp_client::linger_state property.

xtd::net::sockets::linger_option::enabled	xtd::net::sockets::linger_option::linger_time	Behavior
false (disabled), the default value	The time-out is not applicable, (default).	Attempts to send pending data until the default IP protocol time-out expires.
true (enabled)	A nonzero time-out	Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.
true (enabled)	A zero timeout.	Discards any pending data and Winsock resets the connection.

The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application.

This is the default behavior for a socket when the xtd::net::sockets::tcp_client::linger_state property is not set.

When the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::tcp_client::linger_state property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and virtual.

no_delay() [1/2]

bool xtd::net::sockets::tcp_client::no_delay

(

)

const

Gets a value that disables a delay when send or receive buffers are not full.

Returns

true if the delay is disabled; otherwise, false. The default value is false.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

When xtd::net::sockets::tcp_client::no_delay is false, a xtd::net::sockets::tcp_client does not send a packet over the network until it has collected a significant amount of outgoing data.

no_delay() [2/2]

tcp_client& xtd::net::sockets::tcp_client::no_delay

(

bool

value

)

Sets a value that disables a delay when send or receive buffers are not full.

Parameters

value

true if the delay is disabled; otherwise, false. The default value is false.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

When xtd::net::sockets::tcp_client::no_delay is false, a xtd::net::sockets::tcp_client does not send a packet over the network until it has collected a significant amount of outgoing data.

receive_buffer_size() [1/2]

size_t xtd::net::sockets::tcp_client::receive_buffer_size

(

)

const

Gets the size of the receive buffer.

Returns

A size_t that contains the size, in bytes, of the receive buffer. The default is 8192.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::tcp_client::receive_buffer_size property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation. This property actually manipulates the network buffer space allocated for receiving incoming data.

Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the std::iostream::read method. Use the xtd::net::sockets::tcp_client::receive_buffer_size property to set this size. If your application will be receiving bulk data, you should pass the Read method a very large application buffer.

If the network buffer is smaller than the amount of data you request in the std::iostream::read method, you will not be able to retrieve the desired amount of data in one read operation. This incurs the overhead of additional calls to the std::iostream::read method.

receive_buffer_size() [2/2]

tcp_client& xtd::net::sockets::tcp_client::receive_buffer_size

(

size_t

value

)

Sets the size of the receive buffer.

Parameters

value

A size_t that contains the size, in bytes, of the receive buffer. The default is 8192.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::tcp_client::receive_buffer_size property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation. This property actually manipulates the network buffer space allocated for receiving incoming data.

Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the std::iostream::read method. Use the xtd::net::sockets::tcp_client::receive_buffer_size property to set this size. If your application will be receiving bulk data, you should pass the Read method a very large application buffer.

If the network buffer is smaller than the amount of data you request in the std::iostream::read method, you will not be able to retrieve the desired amount of data in one read operation. This incurs the overhead of additional calls to the std::iostream::read method.

receive_timeout() [1/2]

int32_t xtd::net::sockets::tcp_client::receive_timeout

(

)

const

Gets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated.

Returns

The time-out value of the connection in milliseconds. The default value is 0.

Remarks

The xtd::net::sockets::tcp_client::receive_timeout property determines the amount of time that the Read method will block until it is able to receive data. This time is measured in milliseconds. If the time-out expires before Read successfully completes, xtd::net::sockets::tcp_client throws a xtd::io::io_exception. There is no time-out by default.

receive_timeout() [2/2]

tcp_client& xtd::net::sockets::tcp_client::receive_timeout

(

int32_t

value

)

Sets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated.

Parameters

value

The time-out value of the connection in milliseconds. The default value is 0.

Returns

This current instance.

Remarks

The xtd::net::sockets::tcp_client::receive_timeout property determines the amount of time that the Read method will block until it is able to receive data. This time is measured in milliseconds. If the time-out expires before Read successfully completes, xtd::net::sockets::tcp_client throws a xtd::io::io_exception. There is no time-out by default.

send_buffer_size() [1/2]

size_t xtd::net::sockets::tcp_client::send_buffer_size

(

)

const

Gets the size of the send buffer.

Returns

The size of the send buffer, in bytes. The default value is 8192 bytes.

Remarks

The xtd::net::sockets::tcp_client::send_buffer_size property gets or sets the number of bytes that you are expecting to send in each call to the std::iostream::write method. This property actually manipulates the network buffer space allocated for send operation.

Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the xtd::net::sockets::tcp_client::send_buffer_size property to set this size. If your application will be sending bulk data, you should pass the std::iostream::write method a very large application buffer.

If the network buffer is smaller than the amount of data you provide the std::iostream::write method, several network send operations will be performed for every call you make to the std::iostream::write method. You can achieve greater data throughput by ensuring that your network buffer is at least as large as your application buffer.

send_buffer_size() [2/2]

tcp_client& xtd::net::sockets::tcp_client::send_buffer_size

(

size_t

value

)

Sets the size of the send buffer.

Parameters

value

The size of the send buffer, in bytes. The default value is 8192 bytes.

Returns

This current instance.

Remarks

The xtd::net::sockets::tcp_client::send_buffer_size property gets or sets the number of bytes that you are expecting to send in each call to the std::iostream::write method. This property actually manipulates the network buffer space allocated for send operation.

Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the xtd::net::sockets::tcp_client::send_buffer_size property to set this size. If your application will be sending bulk data, you should pass the std::iostream::write method a very large application buffer.

If the network buffer is smaller than the amount of data you provide the std::iostream::write method, several network send operations will be performed for every call you make to the std::iostream::write method. You can achieve greater data throughput by ensuring that your network buffer is at least as large as your application buffer.

send_timeout() [1/2]

int32_t xtd::net::sockets::tcp_client::send_timeout

(

)

const

Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully.

Returns

The send time-out value, in milliseconds. The default value is 0.

Remarks

The xtd::net::sockets::tcp_client::send_timeout property determines the amount of time that the xtd::net::sockets::send method will block until it is able to return successfully. This time is measured in milliseconds..

After you call the Write method, the underlying xtd::net::sockets::socket returns the number of bytes actually sent to the host. The xtd::net::sockets::tcp_client::send_timeout property determines the amount of time a xtd::net::sockets::tcp_client will wait before receiving the number of bytes returned. If the time-out expires before the Send method successfully completes, xtd::net::sockets::tcp_client will throw a xtd::net::sockets::socket_exception. There is no time-out by default.

send_timeout() [2/2]

tcp_client& xtd::net::sockets::tcp_client::send_timeout

(

int32_t

value

)

Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully.

Parameters

value

The send time-out value, in milliseconds. The default value is 0.

Returns

This current instance.

Remarks

The xtd::net::sockets::tcp_client::send_timeout property determines the amount of time that the xtd::net::sockets::send method will block until it is able to return successfully. This time is measured in milliseconds..

After you call the Write method, the underlying xtd::net::sockets::socket returns the number of bytes actually sent to the host. The xtd::net::sockets::tcp_client::send_timeout property determines the amount of time a xtd::net::sockets::tcp_client will wait before receiving the number of bytes returned. If the time-out expires before the Send method successfully completes, xtd::net::sockets::tcp_client will throw a xtd::net::sockets::socket_exception. There is no time-out by default.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/net/sockets/tcp_client.h