join_multicast_group() [3/4]

void xtd::net::sockets::udp_client::join_multicast_group	(	const xtd::net::ip_address &	multicast_address,
		xtd::byte	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.