xtd::net::sockets::tcp_listener Class Reference

Inheritance diagram for xtd::net::sockets::tcp_listener:

Definition

Listens for connections from TCP network clients.

class core_export_ tcp_listener : public xtd::object

Inheritance

xtd::object → xtd::net::sockets::tcp_listener

Header

#include <xtd/net/sockets/tcp_listener>

Namespace

xtd::net::sockets

Library

xtd.core

Remarks

The xtd::net::sockets::tcp_listener class provides simple methods that listen for and accept incoming connection requests in blocking synchronous mode. You can use either a xtd::net::sockets::tcp_client or a xtd::net::sockets::socket to connect with a xtd::net::sockets::tcp_listener. Create a xtd::net::sockets::tcp_listener using an xtd::net::ip_end_point, a Local IP address and port number, or just a port number. Specify Any for the local IP address and 0 for the local port number if you want the underlying service provider to assign those values for you. If you choose to do this, you can use the xtd::net::sockets::tcp_listener::local_end_point property to identify the assigned information, after the socket has connected.

Use the xtd::net::sockets::tcp_listener::start method to begin listening for incoming connection requests. xtd::net::sockets::tcp_listener::start will queue incoming connections until you either call the xtd::net::sockets::tcp_listener::stop method or it has queued xtd::net::sockets::socket_option_name::max_connections. Use either xtd::net::sockets::tcp_listener::accept_socket or xtd::net::sockets::tcp_listener::accept_tcp_client to pull a connection from the incoming connection request queue. These two methods will block. If you want to avoid blocking, you can use the xtd::net::sockets::tcp_listener::pending method first to determine if connection requests are available in the queue.

Call the xtd::net::sockets::tcp_listener::stop method to close the xtd::net::sockets::tcp_listener.

Note

The xtd::net::sockets::tcp_listener::stop method does not close any accepted connections. You are responsible for closing these separately.

Examples

The following example shows how to use IPv4 xtd::net::sockets::tcp_listener class with use xtd::net::sockets::tcp_client, 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 {};
    client.connect(ip_address::loopback, 9400);
    auto stream = client.get_stream();
    auto writer = stream_writer {stream};
    
    auto counter = 0;
    while (!terminate_app) {
      writer.write_line(string::format("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_listener class with use xtd::net::sockets::tcp_client, 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 {ip_end_point(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 = tcp_client {address_family::inter_network_v6};
    client.connect(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(string::format("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

tcp_client_ip_v6.cpp.

Public Constructors
	tcp_listener (const xtd::net::ip_end_point &local_end_point)
	Initializes a new instance of the xtd::net::sockets::tcp_listener class with the specified local endpoint.
	tcp_listener (const xtd::net::ip_address &ip_address, uint16 port)
	Initializes a new instance of the xtd::net::sockets::tcp_listener class that listens for incoming connection attempts on the specified local IP address and port number.

Public Properties
bool	exclusive_address_use () const
	Gets a bool value that specifies whether the xtd::net::sockets::tcp_listener allows only one underlying socket to listen to a specific port.
tcp_listener &	exclusive_address_use (bool value)
	Sets a bool value that specifies whether the xtd::net::sockets::tcp_listener allows only one underlying socket to listen to a specific port.
const xtd::net::end_point &	local_end_point () const noexcept
	Gets the underlying xtd::net::end_point of the current xtd::net::sockets::tcp_listener.
xtd::net::sockets::socket	server () const noexcept
	Gets the underlying network xtd::net::sockets::socket.

Public Methods
xtd::net::sockets::socket	accept_socket ()
	Accepts a pending connection request.
xtd::net::sockets::tcp_client	accept_tcp_client ()
	Accepts a pending connection request.
xtd::sptr< xtd::iasync_result >	begin_accept_socket (xtd::async_callback callback, const std::any &state)
	Begins an asynchronous operation to accept an incoming connection attempt.
xtd::sptr< xtd::iasync_result >	begin_accept_tcp_client (xtd::async_callback callback, const std::any &state)
	Begins an asynchronous operation to accept an incoming connection attempt.
xtd::net::sockets::socket	end_accept_socket (xtd::sptr< xtd::iasync_result > async_result)
	Asynchronously accepts an incoming connection attempt and creates a new Socket to handle remote host communication.
xtd::net::sockets::tcp_client	end_accept_tcp_client (xtd::sptr< xtd::iasync_result > async_result)
	Asynchronously accepts an incoming connection attempt and creates a new xtd::net::sockets::tcp_client to handle remote host communication.
bool	equals (const tcp_listener &s) const noexcept override
bool	pending ()
	Determines if there are pending connection requests.
void	start ()
	xtd::net::sockets::tcp_listener::starts listening for incoming connection requests.
void	start (size_t backlog)
	xtd::net::sockets::tcp_listener::starts listening for incoming connection requests with a maximum number of pending connection.
void	stop ()
	Closes the listener.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
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.

Public Static Methods
static tcp_listener	create (uint16 port)
	Creates a new xtd::net::sockets::tcp_listener instance to listen on the specified port.

Protected Properties
bool	active () const noexcept
	Gets a value that indicates whether xtd::net::sockets::tcp_listener is actively listening for client connections.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual size_t	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::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
Public Member Functions inherited from xtd::iequatable< tcp_listener >
virtual bool	equals (const tcp_listener &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type.
Static Public Member Functions inherited from xtd::object
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_listener() [1/2]

xtd::net::sockets::tcp_listener::tcp_listener ( const xtd::net::ip_end_point &  local_end_point )

explicit

Initializes a new instance of the xtd::net::sockets::tcp_listener class with the specified local endpoint.

Parameters

local_end_point

An xtd::net::ip_end_point that represents the local endpoint to which to bind the listener xtd::net::sockets::socket.

Remarks

This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts.

Before using this constructor, you must create an xtd::net::ip_end_point using the desired local IP address and port number. Pass this xtd::net::ip_end_point to the constructor as the local_end_point parameter.

If you do not care which local address is assigned, you can create an xtd::net::ip_end_point using xtd::net::ip_address::any as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an xtd::net::ip_end_point using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the xtd::net::sockets::tcp_listener::local_end_point property.

Call the xtd::net::sockets::tcp_listener::start method to begin listening for incoming connection attempts.

Note

The 0 for local port functionality is not available.

tcp_listener() [2/2]

xtd::net::sockets::tcp_listener::tcp_listener	(	const xtd::net::ip_address &	ip_address,
		uint16	port
	)

Initializes a new instance of the xtd::net::sockets::tcp_listener class that listens for incoming connection attempts on the specified local IP address and port number.

Parameters

ip_address	An xtd::net::ip_address that represents the local IP address.
port	The port on which to listen for incoming connection attempts.

Remarks

This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts.

Before calling this constructor you must first create an xtd::net::ip_address using the desired local address. Pass this xtd::net::ip_address to the constructor as the ip_address parameter.

If you do not care which local address is assigned, specify xtd::net::ip_address::any for the localaddr parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the xtd::net::sockets::tcp_listener::local_end_point property.

Call the xtd::net::sockets::tcp_listener::start method to begin listening for incoming connection attempts.

Note

The 0 for local port functionality is not available.

Member Function Documentation

exclusive_address_use() [1/2]

bool xtd::net::sockets::tcp_listener::exclusive_address_use

(

)

const

Gets a bool value that specifies whether the xtd::net::sockets::tcp_listener allows only one underlying socket to listen to a specific port.

Returns

true if the xtd::net::sockets::tcp_listener allows only one xtd::net::sockets::tcp_listener to listen to a specific port; otherwise, false. .

Exceptions

xtd::invalid_operation_exception	The xtd::net::sockets::tcp_listener has been started. Call the xtd::net::sockets::tcp_listener::stop() method and then set the xtd::net::sockets::tcp_listener::exclusive_address_use property.
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

By default, multiple listeners can listen to a specific port. However, only one of the listeners can perform operations on the network traffic sent to the port.

If more than one listener attempts to bind to a particular port, then the one with the more specific IP address handles the network traffic sent to that port.

You can use the xtd::net::sockets::tcp_listener::exclusive_address_use property to prevent multiple listeners from listening to a specific port.

Set this property before calling xtd::net::sockets::tcp_listener::start, or call the xtd::net::sockets::tcp_listener::stop method and then set this property.

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

tcp_listener & xtd::net::sockets::tcp_listener::exclusive_address_use

(

bool

value

)

Sets a bool value that specifies whether the xtd::net::sockets::tcp_listener allows only one underlying socket to listen to a specific port.

Parameters

value

true if the xtd::net::sockets::tcp_listener allows only one xtd::net::sockets::tcp_listener to listen to a specific port; otherwise, false. .

Returns

This current instance.

Exceptions

xtd::invalid_operation_exception	The xtd::net::sockets::tcp_listener has been started. Call the xtd::net::sockets::tcp_listener::stop() method and then set the xtd::net::sockets::tcp_listener::exclusive_address_use property.
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

By default, multiple listeners can listen to a specific port. However, only one of the listeners can perform operations on the network traffic sent to the port.

If more than one listener attempts to bind to a particular port, then the one with the more specific IP address handles the network traffic sent to that port.

You can use the xtd::net::sockets::tcp_listener::exclusive_address_use property to prevent multiple listeners from listening to a specific port.

Set this property before calling xtd::net::sockets::tcp_listener::start, or call the xtd::net::sockets::tcp_listener::stop method and then set this property.

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.

local_end_point()

const xtd::net::end_point & xtd::net::sockets::tcp_listener::local_end_point ( ) const

noexcept

Gets the underlying xtd::net::end_point of the current xtd::net::sockets::tcp_listener.

Returns

The xtd::net::end_point to which the xtd::net::sockets::socket is bound.

Remarks

You can use the xtd::net::sockets::tcp_listener::local_end_point property to identify the local network interface and port number being used to listen for incoming client connection requests, after a socket connection has been made. You must first cast this xtd::net::end_point to an xtd::net::ip_end_point. You can then call the xtd::net::ip_end_point::address property to retrieve the local IP address, and the xtd::net::ip_end_point::port property to retrieve the local port number.

server()

xtd::net::sockets::socket xtd::net::sockets::tcp_listener::server ( ) const

noexcept

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

Returns

The underlying xtd::net::sockets::socket.

Remarks

xtd::net::sockets::tcp_listener creates a xtd::net::sockets::socket to listen for incoming client connection requests. Classes deriving from xtd::net::sockets::tcp_listener can use this property to get this xtd::net::sockets::socket.

Use the underlying xtd::net::sockets::socket returned by the xtd::net::sockets::tcp_listener::server property if you require access beyond that which xtd::net::sockets::tcp_listener provides.

Note

The xtd::net::sockets::tcp_listener::server property only returns the xtd::net::sockets::socket used to listen for incoming client connection requests. Use the xtd::net::sockets::tcp_listener::accept_socket method to accept a pending connection request and obtain a xtd::net::sockets::socket for sending and receiving data. You can also use the xtd::net::sockets::tcp_listener::accept_tcp_client method to accept a pending connection request and obtain a xtd::net::sockets::tcp_client for sending and receiving data.

accept_socket()

xtd::net::sockets::socket xtd::net::sockets::tcp_listener::accept_socket

(

)

Accepts a pending connection request.

Returns

A xtd::net::sockets::socket used to send and receive data.

Exceptions

xtd::invalid_operation_exception	The listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket.

Remarks

xtd::net::sockets::tcp_listener::accept_socket is a blocking method that returns a xtd::net::sockets::socket that you can use to send and receive data. If you want to avoid blocking, use the xtd::net::sockets::tcp_listener::pending method to determine if connection requests are available in the incoming connection queue.

The xtd::net::sockets::socket returned is initialized with the IP address and port number of the remote host.

You can use any of the xtd::net::sockets::socket::send and xtd::net::sockets::socket::receive methods available in the xtd::net::sockets::socket class to communicate with the remote host. When you are finished using the xtd::net::sockets::socket, be sure to call its xtd::net::sockets::tcp_listener::close method. If your application is relatively simple, consider using the xtd::net::sockets::tcp_listener::accept_tcp_client method rather than the xtd::net::sockets::tcp_listener::accept_socket method.

xtd::net::sockets::tcp_client provides you with simple methods for sending and receiving data over a network in blocking synchronous mode.

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.

accept_tcp_client()

xtd::net::sockets::tcp_client xtd::net::sockets::tcp_listener::accept_tcp_client

(

)

Accepts a pending connection request.

Returns

A xtd::net::sockets::tcp_client used to send and receive data.

Exceptions

xtd::invalid_operation_exception	The listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket.

Remarks

xtd::net::sockets::tcp_listener::accept_tcp_client is a blocking method that returns a xtd::net::sockets::tcp_client that you can use to send and receive data. Use the xtd::net::sockets::tcp_listener::pending method to determine if connection requests are available in the incoming connection queue if you want to avoid blocking.

Use the xtd::net::sockets::tcp_client::get_stream method to obtain the underlying xtd::net::sockets::network_stream of the returned xtd::net::sockets::tcp_client. The xtd::net::sockets::network_stream will provide you with methods for sending and receiving with the remote host. When you are through with the xtd::net::sockets::tcp_client, be sure to call its xtd::net::sockets::tcp_listener::close method. If you want greater flexibility than a xtd::net::sockets::tcp_client offers, consider using xtd::net::sockets::tcp_listener::accept_socket.

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_accept_socket()

xtd::sptr< xtd::iasync_result > xtd::net::sockets::tcp_listener::begin_accept_socket	(	xtd::async_callback	callback,
		const std::any &	state
	)

Begins an asynchronous operation to accept an incoming connection attempt.

Parameters

async_result	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object containing information about the accept operation. This object is passed to the callback delegate when the operation is complete.

Returns

An xtd::iasync_result that references the asynchronous creation of the xtd::net::sockets::socket.

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_listener::begin_accept_socket operation must be completed by calling the xtd::net::sockets::tcp_listener::end_accept_socket 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 the xtd::net::sockets::tcp_listener::accept_socket method.

Note

You can call the xtd::net::sockets::socket::remote_end_point property of the returned xtd::net::sockets::socket to identify the remote host's network address and port number.

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_accept_tcp_client()

xtd::sptr< xtd::iasync_result > xtd::net::sockets::tcp_listener::begin_accept_tcp_client	(	xtd::async_callback	callback,
		const std::any &	state
	)

Begins an asynchronous operation to accept an incoming connection attempt.

Parameters

async_result	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object containing information about the accept operation. This object is passed to the callback delegate when the operation is complete.

Returns

An xtd::iasync_result that references the asynchronous creation of the xtd::net::sockets::tcp_client.

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_listener::begin_accept_tcp_client operation must be completed by calling the xtd::net::sockets::tcp_listener::end_accept_tcp_client 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 the xtd::net::sockets::tcp_listener::accept_ccp_client 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.

end_accept_socket()

xtd::net::sockets::socket xtd::net::sockets::tcp_listener::end_accept_socket

(

xtd::sptr< xtd::iasync_result >

async_result

)

Asynchronously accepts an incoming connection attempt and creates a new Socket to handle remote host communication.

Parameters

async_result

tAn xtd::iasync_result returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_socket(xtd::async_callback, std::any) method.

Returns

The xtd::net::sockets::socket used to send and receive data.

Exceptions

argument_exception	async_result was not returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_socket 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 the xtd::net::sockets::tcp_listener::accept_socket method.

Note

You can call the xtd::net::sockets::socket::remote_end_point property of the returned xtd::net::sockets::socket to identify the remote host's network address and port number.

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_accept_tcp_client()

xtd::net::sockets::tcp_client xtd::net::sockets::tcp_listener::end_accept_tcp_client

(

xtd::sptr< xtd::iasync_result >

async_result

)

Asynchronously accepts an incoming connection attempt and creates a new xtd::net::sockets::tcp_client to handle remote host communication.

Parameters

async_result	An xtd::iasync_result returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_tcp_client(xtd::async_callback, std::any) method.
state	A user-defined object containing information about the accept operation. This object is passed to the callback delegate when the operation is complete.

Returns

An xtd::iasync_result that references the asynchronous creation of the xtd::net::sockets::tcp_client.

Exceptions

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

The asynchronous xtd::net::sockets::tcp_listener::begin_accept_tcp_client operation must be completed by calling the xtd::net::sockets::tcp_listener::end_accept_tcp_client 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 the xtd::net::sockets::tcp_listener::accept_tcp_client 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.

pending()

bool xtd::net::sockets::tcp_listener::pending

(

)

Determines if there are pending connection requests.

Returns

true if connections are pending; otherwise, false.

Exceptions

xtd::invalid_operation_exception	The listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

This non-blocking method determines if there are any pending connection requests. Because the xtd::net::sockets::tcp_listener::accept_socket and xtd::net::sockets::tcp_listener::accept_tcp_client methods block execution until

the xtd::net::sockets::tcp_listener::start method has queued an incoming connection request, the xtd::net::sockets::tcp_listener::pending method can be used to determine if connections are available before attempting to accept them.

start() [1/2]

void xtd::net::sockets::tcp_listener::start

(

)

xtd::net::sockets::tcp_listener::starts listening for incoming connection requests.

Exceptions

xtd::net::sockets::socket_exception

An error occurred when attempting to access the socket.

Remarks

The xtd::net::sockets::tcp_listener::start method initializes the underlying xtd::net::sockets::socket, binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, the xtd::net::sockets::tcp_listener::start method will queue the request and continue listening for additional requests until you call the xtd::net::sockets::tcp_listener::stop method. If xtd::net::sockets::tcp_listener receives a connection request after it has already queued the maximum number of connections, it will throw a xtd::net::sockets::socket_exception on the client.

To remove a connection from the incoming connection queue, use either the xtd::net::sockets::tcp_listener::accept_tcp_client method or the xtd::net::sockets::tcp_listener::accept_socket method. The xtd::net::sockets::tcp_listener::accept_tcp_client method will remove a connection from the queue and return a xtd::net::sockets::tcp_client that you can use to send and receive data. The xtd::net::sockets::tcp_listener::accept_socket method will return a xtd::net::sockets::socket that you can use to do the same. If your application only requires synchronous I/O, use xtd::net::sockets::tcp_listener::accept_tcp_client. For more detailed behavioral control, use xtd::net::sockets::tcp_listener::accept_socket. Both of these methods block until a connection request is available in the queue.

Use the xtd::net::sockets::tcp_listener::stop method to close the xtd::net::sockets::tcp_listener and stop listening. You are responsible for closing your accepted connections separately.

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.

start() [2/2]

void xtd::net::sockets::tcp_listener::start

(

size_t

backlog

)

xtd::net::sockets::tcp_listener::starts listening for incoming connection requests with a maximum number of pending connection.

Parameters

backlog

The maximum length of the pending connections queue.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the socket.
xtd::argument_out_of_range_exception	The backlog parameter is less than zero or exceeds the maximum number of permitted connections.
xtd::invalid_operation_exception	The underlying xtd::net::sockets::socket is null.

Remarks

The xtd::net::sockets::tcp_listener::start method initializes the underlying xtd::net::sockets::socket, binds it to a local endpoint, and listens for incoming connection attempts. If a connection request is received, the xtd::net::sockets::tcp_listener::start method will queue the request and continue listening for additional requests until you call the xtd::net::sockets::tcp_listener::stop method. If xtd::net::sockets::tcp_listener receives a connection request after it has already queued the maximum number of connections, it will throw a xtd::net::sockets::socket_exception on the client.

To remove a connection from the incoming connection queue, use either the xtd::net::sockets::tcp_listener::accept_tcp_client method or the xtd::net::sockets::tcp_listener::accept_socket method. The xtd::net::sockets::tcp_listener::accept_tcp_client method will remove a connection from the queue and return a xtd::net::sockets::tcp_client that you can use to send and receive data. The xtd::net::sockets::tcp_listener::accept_socket method will return a xtd::net::sockets::socket that you can use to do the same. If your application only requires synchronous I/O, use xtd::net::sockets::tcp_listener::accept_tcp_client. For more detailed behavioral control, use xtd::net::sockets::tcp_listener::accept_socket. Both of these methods block until a connection request is available in the queue.

Use the xtd::net::sockets::tcp_listener::stop method to close the xtd::net::sockets::tcp_listener and stop listening. You are responsible for closing your accepted connections separately.

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.

stop()

void xtd::net::sockets::tcp_listener::stop

(

)

Closes the listener.

Exceptions

xtd::net::sockets::socket_exception

An error occurred when attempting to access the socket.

Remarks

xtd::net::sockets::tcp_listener::stop closes the listener. Any unaccepted connection requests in the queue will be lost. Remote hosts waiting for a connection to be accepted will throw a xtd::net::sockets::socket_exception. You are responsible for closing your accepted connections separately.

Note

The xtd::net::sockets::tcp_listener::stop method also closes the underlying xtd::net::sockets::socket, and creates a new xtd::net::sockets::socket for the xtd::net::sockets::tcp_listener. If you set any properties on the underlying xtd::net::sockets::socket prior to calling the xtd::net::sockets::tcp_listener::stop method, those properties will not carry over to the new xtd::net::sockets::socket.

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.

create()

static tcp_listener xtd::net::sockets::tcp_listener::create ( uint16  port )

static

Creates a new xtd::net::sockets::tcp_listener instance to listen on the specified port.

Parameters

port	The port on which to listen for incoming connection attempts.

Returns

xtd::net::sockets::tcp_listener A new xtd::net::sockets::tcp_listener instance to listen on the specified port.

active()

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

protectednoexcept

Gets a value that indicates whether xtd::net::sockets::tcp_listener is actively listening for client connections.

Returns

true if xtd::net::sockets::tcp_listener is actively listening; otherwise, false.

Remarks

Classes deriving from xtd::net::sockets::tcp_listener can use this property to determine if the xtd::net::sockets::socket is currently listening for incoming connection attempts.

The Active property can be used to avoid redundant xtd::net::sockets::tcp_listener::start attempts.

equals() [1/2]

virtual bool xtd::object::equals ( const object &  obj ) const

virtualnoexcept

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.

Examples

The following code example compares the current instance with another object.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  auto object1 = new_ptr<object>();
  auto object2 = new_ptr<object>();
  
  auto object3 = object2;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
  object3 = object1;
  console::write_line(object1->equals(*object3));
  console::write_line(*object1 == *object3);
}
 
// This code produces the following output :
//
// false
// false
// true
// true

Reimplemented from xtd::object.

equals() [2/2]

template<class object_a_t , class object_b_t >

static bool xtd::object::equals ( const object_a_t &  object_a, const object_b_t &  object_b  )

inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters

object_a	The first object to compare.
object_b	The second object to compare.

Returns

true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.

Examples

The following code example compares different objects.

#include <xtd/console>
 
using namespace xtd;
 
auto main() -> int {
  string s1 = "Tom";
  string s2 = "Carol";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Tom";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "Tom";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "Carol";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
  
  s1 = "";
  s2 = "";
  console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
 
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true

---

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

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