multicast_api.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 #ifndef MULTICAST_API_H_
00015 #define MULTICAST_API_H_
00016 /**
00017  * \file multicast_api.h
00018  * \brief Multicast Trickle Forwarding API.
00019  * \section multi-init Init API:
00020  * - multicast_set_parameters(), Set trickle parameters.
00021  * \section multi-cnf Configure API:
00022  * - multicast_add_address(), Add new address to a multicast group and control trickle forwarding.
00023  * - multicast_free_address(), Remove supported multicast address from list.
00024  *
00025  * \section ZigBeeIP Trickle Setups for Multicast Init
00026  *
00027  * | Parameter         | VALUE |
00028  * | :---------------: | :---: |
00029  * | imin              | 10    |
00030  * | imax              | 0     |
00031  * | k                 | 20    |
00032  * | timer_expirations | 3     |
00033  * | window_expiration | 75    |
00034  *
00035  */
00036 
00037 #include "ns_types.h"
00038 
00039 #ifdef __cplusplus
00040 extern "C" {
00041 #endif
00042 
00043 /**
00044  * \brief Set new parameters for trickle multicast.
00045  *
00046  * \param i_min Minimum trickle timer interval in 50ms resolution: Imin = i_min * 50ms.
00047  * \param i_max Maximum trickle timer interval as a number if doubling the minimum interval.
00048  * \param k Redundancy constant.
00049  * \param timer_expirations Number of trickle timer expirations before terminating the trickle process.
00050  * \param window_expiration The time window for keeping the state after the end of trickle process in 50ms resolution.
00051  *        NOTE: If window_expiration value is set too small an infinite retransmission loop may occur when using the trickle multicast.
00052  */
00053 extern void multicast_set_parameters(uint8_t i_min, uint8_t i_max, uint8_t k, uint8_t timer_expirations, uint16_t window_expiration);
00054 
00055 
00056 /**
00057  * \brief Add new address to multicast group.
00058  *
00059  * \param address_ptr Pointer to a 16-byte array that includes the address to be added.
00060  * \param use_trickle 0 = no trickle multicast forwarding, all other values = trickle multicast forwarding will be used with this address.
00061  *
00062  * \return 0 General error.
00063  * \return 1 Address updated.
00064  * \return 2 Address added.
00065  * \return 255 Link local not allowed when using multicast.
00066 *
00067  */
00068 extern uint8_t multicast_add_address(const uint8_t *address_ptr, uint8_t use_trickle);
00069 
00070 
00071 
00072 /**
00073  * \brief Free address from multicast group.
00074  *
00075  * \param address_ptr Pointer to a 16-byte array that includes the address to be removed.
00076  *
00077  * \return 0 will be returned on successful execution, other values indicate an error on removing the address.
00078  */
00079 extern uint8_t multicast_free_address(uint8_t *address_ptr);
00080 #ifdef __cplusplus
00081 }
00082 #endif
00083 #endif /* MULTICAST_API_H_ */