multicast_api.h File Reference

Control selection of MPL Seed Identifier for packets we originate.

Enumerator:

MULTICAST_MPL_SEED_ID_MAC_SHORT	Default selection (used to make a domain use the interface's default)
MULTICAST_MPL_SEED_ID_MAC	Use short MAC address if available (eg IEEE 802.15.4 interface's macShortAddress (16-bit)), else full MAC.
MULTICAST_MPL_SEED_ID_IID_EUI64	Use MAC padded to 64-bit (eg IEEE 802.15.4 interface's macExtendedAddress, or 48-bit Ethernet MAC followed by 2 zero pad bytes)
MULTICAST_MPL_SEED_ID_IID_SLAAC	Use 64-bit IPv6 IID based on EUI-64 (eg 02:11:22:ff:fe:00:00:00 for an Ethernet interface with MAC 00:11:22:00:00:00)
MULTICAST_MPL_SEED_ID_IPV6_SRC_FOR_DOMAIN	Use 64-bit IPv6 IID that would be used for SLAAC.
MULTICAST_MPL_SEED_ID_16_BIT	Use IPv6 source address selection to choose 128-bit Seed ID based on MPL Domain Address as destination.
MULTICAST_MPL_SEED_ID_64_BIT	Use a manually-specified 16-bit ID.
MULTICAST_MPL_SEED_ID_128_BIT	Use a manually-specified 64-bit ID.

Definition at line 148 of file multicast_api.h.

Add new address to multicast group.

Parameters:

address_ptr	Pointer to a 16-byte array that includes the address to be added.
use_trickle	0 = no trickle multicast forwarding, all other values = trickle multicast forwarding will be used with this address.

Returns:

0 General error.

1 Address updated.

2 Address added.

255 Link local not allowed when using multicast.

Free address from multicast group.

Parameters:

address_ptr

Pointer to a 16-byte array that includes the address to be removed.

Returns:

0 will be returned on successful execution, other values indicate an error on removing the address.

Add multicast forwarding record to an interface.

This adds a group to the forwarding list on the specified interface. Received multicast packets sent to the specified group will be forwarded onto the specified interface from other interfaces, if IP forwarding is enabled on both incoming and outgoing interfaces, subject to a Reverse Path Forwarding check on the source address, and usual scope rules.

If a finite lifetime is set, the record will be removed after that many seconds.

If an entry for the specified group already exists, its lifetime will increased if it is lower than the value passed.

Parameters:

interface_id	interface id
group	IPv6 multicast group address
lifetime	The time in seconds to maintain the forwarding entry - 0xFFFFFFFF means infinite

Returns:

0 for success, negative on failure

Set full multicast forwarding.

If enabled, all multicast packets of specified scope or greater will be forwarded onto the specified interface from other interfaces, if IP forwarding is enabled on both incoming and outgoing interfaces, subject to a Reverse Path Forwarding check on the source address.

Setting this is equivalent to "multicast_fwd_add" being called for all addresses with scope >= min_scope.

This functionality is disabled by setting min_scope to 0x10 or greater (so no packets can match).

Parameters:

interface_id	interface id
min_scope	minimum IPv6 scope value for forwarding (see RFC 4291)

Returns:

0 for success, negative on failure

Remove multicast forwarding record from an interface.

Delete a a group from the forwarding list on the specified interface.

Parameters:

interface_id	interface id
group	IPv6 multicast group address

Returns:

0 for success, negative on failure

Set upstream interface for MLD proxying.

This sets the upstream interface for MLD proxying. If set, the stack will report group membership on that interface according to the forwarding lists of the other interfaces (ie it will send MLD reports or equivalent on that upstream interface).

Parameters:

interface_id

interface id, or -1 to disable

Returns:

0 for success, negative on failure

Subscribe to an MPL Domain (RFC 7731)

This subscribes to an MPL Domain with default parameters on the specified interface. (At present there is no support for subscribing to the same Domain on multiple interfaces)

If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed to, this will automatically also subscribe to it with default parameters.

Once 1 or more MPL Domains have been subscribed to on an interface, multicast transmissions sent to a group with scope greater than link-local on that interface will be sent using MPL.

If the destination corresponds to a subscribed MPL Domain, it will be sent to that MPL Domain (and hence forwarded only by other subscribers to that domain).

If the destination does not correspond to a subscribed MPL Domain, it will be tunnelled, with the outer IP packet sent to the ALL_MPL_FORWARDERS Domain.

Typical behaviour for ZigBee IP and Thread networks would be achieved by subscribing to ff03::1, and enabling realm auto-subscription - [this is done automatically when calling multicast_add_address?]

Parameters:

interface_id	interface id
address	MPL Domain Address (IPv6 multicast address)
seed_id_mode	Seed ID selection mode
seed_id	For positive (constant) types, pointer to Seed ID data

Returns:

0 for success, negative on failure

Subscribe to an MPL Domain (RFC 7731)

This subscribes to an MPL Domain with default parameters on the specified interface.

If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed to, this will automatically also subscribe to it with default parameters.

See multicast_mpl_subscribe_domain and multicast_set_default_parameters for more information on parameters.

Unsubscribe from an MPL Domain.

This subscribes from a previously-subscribed MPL Domain

Parameters:

interface_id	interface id
address	MPL Domain Address (IPv6 multicast address)

Returns:

0 for success, negative on failure

Set default MPL Domain parameters.

Modifies the default parameters for MPL Domains using the specified interface.

This must be set before subscribing to any MPL Domains with default parameters on that interface.

Initial defaults are as specified by RFC 7731.

Parameters:

interface_id	interface id
proactive_forwarding	true to forward Data Messages when first received (default true)
seed_set_entry_lifetime	minimum seed set lifetime (seconds, default 1800 = 30 minutes)
data_message_imin	minimum Trickle timer for Data Messages (ms, default ~= 10 * expected link latency)
data_message_imax	maximum Trickle timer for Data Messages (ms, default = Imin)
data_message_k	Trickle redundancy constant for Data Messages (default = 1)
data_message_timer_expirations	controls termination of retransmissions (default = 3)
control_message_imin	minimum Trickle timer for Control Messages (ms, default ~= 10 * worst-case link latency)
control_message_imax	maximum Trickle timer for Control Messages (ms, default = 5 minutes)
control_message_k	Trickle redundancy constant for Control Messages (default = 1)
control_message_timer_expirations	controls termination of retransmissions (default = 10); 0 disables control messages

Returns:

0 for success, negative on failure

Set default MPL Seed Identifier.

Sets the default MPL Seed Identifier used when acting as an MPL Seed.

Parameters:

interface_id	interface id
seed_id_mode	Seed ID selection mode
seed_id	For positive (constant) types, pointer to Seed ID data

Returns:

0 for success, negative on failure

Treat all Realm-local Domains as one.

If enabled on an interface, then all Realm-local scope multicasts will be treated as if belonging to the All-MPL-Forwarders domain, rather than the domain indicated by their destination address. This is non-standard behaviour, not covered by the real MPL specification, but required by the Thread specification.

All devices in a realm should have this setting set the same. With the setting on, reactive forwarding and control messages will not work.

With this setting on, Realm-scope domains other than All-MPL-Forwarders cannot be joined.

This must be set before bringing up an interface, and then not be modified.

Parameters:

interface_id	interface id
enable	true to enable domain unification

Returns:

0 for success, negative on failure

Set new parameters for trickle multicast.

Parameters:

i_min	Minimum trickle timer interval in 50ms resolution: Imin = i_min * 50ms.
i_doublings	Maximum trickle timer interval expressed as number of doublings of the minimum interval.
k	Redundancy constant.
timer_expirations	Number of trickle timer expirations before terminating the trickle process.
window_expiration	The time window for keeping the state after the end of trickle process in 50ms resolution. NOTE: If window_expiration value is set too small an infinite retransmission loop may occur when using the trickle multicast.