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:

• Create an instance of the xtd::net::sockets::udp_client class using the remote host name and port number as parameters.
• Create an instance of the xtd::net::sockets::udp_client class and then call the xtd::net::sockets::udp_client::connect method.

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([&] {
    udp_client udp(ip_end_point(ip_address::any, 9400));
    
    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([&] {
    udp_client udp;
    
    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));
  });
  
  console::read_key();
  terminate_app = true;
  server.join();
  client.join();
}
 
// This code produces the following output:
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...

Examples

The following example shows how to use IPv6 xtd::net::sockets::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([&] {
    udp_client udp(ip_end_point(ip_address::ip_v6_any, 9400));
    
    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([&] {
    udp_client udp(address_family::inter_network_v6);
    
    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));
  });
  
  console::read_key();
  terminate_app = true;
  server.join();
  client.join();
}
 
// This code produces the following output:
//
// counter=1
// counter=2
// counter=3
// counter=4
// counter=5
// ...

Inherits xtd::object.

Public Member Functions
	udp_client ()
	Initializes a new instance of the xtd::net::sockets::udp_client class. 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 (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...
	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 (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 (xtd::net::sockets::address_family address_Family)
	Initializes a new instance of the xtd::net::sockets::udp_client class. 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_result >	begin_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_result >	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. More...
std::shared_ptr< xtd::iasync_result >	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. More...
std::shared_ptr< xtd::iasync_result >	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. More...
xtd::net::sockets::socket	client () const noexcept
	Gets the underlying network xtd::net::sockets::socket. More...
udp_client &	client (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_address &ip_address, uint16_t port)
	Establishes a default remote host using the specified IP address and port number. 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::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_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. More...
void	drop_multicast_group (const xtd::net::ip_address &multicast_address)
	Leaves a multicast group. More...
void	drop_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_client &	enable_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_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. 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 (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...
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...
bool	multicast_loopback () const
	Gets a boolean value that specifies whether outgoing multicast packets are delivered to the sending application. More...
udp_client &	multicast_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)
	xtd::net::sockets::udp_client::sends a UDP datagram to a 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, 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...
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_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. 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_client &	active (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_exception

An 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

port	The local port number from which you intend to communicate.

Exceptions

xtd::net::sockets::socket_exception

An 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_point

An xtd::net::ip_end_point that represents the local endpoint to which you bind the UDP connection.

Exceptions

xtd::net::sockets::socket_exception

An 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_family

one of the xtd::net::sockets::address_family values that specifies the addressing scheme of the socket.

Exceptions

xtd::argument_exception	family is not xtd::net::sockets::address_family::inter_network or xtd::net::sockets::address_family::inter_network_v6.
xtd::net::sockets::socket_exception	An 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

port	The port on which to listen for incoming connection attempts.
address_family	One of the xtd::net::sockets::address_family values that specifies the addressing scheme of the socket.

Exceptions

xtd::argument_exception	family is not xtd::net::sockets::address_family::inter_network or xtd::net::sockets::address_family::inter_network_v6.
xtd::net::sockets::socket_exception	An 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

hostname	The name of the remote DNS host to which you intend to connect.
port	The remote port number to which you intend to connect.

Exceptions

xtd::net::sockets::socket_exception

An 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

value

bool 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

allowed

A boolean value that specifies whether to enable or disable NAT traversal.

Exceptions

xtd::net::sockets::socket_exception

An 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the 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::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

dgram	A byte array that contains the data to be sent.
bytes	The number of bytes to send.
end_point	The EndPoint that represents the destination for the data.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the 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::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

dgram	A byte array that contains the data to be sent.
bytes	The number of bytes to send.
hostname	The destination host.
port	The destination port number.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the 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

dgram	A byte array that contains the data to be sent.
bytes	The number of bytes to send.
callback	An xtd::async_callback delegate that references the method to invoke when the operation is complete.
state	A user-defined object that contains information about the 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 from::net::sockets::udp_client::client if you require access beyond that which xtd::net::sockets::udp_client provides. You can also use xtd::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

value

The 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 from xtd::net::sockets::udp_client::client if you require access beyond that which xtd::net::sockets::udp_client provides. You can also use xtd::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_exception

An 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_address &	ip_address,
		uint16_t	port
	)

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

Parameters

ip_address	The xtd::net::ip_address of the remote host to which you intend to send data
port	The port number to which you intend send data

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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() [2/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_point

An xtd::net::ip_end_point that specifies the network endpoint to which you intend to send data

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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 the xtd::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() [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

hostname	the hostname to connect to.
port	The port number to which you intend send data

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

value

true 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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() [1/2]

void xtd::net::sockets::udp_client::drop_multicast_group

(

const xtd::net::ip_address &

multicast_address

)

Leaves a multicast group.

Parameters

multicast_address

The xtd::net::ip_address of the multicast group to leave.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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.

drop_multicast_group() [2/2]

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

Leaves a multicast group.

Parameters

multicast_address	The xtd::net::ip_address of the multicast group to leave.
if_index	The local address of the multicast group to leave.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

value

true 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_result	An xtd::iasync_result object returned by a call to xtd::net::sockets::udp_client::begin_receive(xtd::async_callback, Object).
remote_end_point	The specified remote endpoint.

Returns

If successful, an array of bytes that contains datagram data.

Exceptions

argument_exception	asyncResult was not returned by a call to the xtd::net::sockets::udp_client::begin_receive method.
xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_result

An 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_exception	asyncResult was not returned by a call to the xtd::net::sockets::udp_client::begin_send method.
xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

value

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.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_address

The multicast xtd::net::ip_address of the group you want to join.

Exceptions

argument_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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	(	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_address	The multicast xtd::net::ip_address of the group you want to join.
ttl	The Time to Live (TTL), measured in router hops.

Exceptions

argument_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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() [3/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_address	The multicast xtd::net::ip_address of the group you want to join.
local_address	The local xtd::net::ip_address.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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.

join_multicast_group() [4/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_index	The interface index associated with the local IP address on which to join the multicast group.
multicast_address	The multicast xtd::net::ip_address of the group you want to join.

Exceptions

argument_exception	The 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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.

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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

value

true if the xtd::net::sockets::udp_client receives outgoing multicast packets; otherwise, false.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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_point

An 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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
	)

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

Parameters

dgram	An array of type Byte that specifies the UDP datagram that you intend to send represented as an array of bytes.
bytes	The number of bytes in the datagram.

Returns

The number of bytes sent.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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.

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

dgram	An array of type Byte that specifies the UDP datagram that you intend to send, represented as an array of bytes.
bytes	The number of bytes in the datagram.
end_point	An 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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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 the xtd::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,
		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

dgram	An array of type Byte that specifies the UDP datagram that you intend to send represented as an array of bytes.
bytes	The number of bytes in the datagram.
hostname	The name of the remote host to which you intend to send the datagram.
port	The remote port number with which you intend to communicate.

Returns

The number of bytes sent.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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 the xtd::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.

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_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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

value

The TTL value.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	An error occurred when attempting to access the underlying socket.
xtd::object_closed_exception	The 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:

• xtd.core/include/xtd/net/sockets/udp_client.h