Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
multicast_api.h
00001 /* 00002 * Copyright (c) 2012-2018, Arm Limited and affiliates. 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 #ifndef MULTICAST_API_H_ 00018 #define MULTICAST_API_H_ 00019 /** 00020 * \file multicast_api.h 00021 * \brief Multicast Trickle Forwarding API. 00022 * \section multi-init Init API: 00023 * - multicast_set_parameters(), Set trickle parameters. 00024 * \section multi-cnf Configure API: 00025 * - multicast_add_address(), Add new address to a multicast group and control trickle forwarding. 00026 * - multicast_free_address(), Remove supported multicast address from list. 00027 * 00028 * \section ZigBeeIP Trickle Setups for Multicast Init 00029 * 00030 * | Parameter | VALUE | 00031 * | :---------------: | :---: | 00032 * | imin | 10 | 00033 * | imax | 0 | 00034 * | k | 20 | 00035 * | timer_expirations | 3 | 00036 * | window_expiration | 75 | 00037 * 00038 */ 00039 00040 #include "ns_types.h" 00041 00042 #ifdef __cplusplus 00043 extern "C" { 00044 #endif 00045 00046 /** 00047 * \brief Set new parameters for trickle multicast. 00048 * \deprecated 00049 * 00050 * \param i_min Minimum trickle timer interval in 50ms resolution: Imin = i_min * 50ms. 00051 * \param i_doublings Maximum trickle timer interval expressed as number of doublings of the minimum interval. 00052 * \param k Redundancy constant. 00053 * \param timer_expirations Number of trickle timer expirations before terminating the trickle process. 00054 * \param window_expiration The time window for keeping the state after the end of trickle process in 50ms resolution. 00055 * NOTE: If window_expiration value is set too small an infinite retransmission loop may occur when using the trickle multicast. 00056 */ 00057 void multicast_set_parameters(uint8_t i_min, uint8_t i_doublings, uint8_t k, uint8_t timer_expirations, uint16_t window_expiration); 00058 00059 00060 /** 00061 * \brief Add new address to multicast group. 00062 * 00063 * \deprecated Use setsockopt(SOCKET_IPV6_JOIN_GROUP) to join a group. Use 00064 * multicast_mpl_subscribe_domain() to control MPL behaviour. 00065 * 00066 * \param address_ptr Pointer to a 16-byte array that includes the address to be added. 00067 * \param use_trickle 0 = no trickle multicast forwarding, all other values = trickle multicast forwarding will be used with this address. 00068 * 00069 * \return 0 General error. 00070 * \return 1 Address updated. 00071 * \return 2 Address added. 00072 * \return 255 Link local not allowed when using multicast. 00073 * 00074 */ 00075 uint8_t multicast_add_address(const uint8_t *address_ptr, uint8_t use_trickle); 00076 00077 00078 00079 /** 00080 * \brief Free address from multicast group. 00081 * \deprecated Use setsockopt(SOCKET_IPV6_LEAVE_GROUP) 00082 * 00083 * \param address_ptr Pointer to a 16-byte array that includes the address to be removed. 00084 * 00085 * \return 0 will be returned on successful execution, other values indicate an error on removing the address. 00086 */ 00087 uint8_t multicast_free_address(const uint8_t *address_ptr); 00088 00089 /** 00090 * \brief Treat all Realm-local Domains as one 00091 * 00092 * If enabled on an interface, then all Realm-local scope multicasts will 00093 * be treated as if belonging to the All-MPL-Forwarders domain, rather than 00094 * the domain indicated by their destination address. This is non-standard 00095 * behaviour, not covered by the real MPL specification, but required by the 00096 * Thread specification. 00097 * 00098 * All devices in a realm should have this setting set the same. With the 00099 * setting on, reactive forwarding and control messages will not work. 00100 * 00101 * With this setting on, Realm-scope domains other than All-MPL-Forwarders 00102 * cannot be joined. 00103 * 00104 * This must be set before bringing up an interface, and then not be modified. 00105 * 00106 * \param interface_id interface id 00107 * \param enable true to enable domain unification 00108 * 00109 * \return 0 for success, negative on failure 00110 */ 00111 int_fast8_t multicast_mpl_treat_realm_domains_as_one(int8_t interface_id, bool enable); 00112 00113 /** 00114 * \brief Set default MPL Domain parameters 00115 * 00116 * Modifies the default parameters for MPL Domains using the specified 00117 * interface. 00118 * 00119 * This must be set before subscribing to any MPL Domains with default 00120 * parameters on that interface. 00121 * 00122 * Initial defaults are as specified by RFC 7731. 00123 * 00124 * \param interface_id interface id 00125 * \param proactive_forwarding true to forward Data Messages when first received (default true) 00126 * \param seed_set_entry_lifetime minimum seed set lifetime (seconds, default 1800 = 30 minutes) 00127 * \param data_message_imin minimum Trickle timer for Data Messages (ms, default ~= 10 * expected link latency) 00128 * \param data_message_imax maximum Trickle timer for Data Messages (ms, default = Imin) 00129 * \param data_message_k Trickle redundancy constant for Data Messages (default = 1) 00130 * \param data_message_timer_expirations controls termination of retransmissions (default = 3) 00131 * \param control_message_imin minimum Trickle timer for Control Messages (ms, default ~= 10 * worst-case link latency) 00132 * \param control_message_imax maximum Trickle timer for Control Messages (ms, default = 5 minutes) 00133 * \param control_message_k Trickle redundancy constant for Control Messages (default = 1) 00134 * \param control_message_timer_expirations controls termination of retransmissions (default = 10); 0 disables control messages 00135 * 00136 * \return 0 for success, negative on failure 00137 */ 00138 int_fast8_t multicast_mpl_set_default_parameters(int8_t interface_id, 00139 bool proactive_forwarding, 00140 uint16_t seed_set_entry_lifetime, 00141 uint32_t data_message_imin, 00142 uint32_t data_message_imax, 00143 uint8_t data_message_k, 00144 uint8_t data_message_timer_expirations, 00145 uint32_t control_message_imin, 00146 uint32_t control_message_imax, 00147 uint8_t control_message_k, 00148 uint8_t control_message_timer_expirations); 00149 00150 /** Control selection of MPL Seed Identifier for packets we originate */ 00151 typedef enum { 00152 MULTICAST_MPL_SEED_ID_DEFAULT = -256, /** Default selection (used to make a domain use the interface's default) */ 00153 MULTICAST_MPL_SEED_ID_MAC_SHORT = -1, /** Use short MAC address if available (eg IEEE 802.15.4 interface's macShortAddress (16-bit)), else full MAC */ 00154 MULTICAST_MPL_SEED_ID_MAC = -2, /** 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) */ 00155 MULTICAST_MPL_SEED_ID_IID_EUI64 = -3, /** 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) */ 00156 MULTICAST_MPL_SEED_ID_IID_SLAAC = -4, /** Use 64-bit IPv6 IID that would be used for SLAAC */ 00157 MULTICAST_MPL_SEED_ID_IPV6_SRC_FOR_DOMAIN = 0, /** Use IPv6 source address selection to choose 128-bit Seed ID based on MPL Domain Address as destination */ 00158 MULTICAST_MPL_SEED_ID_16_BIT = 2, /** Use a manually-specified 16-bit ID */ 00159 MULTICAST_MPL_SEED_ID_64_BIT = 8, /** Use a manually-specified 64-bit ID */ 00160 MULTICAST_MPL_SEED_ID_128_BIT = 16, /** Use a manually-specified 128-bit ID */ 00161 } multicast_mpl_seed_id_mode_e; 00162 00163 /** 00164 * \brief Set default MPL Seed Identifier 00165 * 00166 * Sets the default MPL Seed Identifier used when acting as an MPL Seed. 00167 * 00168 * \param interface_id interface id 00169 * \param seed_id_mode Seed ID selection mode 00170 * \param seed_id For positive (constant) types, pointer to Seed ID data 00171 * 00172 * \return 0 for success, negative on failure 00173 */ 00174 int_fast8_t multicast_mpl_set_default_seed_id(int8_t interface_id, 00175 multicast_mpl_seed_id_mode_e seed_id_mode, 00176 const void *seed_id); 00177 00178 /** 00179 * \brief Subscribe to an MPL Domain (RFC 7731) 00180 * 00181 * This subscribes to an MPL Domain with default parameters on the 00182 * specified interface. (At present there is no support for subscribing to 00183 * the same Domain on multiple interfaces) 00184 * 00185 * If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed 00186 * to, this will automatically also subscribe to it with default parameters. 00187 * 00188 * Once 1 or more MPL Domains have been subscribed to on an interface, 00189 * multicast transmissions sent to a group with scope greater than link-local 00190 * on that interface will be sent using MPL. 00191 * 00192 * If the destination corresponds to a subscribed MPL Domain, it will be sent 00193 * to that MPL Domain (and hence forwarded only by other subscribers to that 00194 * domain). 00195 * 00196 * If the destination does not correspond to a subscribed MPL Domain, it will 00197 * be tunnelled, with the outer IP packet sent to the ALL_MPL_FORWARDERS Domain. 00198 * 00199 * Typical behaviour for ZigBee IP and Thread networks would be achieved by 00200 * subscribing to ff03::1, and enabling realm auto-subscription - [this is 00201 * done automatically when calling multicast_add_address?] 00202 * 00203 * \param interface_id interface id 00204 * \param address MPL Domain Address (IPv6 multicast address) 00205 * \param seed_id_mode Seed ID selection mode 00206 * \param seed_id For positive (constant) types, pointer to Seed ID data 00207 * 00208 * \return 0 for success, negative on failure 00209 */ 00210 int8_t multicast_mpl_domain_subscribe(int8_t interface_id, 00211 const uint8_t address[16], 00212 multicast_mpl_seed_id_mode_e seed_id_mode, 00213 const void *seed_id); 00214 00215 /** 00216 * \brief Subscribe to an MPL Domain (RFC 7731) 00217 * 00218 * This subscribes to an MPL Domain with default parameters on the 00219 * specified interface. 00220 * 00221 * If the ALL_MPL_FORWARDERS Domain ff03::fc has not already been subscribed 00222 * to, this will automatically also subscribe to it with default parameters. 00223 * 00224 * See multicast_mpl_subscribe_domain and multicast_set_default_parameters 00225 * for more information on parameters. 00226 */ 00227 int8_t multicast_mpl_domain_subscribe_with_parameters 00228 (int8_t interface_id, 00229 const uint8_t address[16], 00230 multicast_mpl_seed_id_mode_e seed_id_mode, 00231 const void *seed_id, 00232 bool proactive_forwarding, 00233 uint16_t seed_set_entry_lifetime, 00234 uint32_t data_message_imin, 00235 uint32_t data_message_imax, 00236 uint8_t data_message_k, 00237 uint8_t data_message_timer_expirations, 00238 uint32_t control_message_imin, 00239 uint32_t control_message_imax, 00240 uint8_t control_message_k, 00241 uint8_t control_message_timer_expirations); 00242 00243 /** 00244 * \brief Unsubscribe from an MPL Domain 00245 * 00246 * This subscribes from a previously-subscribed MPL Domain 00247 * 00248 * \param interface_id interface id 00249 * \param address MPL Domain Address (IPv6 multicast address) 00250 * 00251 * \return 0 for success, negative on failure 00252 */ 00253 int8_t multicast_mpl_domain_unsubscribe(int8_t interface_id, 00254 const uint8_t address[16]); 00255 00256 /** 00257 * \brief Set interface's master multicast forwarding control 00258 * 00259 * Multicast forwarding can occur between interfaces with multicast forwarding 00260 * enabled, according to forwarding records and scope rules controlled by the 00261 * functions below. 00262 * 00263 * If this call disables forwarding on the current proxying upstream interface, 00264 * proxying is disabled, and would need to be manually re-enabled later. 00265 * 00266 * Multicast forwarding state for an interface - forwarding records and scope level - are 00267 * retained even if its master forwarding switch is disabled, enabling the upkeep of backup 00268 * information. 00269 * 00270 * By default this flag is enabled. 00271 * 00272 * \param interface_id interface id 00273 * \param enable Enable / Disable multicast forwarding 00274 * 00275 * \return 0 for success, negative on failure 00276 */ 00277 int8_t multicast_fwd_set_forwarding(int8_t interface_id, bool enable); 00278 00279 /** 00280 * \brief Add multicast forwarding record to an interface 00281 * 00282 * This adds a group to the forwarding list on the specified interface. 00283 * Received multicast packets for the specified group will be forwarded onto 00284 * the specified interface from other interfaces, if multicast forwarding is enabled on 00285 * both incoming and outgoing interfaces, subject to a Reverse Path Forwarding 00286 * check on the source address, and usual scope rules. 00287 * 00288 * If a finite lifetime is set, the record will be removed after that many seconds. 00289 * 00290 * If an entry for the specified group already exists, its lifetime will 00291 * increased if it is lower than the value passed. 00292 * 00293 * \param interface_id interface id 00294 * \param group IPv6 multicast group address 00295 * \param lifetime The time in seconds to maintain the forwarding entry - 0xFFFFFFFF means infinite 00296 * 00297 * \return 0 for success, negative on failure 00298 */ 00299 int8_t multicast_fwd_add(int8_t interface_id, const uint8_t group[16], uint32_t lifetime); 00300 00301 /** 00302 * \brief Remove multicast forwarding record from an interface 00303 * 00304 * Delete a a group from the forwarding list on the specified interface. 00305 * 00306 * \param interface_id interface id 00307 * \param group IPv6 multicast group address 00308 * 00309 * \return 0 for success, negative on failure 00310 */ 00311 int8_t multicast_fwd_remove(int8_t interface_id, const uint8_t group[16]); 00312 00313 /** 00314 * \brief Set full multicast forwarding 00315 * 00316 * If enabled, all multicast packets of specified scope or greater will be 00317 * forwarded onto the specified interface from other interfaces, if multicast 00318 * forwarding is enabled on both incoming and outgoing interfaces, subject to a 00319 * Reverse Path Forwarding check on the source address. 00320 * 00321 * Setting this is equivalent to "multicast_fwd_add" being called for all 00322 * addresses with scope >= min_scope. 00323 * 00324 * This functionality is disabled by setting min_scope to 0x10 or greater (so 00325 * no packets can match). 00326 * 00327 * By default this is set to 0x5 (site-local) for all interfaces. 00328 * 00329 * \param interface_id interface id 00330 * \param min_scope minimum IPv6 scope value for forwarding (see RFC 4291) 00331 * 00332 * \return 0 for success, negative on failure 00333 */ 00334 int8_t multicast_fwd_full_for_scope(int8_t interface_id, uint_fast8_t min_scope); 00335 00336 /** 00337 * \brief Set upstream interface for MLD proxying 00338 * 00339 * This sets the upstream interface for MLD proxying. If set, the stack will 00340 * report group membership on that interface according to the forwarding lists 00341 * of the other interfaces with multicast forwarding enabled (ie it will send 00342 * MLD reports or equivalent on that upstream interface). 00343 * 00344 * Multicast forwarding must be enabled on the upstream interface. 00345 * 00346 * \param interface_id interface id, or -1 to disable 00347 * 00348 * \return 0 for success, negative on failure 00349 */ 00350 int8_t multicast_fwd_set_proxy_upstream(int8_t interface_id); 00351 00352 #ifdef __cplusplus 00353 } 00354 #endif 00355 #endif /* MULTICAST_API_H_ */
Generated on Tue Jul 12 2022 13:54:35 by
