Export (0) Print
Expand All

UdpClient.JoinMulticastGroup Method (IPAddress, Int32)

Adds a UdpClient to a multicast group with the specified Time to Live (TTL).

Namespace:  System.Net.Sockets
Assembly:  System (in System.dll)

public void JoinMulticastGroup(
	IPAddress multicastAddr,
	int timeToLive
)

Parameters

multicastAddr
Type: System.Net.IPAddress

The IPAddress of the multicast group to join.

timeToLive
Type: System.Int32

The Time to Live (TTL), measured in router hops.

ExceptionCondition
ArgumentOutOfRangeException

The TTL provided is not between 0 and 255

ObjectDisposedException

The underlying Socket has been closed.

SocketException

An error occurred when accessing the socket. See the Remarks section for more information.

ArgumentNullException

multicastAddr is null.

ArgumentException

The IP address is not compatible with the AddressFamily value that defines the addressing scheme of the socket.

The JoinMulticastGroup method subscribes the UdpClient to a multicast group using the specified IPAddress. After calling the JoinMulticastGroup method, the underlying 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, UdpClient will throw a SocketException. If you receive a SocketException, use SocketException.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 in MSDN for a detailed description of the error. The timeToLive parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the UdpClient is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified IPAddress.

NoteNote

You must create the UdpClient using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the Connect method prior to calling the JoinMulticastGroup method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast 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 as parameter a port or an endpoint.

To stop receiving multicasted datagrams, call the DropMulticastGroup method and provide the IPAddress of the group from which you would like to withdraw.

NoteNote

You cannot call JoinMulticastGroup on a UdpClient constructed without a specific local port (that is, using the UdpClient() or UdpClient(AddressFamily) constructor).

The following example demonstrates how to join a multicast group by providing two parameters, a multicast address, and a number that represents the TTL.

UdpClient udpClient = new UdpClient();
// Creates an IPAddress to use to join and drop the multicast group.
IPAddress multicastIpAddress = IPAddress.Parse("239.255.255.255");

try{
     // The packet dies after 50 router hops.
     udpClient.JoinMulticastGroup(multicastIpAddress, 50);
}
catch ( Exception e ){
    Console.WriteLine( e.ToString());
}

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft