Rtos API example
multicast_api.h File Reference
Multicast Trickle Forwarding API. More...
Go to the source code of this file.
Enumerations | |
enum | multicast_mpl_seed_id_mode_e { , MULTICAST_MPL_SEED_ID_MAC_SHORT = -1, MULTICAST_MPL_SEED_ID_MAC = -2, MULTICAST_MPL_SEED_ID_IID_EUI64 = -3, MULTICAST_MPL_SEED_ID_IID_SLAAC = -4, MULTICAST_MPL_SEED_ID_IPV6_SRC_FOR_DOMAIN = 0, MULTICAST_MPL_SEED_ID_16_BIT = 2, MULTICAST_MPL_SEED_ID_64_BIT = 8, MULTICAST_MPL_SEED_ID_128_BIT = 16 } |
Control selection of MPL Seed Identifier for packets we originate. More... | |
Functions | |
void | multicast_set_parameters (uint8_t i_min, uint8_t i_doublings, uint8_t k, uint8_t timer_expirations, uint16_t window_expiration) |
Set new parameters for trickle multicast. | |
uint8_t | multicast_add_address (const uint8_t *address_ptr, uint8_t use_trickle) |
Add new address to multicast group. | |
uint8_t | multicast_free_address (const uint8_t *address_ptr) |
Free address from multicast group. | |
int_fast8_t | multicast_mpl_treat_realm_domains_as_one (int8_t interface_id, bool enable) |
Treat all Realm-local Domains as one. | |
int_fast8_t | multicast_mpl_set_default_parameters (int8_t interface_id, bool proactive_forwarding, uint16_t seed_set_entry_lifetime, uint32_t data_message_imin, uint32_t data_message_imax, uint8_t data_message_k, uint8_t data_message_timer_expirations, uint32_t control_message_imin, uint32_t control_message_imax, uint8_t control_message_k, uint8_t control_message_timer_expirations) |
Set default MPL Domain parameters. | |
int_fast8_t | multicast_mpl_set_default_seed_id (int8_t interface_id, multicast_mpl_seed_id_mode_e seed_id_mode, const void *seed_id) |
Set default MPL Seed Identifier. | |
int8_t | multicast_mpl_domain_subscribe (int8_t interface_id, const uint8_t address[16], multicast_mpl_seed_id_mode_e seed_id_mode, const void *seed_id) |
Subscribe to an MPL Domain (RFC 7731) | |
int8_t | multicast_mpl_domain_subscribe_with_parameters (int8_t interface_id, const uint8_t address[16], multicast_mpl_seed_id_mode_e seed_id_mode, const void *seed_id, bool proactive_forwarding, uint16_t seed_set_entry_lifetime, uint32_t data_message_imin, uint32_t data_message_imax, uint8_t data_message_k, uint8_t data_message_timer_expirations, uint32_t control_message_imin, uint32_t control_message_imax, uint8_t control_message_k, uint8_t control_message_timer_expirations) |
Subscribe to an MPL Domain (RFC 7731) | |
int8_t | multicast_mpl_domain_unsubscribe (int8_t interface_id, const uint8_t address[16]) |
Unsubscribe from an MPL Domain. | |
int8_t | multicast_fwd_add (int8_t interface_id, const uint8_t group[16], uint32_t lifetime) |
Add multicast forwarding record to an interface. | |
int8_t | multicast_fwd_remove (int8_t interface_id, const uint8_t group[16]) |
Remove multicast forwarding record from an interface. | |
int8_t | multicast_fwd_full_for_scope (int8_t interface_id, uint_fast8_t min_scope) |
Set full multicast forwarding. | |
int8_t | multicast_fwd_set_proxy_upstream (int8_t interface_id) |
Set upstream interface for MLD proxying. |
Detailed Description
Multicast Trickle Forwarding API.
Init API:
- multicast_set_parameters(), Set trickle parameters.
Configure API:
- multicast_add_address(), Add new address to a multicast group and control trickle forwarding.
- multicast_free_address(), Remove supported multicast address from list.
Trickle Setups for Multicast Init
| Parameter | VALUE | | :---------------: | :---: | | imin | 10 | | imax | 0 | | k | 20 | | timer_expirations | 3 | | window_expiration | 75 |
Definition in file multicast_api.h.
Enumeration Type Documentation
Control selection of MPL Seed Identifier for packets we originate.
- Enumerator:
Definition at line 148 of file multicast_api.h.
Function Documentation
uint8_t multicast_add_address | ( | const uint8_t * | address_ptr, |
uint8_t | use_trickle | ||
) |
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.
uint8_t multicast_free_address | ( | const uint8_t * | address_ptr ) |
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.
int8_t multicast_fwd_add | ( | int8_t | interface_id, |
const uint8_t | group[16], | ||
uint32_t | lifetime | ||
) |
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
int8_t multicast_fwd_full_for_scope | ( | int8_t | interface_id, |
uint_fast8_t | min_scope | ||
) |
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
int8_t multicast_fwd_remove | ( | int8_t | interface_id, |
const uint8_t | group[16] | ||
) |
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
int8_t multicast_fwd_set_proxy_upstream | ( | int8_t | interface_id ) |
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
int8_t multicast_mpl_domain_subscribe | ( | int8_t | interface_id, |
const uint8_t | address[16], | ||
multicast_mpl_seed_id_mode_e | seed_id_mode, | ||
const void * | seed_id | ||
) |
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
int8_t multicast_mpl_domain_subscribe_with_parameters | ( | int8_t | interface_id, |
const uint8_t | address[16], | ||
multicast_mpl_seed_id_mode_e | seed_id_mode, | ||
const void * | seed_id, | ||
bool | proactive_forwarding, | ||
uint16_t | seed_set_entry_lifetime, | ||
uint32_t | data_message_imin, | ||
uint32_t | data_message_imax, | ||
uint8_t | data_message_k, | ||
uint8_t | data_message_timer_expirations, | ||
uint32_t | control_message_imin, | ||
uint32_t | control_message_imax, | ||
uint8_t | control_message_k, | ||
uint8_t | control_message_timer_expirations | ||
) |
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.
int8_t multicast_mpl_domain_unsubscribe | ( | int8_t | interface_id, |
const uint8_t | address[16] | ||
) |
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
int_fast8_t multicast_mpl_set_default_parameters | ( | int8_t | interface_id, |
bool | proactive_forwarding, | ||
uint16_t | seed_set_entry_lifetime, | ||
uint32_t | data_message_imin, | ||
uint32_t | data_message_imax, | ||
uint8_t | data_message_k, | ||
uint8_t | data_message_timer_expirations, | ||
uint32_t | control_message_imin, | ||
uint32_t | control_message_imax, | ||
uint8_t | control_message_k, | ||
uint8_t | control_message_timer_expirations | ||
) |
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
int_fast8_t multicast_mpl_set_default_seed_id | ( | int8_t | interface_id, |
multicast_mpl_seed_id_mode_e | seed_id_mode, | ||
const void * | seed_id | ||
) |
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
int_fast8_t multicast_mpl_treat_realm_domains_as_one | ( | int8_t | interface_id, |
bool | enable | ||
) |
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
void multicast_set_parameters | ( | uint8_t | i_min, |
uint8_t | i_doublings, | ||
uint8_t | k, | ||
uint8_t | timer_expirations, | ||
uint16_t | window_expiration | ||
) |
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.
Generated on Sun Jul 17 2022 08:25:35 by 1.7.2