xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
xtd::net::sockets::tcp_listener Class Reference

#include <tcp_listener.h>

Definition

Listens for connections from TCP network clients.

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

Public Member Functions

 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. More...
 
 tcp_listener (const xtd::net::ip_address &ip_address, uint16_t 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. More...
 
xtd::net::sockets::socket accept_socket ()
 Accepts a pending connection request. More...
 
xtd::net::sockets::tcp_client accept_tcp_client ()
 Accepts a pending connection request. More...
 
std::shared_ptr< xtd::iasync_resultbegin_accept_socket (xtd::async_callback callback, const std::any &state)
 Begins an asynchronous operation to accept an incoming connection attempt. More...
 
std::shared_ptr< xtd::iasync_resultbegin_accept_tcp_client (xtd::async_callback callback, const std::any &state)
 Begins an asynchronous operation to accept an incoming connection attempt. More...
 
xtd::net::sockets::socket end_accept_socket (std::shared_ptr< xtd::iasync_result > async_result)
 Asynchronously accepts an incoming connection attempt and creates a new Socket to handle remote host communication. More...
 
xtd::net::sockets::tcp_client end_accept_tcp_client (std::shared_ptr< 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. More...
 
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. More...
 
tcp_listenerexclusive_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. More...
 
const xtd::net::end_pointlocal_end_point () const noexcept
 Gets the underlying xtd::net::end_point of the current xtd::net::sockets::tcp_listener. More...
 
bool pending ()
 Determines if there are pending connection requests. More...
 
xtd::net::sockets::socket server () const noexcept
 Gets the underlying network xtd::net::sockets::socket. More...
 
void start ()
 xtd::net::sockets::tcp_listener::starts listening for incoming connection requests. More...
 
void start (size_t backlog)
 xtd::net::sockets::tcp_listener::starts listening for incoming connection requests with a maximum number of pending connection. More...
 
void stop ()
 Closes the listener. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Static Public Member Functions

static tcp_listener create (uint16_t port)
 Creates a new xtd::net::sockets::tcp_listener instance to listen on the specified port. 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...
 

Protected Member Functions

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

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_pointAn 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_t  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_addressAn xtd::net::ip_address that represents the local IP address.
portThe 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

◆ 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_exceptionThe listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::net::sockets::socket_exceptionAn 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_exceptionThe listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::net::sockets::socket_exceptionAn 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.

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

◆ begin_accept_socket()

std::shared_ptr<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_resultAn xtd::async_callback delegate that references the method to invoke when the operation is complete.
stateA 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_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_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()

std::shared_ptr<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_resultAn xtd::async_callback delegate that references the method to invoke when the operation is complete.
stateA 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_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_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.

◆ create()

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

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

Parameters
portThe 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.

◆ end_accept_socket()

xtd::net::sockets::socket xtd::net::sockets::tcp_listener::end_accept_socket ( std::shared_ptr< xtd::iasync_result async_result)

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

Parameters
async_resulttAn 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_exceptionasync_result was not returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_socket 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 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 ( std::shared_ptr< 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_resultAn xtd::iasync_result returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_tcp_client(xtd::async_callback, std::any) method.
stateA 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_exceptionasync_result was not returned by a call to the xtd::net::sockets::tcp_listener::begin_accept_tcp_client 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
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.

◆ 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_exceptionThe 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_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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
valuetrue 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_exceptionThe 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_exceptionAn error occurred when attempting to access the socket.
xtd::object_closed_exceptionThe 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.

◆ 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_exceptionThe listener has not been started with a call to xtd::net::sockets::tcp_listener::start.
xtd::object_closed_exceptionThe 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.

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

◆ 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_exceptionAn 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
backlogThe maximum length of the pending connections queue.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the socket.
xtd::argument_out_of_range_exceptionThe backlog parameter is less than zero or exceeds the maximum number of permitted connections.
xtd::invalid_operation_exceptionThe 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_exceptionAn 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.

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