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

Definition

Provides client connections for TCP network services.

class core_export_ tcp_client : public xtd::object
Inheritance
xtd::objectxtd::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:
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/io/stream_reader>
#include <xtd/net/sockets/tcp_client>
#include <xtd/net/sockets/tcp_listener>
#include <xtd/threading/thread>
#include <xtd/console>
using namespace xtd;
using namespace xtd::io;
using namespace xtd::net;
using namespace xtd::net::sockets;
using namespace xtd::threading;
auto main()->int {
auto terminate_app = false;
auto server = thread {[&] {
auto listener = 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 = tcp_client {};
auto stream = client.get_stream();
auto writer = stream_writer {stream};
auto counter = 0;
while (!terminate_app) {
writer.write_line(ustring::format("counter={}", ++counter));
thread::sleep(50_ms);
}
}};
server.start();
client.start();
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/io/stream_reader>
#include <xtd/net/sockets/tcp_client>
#include <xtd/net/sockets/tcp_listener>
#include <xtd/threading/thread>
#include <xtd/console>
using namespace xtd;
using namespace xtd::io;
using namespace xtd::net;
using namespace xtd::net::sockets;
using namespace xtd::threading;
auto main()->int {
auto terminate_app = false;
auto server = thread {[&] {
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 stream = client.get_stream();
auto writer = stream_writer {stream};
auto counter = 0;
while (!terminate_app) {
writer.write_line(ustring::format("counter={}", ++counter));
thread::sleep(50_ms);
}
}};
server.start();
client.start();
terminate_app = true;
server.join();
client.join();
}
// This code produces the following output:
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...
Examples:
tcp_client_ip_v4.cpp, and tcp_client_ip_v6.cpp.

Constructors

 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 (xtd::net::sockets::address_family address_family)
 The xtd::net::sockets::address_family of the IP protocol. More...
 
 tcp_client (const xtd::ustring &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. More...
 

Properties

size_t available () const
 Gets the amount of data that has been received from the network and is available to be read. More...
 
xtd::net::sockets::socket client () const noexcept
 Gets the underlying network xtd::net::sockets::socket. More...
 
tcp_clientclient (const xtd::net::sockets::socket &value) noexcept
 Sets the underlying network xtd::net::sockets::socket. 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...
 
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_clientexclusive_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::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_clientlinger_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_clientno_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_clientreceive_buffer_size (size_t value)
 Sets the size of the receive buffer. More...
 
int32 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_clientreceive_timeout (int32 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_clientsend_buffer_size (size_t value)
 Sets the size of the send buffer. More...
 
int32 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_clientsend_timeout (int32 value)
 Gets the amount of time a xtd::net::sockets::tcp_client will wait for a send operation to complete successfully. More...
 

Methods

std::shared_ptr< xtd::iasync_resultbegin_connect (const xtd::net::ip_address &address, uint16 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). More...
 
std::shared_ptr< xtd::iasync_resultbegin_connect (const std::vector< xtd::net::ip_address > &addresses, uint16 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). More...
 
std::shared_ptr< xtd::iasync_resultbegin_connect (const xtd::ustring &host, uint16 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). 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_end_point &remote_end_point)
 Connects the client to a remote TCP host using the specified remote network endpoint. More...
 
void connect (const xtd::net::ip_address &ip_address, uint16 port)
 Connects the client to a remote TCP host using the specified IP address and port number. More...
 
void connect (const xtd::ustring &hostname, uint16 port)
 Connects the client to the specified port on the specified host. More...
 
void end_connect (std::shared_ptr< xtd::iasync_result > async_result)
 Ends a pending asynchronous connection attempt. More...
 
bool equals (const tcp_client &s) const noexcept override
 
xtd::net::sockets::network_stream get_stream () const
 Returns the xtd::net::sockets::network_stream used to send and receive data. More...
 

Protected properties

bool active () const noexcept
 Gets a value that indicates whether a connection has been made. More...
 
tcp_clientactive (bool value) noexcept
 Sets a value that indicates whether a connection has been made. More...
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
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...
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const noexcept
 Creates a shallow copy of the current object. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a sxd::ustring that represents the current object. More...
 
- Public Member Functions inherited from xtd::iequatable< tcp_client >
virtual bool equals (const tcp_client &) const noexcept=0
 Indicates whether the current object is equal to another object of the same type. More...
 
- 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)
explicit

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

Parameters
local_end_pointThe 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_exceptionThe 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  port 
)

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

Parameters
hostnameThe DNS name of the remote host to which you intend to connect.
portThe port number of the remote host to which you intend to connect.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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
valuetrue 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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 xtd::net::ip_address address,
uint16  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).

Parameters
addressThe xtd::net::ip_address of the remote host.
portThe port number of the remote host.
callbackAn xtd::async_callback delegate that references the method to invoke when the operation is complete.
stateA 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_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::tcp_client::begin_connect ( const std::vector< xtd::net::ip_address > &  addresses,
uint16  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).

Parameters
addressesAt least one xtd::net::ip_address that designates the remote hosts.
portThe port number of the remote host.
callbackAn xtd::async_callback delegate that references the method to invoke when the operation is complete.
stateA 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_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::tcp_client::begin_connect ( const xtd::ustring host,
uint16  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).

Parameters
hostThe name of the remote host.
portThe port number of the remote host.
callbackAn xtd::async_callback delegate that references the method to invoke when the operation is complete.
stateA 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_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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
valueThe 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_end_point remote_end_point)

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

Parameters
remote_end_pointThe xtd::net::ip_end_point to which you intend to connect.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when accessing the socket.
xtd::object_closed_exceptionThe 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.
Examples:
tcp_client_ip_v4.cpp, and tcp_client_ip_v6.cpp.

◆ connect() [2/3]

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

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

Parameters
ip_addressThe xtd::net::ip_address of the remote host to which you intend to send data
portThe port number to which you intend send data
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when accessing the socket.
xtd::object_closed_exceptionThe 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]

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

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

Parameters
hostnameThe DNS name of the remote host to which you intend to connect.
portThe port number of the remote host to which you intend to connect.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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) 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
resultAn xtd::iasync_result object returned by a call to xtd::net::sockets::tcp_client::client::begin_connect.
Exceptions
argument_exceptionasync_result was not returned by a call to the xtd::net::sockets::socket::begin_connect method.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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), 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
valuebool 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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), 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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
valueA xtd::net::sockets::linger_option that specifies how to linger while closing a socket.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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
valuetrue if the delay is disabled; otherwise, false. The default value is false.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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
valueA 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_exceptionAn error occurred when attempting to access the socket. See the Remarks section for more information.
xtd::object_closed_exceptionThe 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 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  value)

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

Parameters
valueThe 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
valueThe 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 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  value)

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

Parameters
valueThe 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: