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 | Protected Member Functions | List of all members
xtd::net::sockets::udp_client Class Reference

#include <udp_client.h>

Definition

Provides User Datagram Protocol (UDP) network services.

Namespace
xtd::net::sockets
Library
xtd.core
Remarks
The xtd::net::sockets::udp_client class provides simple methods for sending and receiving connectionless UDP datagrams in blocking synchronous mode. Because UDP is a connectionless transport protocol, you do not need to establish a remote host connection prior to sending and receiving data. You do, however, have the option of establishing a default remote host in one of the following two ways:
You can use any of the send methods provided in the xtd::net::sockets::udp_client to send data to a remote device. Use the xtd::net::sockets::udp_client::receive method to receive data from remote hosts.
Note
Do not call xtd::net::sockets::udp_client::send using a host name or xtd::net::ip_end_point if you have already specified a default remote host. If you do, xtd::net::sockets::udp_client will throw an exception.
Remarks
xtd::net::sockets::udp_client methods also allow you to send and receive multicast datagrams. Use the xtd::net::sockets::udp_client::join_multicast_group method to subscribe a xtd::net::sockets::udp_client to a multicast group. Use the xtd::net::sockets::udp_client::drop_multicast_group method to unsubscribe a xtd::net::sockets::udp_client from a multicast group.
Examples
The following example shows how to use IPv4 xtd::net::sockets::udp_client class.
#include <xtd/xtd>
using namespace std;
using namespace std::literals;
using namespace xtd;
using namespace xtd::net;
using namespace xtd::net::sockets;
int main() {
auto terminate_app = false;
thread server([&] {
while (!terminate_app) {
ip_end_point incoming_end_point;
auto buffer = udp.receive(incoming_end_point);
if (buffer.size() && buffer[0] != 0xFF)
console::write_line(ustring(buffer.begin(), buffer.end()));
}
});
thread client([&] {
auto counter = 1;
while (!terminate_app) {
auto str = ustring::format("counter={}", counter++);
udp.send(vector<byte_t>(str.begin(), str.end()), str.size(), ip_end_point(ip_address::loopback, 9400));
this_thread::sleep_for(50ms);
}
udp.send(vector<byte_t> {0xFF}, 1, ip_end_point(ip_address::loopback, 9400));
});
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::udp_client class.
#include <xtd/xtd>
using namespace std;
using namespace std::literals;
using namespace xtd;
using namespace xtd::net;
using namespace xtd::net::sockets;
int main() {
auto terminate_app = false;
thread server([&] {
while (!terminate_app) {
ip_end_point incoming_end_point;
auto buffer = udp.receive(incoming_end_point);
if (buffer.size() && buffer[0] != 0xFF)
console::write_line(ustring(buffer.begin(), buffer.end()));
}
});
thread client([&] {
auto counter = 1;
while (!terminate_app) {
auto str = ustring::format("counter={}", counter++);
udp.send(vector<byte_t>(str.begin(), str.end()), str.size(), ip_end_point(ip_address::ip_v6_loopback, 9400));
this_thread::sleep_for(50ms);
}
udp.send(vector<byte_t> {0xFF}, 1, ip_end_point(ip_address::ip_v6_loopback, 9400));
});
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

 udp_client ()
 Initializes a new instance of the xtd::net::sockets::udp_client class. More...
 
 udp_client (uint16_t port)
 Initializes a new instance of the xtd::net::sockets::udp_client class and binds it to the local port number provided. More...
 
 udp_client (const xtd::net::ip_end_point &local_end_point)
 Initializes a new instance of the xtd::net::sockets::udp_client class and binds it to the specified local endpoint. More...
 
 udp_client (xtd::net::sockets::address_family address_Family)
 Initializes a new instance of the xtd::net::sockets::udp_client class. More...
 
 udp_client (uint16_t port, xtd::net::sockets::address_family addressFamily)
 Initializes a new instance of the xtd::net::sockets::udp_client class and binds it to the local port number provided. More...
 
 udp_client (const xtd::ustring &hostname, uint16_t port)
 Initializes a new instance of the xtd::net::sockets::udp_client class and establishes a default remote host. More...
 
void allow_nat_traversal (bool allowed)
 Enables or disables Network Address Translation (NAT) traversal on a xtd::net::sockets::udp_client instance. More...
 
size_t available () const
 Gets the amount of data received from the network that is available to read. More...
 
std::shared_ptr< xtd::iasync_resultbegin_receive (xtd::async_callback callback, const std::any &state)
 xtd::net::sockets::udp_client::receives a datagram from a remote host asynchronously. More...
 
std::shared_ptr< xtd::iasync_resultbegin_send (const std::vector< byte_t > &dgram, size_t bytes, const xtd::ustring &hostname, uint16_t port, xtd::async_callback callback, const std::any &state)
 xtd::net::sockets::udp_client::sends a datagram to a destination asynchronously. The destination is specified by the host name and port number. More...
 
std::shared_ptr< xtd::iasync_resultbegin_send (const std::vector< byte_t > &dgram, size_t bytes, const xtd::net::ip_end_point &end_point, xtd::async_callback callback, const std::any &state)
 xtd::net::sockets::udp_client::sends a datagram to a destination asynchronously. The destination is specified by a EndPoint. More...
 
std::shared_ptr< xtd::iasync_resultbegin_send (const std::vector< byte_t > &dgram, size_t bytes, xtd::async_callback callback, const std::any &state)
 xtd::net::sockets::udp_client::sends a datagram to a remote host asynchronously. The destination was specified previously by a call to xtd::net::sockets::udp_client::connect. More...
 
xtd::net::sockets::socket client () const noexcept
 Gets the underlying network xtd::net::sockets::socket. More...
 
udp_clientclient (const xtd::net::sockets::socket &value) noexcept
 Sets the underlying network xtd::net::sockets::socket. More...
 
void close ()
 Closes the UDP connection. More...
 
void connect (const xtd::net::ip_end_point &end_point)
 Establishes a default remote host using the specified network endpoint. More...
 
void connect (const xtd::net::ip_address &ip_address, uint16_t port)
 Establishes a default remote host using the specified IP address and port number. More...
 
void connect (const xtd::ustring &hostname, uint16_t port)
 Establishes a default remote host using the specified hostname and port number. More...
 
bool dont_fragment () const
 Gets a boolean value that specifies whether the xtd::net::sockets::udp_client allows Internet Protocol (IP) datagrams to be fragmented. More...
 
udp_clientdont_fragment (bool value)
 Sets boolean value that specifies whether the xtd::net::sockets::udp_client allows Internet Protocol (IP) datagrams to be fragmented. More...
 
void drop_multicast_group (const xtd::net::ip_address &multicast_address)
 Leaves a multicast group. More...
 
void dropo_multicast_group (const xtd::net::ip_address &multicast_address, uint32_t if_index)
 Leaves a multicast group. More...
 
bool enable_broadcast () const
 Gets a boolean value that specifies whether the xtd::net::sockets::udp_client may send or receive broadcast packets. More...
 
udp_clientenable_broadcast (bool value)
 Sets a boolean value that specifies whether the xtd::net::sockets::udp_client may send or receive broadcast packets. More...
 
std::vector< byte_t > end_receive (std::shared_ptr< xtd::iasync_result > async_result, xtd::net::ip_end_point &remote_end_point)
 Ends a pending asynchronous receive. More...
 
size_t end_send (std::shared_ptr< xtd::iasync_result > async_result)
 Ends a pending asynchronous send. More...
 
bool exclusive_address_use () const
 Gets a boolean value that specifies whether the xtd::net::sockets::udp_client allows only one client to use a port. More...
 
udp_clientexclusive_address_use (bool value)
 Sets a boolean value that specifies whether the xtd::net::sockets::udp_client allows only one client to use a port. More...
 
void join_multicast_group (const xtd::net::ip_address &multicast_address)
 Adds a xtd::net::sockets::udp_client to a multicast group. More...
 
void join_multicast_group (uint32_t if_index, const xtd::net::ip_address &multicast_address)
 Adds a xtd::net::sockets::udp_client to a multicast group. More...
 
void join_multicast_group (const xtd::net::ip_address &multicast_address, byte_t ttl)
 Adds a xtd::net::sockets::udp_client to a multicast group with the specified Time to Live (TTL). More...
 
void join_multicast_group (const xtd::net::ip_address &multicast_address, const xtd::net::ip_address &local_address)
 Adds a xtd::net::sockets::udp_client to a multicast group. More...
 
bool multicast_loopback () const
 Gets a boolean value that specifies whether outgoing multicast packets are delivered to the sending application. More...
 
udp_clientmulticast_loopback (bool value)
 Sets a boolean value that specifies whether outgoing multicast packets are delivered to the sending application. More...
 
std::vector< byte_t > receive (xtd::net::ip_end_point &remote_end_point)
 Returns a UDP datagram that was sent by a remote host. More...
 
size_t send (const std::vector< byte_t > &dgram, size_t bytes, const xtd::ustring &hostname, uint16_t port)
 xtd::net::sockets::udp_client::sends a UDP datagram to a specified port on a specified remote host. More...
 
size_t send (const std::vector< byte_t > &dgram, size_t bytes, const xtd::net::ip_end_point &end_point)
 xtd::net::sockets::udp_client::sends a UDP datagram to the host at the specified remote endpoint. More...
 
size_t send (const std::vector< byte_t > &dgram, size_t bytes)
 xtd::net::sockets::udp_client::sends a UDP datagram to a remote host. More...
 
byte_t ttl () const
 Gets a value that specifies the Time to Live (TTL) value of Internet Protocol (IP) packets sent by the xtd::net::sockets::udp_client. More...
 
udp_clientttl (byte_t value)
 Sets a value that specifies the Time to Live (TTL) value of Internet Protocol (IP) packets sent by the xtd::net::sockets::udp_client. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Protected Member Functions

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

Additional Inherited Members

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

Constructor & Destructor Documentation

◆ udp_client() [1/6]

xtd::net::sockets::udp_client::udp_client ( )

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

Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
This constructor creates a new xtd::net::sockets::udp_client and allows the underlying service provider to assign the most appropriate local IPv4 address and port number. If this constructor is used, the xtd::net::sockets::udp_client instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target.
This constructor is not suitable for joining a multicast group because it does not perform socket binding. Also, it works only with IPv4 address types.
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.

◆ udp_client() [2/6]

xtd::net::sockets::udp_client::udp_client ( uint16_t  port)
explicit

Initializes a new instance of the xtd::net::sockets::udp_client class and binds it to the local port number provided.

Parameters
portThe local port number from which you intend to communicate.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
This constructor creates an underlying xtd::net::sockets::socket and binds it to the port number from which you intend to communicate. Use this constructor if you are only interested in setting the local port number. The underlying service provider will assign the local IP address. If you pass 0 to the constructor, the underlying service provider will assign a port number. If this constructor is used, the xtd::net::sockets::udp_client instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target.
This constructor works only with IPv4 address types.
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.

◆ udp_client() [3/6]

xtd::net::sockets::udp_client::udp_client ( const xtd::net::ip_end_point local_end_point)
explicit

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

Parameters
local_end_pointAn xtd::net::ip_end_point that represents the local endpoint to which you bind the UDP connection.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
This constructor creates a new xtd::net::sockets::udp_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 for sending and receiving data. If you do not, the underlying service provider will assign the most appropriate local IP address and port number.
If this constructor is used, the xtd::net::sockets::udp_client instance is set with the address family specified by the local_end_point parameter that cannot be changed or overwritten by a connect method call with a different address family.
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.

◆ udp_client() [4/6]

xtd::net::sockets::udp_client::udp_client ( xtd::net::sockets::address_family  address_Family)
explicit

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

Parameters
address_familyone of the xtd::net::sockets::address_family values that specifies the addressing scheme of the socket.
Exceptions
xtd::argument_exceptionfamily is not xtd::net::sockets::address_family::inter_network or xtd::net::sockets::address_family::inter_network_v6.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
The family parameter determines whether the listener uses an IP version 4 address (IPv4) or an IP version 6 (IPv6) address. To use an IPv4 address, pass the xtd::net::sockets::address_family::inter_network value. To use an IPv6 address, pass the xtd::net::sockets::address_family::inter_network_v6 value. Passing any other value will cause the method to throw an xtd::argument_exception.
If this constructor is used, the xtd::net::sockets::udp_client instance is set with the address family specified by the family parameter that cannot be changed or overwritten by a connect method call with a different address family.
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.
Remarks
The xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(xtd::net::sockets::address_family) is not suitable for joining a multicast group because it does not perform socket binding.

◆ udp_client() [5/6]

xtd::net::sockets::udp_client::udp_client ( uint16_t  port,
xtd::net::sockets::address_family  addressFamily 
)

Initializes a new instance of the xtd::net::sockets::udp_client class and binds it to the local port number provided.

Parameters
portThe port on which to listen for incoming connection attempts.
address_familyOne of the xtd::net::sockets::address_family values that specifies the addressing scheme of the socket.
Exceptions
xtd::argument_exceptionfamily is not xtd::net::sockets::address_family::inter_network or xtd::net::sockets::address_family::inter_network_v6.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
This constructor creates an underlying xtd::net::sockets::socket and binds it to the port number from which you intend to communicate.
The family parameter determines whether the listener uses an IP version 4 address (IPv4) or an IP version 6 (IPv6) address. To use an IPv4 address, pass the xtd::net::sockets::address_family::inter_network value. To use an IPv6 address, pass the xtd::net::sockets::address_family::inter_network_v6 value. Passing any other value will cause the method to throw an xtd::argument_exception.
If this constructor is used, the xtd::net::sockets::udp_client instance is set with the address family specified by the family parameter that cannot be changed or overwritten by a connect method call with a different address family.
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.

◆ udp_client() [6/6]

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

Initializes a new instance of the xtd::net::sockets::udp_client class and establishes a default remote host.

Parameters
hostnameThe name of the remote DNS host to which you intend to connect.
portThe remote port number to which you intend to connect.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
This constructor initializes a new xtd::net::sockets::udp_client and establishes a remote host using the hostname and port parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the xtd::net::sockets::udp_client::send method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the xtd::net::sockets::udp_client::connect method. If you want to specify a remote host in your call to the xtd::net::sockets::udp_client::send method, do not use this constructor.
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::udp_client::active ( ) const
protectednoexcept

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

Returns
bool true if the connection has been made; otherwise, false.
Remarks
Classes deriving from xtd::net::sockets::udp_client can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the xtd::net::sockets::udp_client::connect method. If you do establish a default remote host, you cannot specify a remote host in your call to xtd::net::sockets::udp_client::send.

◆ active() [2/2]

udp_client& xtd::net::sockets::udp_client::active ( bool  value)
protectednoexcept

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

Parameters
valuebool true if the connection has been made; otherwise, false.
Returns
This current instance.
Remarks
Classes deriving from xtd::net::sockets::udp_client can use this property to determine if a default remote host has been established. You can establish a default remote host by using the appropriate constructor or by calling the xtd::net::sockets::udp_client::connect method. If you do establish a default remote host, you cannot specify a remote host in your call to xtd::net::sockets::udp_client::send.

◆ allow_nat_traversal()

void xtd::net::sockets::udp_client::allow_nat_traversal ( bool  allowed)

Enables or disables Network Address Translation (NAT) traversal on a xtd::net::sockets::udp_client instance.

Parameters
allowedA boolean value that specifies whether to enable or disable NAT traversal.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
The xtd::net::sockets::udp_client::allow_nat_traversal method is used to enable or disable NAT traversal for a xtd::net::sockets::udp_client instance. NAT traversal may be provided using Teredo, 6to4, or an ISATAP tunnel.
When the allowed parameter is false, the xtd::net::sockets::ip_protection_level option on the associated socket is set to xtd::net::sockets::ip_protection_level::edge_restricted. This explicitly disables NAT traversal for a xtd::net::sockets::udp_client instance.
When the allowed parameter is true, the xtd::net::sockets::ip_protection_level option on the associated socket is set to xtd::net::sockets::ip_protection_level::edge_unrestricted. This may allow NAT traversal for a xtd::net::sockets::udp_client depending on firewall rules in place on the system.
A Teredo address is an IPv6 address with the prefix of 2001::/32. Teredo addresses can be returned through normal DNS name resolution or enumerated as an IPv6 address assigned to a local interface.
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.

◆ available()

size_t xtd::net::sockets::udp_client::available ( ) const

Gets the amount of data received from the network that is available to read.

Returns
The number of bytes of data received from the network.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::available property is used to determine the amount of data queued in the network buffer for reading. If data is available, call Read to get the data. If no data is available, the xtd::net::sockets::udp_client::available property returns 0.
If the remote host shuts down or closes the connection, the xtd::net::sockets::udp_client::available property throws a xtd::net::sockets::socket_exception.
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_receive()

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::udp_client::begin_receive ( xtd::async_callback  callback,
const std::any state 
)

xtd::net::sockets::udp_client::receives a datagram from a remote host asynchronously.

Parameters
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 receive operation. This object is passed to the callback delegate when the operation is complete.
Returns
An xtd::iasync_result object that references the asynchronous receive.
Remarks
The asynchronous xtd::net::sockets::udp_client::begin_receive operation must be completed by calling the xtd::net::sockets::udp_client::end_receive method. Typically, the method is invoked by the callback delegate.
This method does not block until the operation is complete. To block until the operation is complete, use the xtd::net::sockets::udp_client::receive method.

◆ begin_send() [1/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::udp_client::begin_send ( const std::vector< byte_t > &  dgram,
size_t  bytes,
const xtd::ustring hostname,
uint16_t  port,
xtd::async_callback  callback,
const std::any state 
)

xtd::net::sockets::udp_client::sends a datagram to a destination asynchronously. The destination is specified by the host name and port number.

Parameters
dgramA byte array that contains the data to be sent.
bytesThe number of bytes to send.
hostnameThe destination host.
portThe destination port number.
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 send operation. This object is passed to the callback delegate when the operation is complete.
Returns
An xtd::iasync_result object that references the asynchronous send.
Remarks
The asynchronous xtd::net::sockets::udp_client::begin_send operation must be completed by calling the xtd::net::sockets::udp_client::end_send method. Typically, the method is invoked by the callback delegate.
This method does not block until the operation is complete. To block until the operation is complete, use one of the xtd::net::sockets::udp_client::send method overloads.

◆ begin_send() [2/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::udp_client::begin_send ( const std::vector< byte_t > &  dgram,
size_t  bytes,
const xtd::net::ip_end_point end_point,
xtd::async_callback  callback,
const std::any state 
)

xtd::net::sockets::udp_client::sends a datagram to a destination asynchronously. The destination is specified by a EndPoint.

Parameters
dgramA byte array that contains the data to be sent.
bytesThe number of bytes to send.
end_pointThe EndPoint that represents the destination for the data.
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 send operation. This object is passed to the callback delegate when the operation is complete.
Returns
An xtd::iasync_result object that references the asynchronous send.
Remarks
The asynchronous xtd::net::sockets::udp_client::begin_send operation must be completed by calling the xtd::net::sockets::udp_client::end_send method. Typically, the method is invoked by the callback delegate.
This method does not block until the operation is complete. To block until the operation is complete, use one of the xtd::net::sockets::udp_client::send method overloads.

◆ begin_send() [3/3]

std::shared_ptr<xtd::iasync_result> xtd::net::sockets::udp_client::begin_send ( const std::vector< byte_t > &  dgram,
size_t  bytes,
xtd::async_callback  callback,
const std::any state 
)

xtd::net::sockets::udp_client::sends a datagram to a remote host asynchronously. The destination was specified previously by a call to xtd::net::sockets::udp_client::connect.

Parameters
dgramA byte array that contains the data to be sent.
bytesThe number of bytes to send.
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 send operation. This object is passed to the callback delegate when the operation is complete.
Returns
An xtd::iasync_result object that references the asynchronous send.
Remarks
The asynchronous xtd::net::sockets::udp_client::begin_send operation must be completed by calling the xtd::net::sockets::udp_client::end_send method. Typically, the method is invoked by the callback delegate.
This method does not block until the operation completes. To block until the operation is complete, use one of the xtd::net::sockets::udp_client::send method overloads.

◆ client() [1/2]

xtd::net::sockets::socket xtd::net::sockets::udp_client::client ( ) const
noexcept

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

Returns
The underlying Network xtd::net::sockets::socket.
Remarks
xtd::net::sockets::udp_client creates a xtd::net::sockets::socket used to send and receive data over a network. Classes deriving from xtd::net::sockets::udp_client can use this property to get or set this xtd::net::sockets::socket. Use the underlying xtd::net::sockets::socket returned fromxtd::net::sockets::udp_client::client if you require access beyond that which xtd::net::sockets::udp_client provides. You can also usextd::net::sockets::udp_client::client to set the underlying xtd::net::sockets::socket to an existing xtd::net::sockets::socket. This is useful if you want to take advantage of the simplicity of xtd::net::sockets::udp_client using a pre-existing xtd::net::sockets::socket.

◆ client() [2/2]

udp_client& xtd::net::sockets::udp_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::udp_client creates a xtd::net::sockets::socket used to send and receive data over a network. Classes deriving from xtd::net::sockets::udp_client can use this property to get or set this xtd::net::sockets::socket. Use the underlying xtd::net::sockets::socket returned fromxtd::net::sockets::udp_client::client if you require access beyond that which xtd::net::sockets::udp_client provides. You can also usextd::net::sockets::udp_client::client to set the underlying xtd::net::sockets::socket to an existing xtd::net::sockets::socket. This is useful if you want to take advantage of the simplicity of xtd::net::sockets::udp_client using a pre-existing xtd::net::sockets::socket.

◆ close()

void xtd::net::sockets::udp_client::close ( )

Closes the UDP connection.

Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
Remarks
The xtd::net::sockets::udp_client::close disables the underlying xtd::net::sockets::socket and releases all managed and unmanaged resources associated with the xtd::net::sockets::udp_client.
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() [1/3]

void xtd::net::sockets::udp_client::connect ( const xtd::net::ip_end_point end_point)

Establishes a default remote host using the specified network endpoint.

Parameters
end_pointAn xtd::net::ip_end_point that specifies the network endpoint to which you intend to send data
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::connect method establishes a default remote host using the value specified in the endPoint parameter. Once established, you do not have to specify a remote host in each call to the xtd::net::sockets::udp_client::send method.
Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the xtd::net::sockets::udp_client::connect method or create another xtd::net::sockets::udp_client without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the xtd::net::sockets::udp_client::send method, xtd::net::sockets::udp_client::send will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
If you call the xtd::net::sockets::udp_client::connect method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from xtd::net::sockets::udp_client, use thextd::net::sockets::udp_client::client method to obtain the underlying xtd::net::sockets::socket, and set the socket option to SocketOptionName.Broadcast.
You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify xtd::net::ip_address::broadcast in your call to the xtd::net::sockets::udp_client::send method. If your application requires greater control over broadcast addresses, you can also revert to using the xtd::net::sockets::socket class.
Note
Since the UDP protocol is connectionless, the xtd::net::sockets::udp_client::connect method does not block. Do not call the xtd::net::sockets::udp_client::connect method if you intend to receive multicasted datagrams.
If you receive a xtd::net::sockets::socket_exception, use the xtd::net::sockets::socket_exception::error_code property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error.

◆ connect() [2/3]

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

Establishes a default remote 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 attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::connect method establishes a default remote host using the values specified in the addr and port parameters. Once established, you do not have to specify a remote host in each call to the xtd::net::sockets::udp_client::send method.
Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the xtd::net::sockets::udp_client::connect method or create another xtd::net::sockets::udp_client without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the xtd::net::sockets::udp_client::send method, xtd::net::sockets::udp_client::send will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
If you call the xtd::net::sockets::udp_client::connect method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from xtd::net::sockets::udp_client, use the client method to obtain the underlying xtd::net::sockets::socket, and set the socket option to SocketOptionName.Broadcast.
You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify xtd::net::ip_address::broadcast in your call to the xtd::net::sockets::udp_client::send method. If your application requires greater control over broadcast addresses, you can also revert to using the xtd::net::sockets::socket class.
Note
Since the UDP protocol is connectionless, the xtd::net::sockets::udp_client::connect method does not block. Do not call the xtd::net::sockets::udp_client::connect method if you intend to receive multicasted datagrams.
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::udp_client::connect ( const xtd::ustring hostname,
uint16_t  port 
)

Establishes a default remote host using the specified hostname and port number.

Parameters
hostnamethe hostname to connect to.
portThe port number to which you intend send data
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::connect method establishes a default remote host using the values specified in the addr and port parameters. Once established, you do not have to specify a remote host in each call to the xtd::net::sockets::udp_client::send method.
Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the xtd::net::sockets::udp_client::connect method or create another xtd::net::sockets::udp_client without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the xtd::net::sockets::udp_client::send method, xtd::net::sockets::udp_client::send will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
If you call the xtd::net::sockets::udp_client::connect method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from xtd::net::sockets::udp_client, use the client method to obtain the underlying xtd::net::sockets::socket, and set the socket option to SocketOptionName.Broadcast.
You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify xtd::net::ip_address::broadcast in your call to the xtd::net::sockets::udp_client::send method. If your application requires greater control over broadcast addresses, you can also revert to using the xtd::net::sockets::socket class.
Note
Since the UDP protocol is connectionless, the xtd::net::sockets::udp_client::connect method does not block. Do not call the xtd::net::sockets::udp_client::connect method if you intend to receive multicasted datagrams.
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.

◆ dont_fragment() [1/2]

bool xtd::net::sockets::udp_client::dont_fragment ( ) const

Gets a boolean value that specifies whether the xtd::net::sockets::udp_client allows Internet Protocol (IP) datagrams to be fragmented.

Returns
true if the xtd::net::sockets::udp_client allows datagram fragmentation; otherwise, false. The default is true.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Datagrams require fragmentation when their size exceeds the Maximum Transfer Unit (MTU) of the transmission medium. Datagrams may be fragmented by the sending host or by an intermediate router. If a datagram must be fragmented, and the xtd::net::sockets::socket_option_name::dont_fragment option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram.
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.

◆ dont_fragment() [2/2]

udp_client& xtd::net::sockets::udp_client::dont_fragment ( bool  value)

Sets boolean value that specifies whether the xtd::net::sockets::udp_client allows Internet Protocol (IP) datagrams to be fragmented.

Parameters
valuetrue if the xtd::net::sockets::udp_client allows datagram fragmentation; otherwise, false. The default is true.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Datagrams require fragmentation when their size exceeds the Maximum Transfer Unit (MTU) of the transmission medium. Datagrams may be fragmented by the sending host or by an intermediate router. If a datagram must be fragmented, and the xtd::net::sockets::socket_option_name::dont_fragment option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram.
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.

◆ drop_multicast_group()

void xtd::net::sockets::udp_client::drop_multicast_group ( const xtd::net::ip_address multicast_address)

Leaves a multicast group.

Parameters
multicast_addressThe xtd::net::ip_address of the multicast group to leave.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::drop_multicast_group method withdraws the xtd::net::sockets::udp_client from the multicast group identified by the specified xtd::net::ip_address. After calling the xtd::net::sockets::udp_client::drop_multicast_group method, the underlying xtd::net::sockets::socket sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a xtd::net::sockets::udp_client withdraws from the group, it will no longer be able to receive datagrams sent to that group.
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.

◆ dropo_multicast_group()

void xtd::net::sockets::udp_client::dropo_multicast_group ( const xtd::net::ip_address multicast_address,
uint32_t  if_index 
)

Leaves a multicast group.

Parameters
multicast_addressThe xtd::net::ip_address of the multicast group to leave.
if_indexThe local address of the multicast group to leave.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::drop_multicast_group method withdraws the xtd::net::sockets::udp_client from the multicast group identified by the specified xtd::net::ip_address. After calling the xtd::net::sockets::udp_client::drop_multicast_group method, the underlying xtd::net::sockets::socket sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a xtd::net::sockets::udp_client withdraws from the group, it will no longer be able to receive datagrams sent to that group.
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.

◆ enable_broadcast() [1/2]

bool xtd::net::sockets::udp_client::enable_broadcast ( ) const

Gets a boolean value that specifies whether the xtd::net::sockets::udp_client may send or receive broadcast packets.

Returns
true if the xtd::net::sockets::udp_client allows broadcast packets; otherwise, false. The default is false.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Broadcasting is limited to a specific subnet. You can broadcast to your local subnet by sending a packet to 255.255.255.255; or, you can use the directed broadcast address, which is the network portion of an Internet Protocol (IP) address with all bits set in the host portion. For example, if your IP address is 192.168.1.40 (a Class C address, with the network portion as the first three octets, and the host portion is the last octet), your directed broadcast address is 192.168.1.255.
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.

◆ enable_broadcast() [2/2]

udp_client& xtd::net::sockets::udp_client::enable_broadcast ( bool  value)

Sets a boolean value that specifies whether the xtd::net::sockets::udp_client may send or receive broadcast packets.

Parameters
valuetrue if the xtd::net::sockets::udp_client allows broadcast packets; otherwise, false. The default is false.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Broadcasting is limited to a specific subnet. You can broadcast to your local subnet by sending a packet to 255.255.255.255; or, you can use the directed broadcast address, which is the network portion of an Internet Protocol (IP) address with all bits set in the host portion. For example, if your IP address is 192.168.1.40 (a Class C address, with the network portion as the first three octets, and the host portion is the last octet), your directed broadcast address is 192.168.1.255.
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_receive()

std::vector<byte_t> xtd::net::sockets::udp_client::end_receive ( std::shared_ptr< xtd::iasync_result async_result,
xtd::net::ip_end_point remote_end_point 
)

Ends a pending asynchronous receive.

Parameters
async_resultAn xtd::iasync_result object returned by a call to xtd::net::sockets::udp_client::begin_receive(xtd::async_callback, Object).
remote_end_pointThe specified remote endpoint.
Returns
If successful, an array of bytes that contains datagram data.
Exceptions
argument_exceptionasyncResult was not returned by a call to the xtd::net::sockets::udp_clientt::begin_receive method.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying 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::udp_client::receive 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_send()

size_t xtd::net::sockets::udp_client::end_send ( std::shared_ptr< xtd::iasync_result async_result)

Ends a pending asynchronous send.

Parameters
async_resultAn xtd::iasync_result object returned by a call to xtd::net::sockets::udp_client::begin_send.
Returns
If successful, the number of bytes sent to the xtd::net::sockets::udp_client.
Exceptions
argument_exceptionasyncResult was not returned by a call to the xtd::net::sockets::udp_client::begin_send method.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying 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::udp_client::send 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::udp_client::exclusive_address_use ( ) const

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

Returns
true if the xtd::net::sockets::udp_client allows only one client to use a specific port; otherwise, false. The default is true for Windows Server 2003 and Windows XP Service Pack 2 and later, and false for all other versions.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying 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::udp_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::udp_client.xtd::net::sockets::udp_client(Int32), xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(Int32, xtd::net::sockets::address_family), xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(xtd::net::ip_end_point), or xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(String, Int32), the client port is bound as a side effect of the constructor, and you cannot subsequently set the xtd::net::sockets::udp_client::exclusive_address_use 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]

udp_client& xtd::net::sockets::udp_client::exclusive_address_use ( bool  value)

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

Parameters
valuetrue if the xtd::net::sockets::udp_client allows only one client to use a specific port; otherwise, false. The default is true for Windows Server 2003 and Windows XP Service Pack 2 and later, and false for all other versions.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying 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::udp_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::udp_client.xtd::net::sockets::udp_client(Int32), xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(Int32, xtd::net::sockets::address_family), xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(xtd::net::ip_end_point), or xtd::net::sockets::udp_client.xtd::net::sockets::udp_client(String, Int32), the client port is bound as a side effect of the constructor, and you cannot subsequently set the xtd::net::sockets::udp_client::exclusive_address_use 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.

◆ join_multicast_group() [1/4]

void xtd::net::sockets::udp_client::join_multicast_group ( const xtd::net::ip_address multicast_address)

Adds a xtd::net::sockets::udp_client to a multicast group.

Parameters
multicast_addressThe multicast xtd::net::ip_address of the group you want to join.
Exceptions
argument_exceptionThe IP address is not compatible with the xtd::net::sockets::address_family value that defines the addressing scheme of the socket.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::join_multicast_group method subscribes the xtd::net::sockets::udp_client to a multicast group using the specified xtd::net::ip_address. After calling the xtd::net::sockets::udp_client::join_multicast_group method, the underlying xtd::net::sockets::socket sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, xtd::net::sockets::udp_client will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error. Once the xtd::net::sockets::udp_client is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified xtd::net::ip_address.
Note
You must create the xtd::net::sockets::udp_client using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the xtd::net::sockets::udp_client::connect method prior to calling the xtd::net::sockets::udp_client::join_multicast_group method, or the xtd::net::sockets::udp_client::receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address.
Remarks
Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter.
To stop receiving multicasted datagrams, call the xtd::net::sockets::udp_client::drop_multicast_group method and provide the xtd::net::ip_address of the group from which you would like to withdraw.
Note
In the IPv6 case, there are several multicast address ranges you can choose from. Please, refer to the IETF RFC 2375.
You cannot call xtd::net::sockets::udp_client::join_multicast_group on a xtd::net::sockets::udp_client constructed without a specific local port (that is, using the xtd::net::sockets::udp_client() or xtd::net::sockets::udp_client(xtd::net::sockets::address_family) constructor).
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.

◆ join_multicast_group() [2/4]

void xtd::net::sockets::udp_client::join_multicast_group ( uint32_t  if_index,
const xtd::net::ip_address multicast_address 
)

Adds a xtd::net::sockets::udp_client to a multicast group.

Parameters
if_indexThe interface index associated with the local IP address on which to join the multicast group.
multicast_addressThe multicast xtd::net::ip_address of the group you want to join.
Exceptions
argument_exceptionThe IP address is not compatible with the xtd::net::sockets::address_family value that defines the addressing scheme of the socket.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::join_multicast_group method subscribes the xtd::net::sockets::udp_client to a multicast group using the specified xtd::net::ip_address. After calling the xtd::net::sockets::udp_client::join_multicast_group method, the underlying xtd::net::sockets::socket sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, xtd::net::sockets::udp_client will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error. Once the xtd::net::sockets::udp_client is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified xtd::net::ip_address.
Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter.
The if_index parameter is used to identify a hardware interface on the same link.
Note
There are several multicast address ranges to choose from. Refer to the IETF RFC 2375.
You cannot call xtd::net::sockets::udp_client::join_multicast_group on a xtd::net::sockets::udp_client constructed without a specific local port (that is, using the xtd::net::sockets::udp_client() or xtd::net::sockets::udp_client(xtd::net::sockets::address_family) constructor).
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.

◆ join_multicast_group() [3/4]

void xtd::net::sockets::udp_client::join_multicast_group ( const xtd::net::ip_address multicast_address,
byte_t  ttl 
)

Adds a xtd::net::sockets::udp_client to a multicast group with the specified Time to Live (TTL).

Parameters
multicast_addressThe multicast xtd::net::ip_address of the group you want to join.
ttlThe Time to Live (TTL), measured in router hops.
Exceptions
argument_exceptionThe IP address is not compatible with the xtd::net::sockets::address_family value that defines the addressing scheme of the socket.
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::join_multicast_group method subscribes the xtd::net::sockets::udp_client to a multicast group using the specified xtd::net::ip_address. After calling the xtd::net::sockets::udp_client::join_multicast_group method, the underlying xtd::net::sockets::socket sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, xtd::net::sockets::udp_client will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error. Once the xtd::net::sockets::udp_client is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified xtd::net::ip_address.
Note
You must create the xtd::net::sockets::udp_client using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the xtd::net::sockets::udp_client::connect method prior to calling the xtd::net::sockets::udp_client::join_multicast_group method, or the xtd::net::sockets::udp_client::receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address.
Remarks
Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter.
To stop receiving multicasted datagrams, call the xtd::net::sockets::udp_client::drop_multicast_group method and provide the xtd::net::ip_address of the group from which you would like to withdraw.
Note
You cannot call xtd::net::sockets::udp_client::join_multicast_group on a xtd::net::sockets::udp_client constructed without a specific local port (that is, using the xtd::net::sockets::udp_client() or xtd::net::sockets::udp_client(xtd::net::sockets::address_family) constructor).
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.

◆ join_multicast_group() [4/4]

void xtd::net::sockets::udp_client::join_multicast_group ( const xtd::net::ip_address multicast_address,
const xtd::net::ip_address local_address 
)

Adds a xtd::net::sockets::udp_client to a multicast group.

Parameters
multicast_addressThe multicast xtd::net::ip_address of the group you want to join.
local_addressThe local xtd::net::ip_address.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Before joining a multicast group, make sure the socket is bound to the port or endpoint. You do that by calling one of the constructors that accept a port or an endpoint as a parameter.
Note
There are several multicast address ranges to choose from. Refer to the IETF RFC 2375.
You cannot call xtd::net::sockets::udp_client::join_multicast_group on a xtd::net::sockets::udp_client constructed without a specific local port (that is, using the xtd::net::sockets::udp_client() or xtd::net::sockets::udp_client(xtd::net::sockets::address_family) constructor).
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.

◆ multicast_loopback() [1/2]

bool xtd::net::sockets::udp_client::multicast_loopback ( ) const

Gets a boolean value that specifies whether outgoing multicast packets are delivered to the sending application.

Returns
true if the xtd::net::sockets::udp_client receives outgoing multicast packets; otherwise, false.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Multicast is a scalable method for many-to-many communication on the Internet. If a process subscribes to a multicast address, any packets sent by that process are received by every other process that has subscribed to the multicast 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.

◆ multicast_loopback() [2/2]

udp_client& xtd::net::sockets::udp_client::multicast_loopback ( bool  value)

Sets a boolean value that specifies whether outgoing multicast packets are delivered to the sending application.

Parameters
valuetrue if the xtd::net::sockets::udp_client receives outgoing multicast packets; otherwise, false.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
Multicast is a scalable method for many-to-many communication on the Internet. If a process subscribes to a multicast address, any packets sent by that process are received by every other process that has subscribed to the multicast 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.

◆ receive()

std::vector<byte_t> xtd::net::sockets::udp_client::receive ( xtd::net::ip_end_point remote_end_point)

Returns a UDP datagram that was sent by a remote host.

Parameters
remote_end_pointAn xtd::net::ip_end_point that represents the remote host from which the data was sent.
Returns
An array of type Byte that contains datagram data.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::receive method will block until a datagram arrives from a remote host. When data is available, the xtd::net::sockets::udp_client::receive method will read the first enqueued datagram and return the data portion as a byte array. This method populates the remoteEP parameter with the xtd::net::ip_address and port number of the sender.
If you specify a default remote host in the xtd::net::sockets::udp_client::connect method, the xtd::net::sockets::udp_client::receive method will accept datagrams from that host only. All other datagrams will be discarded.
If you receive a xtd::net::sockets::socket_exception, use xtd::net::sockets::socket_exception.ErrorCode to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
Note
If you intend to receive multicasted datagrams, do not call the xtd::net::sockets::udp_client::connect method prior to calling the xtd::net::sockets::udp_client::receive method. The xtd::net::sockets::udp_client you use to receive datagrams must be created using the multicast 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.

◆ send() [1/3]

size_t xtd::net::sockets::udp_client::send ( const std::vector< byte_t > &  dgram,
size_t  bytes,
const xtd::ustring hostname,
uint16_t  port 
)

xtd::net::sockets::udp_client::sends a UDP datagram to a specified port on a specified remote host.

Parameters
dgramAn array of type Byte that specifies the UDP datagram that you intend to send represented as an array of bytes.
bytesThe number of bytes in the datagram.
hostnameThe name of the remote host to which you intend to send the datagram.
portThe remote port number with which you intend to communicate.
Returns
The number of bytes sent.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::send method sends datagrams to the values specified by the hostname and port parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the hostname parameter value.
If you want to send datagrams to any other broadcast address, use thextd::net::sockets::udp_client::client method to obtain the underlying xtd::net::sockets::socket, and set the socket option to SocketOptionName.Broadcast. You can also revert to using the xtd::net::sockets::socket class.
Note
Do not provide a host name or port number to this method if you have already established a remote host with the xtd::net::sockets::udp_client::connect method. If you do, the xtd::net::sockets::udp_client::send method will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
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.

◆ send() [2/3]

size_t xtd::net::sockets::udp_client::send ( const std::vector< byte_t > &  dgram,
size_t  bytes,
const xtd::net::ip_end_point end_point 
)

xtd::net::sockets::udp_client::sends a UDP datagram to the host at the specified remote endpoint.

Parameters
dgramAn array of type Byte that specifies the UDP datagram that you intend to send, represented as an array of bytes.
bytesThe number of bytes in the datagram.
end_pointAn xtd::net::ip_end_point that represents the host and port to which to send the datagram.
Returns
The number of bytes sent.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The xtd::net::sockets::udp_client::send method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an xtd::net::ip_end_point using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying SocketOptionName.Broadcast for the Address property of the xtd::net::ip_end_point. After you have created this xtd::net::ip_end_point, pass it to the xtd::net::sockets::udp_client::send method as the endPoint parameter.
If you want to send datagrams to any other broadcast address, use thextd::net::sockets::udp_client::client method to obtain the underlying xtd::net::sockets::socket, and set the socket option to SocketOptionName.Broadcast. You can also revert to using the xtd::net::sockets::socket class.
Do not provide an endPoint parameter to this method if you have already established a remote host with the xtd::net::sockets::udp_client::connect method. If you do, the xtd::net::sockets::udp_client::send method will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
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.

◆ send() [3/3]

size_t xtd::net::sockets::udp_client::send ( const std::vector< byte_t > &  dgram,
size_t  bytes 
)

xtd::net::sockets::udp_client::sends a UDP datagram to a remote host.

Parameters
dgramAn array of type Byte that specifies the UDP datagram that you intend to send represented as an array of bytes.
bytesThe number of bytes in the datagram.
Returns
The number of bytes sent.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
This overload sends datagrams to the remote host established in the xtd::net::sockets::udp_client::connect method and returns the number of bytes sent. If you do not call xtd::net::sockets::udp_client::connect before calling this overload, the xtd::net::sockets::udp_client::send method will 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. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.
If you want to send datagrams to a different remote host, you must call the xtd::net::sockets::udp_client::connect method and specify the desired remote host. Use either of the other xtd::net::sockets::udp_client::send method overloads to send datagrams to a broadcast 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.

◆ ttl() [1/2]

byte_t xtd::net::sockets::udp_client::ttl ( ) const

Gets a value that specifies the Time to Live (TTL) value of Internet Protocol (IP) packets sent by the xtd::net::sockets::udp_client.

Returns
The TTL value.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The TTL value indicates the maximum number of routers a packet can traverse before the router discards the packet and an Internet Control Message Protocol (ICMP) "TTL exceeded" error message is returned to the sender.
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.

◆ ttl() [2/2]

udp_client& xtd::net::sockets::udp_client::ttl ( byte_t  value)

Sets a value that specifies the Time to Live (TTL) value of Internet Protocol (IP) packets sent by the xtd::net::sockets::udp_client.

Parameters
valueThe TTL value.
Returns
This current instance.
Exceptions
xtd::net::sockets::socket_exceptionAn error occurred when attempting to access the underlying socket.
xtd::object_closed_exceptionThe underlying xtd::net::sockets::socket has been closed.
Remarks
The TTL value indicates the maximum number of routers a packet can traverse before the router discards the packet and an Internet Control Message Protocol (ICMP) "TTL exceeded" error message is returned to the sender.
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.

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