TCPIP_IGMP_Subscribe Function

C

TCPIP_IGMP_RESULT TCPIP_IGMP_Subscribe(
    UDP_SOCKET socket, 
    TCPIP_NET_HANDLE hNet, 
    IPV4_ADDR mcastAddress, 
    TCPIP_IGMP_FILTER_TYPE filterMode, 
    const IPV4_ADDR* sourceList, 
    size_t* listSize
);

Description

This function performs the subscription of a UDP socket to multicast traffic. Following this call, the IGMP module will inform network routers of this host desire to take part in multicast traffic.

Preconditions

The IGMP module must be initialized.

Parameters

ParametersDescription
socketThe UDP multicast socket.
hNetInterface handle. if hNet == 0, then the default interface will be used.
mcastAddressThe multicast address to subscribe to. It has to be within the IANA specified multicast address range.
filterModeFile type required for this subscription: include/exclude.
sourceListArray of destination sources for which the socket is supposed to listen (filer is include) or is not interested in (filter is exclude).
listSizeThe number of sources in the sourceList array. On input, if listSize == 0 or *listSize == 0, then no sources will be considered and sourceList will be ignored. On output, if listSize != 0, it will contain the number of new sources added/removed.

Returns

  • TCPIP_IGMP_OK - if operation succeeded. An error code otherwise.

Remarks

The function supports both SSM (Source Specific Multicast) and ASM (Any Source Multicast) functionality.

Subscribe(skt, INCLUDE, {a,b}) and then Subscribe(skt, INCLUDE, {c, d}) is legal and will just add new sources to include. Subscribe(skt, EXCLUDE, {a, b}) and then Subscribe(skt, EXCLUDE, {c, d}) is also legal and will just exclude new sources.

However, Subscribe(skt, INCLUDE, {a, b}) and then Subscribe(sky, EXCLUDE, {c, d}) will change the socket filter mode and old sources will be removed. Same for Subscribe(skt, EXCLUDE, {a,b}) and then Subscribe(skt, INCLUDE, {c, d}).

Subscribe(skt, INCLUDE, {}) will remove all subscriptions for the socket .

For SSM sources, the EXCLUDE mode is not allowed.