Jump to main content

##

# 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

Parameters | Description
--- | ---
socket | The UDP multicast socket.
hNet | Interface handle. if hNet == 0, then the default interface will be used.
mcastAddress | The multicast address to subscribe to. It has to be within the IANA specified multicast address range.
filterMode | File type required for this subscription: include/exclude.
sourceList | Array of destination sources for which the socket is supposed to listen (filer is include) or is not interested in (filter is exclude).
listSize | The 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.