include/zdo/zb_zdo_bind_mgr.h

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef __TIZEN_NETWORK_ZIGBEE_ZB_ZDO_BIND_MANAGER_H__
  17 #define __TIZEN_NETWORK_ZIGBEE_ZB_ZDO_BIND_MANAGER_H__
  18
  19 #include <zdo/zb_zdo_type.h>
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 /**
  26  * @file zb_zdo_bind_mgr.h
  27  */
  28
  29 /**
  30  * @ingroup CAPI_NETWORK_ZIGBEE_ZDO_MODULE
  31  * @defgroup CAPI_NETWORK_ZIGBEE_ZDO_BINDING_MANAGER_MODULE Binding Manager
  32  *
  33  * @brief Zigbee provides API for Binding.
  34  *
  35  * @section CAPI_NETWORK_ZIGBEE_ZDO_BINDING_MANAGER_HEADER Required Header
  36  *  \#include <zigbee.h>
  37  *
  38  * @section CAPI_NETWORK_ZIGBEE_ZDO_BINDING_MANAGER_OVERVIEW Overview
  39  * Binding provides a mechanism for attaching an endpoint on one node to one or more
  40  * endpoints on another node. Binding can even be destined for groups of nodes. Then,
  41  * when using APSDE-DATA.request, simply use the "indirect" addressing mode, and the
  42  * request will be sent to each endpoint or group listed in the local binding table.\n\n
  43  * The binding table is smart, and keeps track of both the short (16-bit NwkAddr) and long
  44  * (IEEE) address of a node. If a destination device has changed its short address (either
  45  * due to a ZigBee End-Device moving from one parent to another in ZigBee stack profile
  46  * 0x01, or due to a address conflict in ZigBee Pro), the binding table entry is updated
  47  * automatically to point to that new address.\n\n
  48  *
  49  * @{
  50  */
  51
  52 /**
  53  * @brief Called after 'bind' command.
  54  * @details The Bind_rsp is generated in response to a Bind_req. If the Bind_req is
  55  * processed and the Binding Table entry committed on the Remote Device, a Status of
  56  * SUCCESS is returned.\n\n If the Remote Device is not a Primary binding table cache
  57  * or the SrcAddress, a Status of NOT_SUPPORTED is returned.\n\n The supplied
  58  * endpoint shall be checked to determine whether it falls within the specified range.
  59  * If it does not, a Status of INVALID_EP shall be returned.\n\n If the Remote Device is
  60  * the Primary binding table cache or SrcAddress but does not have Binding Table
  61  * resources for the request, a Status of TABLE_FULL is returned.
  62  *
  63  * @since_tizen 4.0
  64  *
  65  * @param[in] status #ZB_ZDP_SUCCESS \n
  66  *                    #ZB_ZDP_NOT_SUPPORTED \n
  67  *                    #ZB_ZDP_INVALID_EP \n
  68  *                    #ZB_ZDP_TABLE_FULL \n
  69  *                    #ZB_ZDP_NOT_AUTHORIZED \n
  70  * @param[in] user_data user data
  71  *
  72  * @see zb_zdo_bind_req()
  73  *
  74  */
  75 typedef void (*zb_zdo_bind_rsp)(
  76                 unsigned char status,
  77                 void *user_data);
  78
  79 /**
  80  * @brief Sends 'bind' command.
  81  * @details Binding request when destination address present but not endpoint present.
  82  * The Bind_req is generated from a Local Device wishing to create a Binding
  83  * Table entry for the source and destination addresses contained as parameters.\n\n The
  84  * destination addressing on this command shall be unicast only, and the destination
  85  * address shall be that of a Primary binding table cache or to the SrcAddress itself.
  86  * The Binding Manager is optionally supported on the source device (unless that
  87  * device is also the ZigBee Coordinator) so that device shall issue a
  88  * NOT_SUPPORTED status to the Bind_req if not supported.
  89  *
  90  * @since_tizen 4.0
  91  * @privlevel public
  92  * @privilege %http://tizen.org/privilege/zigbee
  93  *
  94  * @param[in] handle The handle of zigbee
  95  * @param[in] dst_addr16 The Network address of destination
  96  * @param[in] src_addr64 The IEEE address of source
  97  * @param[in] src_ep The source endpoint for the binding entry
  98  * @param[in] cluster_id The identifier of the cluster on the source device that is bound
  99  *                       to the destination.
 100  * @param[in] dst_addr64 The IEEE address of destination
 101  * @param[in] type ZB_UNICAST_BINDING : A unicast binding whose 64-bit identifier is the
 102  *      destination ieee_addr. \n
 103  *      ZB_MANY_TO_ONE_BINDING : A unicast binding whose 64-bit identifier is
 104  *                                          the many-to-one destination ieee_addr.
 105  *                                          A Route discovery should be disabled when
 106  *                                          sending unicast via may-to-one binding \n
 107  *                 ZB_MULTICAST_BINDING : A multicast binding whose 64-bit identifier is
 108  *                                        the group address. A multicast binding can be
 109  *                                        used to send messages to the group and to
 110  *                                        receive message sent to the group
 111  * @param[in] group_addr The destination address for the binding entry
 112  * @param[in] dst_ep The destination endpoint for the binding entry.
 113  * @param[in] cb Response callback
 114  * @param[in] user_data user data
 115  *
 116  * @return 0 on success, otherwise a negative error value.
 117  * @retval #ZIGBEE_ERROR_NONE Successful
 118  * @retval #ZIGBEE_ERROR_INVALID_PARAMETER Invalid parameter
 119  * @retval #ZIGBEE_ERROR_INVALID_ENDPOINT Invalid endpoint. 0 is reserved for ZDP
 120  * @retval #ZIGBEE_ERROR_OUT_OF_MEMORY Out-of-memory
 121  * @retval #ZIGBEE_ERROR_IO_ERROR Unexpected d-bus error
 122  * @retval #ZIGBEE_ERROR_PERMISSION_DENIED Permission denied
 123  * @retval #ZIGBEE_ERROR_NOT_SUPPORTED Not supported
 124  *
 125  * @see zb_zdo_bind_rsp()
 126  */
 127 int zb_zdo_bind_req(
 128                 zigbee_h handle,
 129                 nwk_addr dst_addr16,
 130                 ieee_addr src_addr64,
 131                 unsigned char src_ep,
 132                 unsigned short cluster_id,
 133                 ieee_addr dst_addr64,
 134                 unsigned char type,
 135                 nwk_addr group_addr,
 136                 unsigned char dst_ep,
 137                 zb_zdo_bind_rsp cb,
 138                 void *user_data);
 139
 140 /**
 141  * @brief Called after 'unbind' command.
 142  * @details The Unbind_rsp is generated in response to an Unbind_req. If the Unbind_req is
 143  * processed and the corresponding Binding Table entry is removed from the Remote
 144  * Device, a Status of SUCCESS is returned. If the Remote Device is not the ZigBee
 145  * Coordinator or the SrcAddress, a Status of NOT_SUPPORTED is returned.\n\n The
 146  * supplied endpoint shall be checked to determine whether it falls within the
 147  * specified range. If it does not, a Status of INVALID_EP shall be returned If the
 148  * Remote Device is the ZigBee Coordinator or SrcAddress but does not have a
 149  * Binding Table entry corresponding to the parameters received in the request, a
 150  * Status of NO_ENTRY is returned.
 151  *
 152  * @since_tizen 4.0
 153  *
 154  * @param[in] status #ZB_ZDP_SUCCESS \n
 155  *                    #ZB_ZDP_NOT_SUPPORTED \n
 156  *                    #ZB_ZDP_INVALID_EP \n
 157  *                    #ZB_ZDP_NO_ENTRY \n
 158  *                    #ZB_ZDP_NOT_AUTHORIZED
 159  * @param[in] user_data user data
 160  *
 161  * @see zb_zdo_unbind_req_addr()
 162  *
 163  */
 164 typedef void (*zb_zdo_unbind_rsp)(
 165                 unsigned char status,
 166                 void *user_data);
 167
 168 /**
 169  * @brief Sends 'Unbind' command.
 170  * @details Binding request when destination address present but not endpoint present
 171  * The Unbind_req is generated from a Local Device wishing to remove a Binding
 172  * Table entry for the source and destination addresses contained as parameters.\n\n The
 173  * destination addressing on this command shall be unicast only and the destination
 174  * address must be that of the a Primary binding table cache or the SrcAddress.
 175  *
 176  * @since_tizen 4.0
 177  * @privlevel public
 178  * @privilege %http://tizen.org/privilege/zigbee
 179  *
 180  * @param[in] handle The handle of zigbee
 181  * @param[in] dst_addr16 The Network address of destination
 182  * @param[in] src_addr64 The IEEE address of source
 183  * @param[in] src_ep The source endpoint for the binding entry
 184  * @param[in] cluster_id The identifier of the cluster on the source device that is bound
 185  *                       to the destination.
 186  * @param[in] dst_addr64 The IEEE address of destination
 187  * @param[in] type #ZB_UNICAST_BINDING : A unicast binding whose 64-bit identifier is the
 188  *                                                                      destination ieee_addr. \n
 189  *                     #ZB_MANY_TO_ONE_BINDING : A unicast binding whose 64-bit identifier is
 190  *                                          the many-to-one destination ieee_addr.
 191  *                                          A Route discovery should be disabled when
 192  *                                          sending unicast via may-to-one binding \n
 193  *                 #ZB_MULTICAST_BINDING : A multicast binding whose 64-bit identifier is
 194  *                                        the group address. A multicast binding can be
 195  *                                        used to send messages to the group and to
 196  *                                        receive message sent to the group
 197  * @param[in] group_addr The destination address for the binding entry
 198  * @param[in] dst_ep The destination endpoint for the binding entry.
 199  * @param[in] cb Response callback
 200  * @param[in] user_data user data
 201  *
 202  * @return 0 on success, otherwise a negative error value.
 203  * @retval #ZIGBEE_ERROR_NONE Successful
 204  * @retval #ZIGBEE_ERROR_INVALID_PARAMETER Invalid parameter
 205  * @retval #ZIGBEE_ERROR_INVALID_ENDPOINT Invalid endpoint. 0 is reserved for ZDP
 206  * @retval #ZIGBEE_ERROR_OUT_OF_MEMORY Out-of-memory
 207  * @retval #ZIGBEE_ERROR_IO_ERROR Unexpected d-bus error
 208  * @retval #ZIGBEE_ERROR_PERMISSION_DENIED Permission denied
 209  * @retval #ZIGBEE_ERROR_NOT_SUPPORTED Not supported
 210  *
 211  * @see zb_zdo_unbind_rsp()
 212  *
 213  */
 214 int zb_zdo_unbind_req(
 215                 zigbee_h handle,
 216                 nwk_addr dst_addr16,
 217                 ieee_addr src_addr64,
 218                 unsigned char src_ep,
 219                 unsigned short cluster_id,
 220                 ieee_addr dst_addr64,
 221                 unsigned char type,
 222                 nwk_addr group_addr,
 223                 unsigned char dst_ep,
 224                 zb_zdo_unbind_rsp cb,
 225                 void *user_data);
 226
 227 /**
 228  * @}
 229  */
 230
 231 #ifdef __cplusplus
 232 }
 233 #endif
 234
 235 #endif /* __TIZEN_NETWORK_ZIGBEE_ZB_ZDO_BIND_MANAGER_H__ */