summaryrefslogtreecommitdiff
path: root/digital/zigbit/bitcloud/stack/Components/APS/include/apsmeGroup.h
blob: c206f988c6597975b012e2512646210300884a20 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
/**************************************************************************//**
  \file apsmeGroup.h

  \brief Interface of APS Group table.

  \author
    Atmel Corporation: http://www.atmel.com \n
    Support email: avr@atmel.com

  Copyright (c) 2008-2011, Atmel Corporation. All rights reserved.
  Licensed under Atmel's Limited License Agreement (BitCloudTM).

  \internal
   History:
    24/07/07 A. Potashov - Created.
    21/07/10 M. Gekk     - Refactoring.
   Last change:
    $Id: apsmeGroup.h 17448 2011-06-09 13:53:59Z ataradov $
 ******************************************************************************/
#if !defined _APSME_GROUP_H
#define _APSME_GROUP_H
/**//**
 *
 *  This interface allows the next higher layer to manage group membership
 * for endpoints on the current device by adding and removing entries in
 * the group table. See ZigBee spec. r18, 2.2.4.5, page 45.
 *
 **/

/******************************************************************************
                               Includes section
 ******************************************************************************/
#include <apsCommon.h>

/******************************************************************************
                                Types section
 ******************************************************************************/
/**//**
 * \struct APS_AddGroupConf_t apsmeGroup.h "aps.h"
 *
 * \brief Parameters of the APSME-ADD-GROUP.confirm primitive.
 **/
typedef struct
{
  /** The status of the request to add a group. */
  APS_Status_t status;
} APS_AddGroupConf_t;

/**//**
 * \struct APS_AddGroupReq_t apsmeGroup.h "aps.h"
 *
 * \brief Parameters of the APS_AddGroupReq() function.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The 16-bit address of the group being added. */
  GroupAddr_t groupAddress;
  /** The endpoint to which the given group is being added. */
  Endpoint_t endpoint;

  /** The confirm primitive as transaction result. */
  APS_AddGroupConf_t confirm;
} APS_AddGroupReq_t;

/**//**
 * \struct APS_RemoveGroupConf_t apsmeGroup.h "aps.h"
 *
 * \brief The primitive presenting the result of APS_RemoveAllGroupReq() function.
 **/
typedef struct
{
  /** The status of the request to remove a group. */
  APS_Status_t status;
} APS_RemoveGroupConf_t;

/**//**
 * \struct APS_RemoveGroupReq_t apsmeGroup.h "aps.h"
 *
 * \brief Parameters of the APS_RemoveGroupReq() function.
 **/
typedef struct
{
  /** \ref Endian "[LE]" The 16-bit address of the group being removed. */
  GroupAddr_t groupAddress;
  /** The endpoint at which the given group is being removed. */
  Endpoint_t endpoint;

  /** The confirm primitive containing the result of the function call. */
  APS_RemoveGroupConf_t confirm;
} APS_RemoveGroupReq_t;

/**//**
 * \struct APS_RemoveAllGroupsConf_t apsmeGroup.h "aps.h"
 *
 * \brief The structure presenting the result of APS_RemoveAllGroupReq() function.
 **/
typedef struct
{
  /** The status of the request to remove all groups. */
  APS_Status_t status;
} APS_RemoveAllGroupsConf_t;

/**//**
 * \struct APS_RemoveAllGroupsReq_t apsmeGroup.h "aps.h"
 *
 * \brief Parameters of the APS_RemoveAllGroupsReq() function.
 **/
typedef struct
{
  /** The endpoint from which the group is being removed. */
  Endpoint_t endpoint;

  /** The confirm primitive as transaction result. */
  APS_RemoveAllGroupsConf_t confirm;
} APS_RemoveAllGroupsReq_t;

/******************************************************************************
                               Prototypes section
 ******************************************************************************/
/**************************************************************************//**
  \brief Adds the current device to the members of a certain group.

  The function makes the current device a member of the specified group. A call to the function is done
  synchronously since no requests are sent to the network. Instead, the function simply adds a new entry
  to the group table associating the group address and the endpoint ID specified within the parameters.
  The function can be called several times with the same group address and different endpoints which will
  cause inserting an entry for each distinct pair of the group address and an endpoint. When a data frame is
  sent to a group each group member upon reception of the frame fires indication callbacks for all endpoints
  associated with the group address specified in the request.
  
  The result of task execution is indicated by APS_AddGroupReq_t::confirm property inside the request
  parameters. The status field reports
  \li APS_SUCCESS_STATUS if the device has been added to the group
  \li APS_TABLE_FULL_STATUS if the group table is full and a new entry can not be added.
  
  \param[in] req - pointer to parameters of the APSME-ADD-GROUP.request.
 *****************************************************************************/
void APS_AddGroupReq(APS_AddGroupReq_t *const req);

/**************************************************************************//**
  \brief Removes the current device from the members of a certain group.

  The function removes the node from a group. A call to the function is done synchronously. The function drops
  all entries with the specified group and endpoint inside from the group table.
  
  The result of task execution is indicated by APS_AddGroupReq_t::confirm property inside the request
  parameters.  The status field reports
  \li APS_SUCCESS_STATUS if the device has been removed from the group
  \li APS_INVALID_PARAMETER_STATUS if requested entry has not been found in the group table
  
  \param[in] req - pointer to parameters of the APSME-REMOVE-GROUP.request.
 ******************************************************************************/
void APS_RemoveGroupReq(APS_RemoveGroupReq_t *const req);

/**************************************************************************//**
  \brief Removes the current device from the members of all groups for which a given
  endpoint if registered

  The function unscribe the current device from the members of all groups for which
  a given endpoint is registered. To fullfill the task the function deletes all entries with a given
  endpoint inside from the group table. If 0xFF is specified for endpoint the node is removed
  from all groups.
  
  The result of task execution is indicated by APS_AddGroupReq_t::confirm property inside the request
  parameters.
  
  \param[in] req - pointer to parameters of the APSME-REMOVE-ALL-GROUPS.request.
 ******************************************************************************/
void APS_RemoveAllGroupsReq(APS_RemoveAllGroupsReq_t *const req);

#endif /* _APSME_GROUP_H */
/** eof apsmeGroup.h */