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

Inheritance diagram for xtd::net::sockets::tcp_client:

Definition

Provides client connections for TCP network services.

class core_export_ tcp_client : public xtd::object

Inheritance

xtd::object → xtd::net::sockets::tcp_client

Header

#include <xtd/net/sockets/tcp_client>

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>
 
auto main() -> int {
  auto terminate_app = false;
  
  auto server = thread {[&] {
    auto listener = net::sockets::tcp_listener::create(9400);
    listener.start();
    auto stream = listener.accept_tcp_client().get_stream();
    auto reader = stream_reader {stream};
    
    while (!terminate_app)
      if (stream.data_available()) console::write_line(reader.read_line());
  }};
  
  auto client = thread {[&] {
    auto client = net::sockets::tcp_client {};
    client.connect(net::ip_address::loopback, 9400);
    auto stream = client.get_stream();
    auto writer = stream_writer {stream};
    
    auto counter = 0;
    while (!terminate_app) {
      writer.write_line("counter={}", ++counter);
      thread::sleep(50_ms);
    }
  }};
 
  server.start();
  client.start();
 
  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>
 
auto main() -> int {
  auto terminate_app = false;
  
  auto server = thread {[&] {
    auto listener = net::sockets::tcp_listener {net::ip_end_point(net::ip_address::ip_v6_any, 9400)};
    listener.start();
    auto stream = listener.accept_tcp_client().get_stream();
    auto reader = stream_reader {stream};
    
    while (!terminate_app)
      if (stream.data_available()) console::write_line(reader.read_line());
  }};
  
  auto client = thread {[&] {
    auto client = net::sockets::tcp_client {net::sockets::address_family::inter_network_v6};
    client.connect(net::ip_address::ip_v6_loopback, 9400);
    auto stream = client.get_stream();
    auto writer = stream_writer {stream};
    
    auto counter = 0;
    while (!terminate_app) {
      writer.write_line("counter={}", ++counter);
      thread::sleep(50_ms);
    }
  }};
 
  server.start();
  client.start();
 
  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
// ...

Public Constructors
	tcp_client ()
	Initializes a new instance of the xtd::net::sockets::tcp_client class.
	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.
	tcp_client (xtd::net::sockets::address_family address_family)
	The xtd::net::sockets::address_family of the IP protocol.
	tcp_client (const xtd::string &hostname, uint16 port)
	Initializes a new instance of the xtd::net::sockets::tcp_client class and connects to the specified port on the specified host.

Public Properties
auto	available () const -> xtd::size
	Gets the amount of data that has been received from the network and is available to be read.
auto	client () const noexcept -> xtd::net::sockets::socket
	Gets the underlying network xtd::net::sockets::socket.
auto	client (const xtd::net::sockets::socket &value) noexcept -> tcp_client &
	Sets the underlying network xtd::net::sockets::socket.
auto	connected () const noexcept -> bool
	Gets a value indicating whether the underlying xtd::net::sockets::socket for a xtd::net::sockets::tcp_client is connected to a remote host.
auto	exclusive_address_use () const -> bool
	Gets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port.
auto	exclusive_address_use (bool value) -> tcp_client &
	Sets a bool value that specifies whether the xtd::net::sockets::tcp_client allows only one client to use a port.
auto	linger_state () const -> xtd::net::sockets::linger_option
	Gets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data.
auto	linger_state (const xtd::net::sockets::linger_option &value) -> tcp_client &
	Sets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data.
auto	no_delay () const -> bool
	Gets a value that disables a delay when send or receive buffers are not full.
auto	no_delay (bool value) -> tcp_client &
	Sets a value that disables a delay when send or receive buffers are not full.
auto	receive_buffer_size () const -> xtd::size
	Gets the size of the receive buffer.
auto	receive_buffer_size (xtd::size value) -> tcp_client &
	Sets the size of the receive buffer.
auto	receive_timeout () const -> xtd::int32
	Gets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated.
auto	receive_timeout (xtd::int32 value) -> tcp_client &
	Sets the amount of time a xtd::net::sockets::tcp_client will wait to receive data once a read operation is initiated.
auto	send_buffer_size () const -> xtd::size
	Gets the size of the send buffer.
auto	send_buffer_size (xtd::size value) -> tcp_client &
	Sets the size of the send buffer.
auto	send_timeout () const -> xtd::int32
	Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully.
auto	send_timeout (xtd::int32 value) -> tcp_client &
	Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully.

Public Methods
auto	begin_connect (const xtd::net::ip_address &address, uint16 port, xtd::async_callback callback, const xtd::any_object &state) -> xtd::sptr< xtd::iasync_result >
	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).
auto	begin_connect (const xtd::array< xtd::net::ip_address > &addresses, uint16 port, xtd::async_callback callback, const xtd::any_object &state) -> xtd::sptr< xtd::iasync_result >
	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).
auto	begin_connect (const xtd::string &host, uint16 port, xtd::async_callback callback, const xtd::any_object &state) -> xtd::sptr< xtd::iasync_result >
	Begins an asynchronous request for a remote host connection. The remote host is specified by a host name (xtd::string) and a port number (uint16).
auto	close () -> void
	Disposes this xtd::net::sockets::tcp_client instance and requests that the underlying TCP connection be closed.
auto	connect (const xtd::net::ip_end_point &remote_end_point) -> void
	Connects the client to a remote TCP host using the specified remote network endpoint.
auto	connect (const xtd::net::ip_address &ip_address, uint16 port) -> void
	Connects the client to a remote TCP host using the specified IP address and port number.
auto	connect (const xtd::string &hostname, uint16 port) -> void
	Connects the client to the specified port on the specified host.
auto	end_connect (xtd::sptr< xtd::iasync_result > async_result) -> void
	Ends a pending asynchronous connection attempt.
auto	equals (const object &obj) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	equals (const tcp_client &other) const noexcept -> bool override
	Determines whether the specified object is equal to the current object.
auto	get_stream () const -> xtd::net::sockets::network_stream
	Returns the xtd::net::sockets::network_stream used to send and receive data.

Protected Properties
auto	active () const noexcept -> bool
	Gets a value that indicates whether a connection has been made.
auto	active (bool value) noexcept -> tcp_client &
	Sets a value that indicates whether a connection has been made.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const
	Returns a xtd::string that represents the current object.
virtual bool	equals (const tcp_client &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

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 )

explicit

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 )

explicit

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::string &	hostname,
		uint16	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

available()

auto xtd::net::sockets::tcp_client::available ( ) const -> xtd::size

nodiscard

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.

client() [1/2]

auto xtd::net::sockets::tcp_client::client ( ) const -> xtd::net::sockets::socket

nodiscardnoexcept

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]

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

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.

connected()

auto xtd::net::sockets::tcp_client::connected ( ) const -> bool

nodiscardnoexcept

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.

exclusive_address_use() [1/2]

auto xtd::net::sockets::tcp_client::exclusive_address_use ( ) const -> bool

nodiscard

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::string, uint16), 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]

auto xtd::net::sockets::tcp_client::exclusive_address_use

(

bool

value

)

-> tcp_client &

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::string, uint16), 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.

linger_state() [1/2]

auto xtd::net::sockets::tcp_client::linger_state ( ) const -> xtd::net::sockets::linger_option

nodiscard

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]

auto xtd::net::sockets::tcp_client::linger_state

(

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

value

)

-> tcp_client &

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]

auto xtd::net::sockets::tcp_client::no_delay ( ) const -> bool

nodiscard

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]

auto xtd::net::sockets::tcp_client::no_delay

(

bool

value

)

-> tcp_client &

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]

auto xtd::net::sockets::tcp_client::receive_buffer_size ( ) const -> xtd::size

nodiscard

Gets the size of the receive buffer.

Returns

A xtd::size 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]

auto xtd::net::sockets::tcp_client::receive_buffer_size

(

xtd::size

value

)

-> tcp_client &

Sets the size of the receive buffer.

Parameters

value

A xtd::size 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]

auto xtd::net::sockets::tcp_client::receive_timeout ( ) const -> xtd::int32

nodiscard

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]

auto xtd::net::sockets::tcp_client::receive_timeout

(

xtd::int32

value

)

-> tcp_client &

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]

auto xtd::net::sockets::tcp_client::send_buffer_size ( ) const -> xtd::size

nodiscard

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]

auto xtd::net::sockets::tcp_client::send_buffer_size

(

xtd::size

value

)

-> tcp_client &

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]

auto xtd::net::sockets::tcp_client::send_timeout ( ) const -> xtd::int32

nodiscard

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]

auto xtd::net::sockets::tcp_client::send_timeout

(

xtd::int32

value

)

-> tcp_client &

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.

begin_connect() [1/3]

auto xtd::net::sockets::tcp_client::begin_connect	(	const xtd::net::ip_address &	address,
		uint16	port,
		xtd::async_callback	callback,
		const xtd::any_object &	state ) -> xtd::sptr< xtd::iasync_result >

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).

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() [2/3]

auto xtd::net::sockets::tcp_client::begin_connect	(	const xtd::array< xtd::net::ip_address > &	addresses,
		uint16	port,
		xtd::async_callback	callback,
		const xtd::any_object &	state ) -> xtd::sptr< xtd::iasync_result >

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).

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() [3/3]

auto xtd::net::sockets::tcp_client::begin_connect	(	const xtd::string &	host,
		uint16	port,
		xtd::async_callback	callback,
		const xtd::any_object &	state ) -> xtd::sptr< xtd::iasync_result >

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

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.

close()

auto xtd::net::sockets::tcp_client::close

(

)

-> void

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]

auto xtd::net::sockets::tcp_client::connect

(

const xtd::net::ip_end_point &

remote_end_point

)

-> void

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() [2/3]

auto xtd::net::sockets::tcp_client::connect	(	const xtd::net::ip_address &	ip_address,
		uint16	port ) -> void

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() [3/3]

auto xtd::net::sockets::tcp_client::connect	(	const xtd::string &	hostname,
		uint16	port ) -> void

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::string, uint16) 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.

end_connect()

auto xtd::net::sockets::tcp_client::end_connect

(

xtd::sptr< xtd::iasync_result >

async_result

)

-> void

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.

equals() [1/2]

auto xtd::net::sockets::tcp_client::equals ( const object & obj ) const -> bool

overridevirtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters

obj	The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

Reimplemented from xtd::object.

equals() [2/2]

auto xtd::net::sockets::tcp_client::equals ( const tcp_client & other ) const -> bool

overridenoexcept

Determines whether the specified object is equal to the current object.

Parameters

other

The object to compare with the current object.

Returns

true if the specified object is equal to the current object. otherwise, false.

get_stream()

auto xtd::net::sockets::tcp_client::get_stream ( ) const -> xtd::net::sockets::network_stream

nodiscard

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.

active() [1/2]

auto xtd::net::sockets::tcp_client::active ( ) const -> bool

nodiscardprotectednoexcept

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]

auto xtd::net::sockets::tcp_client::active ( bool value ) -> tcp_client &

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.

---

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

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