getsourcefilter

Jump to: navigation, search

Table of Contents >> IPv6 Programmer's Reference >> MLDv2


#include <trsocket.h>


int getsourcefilter (
int sd,
ttUser32Bit ifindex,
struct sockaddr TM_FAR * group,
unsigned int grouplen,
ttUser32BitPtr fmodePtr,
unsigned int TM_FAR * numsrcPtr,
struct sockaddr_storage TM_FAR * slist
);


Function Description

This function API allows the user to retrieve the source address filter list for a given socket, interface, and multicast source address. This function supports IPv4 (IGMPv3) and IPv6 (MLDv2).


Parameters

  • sd
    The socket descriptor.
  • ifindex
    Index of the corresponding configured interface as returned by if_nametoindex(). Note that a zero index is valid if the user has either designated a default multicast interface for the socket via the IP_MULTICAST_IF or IPV6_MULTICAST_IF socket options, or designated a default multicast interface for the system via tfSetMcastInterface() or tf6SetMcastInterface().
  • group
    Destination multicast group address (IPv4 or IPv6).
  • grouplen
    The size of the structure pointed to by group.
  • fmodePtr
    Points to a 32-bit integer that will contain the filter mode upon a successful return. The value of this field will either be MCAST_INCLUDE or MCAST_EXCLUDE.
  • numsrcPtr
    On input, the numsrcPtr argument holds the number of source addresses that will fit in the slist array. On output, the numsrcPtr argument will hold the actual number of sources in the filter. If the application does not know the size of the source list beforehand, it can make a guess (e.g., 0), and if upon completion, numsrcPtr points to a larger value, the operation can be repeated with a large enough buffer. That is, on return, numsrcPtr is always updated to point to the actual number of sources in the filter, while slist will hold as many source addresses as will fit, up to the minimum of the array size passed in as the original numsrc value and the total number of sources in the filter.
  • slist
    Points to a buffer into which an array of IPv4 or IPv6 addresses of included or excluded (depending on the filter mode) sources will be written. If numsrcPtr points to the value 0 on input, a NULL pointer may be supplied.


Return Values

  • TM_ENOERROR
    Success
  • TM_SOCKET_ERROR
    Failure


Note Note: TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.

To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).


Possible socket errors

  • TM_EBADF
    The socket descriptor is invalid.
  • TM_EINVAL
    The operation is not legal on the group. For example fmode contains a value other than MCAST_INCLUDE or MCAST_EXCLUDE.
  • TM_EPROTOTYPE
    The socket is not of type SOCK_DGRAM or SOCK_RAW.
  • TM_EADDRNOTAVAIL
    Address is invalid. Here are a few examples:
  • No interface at the specified index.
  • A source address is invalid.
  • The group address is not multicast.
  • The group address is not joined.
  • TM_ENOBUFS
    No memory for operation, most probably because the maximum number of filters has been reached.
  • TM_EAFNOSUPPORT
    Address family is unsupported (IGMPv3 or MLDv2 must be present, depending on the address family).


Table of Contents >> IPv6 Programmer's Reference >> MLDv2