Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
att_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief Attribute protocol client and server API.
6  *
7  * Copyright (c) 2009-2019 Arm Ltd. All Rights Reserved.
8  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 #ifndef ATT_API_H
25 #define ATT_API_H
26 
27 #include "wsf_timer.h"
28 #include "att_defs.h"
29 #include "att_uuid.h"
30 #include "dm_api.h"
31 #include "cfg_stack.h"
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36 
37 /**************************************************************************************************
38  Macros
39 **************************************************************************************************/
40 /*! \addtogroup STACK_ATTS_API
41  * \{ */
42 /** \name ATT Server Attribute Settings
43  * Settings that may be set on each attribute.
44  */
45 /**@{*/
46 #define ATTS_SET_UUID_128 0x01 /*!< \brief Set if the UUID is 128 bits in length */
47 #define ATTS_SET_WRITE_CBACK 0x02 /*!< \brief Set if the group callback is executed when
48  this attribute is written by a client device */
49 #define ATTS_SET_READ_CBACK 0x04 /*!< \brief Set if the group callback is executed when
50  this attribute is read by a client device */
51 #define ATTS_SET_VARIABLE_LEN 0x08 /*!< \brief Set if the attribute has a variable length */
52 #define ATTS_SET_ALLOW_OFFSET 0x10 /*!< \brief Set if writes are allowed with an offset */
53 #define ATTS_SET_CCC 0x20 /*!< \brief Set if the attribute is a client characteristic
54  configuration descriptor */
55 #define ATTS_SET_ALLOW_SIGNED 0x40 /*!< \brief Set if signed writes are allowed */
56 #define ATTS_SET_REQ_SIGNED 0x80 /*!< \brief Set if signed writes are required if link
57  is not encrypted */
58 /**@}*/
59 
60 /** \name ATT Server Attribute Permissions
61  * Permissions used to describe a attribute's security setting.
62  * These values can be set in any combination.
63  */
64 /**@{*/
65 #define ATTS_PERMIT_READ 0x01 /*!< \brief Set if attribute can be read */
66 #define ATTS_PERMIT_READ_AUTH 0x02 /*!< \brief Set if attribute read requires authentication */
67 #define ATTS_PERMIT_READ_AUTHORIZ 0x04 /*!< \brief Set if attribute read requires authorization */
68 #define ATTS_PERMIT_READ_ENC 0x08 /*!< \brief Set if attribute read requires encryption */
69 #define ATTS_PERMIT_WRITE 0x10 /*!< \brief Set if attribute can be written */
70 #define ATTS_PERMIT_WRITE_AUTH 0x20 /*!< \brief Set if attribute write requires authentication */
71 #define ATTS_PERMIT_WRITE_AUTHORIZ 0x40 /*!< \brief Set if attribute write requires authorization */
72 #define ATTS_PERMIT_WRITE_ENC 0x80 /*!< \brief Set if attribute write requires encryption */
73 /**@}*/
74 /*! \} */ /* STACK_ATTS_API */
75 
76 /*! \addtogroup STACK_ATTC_API
77  * \{ */
78 /** \name ATT Client Discovery and Configuration Settings
79  * Settings used to configurate ATT Discovery procedure for ATT Clients.
80  */
81 /**@{*/
82 #define ATTC_SET_UUID_128 0x01 /*!< \brief Set if the UUID is 128 bits in length */
83 #define ATTC_SET_REQUIRED 0x02 /*!< \brief Set if characteristic must be discovered */
84 #define ATTC_SET_DESCRIPTOR 0x04 /*!< \brief Set if this is a characteristic descriptor */
85 /**@}*/
86 /*! \} */ /* STACK_ATTC_API */
87 
88 /*! \addtogroup STACK_ATT_API
89  * \{ */
90 /** \name ATT Callback Events
91  * Events related to ATT transactions.
92  */
93 /**@{*/
94 #define ATT_CBACK_START 0x02 /*!< \brief ATT callback event starting value */
95 
96 /*! \brief ATT client callback events */
97 enum /*!< \brief Internal note: event values match method values */
98 {
99  ATTC_FIND_INFO_RSP = ATT_CBACK_START, /*!< \brief Find information response */
100  ATTC_FIND_BY_TYPE_VALUE_RSP, /*!< \brief Find by type value response */
101  ATTC_READ_BY_TYPE_RSP, /*!< \brief Read by type value response */
102  ATTC_READ_RSP, /*!< \brief Read response */
103  ATTC_READ_LONG_RSP, /*!< \brief Read long response */
104  ATTC_READ_MULTIPLE_RSP, /*!< \brief Read multiple response */
105  ATTC_READ_BY_GROUP_TYPE_RSP, /*!< \brief Read group type response */
106  ATTC_WRITE_RSP, /*!< \brief Write response */
107  ATTC_WRITE_CMD_RSP, /*!< \brief Write command response */
108  ATTC_PREPARE_WRITE_RSP, /*!< \brief Prepare write response */
109  ATTC_EXECUTE_WRITE_RSP, /*!< \brief Execute write response */
110  ATTC_HANDLE_VALUE_NTF, /*!< \brief Handle value notification */
111  ATTC_HANDLE_VALUE_IND, /*!< \brief Handle value indication */
112  ATTC_READ_MULT_VAR_RSP = 16, /*!< \brief Read multiple variable length response */
113  ATTC_MULT_VALUE_NTF, /*!< \brief Read multiple value notification */
114  /* ATT server callback events */
115  ATTS_HANDLE_VALUE_CNF, /*!< \brief Handle value confirmation */
116  ATTS_MULT_VALUE_CNF, /*!< \brief Handle multiple value confirmation */
117  ATTS_CCC_STATE_IND, /*!< \brief Client chracteristic configuration state change */
118  ATTS_DB_HASH_CALC_CMPL_IND, /*!< \brief Database hash calculation complete */
119  /* ATT common callback events */
120  ATT_MTU_UPDATE_IND, /*!< \brief Negotiated MTU value */
121  ATT_EATT_CONN_CMPL_IND, /*!< \brief EATT Connect channels complete */
122  ATT_EATT_RECONFIG_CMPL_IND /*!< \brief EATT Reconfigure complete */
123 };
124 
125 /*! \brief ATT callback events */
126 #define ATT_CBACK_END ATT_EATT_RECONFIG_CMPL_IND /*!< \brief ATT callback event ending value */
127 /**@}*/
128 
129 /** \name ATT Client Awareness of Database Change
130  * Status of a client's awareness of a database change.
131  */
132 /**@{*/
133 /*! \brief client's awareness to database change. */
134 enum attClientAwareStates
135 {
136  ATTS_CLIENT_CHANGE_AWARE = 0, /*!< Client Aware. */
137  ATTS_CLIENT_CHANGE_PENDING_AWARE, /*!< Client Aware pending ATT Request. For internal stack use only. */
138  ATTS_CLIENT_CHANGE_AWARE_DB_READ_PENDING, /*!< Client Aware, Database Hash read pending hash update completion. For internal stack use only. */
139  ATTS_CLIENT_CHANGE_UNAWARE, /*!< Client Unaware. */
140 };
141 /**@}*/
142 
143 /**************************************************************************************************
144  Data Types
145 **************************************************************************************************/
146 
147 /*! \brief ATT run-time configurable parameters */
148 typedef struct
149 {
150  wsfTimerTicks_t discIdleTimeout; /*!< \brief ATT server service discovery connection idle timeout in seconds */
151  uint16_t mtu; /*!< \brief desired ATT MTU */
152  uint8_t transTimeout; /*!< \brief transcation timeout in seconds */
153  uint8_t numPrepWrites; /*!< \brief number of queued prepare writes supported by server */
154 } attCfg_t;
155 
156 /*! \brief EATT run-time configurable parameters */
157 typedef struct
158 {
159  uint16_t mtu; /*!< \brief MTU */
160  uint16_t mps; /*!< \brief MPS */
161  bool_t initiateEatt; /*!< \brief Open EATT channels automatically on connect */
162  uint8_t authoriz; /*!< \brief Authorization required */
163  uint8_t secLevel; /*!< \brief Security level required */
164  uint8_t numChans; /*!< \brief Number of enhanced l2cap channels per connection */
165  uint8_t *pPriorityTbl; /*!< \brief Min priority required for each channel */
166 } eattCfg_t;
167 
168 /*!
169  * \brief ATT callback event
170  *
171  * \param hdr.event Callback event
172  * \param hdr.param DM connection ID
173  * \param hdr.status Event status: ATT_SUCCESS or error status
174  * \param pValue Pointer to value data, valid if valueLen > 0
175  * \param valueLen Length of value data
176  * \param handle Attribute handle
177  * \param continuing TRUE if more response packets expected
178  * \param mtu Negotiated MTU value
179  */
180 typedef struct
181 {
182  wsfMsgHdr_t hdr; /*!< \brief Header structure */
183  uint8_t *pValue; /*!< \brief Value */
184  uint16_t valueLen; /*!< \brief Value length */
185  uint16_t handle; /*!< \brief Attribute handle */
186  bool_t continuing; /*!< \brief TRUE if more response packets expected */
187  uint16_t mtu; /*!< \brief Negotiated MTU value */
188 } attEvt_t;
189 
190 /*! \brief ATT event callback type.
191  *
192  * This callback function sends ATT events to the client application. A
193  * single callback function is used for both ATTS and ATTC.
194  *
195  * \param pEvt Pointer to ATT event structure.
196  *
197  * \return None.
198  */
199 typedef void (*attCback_t)(attEvt_t *pEvt);
200 /*! \} */ /* STACK_ATT_API */
201 
202 /*! \addtogroup STACK_ATTS_API
203  * \{ */
204 /**
205  * \name Attribute Server Data Types
206  *
207  */
208 /**@{*/
209 /*! \brief Attribute structure */
210 typedef struct
211 {
212  uint8_t const *pUuid; /*!< \brief Pointer to the attribute's UUID */
213  uint8_t *pValue; /*!< \brief Pointer to the attribute's value */
214  uint16_t *pLen; /*!< \brief Pointer to the length of the attribute's value */
215  uint16_t maxLen; /*!< \brief Maximum length of attribute's value */
216  uint8_t settings; /*!< \brief Attribute settings */
217  uint8_t permissions; /*!< \brief Attribute permissions */
218 } attsAttr_t;
219 
220 /*! \brief Client supported features record structure. */
221 typedef struct
222 {
223  uint8_t csf; /*!< Client supported features characteristic value */
224  uint8_t changeAwareState; /*!< Client awareness of GATT database changes */
225 } attsCsfRec_t;
226 /**@}*/
227 
228 /** \name ATT Server Callbacks
229  *
230  */
231 /**@{*/
232 /*! \brief Attribute group read callback
233  *
234  * This is the attribute server read callback. It is executed on an attribute
235  * read operation if bitmask ATTS_SET_READ_CBACK is set in the settings field
236  * of the attribute structure.
237  * For a read operation, if the operation is successful the function must set
238  * pAttr->pValue to the data to be read. In addition, if the attribute is
239  * variable length then pAttr->pLen must be set as well.
240  *
241  * \param connId DM connection ID.
242  * \param handle Attribute handle.
243  * \param operation Operation type.
244  * \param offset Read data offset.
245  * \param pAttr Pointer to attribute structure.
246  *
247  * \return status of the operation. \ref ATT_SUCCESS if successful.
248  */
249 typedef uint8_t (*attsReadCback_t)(dmConnId_t connId, uint16_t handle, uint8_t operation,
250  uint16_t offset, attsAttr_t *pAttr);
251 
252 /*! \brief Attribute group write callback
253  *
254  * This is the attribute server write callback. It is executed on an
255  * attribute write operation if bitmask ATTS_SET_WRITE_CBACK is set
256  * in the settings field of the attribute structure.
257  *
258  * \param connId DM connection ID.
259  * \param handle Attribute handle.
260  * \param operation Operation type.
261  * \param offset Write data offset.
262  * \param len Length of data to write.
263  * \param pValue Pointer to data to write.
264  * \param pAttr Pointer to attribute structure.
265  *
266  * \return status of operation. \ref ATT_SUCCESS if successful.
267  */
268 typedef uint8_t (*attsWriteCback_t)(dmConnId_t connId, uint16_t handle, uint8_t operation,
269  uint16_t offset, uint16_t len, uint8_t *pValue,
270  attsAttr_t *pAttr);
271 
272 /*! \brief ATTS authorization callback type
273  *
274  * This callback function is executed when a read or write operation occurs
275  * and the security field of an attribute structure is set to
276  * \ref ATTS_PERMIT_READ_AUTHORIZ or \ref ATTS_PERMIT_WRITE_AUTHORIZ respectively.
277  *
278  * \param connId DM Connection ID.
279  * \param permit Set to \ref ATTS_PERMIT_WRITE for a writre operation or
280  * \ref ATTS_PERMIT_READ for a read operation.
281  * \param handle Attribute handle.
282  *
283  * \return status of the operation. \ref ATT_SUCCESS if successful, else if failure
284  * the \ref ATT_ERR_AUTH is typically returned.
285  */
286 typedef uint8_t (*attsAuthorCback_t)(dmConnId_t connId, uint8_t permit, uint16_t handle);
287 
288 /*! \brief ATTS client supported features write callback type
289  *
290  * This callback function is executed when the client supported features record for
291  * this client has been updated.
292  *
293  * \param connId DM Connection ID.
294  * \param changeAwareState The state of awareness to a change, see ::attClientAwareStates.
295  * \param pCsf Pointer to the client supported features value.
296  *
297  * \return None.
298  */
299 typedef void (*attsCsfWriteCback_t)(dmConnId_t connId, uint8_t changeAwareState, uint8_t *pCsf);
300 /**@}*/
301 
302 /**
303  * \name Attribute Server Data Types
304  *
305  */
306 /**@{*/
307 /*! \brief Attribute group */
308 typedef struct attsGroup_tag
309 {
310  struct attsGroup_tag *pNext; /*!< \brief For internal use only */
311  attsAttr_t *pAttr; /*!< \brief Pointer to attribute list for this group */
312  attsReadCback_t readCback; /*!< \brief Read callback function */
313  attsWriteCback_t writeCback; /*!< \brief Write callback function */
314  uint16_t startHandle; /*!< \brief The handle of the first attribute in this group */
315  uint16_t endHandle; /*!< \brief The handle of the last attribute in this group */
316 } attsGroup_t;
317 
318 /*! \brief Client characteristc configuration settings */
319 typedef struct
320 {
321  uint16_t handle; /*!< \brief Client characteristc configuration descriptor handle */
322  uint16_t valueRange; /*!< \brief Acceptable value range of the descriptor value */
323  uint8_t secLevel; /*!< \brief Security level of characteristic value */
324 } attsCccSet_t;
325 
326 /*! \brief ATTS client characteristic configuration callback structure */
327 typedef struct
328 {
329  wsfMsgHdr_t hdr; /*!< \brief Header structure */
330  uint16_t handle; /*!< \brief CCCD handle */
331  uint16_t value; /*!< \brief CCCD value */
332  uint8_t idx; /*!< \brief CCCD settings index */
333 } attsCccEvt_t;
334 /**@}*/
335 /*! \} */ /* STACK_ATTS_API */
336 
337 /*! \addtogroup STACK_ATTC_API
338  * \{ */
339 /**
340  * \name ATT Client Data Types
341  */
342 /**@{*/
343 /*! \brief ATT client structure for characteristic and descriptor discovery */
344 typedef struct attcDiscChar_tag
345 {
346  uint8_t const *pUuid; /*!< \brief Pointer to UUID */
347  uint8_t settings; /*!< \brief Characteristic discovery settings */
348 } attcDiscChar_t;
349 
350 /*! \brief ATT client structure for characteristic and descriptor configuration */
351 typedef struct
352 {
353  uint8_t const *pValue; /*!< \brief Pointer to default value or NULL */
354  uint8_t valueLen; /*!< \brief Default value length */
355  uint8_t hdlIdx; /*!< \brief Index of its handle in handle list */
356 } attcDiscCfg_t;
357 
358 /*! \brief ATT client discovery control block */
359 typedef struct
360 {
361  attcDiscChar_t **pCharList; /*!< \brief Characterisic list for discovery */
362  uint16_t *pHdlList; /*!< \brief Characteristic handle list */
363  attcDiscCfg_t *pCfgList; /*!< \brief Characterisic list for configuration */
364  uint8_t charListLen; /*!< \brief Characteristic and handle list length */
365  uint8_t cfgListLen; /*!< \brief Configuration list length */
366 
367  uint16_t svcStartHdl; /*!< \brief Internal use only */
368  uint16_t svcEndHdl; /*!< \brief Internal use only */
369  uint8_t charListIdx; /*!< \brief Internal use only */
370  uint8_t endHdlIdx; /*!< \brief Internal use only */
371 } attcDiscCb_t;
372 /**@}*/
373 /*! \} */ /* STACK_ATTC_API */
374 
375 /*! \addtogroup STACK_ATTS_API
376  * \{ */
377 /** \name ATT Server Callbacks
378  *
379  */
380 /**@{*/
381 /*! \brief ATTS client characteristic configuration callback
382  *
383  * Client characteristic configuration callback. This function is executed
384  * when a CCCD value changes. This happens when a peer device writes a new
385  * value to the CCCD or when a CCCD table is initialized by calling \ref AttsCccInitTable.
386  *
387  * \param pEvt Pointer to callback structure.
388  *
389  * \return None.
390  */
391 typedef void (*attsCccCback_t)(attsCccEvt_t *pEvt);
392 /**@}*/
393 /*! \} */ /* STACK_ATTS_API */
394 
395 /**************************************************************************************************
396  Global Variables
397 **************************************************************************************************/
398 
399 /*! \addtogroup STACK_INIT
400  * \{ */
401 /** \name ATT Configuration Structure
402  * Pointer to structure containing initialization details of the ATT Subsystem. To be configured
403  * by Application.
404  */
405 /**@{*/
406 /*! \brief Configuration pointer */
407 extern attCfg_t *pAttCfg;
408 
409 /*! \brief Enhanced configuration pointer */
410 extern eattCfg_t *pEattCfg;
411 /**@}*/
412 /*! \} */ /* STACK_INIT */
413 
414 /**************************************************************************************************
415  Function Declarations
416 **************************************************************************************************/
417 
418 /*! \addtogroup STACK_ATT_API
419  * \{ */
420 /** \name ATT Setup Functions
421  *
422  */
423 /**@{*/
424 /*************************************************************************************************/
425 /*!
426  * \brief Register a callback with ATT. This callback will be used for messages from both ATTC
427  * and ATTS.
428  *
429  * \param cback Client callback function.
430  *
431  * \return None.
432  */
433 /*************************************************************************************************/
434 void AttRegister(attCback_t cback);
435 
436 /*************************************************************************************************/
437 /*!
438  * \brief Register a connection callback with ATT. The callback is typically used to
439  * manage the attribute server database.
440  *
441  * \param cback Client callback function.
442  *
443  * \return None.
444  */
445 /*************************************************************************************************/
446 void AttConnRegister(dmCback_t cback);
447 /**@}*/
448 
449 /** \name ATT Parameter Functions
450  * Functions specific to a connection between 2 devices. Functions may be called by either
451  * Client or server.
452  */
453 /**@{*/
454 /*************************************************************************************************/
455 /*!
456  * \brief Get the attribute protocol MTU of a connection.
457  *
458  * \param connId DM connection ID.
459  *
460  * \return MTU of the connection.
461  */
462 /*************************************************************************************************/
463 uint16_t AttGetMtu(dmConnId_t connId);
464 /**@}*/
465 
466 /** \name ATT Message Passing Functions
467  *
468  */
469 /**@{*/
470 /*************************************************************************************************/
471 /*!
472  * \brief Allocate an ATT message buffer to be sent with the ATT attribute protocol
473  * zero-copy APIs.
474  *
475  * \param len Message length in bytes.
476  * \param opcode Opcode for ATT message.
477  *
478  * \return Pointer to message buffer or NULL if allocation failed.
479  */
480 /*************************************************************************************************/
481 void *AttMsgAlloc(uint16_t len, uint8_t opcode);
482 
483 /*************************************************************************************************/
484 /*!
485  * \brief Free an ATT message buffer allocated with AttMsgAlloc().
486  *
487  * \param pMsg Pointer to message buffer.
488  * \param opcode Opcode for ATT message.
489  *
490  * \return None.
491  */
492 /*************************************************************************************************/
493 void AttMsgFree(void *pMsg, uint8_t opcode);
494 /**@}*/
495 /*! \} */ /* STACK_ATT_API */
496 
497 /*! \addtogroup STACK_ATTS_API
498  * \{ */
499 /** \name ATT Server Functions
500  *
501  */
502 /**@{*/
503 /*************************************************************************************************/
504 /*!
505  * \brief Initialize ATT server.
506  *
507  * \return None.
508  */
509 /*************************************************************************************************/
510 void AttsInit(void);
511 
512 /*************************************************************************************************/
513 /*!
514  * \brief Initialize ATT server for indications/notifications.
515  *
516  * \return None.
517  */
518 /*************************************************************************************************/
519 void AttsIndInit(void);
520 
521 /*************************************************************************************************/
522 /*!
523  * \brief Initialize ATT server for data signing.
524  *
525  * \return None.
526  */
527 /*************************************************************************************************/
528 void AttsSignInit(void);
529 
530 /*************************************************************************************************/
531 /*!
532  * \brief Register an authorization callback with the attribute server.
533  *
534  * \param cback Client callback function.
535  *
536  * \return None.
537  */
538 /*************************************************************************************************/
539 void AttsAuthorRegister(attsAuthorCback_t cback);
540 
541 /*************************************************************************************************/
542 /*!
543  * \brief Add an attribute group to the attribute server.
544  *
545  * \param pGroup Pointer to an attribute group structure.
546  *
547  * \return None.
548  */
549 /*************************************************************************************************/
550 void AttsAddGroup(attsGroup_t *pGroup);
551 
552 /*************************************************************************************************/
553 /*!
554  * \brief Remove an attribute group from the attribute server.
555  *
556  * \param startHandle Start handle of attribute group to be removed.
557  *
558  * \return None.
559  */
560 /*************************************************************************************************/
561 void AttsRemoveGroup(uint16_t startHandle);
562 
563 /*************************************************************************************************/
564 /*!
565 * \brief Calculate database hash from the GATT database.
566 *
567 * \return None.
568 */
569 /*************************************************************************************************/
570 void AttsCalculateDbHash(void);
571 
572 /*************************************************************************************************/
573 /*!
574  * \brief Create hash from the database string.
575  *
576  * \param pKey Key for hashing.
577  * \param pMsg Plaintext to hash.
578  * \param msgLen Length of Plaintext data.
579  *
580  * \return \ref TRUE if successful, \ref FALSE if not.
581  */
582 /*************************************************************************************************/
583 bool_t AttsHashDatabaseString(uint8_t *pKey, uint8_t *pMsg, uint16_t msgLen);
584 
585 /*************************************************************************************************/
586 /*!
587  * \brief Set an attribute value in the attribute server.
588  *
589  * \param handle Attribute handle.
590  * \param valueLen Attribute length.
591  * \param pValue Attribute value.
592  *
593  * \return ATT_SUCCESS if successful otherwise error.
594  */
595 /*************************************************************************************************/
596 uint8_t AttsSetAttr(uint16_t handle, uint16_t valueLen, uint8_t *pValue);
597 
598 /*************************************************************************************************/
599 /*!
600  * \brief Get an attribute value in the attribute server.
601  *
602  * \param handle Attribute handle.
603  * \param pLen Returned attribute length pointer.
604  * \param pValue Returned attribute value pointer.
605  *
606  * \return ATT_SUCCESS if successful otherwise error.
607  * \return This function returns the attribute length in pLen and a pointer to the attribute
608  * value in pValue.
609  */
610 /*************************************************************************************************/
611 uint8_t AttsGetAttr(uint16_t handle, uint16_t *pLen, uint8_t **pValue);
612 
613 /*************************************************************************************************/
614 /*!
615  * \brief Send an attribute protocol Handle Value Indication.
616  *
617  * \param connId DM connection ID.
618  * \param handle Attribute handle.
619  * \param valueLen Length of value data.
620  * \param pValue Pointer to value data.
621  *
622  * \return None.
623  */
624 /*************************************************************************************************/
625 void AttsHandleValueInd(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue);
626 
627 /*************************************************************************************************/
628 /*!
629  * \brief Send an attribute protocol Handle Value Notification.
630  *
631  * \param connId DM connection ID.
632  * \param handle Attribute handle.
633  * \param valueLen Length of value data.
634  * \param pValue Pointer to value data.
635  *
636  * \return None.
637  */
638 /*************************************************************************************************/
639 void AttsHandleValueNtf(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue);
640 
641 /*************************************************************************************************/
642 /*!
643  * \brief Send an attribute protocol Handle Value Indication without copying the attribute
644  * value data.
645  *
646  * Note: attribute value buffer 'pValue' must be allocated with AttMsgAlloc().
647  *
648  * \param connId DM connection ID.
649  * \param handle Attribute handle.
650  * \param valueLen Length of value data.
651  * \param pValue Pointer to value data.
652  *
653  * \return None.
654  */
655 /*************************************************************************************************/
656 void AttsHandleValueIndZeroCpy(dmConnId_t connId, uint16_t handle, uint16_t valueLen,
657  uint8_t *pValue);
658 
659 /*************************************************************************************************/
660 /*!
661  * \brief Send an attribute protocol Handle Value Notification without copying the attribute
662  * value data.
663  *
664  * Note: attribute value buffer 'pValue' must be allocated with AttMsgAlloc().
665  *
666  * \param connId DM connection ID.
667  * \param handle Attribute handle.
668  * \param valueLen Length of value data.
669  * \param pValue Pointer to value data.
670  *
671  * \return None.
672  */
673 /*************************************************************************************************/
674 void AttsHandleValueNtfZeroCpy(dmConnId_t connId, uint16_t handle, uint16_t valueLen,
675  uint8_t *pValue);
676 
677 /*************************************************************************************************/
678 /*!
679  * \brief Register the utility service for managing client characteristic
680  * configuration descriptors. This function is typically called once on
681  * system initialization.
682  *
683  * \param setLen Length of settings array.
684  * \param pSet Array of CCC descriptor settings.
685  * \param cback Client callback function.
686  *
687  * \return None.
688  */
689 /*************************************************************************************************/
690 void AttsCccRegister(uint8_t setLen, attsCccSet_t *pSet, attsCccCback_t cback);
691 
692 /*************************************************************************************************/
693 /*!
694  * \brief Initialize the client characteristic configuration descriptor value table for a
695  * connection. The table is initialized with the values from pCccTbl. If pCccTbl
696  * is NULL the table will be initialized to zero.
697  *
698  * This function must be called when a connection is established or when a
699  * device is bonded.
700  *
701  * \param connId DM connection ID.
702  * \param pCccTbl Pointer to the descriptor value array. The length of the array
703  * must equal the value of setLen passed to AttsCccRegister().
704  *
705  * \return None.
706  */
707 /*************************************************************************************************/
708 void AttsCccInitTable(dmConnId_t connId, uint16_t *pCccTbl);
709 
710 /*************************************************************************************************/
711 /*!
712  * \brief Clear and deallocate the client characteristic configuration descriptor value
713  * table for a connection. This function must be called when a connection is closed.
714  *
715  * \param connId DM connection ID.
716  *
717  * \return None.
718  */
719 /*************************************************************************************************/
720 void AttsCccClearTable(dmConnId_t connId);
721 
722 /*************************************************************************************************/
723 /*!
724  * \brief Get the value of a client characteristic configuration descriptor by its index.
725  * If not found, return zero.
726  *
727  * \param connId DM connection ID.
728  * \param idx Index of descriptor in CCC descriptor handle table.
729  *
730  * \return Value of the descriptor.
731  */
732 /*************************************************************************************************/
733 uint16_t AttsCccGet(dmConnId_t connId, uint8_t idx);
734 
735 /*************************************************************************************************/
736 /*!
737  * \brief Set the value of a client characteristic configuration descriptor by its index.
738  *
739  * \param connId DM connection ID.
740  * \param idx Index of descriptor in CCC descriptor handle table.
741  * \param value Value of the descriptor.
742  *
743  * \return None.
744  */
745 /*************************************************************************************************/
746 void AttsCccSet(dmConnId_t connId, uint8_t idx, uint16_t value);
747 
748 /*************************************************************************************************/
749 /*!
750  * \brief Check if a client characteristic configuration descriptor is enabled and if
751  * the characteristic's security level has been met.
752  *
753  * \param connId DM connection ID.
754  * \param idx Index of descriptor in CCC descriptor handle table.
755  *
756  * \return Value of the descriptor if security level is met, otherwise zero.
757  */
758 /*************************************************************************************************/
759 uint16_t AttsCccEnabled(dmConnId_t connId, uint8_t idx);
760 
761 /*************************************************************************************************/
762 /*!
763  * \brief Get number of CCC entries in table.
764  *
765  * \return Number of CCC entries in table.
766  */
767 /*************************************************************************************************/
768 uint8_t AttsGetCccTableLen(void);
769 
770 /*************************************************************************************************/
771 /*!
772  * \brief Send a response to a pending write request. For use with ATT_RSP_PENDING.
773  *
774  * \param connId Connection ID.
775  * \param handle Attribute handle.
776  * \param status Status of the write request.
777  *
778  * \return None.
779  *
780  * \note When a higher layer returns ATT_RSP_PENDING to an ATT write callback indicating the
781  * response status is pending, the higher layer must subsequently call this function
782  * with the status of the write request.
783  */
784 /*************************************************************************************************/
785 void AttsContinueWriteReq(dmConnId_t connId, uint16_t handle, uint8_t status);
786 
787 /*************************************************************************************************/
788 /*!
789  * \brief Set the peer's data signing key on this connection. This function
790  * is typically called from the ATT connection callback when the connection is
791  * established. The caller is responsible for maintaining the memory that
792  * contains the key.
793  *
794  * \param connId DM connection ID.
795  * \param pCsrk Pointer to data signing key (CSRK).
796  * \param authenticated True if CSRK is authenticated and false otherwise.
797  *
798  * \return None.
799  */
800 /*************************************************************************************************/
801 void AttsSetCsrk(dmConnId_t connId, uint8_t *pCsrk, bool_t authenticated);
802 
803 /*************************************************************************************************/
804 /*!
805  * \brief Set the peer's sign counter on this connection. This function
806  * is typically called from the ATT connection callback when the connection is
807  * established. ATT maintains the value of the sign counter internally and
808  * sets the value when a signed packet is successfully received.
809  *
810  * \param connId DM connection ID.
811  * \param signCounter Sign counter.
812  *
813  * \return None.
814  */
815 /*************************************************************************************************/
816 void AttsSetSignCounter(dmConnId_t connId, uint32_t signCounter);
817 
818 /*************************************************************************************************/
819 /*!
820  * \brief Get the current value peer's sign counter on this connection. This function
821  * is typically called from the ATT connection callback when the connection is
822  * closed so the application can store the sign counter for use on future
823  * connections.
824  *
825  * \param connId DM connection ID.
826  *
827  * \return Sign counter.
828  */
829 /*************************************************************************************************/
830 uint32_t AttsGetSignCounter(dmConnId_t connId);
831 
832 /*************************************************************************************************/
833 /*!
834  * \brief Initialize ATTS client supported features module.
835  *
836  * \return None.
837  */
838 /*************************************************************************************************/
839 void AttsCsfInit(void);
840 
841 /*************************************************************************************************/
842 /*!
843  * \brief Initialize the client supported features for a connection.
844  *
845  * \param connId DM connection ID.
846  * \param changeAwareState The state of awareness to a change in the database.
847  * \param pCsf Pointer to the client supported features value to cache. \ref NULL or
848  * buffer of length \ref ATT_CSF_LEN.
849  *
850  * \return None.
851  */
852 /*************************************************************************************************/
853 void AttsCsfConnOpen(dmConnId_t connId, uint8_t changeAwareState, uint8_t *pCsf);
854 
855 /*************************************************************************************************/
856 /*!
857  * \brief GATT write of client supported feature characteristic value.
858  *
859  * \param connId DM connection ID.
860  * \param offset offset into csf characteristic.
861  * \param valueLen length of write in bytes.
862  * \param pValue Pointer to client's supported features characteristic value.
863  *
864  * \return \ref ATT_SUCCESS is successful, \ref ATT_ERR_VALUE_NOT_ALLOWED if any supported
865  * features are flipped from 1 to 0.
866  */
867 /*************************************************************************************************/
868 uint8_t AttsCsfWriteFeatures(dmConnId_t connId, uint16_t offset, uint16_t valueLen,
869  uint8_t *pValue);
870 
871 /*************************************************************************************************/
872 /*!
873  * \brief Get client supported feature record.
874  *
875  * \param connId DM connection ID.
876  * \param pCsfOut Output parameter for client supported features buffer.
877  * \param pCsfOutLen Length of output parameter buffer.
878  *
879  * \return None.
880  */
881 /*************************************************************************************************/
882 void AttsCsfGetFeatures(dmConnId_t connId, uint8_t *pCsfOut, uint8_t pCsfOutLen);
883 
884 /*************************************************************************************************/
885 /*!
886  * \brief Get client state of awareness to a change in the database.
887  *
888  * \param connId DM connection ID.
889  *
890  * \return Client's change-aware state. See ::attClientAwareStates.
891  */
892 /*************************************************************************************************/
893 uint8_t AttsCsfGetClientChangeAwareState(dmConnId_t connId);
894 
895 /*************************************************************************************************/
896 /*!
897  * \brief Update a client's state of awareness to a change in the database.
898  *
899  * \param connId DM connection ID. if \ref DM_CONN_ID_NONE, sets the state for all connected
900  * clients.
901  * \param state The state of awareness to a change, see \ref attClientAwareStates.
902  *
903  * \return None.
904  *
905  * \note A callback to application is not needed as it is expected the caller (i.e. the
906  * application) will have updated all persistent records prior to calling this function.
907  */
908 /*************************************************************************************************/
909 void AttsCsfSetClientChangeAwareState(dmConnId_t connId, uint8_t state);
910 
911 /*************************************************************************************************/
912 /*!
913  * \brief Register callback.
914  *
915  * \param writeCback Application callback for when client supported features record is updated.
916  *
917  * \return None.
918  */
919 /*************************************************************************************************/
920 void AttsCsfRegister(attsCsfWriteCback_t writeCback);
921 /**@}*/
922 
923 /** \name ATT Server Dynamic Service Subsystem Functions
924  *
925  */
926 /**@{*/
927 /*************************************************************************************************/
928 /*!
929  * \brief Initialize the Dynamic ATT Service subsystem.
930  *
931  * \return None.
932  */
933 /*************************************************************************************************/
934 void AttsDynInit(void);
935 
936 /*************************************************************************************************/
937 /*!
938  * \brief Dynamically create an ATT Service at runtime.
939  *
940  * \param startHandle Starting attribute handle in the service
941  * \param endHandle Last attribute handle in the service
942  *
943  * \return Service Handle.
944  */
945 /*************************************************************************************************/
946 void *AttsDynCreateGroup(uint16_t startHandle, uint16_t endHandle);
947 
948 /*************************************************************************************************/
949 /*!
950  * \brief Dynamically delete an ATT Service at runtime.
951  *
952  * \param pSvcHandle Service handle returned by \ref AttsDynCreateGroup
953  *
954  * \return None.
955  */
956 /*************************************************************************************************/
957 void AttsDynDeleteGroup(void *pSvcHandle);
958 
959 /*************************************************************************************************/
960 /*!
961  * \brief Register callback functions for a dynamic ATT Service at runtime.
962  *
963  * \param pSvcHandle Service handle returned by \ref AttsDynCreateGroup
964  * \param readCback Read callback function
965  * \param writeCback Write callback function
966  *
967  * \return None.
968  */
969 /*************************************************************************************************/
970 void AttsDynRegister(void *pSvcHandle, attsReadCback_t readCback, attsWriteCback_t writeCback);
971 
972 /*************************************************************************************************/
973 /*!
974  * \brief Dynamically add an attribute to a dynamic ATT Services at runtime.
975  *
976  * \param pSvcHandle Service handle returned by \ref AttsDynCreateGroup
977  * \param pUuid Constant UUID
978  * \param pValue Initial value of attribute (copied into attribute memory)
979  * \param len Length of pValue in bytes
980  * \param maxLen Maximum length of the attribute in bytes
981  * \param settings Attribute settings
982  * \param permissions Attribute permissions
983  *
984  * \return None.
985  */
986 /*************************************************************************************************/
987 void AttsDynAddAttr(void *pSvcHandle, const uint8_t *pUuid, const uint8_t *pValue, uint16_t len,
988  const uint16_t maxLen, uint8_t settings, uint8_t permissions);
989 
990 /*************************************************************************************************/
991 /*!
992  * \brief Dynamically add an attribute with a constant value to a dynamic ATT Services at runtime.
993  *
994  * \param pSvcHandle Service handle returned by \ref AttsDynCreateGroup
995  * \param pUuid Constant UUID
996  * \param pValue Pointer to constant attribute memory
997  * \param len Length of pValue in bytes
998  * \param settings Attribute settings
999  * \param permissions Attribute permissions
1000  *
1001  * \return None.
1002  */
1003 /*************************************************************************************************/
1004 void AttsDynAddAttrConst(void *pSvcHandle, const uint8_t *pUuid, const uint8_t *pValue,
1005  const uint16_t len, uint8_t settings, uint8_t permissions);
1006 /**@}*/
1007 
1008 /** \name ATT Server Testing
1009  *
1010  */
1011 /**@{*/
1012 /*************************************************************************************************/
1013 /*!
1014  * \brief For testing purposes only.
1015  *
1016  * \param status ATT status
1017  *
1018  * \return None.
1019  */
1020 /*************************************************************************************************/
1021 void AttsErrorTest(uint8_t status);
1022 /**@}*/
1023 /*! \} */ /* STACK_ATTS_API */
1024 
1025 /*! \addtogroup STACK_ATTC_API
1026  * \{ */
1027 /** \name ATT Client Functions
1028  *
1029  */
1030 /**@{*/
1031 /*************************************************************************************************/
1032 /*!
1033  * \brief Initialize ATT client.
1034  *
1035  * \return None.
1036  */
1037 /*************************************************************************************************/
1038 void AttcInit(void);
1039 
1040 /*************************************************************************************************/
1041 /*!
1042  * \brief Initialize ATT client for data signing.
1043  *
1044  * \return None.
1045  */
1046 /*************************************************************************************************/
1047 void AttcSignInit(void);
1048 
1049 /*************************************************************************************************/
1050 /*!
1051  * \brief Initiate an attribute protocol Find Information Request.
1052  *
1053  * \param connId DM connection ID.
1054  * \param startHandle Attribute start handle.
1055  * \param endHandle Attribute end handle.
1056  * \param continuing TRUE if ATTC continues sending requests until complete.
1057  *
1058  * \return None.
1059  */
1060 /*************************************************************************************************/
1061 void AttcFindInfoReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle, bool_t continuing);
1062 
1063 /*************************************************************************************************/
1064 /*!
1065  * \brief Initiate an attribute protocol Find By Type Value Request.
1066  *
1067  * \param connId DM connection ID.
1068  * \param startHandle Attribute start handle.
1069  * \param endHandle Attribute end handle.
1070  * \param uuid16 16-bit UUID to find.
1071  * \param valueLen Length of value data.
1072  * \param pValue Pointer to value data.
1073  * \param continuing TRUE if ATTC continues sending requests until complete.
1074  *
1075  * \return None.
1076  */
1077 /*************************************************************************************************/
1078 void AttcFindByTypeValueReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle,
1079  uint16_t uuid16, uint16_t valueLen, uint8_t *pValue, bool_t continuing);
1080 
1081 /*************************************************************************************************/
1082 /*!
1083  * \brief Initiate an attribute protocol Read By Type Request.
1084  *
1085  * \param connId DM connection ID.
1086  * \param startHandle Attribute start handle.
1087  * \param endHandle Attribute end handle.
1088  * \param uuidLen Length of UUID (2 or 16).
1089  * \param pUuid Pointer to UUID data.
1090  * \param continuing TRUE if ATTC continues sending requests until complete.
1091  *
1092  * \return None.
1093  */
1094 /*************************************************************************************************/
1095 void AttcReadByTypeReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle,
1096  uint8_t uuidLen, uint8_t *pUuid, bool_t continuing);
1097 
1098 /*************************************************************************************************/
1099 /*!
1100  * \brief Initiate an attribute protocol Read Request.
1101  *
1102  * \param connId DM connection ID.
1103  * \param handle Attribute handle.
1104  *
1105  * \return None.
1106  */
1107 /*************************************************************************************************/
1108 void AttcReadReq(dmConnId_t connId, uint16_t handle);
1109 
1110 /*************************************************************************************************/
1111 /*!
1112  * \brief Initiate an attribute protocol Read Long Request.
1113  *
1114  * \param connId DM connection ID.
1115  * \param handle Attribute handle.
1116  * \param offset Read attribute data starting at this offset.
1117  * \param continuing TRUE if ATTC continues sending requests until complete.
1118  *
1119  * \return None.
1120  */
1121 /*************************************************************************************************/
1122 void AttcReadLongReq(dmConnId_t connId, uint16_t handle, uint16_t offset, bool_t continuing);
1123 
1124 /*************************************************************************************************/
1125 /*!
1126  * \brief Initiate an attribute protocol Read Multiple Request.
1127  *
1128  * \param connId DM connection ID.
1129  * \param numHandles Number of handles in attribute handle list.
1130  * \param pHandles List of attribute handles.
1131  *
1132  * \return None.
1133  */
1134 /*************************************************************************************************/
1135 void AttcReadMultipleReq(dmConnId_t connId, uint8_t numHandles, uint16_t *pHandles);
1136 
1137 /*************************************************************************************************/
1138 /*!
1139  * \brief Initiate an attribute protocol Read By Group Type Request.
1140  *
1141  * \param connId DM connection ID.
1142  * \param startHandle Attribute start handle.
1143  * \param endHandle Attribute end handle.
1144  * \param uuidLen Length of UUID (2 or 16).
1145  * \param pUuid Pointer to UUID data.
1146  * \param continuing TRUE if ATTC continues sending requests until complete.
1147  *
1148  * \return None.
1149  */
1150 /*************************************************************************************************/
1151 void AttcReadByGroupTypeReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle,
1152  uint8_t uuidLen, uint8_t *pUuid, bool_t continuing);
1153 
1154 /*************************************************************************************************/
1155 /*!
1156  * \brief Initiate an attribute protocol Write Request.
1157  *
1158  * \param connId DM connection ID.
1159  * \param handle Attribute handle.
1160  * \param valueLen Length of value data.
1161  * \param pValue Pointer to value data.
1162  *
1163  * \return None.
1164  */
1165 /*************************************************************************************************/
1166 void AttcWriteReq(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue);
1167 
1168 /*************************************************************************************************/
1169 /*!
1170  * \brief Initiate an attribute protocol Write Command.
1171  *
1172  * \param connId DM connection ID.
1173  * \param handle Attribute handle.
1174  * \param valueLen Length of value data.
1175  * \param pValue Pointer to value data.
1176  *
1177  * \return None.
1178  */
1179 /*************************************************************************************************/
1180 void AttcWriteCmd(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue);
1181 
1182 /*************************************************************************************************/
1183 /*!
1184  * \brief Initiate an attribute protocol signed Write Command.
1185  *
1186  * \param connId DM connection ID.
1187  * \param handle Attribute handle.
1188  * \param signCounter Value of the sign counter.
1189  * \param valueLen Length of value data.
1190  * \param pValue Pointer to value data.
1191  *
1192  * \return None.
1193  */
1194 /*************************************************************************************************/
1195 void AttcSignedWriteCmd(dmConnId_t connId, uint16_t handle, uint32_t signCounter,
1196  uint16_t valueLen, uint8_t *pValue);
1197 
1198 /*************************************************************************************************/
1199 /*!
1200  * \brief Initiate an attribute protocol Prepare Write Request.
1201  *
1202  * \param connId DM connection ID.
1203  * \param handle Attribute handle.
1204  * \param offset Write attribute data starting at this offset.
1205  * \param valueLen Length of value data.
1206  * \param pValue Pointer to value data.
1207  * \param valueByRef TRUE if pValue data is accessed by reference rather than copied.
1208  * \param continuing TRUE if ATTC continues sending requests until complete.
1209  *
1210  * \return None.
1211  */
1212 /*************************************************************************************************/
1213 void AttcPrepareWriteReq(dmConnId_t connId, uint16_t handle, uint16_t offset, uint16_t valueLen,
1214  uint8_t *pValue, bool_t valueByRef, bool_t continuing);
1215 
1216 /*************************************************************************************************/
1217 /*!
1218  * \brief Initiate an attribute protocol Execute Write Request.
1219  *
1220  * \param connId DM connection ID.
1221  * \param writeAll TRUE to write all queued writes, FALSE to cancel all queued writes.
1222  *
1223  * \return None.
1224  */
1225 /*************************************************************************************************/
1226 void AttcExecuteWriteReq(dmConnId_t connId, bool_t writeAll);
1227 
1228 /*************************************************************************************************/
1229 /*!
1230  * \brief Cancel an attribute protocol request in progress.
1231  *
1232  * \param connId DM connection ID.
1233  *
1234  * \return None.
1235  */
1236 /*************************************************************************************************/
1237 void AttcCancelReq(dmConnId_t connId);
1238 
1239 /*************************************************************************************************/
1240 /*!
1241  * \brief This utility function discovers the given service on a peer device. Function
1242  * AttcFindByTypeValueReq() is called to initiate the discovery procedure.
1243  *
1244  * \param connId DM connection ID.
1245  * \param pCb Pointer to discovery control block.
1246  * \param uuidLen Length of service UUID (2 or 16).
1247  * \param pUuid Pointer to service UUID.
1248  *
1249  * \return None.
1250  */
1251 /*************************************************************************************************/
1252 void AttcDiscService(dmConnId_t connId, attcDiscCb_t *pCb, uint8_t uuidLen, uint8_t *pUuid);
1253 
1254 /*************************************************************************************************/
1255 /*!
1256  * \brief This utility function processes a service discovery result. It should be called
1257  * when an \ref ATTC_FIND_BY_TYPE_VALUE_RSP callback event is received after service
1258  * discovery is initiated by calling AttcDiscService().
1259  *
1260  * \param pCb Pointer to discovery control block.
1261  * \param pMsg ATT callback event message.
1262  *
1263  * \return ATT_SUCCESS if successful otherwise error.
1264  */
1265 /*************************************************************************************************/
1266 uint8_t AttcDiscServiceCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg);
1267 
1268 /*************************************************************************************************/
1269 /*!
1270  * \brief This utility function starts characteristic and characteristic descriptor
1271  * discovery for a service on a peer device. The service must have been previously
1272  * discovered by calling AttcDiscService() and AttcDiscServiceCmpl().
1273  *
1274  * \param connId DM connection ID.
1275  * \param pCb Pointer to discovery control block.
1276  *
1277  * \return None.
1278  */
1279 /*************************************************************************************************/
1280 void AttcDiscCharStart(dmConnId_t connId, attcDiscCb_t *pCb);
1281 
1282 /*************************************************************************************************/
1283 /*!
1284  * \brief This utility function processes a characteristic discovery result. It should be
1285  * called when an \ref ATTC_READ_BY_TYPE_RSP or \ref ATTC_FIND_INFO_RSP callback event is
1286  * received after characteristic discovery is initiated by calling AttcDiscCharStart().
1287  *
1288  * \param pCb Pointer to discovery control block.
1289  * \param pMsg ATT callback event message.
1290  *
1291  * \return ATT_CONTINUING if successful and the discovery procedure is continuing.
1292  * ATT_SUCCESS if the discovery procedure completed successfully.
1293  * Otherwise the discovery procedure failed.
1294  */
1295 /*************************************************************************************************/
1296 uint8_t AttcDiscCharCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg);
1297 
1298 /*************************************************************************************************/
1299 /*!
1300  * \brief This utility function starts service include discovery for a service on a peer device.
1301  * The service must have been previously discovered by calling AttcDiscService() and
1302 * AttcDiscServiceCmpl().
1303  *
1304  * \param connId DM connection ID.
1305  * \param pCb Pointer to service discovery control block.
1306  *
1307  * \return None.
1308  */
1309 /*************************************************************************************************/
1310 void AttcDiscIncSvcStart(dmConnId_t connId, attcDiscCb_t *pCb);
1311 
1312 /*************************************************************************************************/
1313 /*!
1314  * \brief This utility function processes a service include discovery result. It should be
1315  * called when an ATTC_READ_BY_TYPE_RSP allback event is received after service include
1316  * discovery is initiated by calling AttcDiscIncSvcStart().
1317  *
1318  * \param pCb Pointer to service discovery control block.
1319  * \param pMsg ATT callback event message.
1320  *
1321  * \return ATT_CONTINUING if successful and discovery procedure is continuing.
1322  * ATT_SUCCESS if discovery procedure completed successfully.
1323  * Otherwise the discovery procedure failed.
1324  */
1325 /*************************************************************************************************/
1326 uint8_t AttcDiscIncSvcCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg);
1327 
1328 /*************************************************************************************************/
1329 /*!
1330  * \brief This utility function starts characteristic configuration for characteristics on a
1331  * peer device. The characteristics must have been previously discovered by calling
1332  * AttcDiscCharStart() and AttcDiscCharCmpl().
1333  *
1334  * \param connId DM connection ID.
1335  * \param pCb Pointer to discovery control block.
1336  *
1337  * \return ATT_CONTINUING if successful and configuration procedure is continuing.
1338  * ATT_SUCCESS if nothing to configure.
1339  */
1340 /*************************************************************************************************/
1341 uint8_t AttcDiscConfigStart(dmConnId_t connId, attcDiscCb_t *pCb);
1342 
1343 /*************************************************************************************************/
1344 /*!
1345  * \brief This utility function initiates the next characteristic configuration procedure.
1346  * It should be called when an \ref ATTC_READ_RSP or \ref ATTC_WRITE_RSP callback event
1347  * is received after characteristic configuration is initiated by calling
1348  * AttcDiscConfigStart().
1349  *
1350  * \param connId DM connection ID.
1351  * \param pCb Pointer to discovery control block.
1352  *
1353  * \return ATT_CONTINUING if successful and configuration procedure is continuing.
1354  * ATT_SUCCESS if configuration procedure completed successfully.
1355  */
1356 /*************************************************************************************************/
1357 uint8_t AttcDiscConfigCmpl(dmConnId_t connId, attcDiscCb_t *pCb);
1358 
1359 /*************************************************************************************************/
1360 /*!
1361  * \brief This utility function resumes the characteristic configuration procedure. It can
1362  * be called when an \ref ATTC_READ_RSP or \ref ATTC_WRITE_RSP callback event is received
1363  * with failure status to attempt the read or write procedure again.
1364  *
1365  * \param connId DM connection ID.
1366  * \param pCb Pointer to discovery control block.
1367  *
1368  * \return ATT_CONTINUING if successful and configuration procedure is continuing.
1369  * ATT_SUCCESS if configuration procedure completed successfully.
1370  */
1371 /*************************************************************************************************/
1372 uint8_t AttcDiscConfigResume(dmConnId_t connId, attcDiscCb_t *pCb);
1373 
1374 /*************************************************************************************************/
1375 /*!
1376  * \brief Initiate an attribute protocol Exchange MTU Request.
1377  *
1378  * \param connId DM connection ID.
1379  * \param mtu Attribute protocol MTU.
1380  *
1381  * \return None.
1382  *
1383  * \note The Exchange MTU Request will be initiated automatically on a master connection.
1384  *
1385  * \note This API can be used by the application to initiate an Exchange MTU Request on slave
1386  * connections.
1387  */
1388 /*************************************************************************************************/
1389 void AttcMtuReq(dmConnId_t connId, uint16_t mtu);
1390 
1391 /*************************************************************************************************/
1392 /*!
1393  * \brief Set automatic Indication Confirmations sent from this ATT Client.
1394  *
1395  * \param enable \ref TRUE to enable automatic confirmations (default), \ref FALSE to disable.
1396  *
1397  * \return None.
1398  */
1399 /*************************************************************************************************/
1400 void AttcSetAutoConfirm(bool_t enable);
1401 
1402 /*************************************************************************************************/
1403 /*!
1404  * \brief Send an attribute protocol indication confirmation.
1405  *
1406  * \param connId DM connection ID.
1407  *
1408  * \return None.
1409  */
1410 /*************************************************************************************************/
1411 void AttcIndConfirm(dmConnId_t connId);
1412 /**@}*/
1413 /*! \} */ /* STACK_ATTC_API */
1414 
1415 
1416 #ifdef __cplusplus
1417 };
1418 #endif
1419 
1420 #endif /* ATT_API_H */
ATTS_CLIENT_CHANGE_PENDING_AWARE
Definition: att_api.h:141
AttsCccGet
uint16_t AttsCccGet(dmConnId_t connId, uint8_t idx)
Get the value of a client characteristic configuration descriptor by its index. If not found...
ATT_CBACK_START
#define ATT_CBACK_START
ATT callback event starting value.
Definition: att_api.h:98
AttcReadLongReq
void AttcReadLongReq(dmConnId_t connId, uint16_t handle, uint16_t offset, bool_t continuing)
Initiate an attribute protocol Read Long Request.
AttcReadMultipleReq
void AttcReadMultipleReq(dmConnId_t connId, uint8_t numHandles, uint16_t *pHandles)
Initiate an attribute protocol Read Multiple Request.
dmConnId_t
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:588
ATTC_WRITE_RSP
Write response.
Definition: att_api.h:110
AttsContinueWriteReq
void AttsContinueWriteReq(dmConnId_t connId, uint16_t handle, uint8_t status)
Send a response to a pending write request. For use with ATT_RSP_PENDING.
attEvt_t
ATT callback event.
Definition: att_api.h:184
AttsDynDeleteGroup
void AttsDynDeleteGroup(void *pSvcHandle)
Dynamically delete an ATT Service at runtime.
AttsCsfWriteFeatures
uint8_t AttsCsfWriteFeatures(dmConnId_t connId, uint16_t offset, uint16_t valueLen, uint8_t *pValue)
GATT write of client supported feature characteristic value.
AttsCsfGetFeatures
void AttsCsfGetFeatures(dmConnId_t connId, uint8_t *pCsfOut, uint8_t pCsfOutLen)
Get client supported feature record.
ATT_MTU_UPDATE_IND
Negotiated MTU value.
Definition: att_api.h:124
AttcReadByGroupTypeReq
void AttcReadByGroupTypeReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle, uint8_t uuidLen, uint8_t *pUuid, bool_t continuing)
Initiate an attribute protocol Read By Group Type Request.
ATTC_READ_LONG_RSP
Read long response.
Definition: att_api.h:107
AttcDiscServiceCmpl
uint8_t AttcDiscServiceCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg)
This utility function processes a service discovery result. It should be called when an ATTC_FIND_BY_...
ATTC_HANDLE_VALUE_IND
Handle value indication.
Definition: att_api.h:115
AttcDiscCharStart
void AttcDiscCharStart(dmConnId_t connId, attcDiscCb_t *pCb)
This utility function starts characteristic and characteristic descriptor discovery for a service on ...
AttsRemoveGroup
void AttsRemoveGroup(uint16_t startHandle)
Remove an attribute group from the attribute server.
AttsGetSignCounter
uint32_t AttsGetSignCounter(dmConnId_t connId)
Get the current value peer&#39;s sign counter on this connection. This function is typically called from ...
AttsAuthorRegister
void AttsAuthorRegister(attsAuthorCback_t cback)
Register an authorization callback with the attribute server.
AttRegister
void AttRegister(attCback_t cback)
Register a callback with ATT. This callback will be used for messages from both ATTC and ATTS...
AttsSetSignCounter
void AttsSetSignCounter(dmConnId_t connId, uint32_t signCounter)
Set the peer&#39;s sign counter on this connection. This function is typically called from the ATT connec...
attsWriteCback_t
uint8_t(* attsWriteCback_t)(dmConnId_t connId, uint16_t handle, uint8_t operation, uint16_t offset, uint16_t len, uint8_t *pValue, attsAttr_t *pAttr)
Attribute group write callback.
Definition: att_api.h:272
AttsCccRegister
void AttsCccRegister(uint8_t setLen, attsCccSet_t *pSet, attsCccCback_t cback)
Register the utility service for managing client characteristic configuration descriptors. This function is typically called once on system initialization.
ATTS_CCC_STATE_IND
Client chracteristic configuration state change.
Definition: att_api.h:121
AttcDiscConfigStart
uint8_t AttcDiscConfigStart(dmConnId_t connId, attcDiscCb_t *pCb)
This utility function starts characteristic configuration for characteristics on a peer device...
AttsDynAddAttr
void AttsDynAddAttr(void *pSvcHandle, const uint8_t *pUuid, const uint8_t *pValue, uint16_t len, const uint16_t maxLen, uint8_t settings, uint8_t permissions)
Dynamically add an attribute to a dynamic ATT Services at runtime.
AttsCsfRegister
void AttsCsfRegister(attsCsfWriteCback_t writeCback)
Register callback.
AttsCsfSetClientChangeAwareState
void AttsCsfSetClientChangeAwareState(dmConnId_t connId, uint8_t state)
Update a client&#39;s state of awareness to a change in the database.
AttcSignedWriteCmd
void AttcSignedWriteCmd(dmConnId_t connId, uint16_t handle, uint32_t signCounter, uint16_t valueLen, uint8_t *pValue)
Initiate an attribute protocol signed Write Command.
AttsCccClearTable
void AttsCccClearTable(dmConnId_t connId)
Clear and deallocate the client characteristic configuration descriptor value table for a connection...
pAttCfg
attCfg_t * pAttCfg
Configuration pointer.
attCfg_t
ATT run-time configurable parameters.
Definition: att_api.h:152
AttsDynInit
void AttsDynInit(void)
Initialize the Dynamic ATT Service subsystem.
attCback_t
void(* attCback_t)(attEvt_t *pEvt)
ATT event callback type.
Definition: att_api.h:203
ATTC_EXECUTE_WRITE_RSP
Execute write response.
Definition: att_api.h:113
attsGroup_tag::startHandle
uint16_t startHandle
The handle of the first attribute in this group.
Definition: att_api.h:318
AttcIndConfirm
void AttcIndConfirm(dmConnId_t connId)
Send an attribute protocol indication confirmation.
AttcFindByTypeValueReq
void AttcFindByTypeValueReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle, uint16_t uuid16, uint16_t valueLen, uint8_t *pValue, bool_t continuing)
Initiate an attribute protocol Find By Type Value Request.
attsGroup_tag::writeCback
attsWriteCback_t writeCback
Write callback function.
Definition: att_api.h:317
attsGroup_tag::readCback
attsReadCback_t readCback
Read callback function.
Definition: att_api.h:316
AttcExecuteWriteReq
void AttcExecuteWriteReq(dmConnId_t connId, bool_t writeAll)
Initiate an attribute protocol Execute Write Request.
attcDiscChar_tag
ATT client structure for characteristic and descriptor discovery.
Definition: att_api.h:348
AttsAddGroup
void AttsAddGroup(attsGroup_t *pGroup)
Add an attribute group to the attribute server.
AttcSetAutoConfirm
void AttcSetAutoConfirm(bool_t enable)
Set automatic Indication Confirmations sent from this ATT Client.
attsGroup_tag
Attribute group.
Definition: att_api.h:312
AttcInit
void AttcInit(void)
Initialize ATT client.
AttcWriteCmd
void AttcWriteCmd(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Initiate an attribute protocol Write Command.
ATTS_DB_HASH_CALC_CMPL_IND
Database hash calculation complete.
Definition: att_api.h:122
ATTC_FIND_INFO_RSP
ATT callback event starting value.
Definition: att_api.h:103
attsCccCback_t
void(* attsCccCback_t)(attsCccEvt_t *pEvt)
ATTS client characteristic configuration callback.
Definition: att_api.h:395
AttsSignInit
void AttsSignInit(void)
Initialize ATT server for data signing.
AttsInit
void AttsInit(void)
Initialize ATT server.
AttsHandleValueNtf
void AttsHandleValueNtf(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Send an attribute protocol Handle Value Notification.
AttcDiscCharCmpl
uint8_t AttcDiscCharCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg)
This utility function processes a characteristic discovery result. It should be called when an ATTC_R...
attsAuthorCback_t
uint8_t(* attsAuthorCback_t)(dmConnId_t connId, uint8_t permit, uint16_t handle)
ATTS authorization callback type.
Definition: att_api.h:290
ATTC_WRITE_CMD_RSP
Write command response.
Definition: att_api.h:111
AttcSignInit
void AttcSignInit(void)
Initialize ATT client for data signing.
AttMsgFree
void AttMsgFree(void *pMsg, uint8_t opcode)
Free an ATT message buffer allocated with AttMsgAlloc().
eattCfg_t
EATT run-time configurable parameters.
Definition: att_api.h:161
attsGroup_t
struct attsGroup_tag attsGroup_t
Attribute group.
ATTC_READ_MULTIPLE_RSP
Read multiple response.
Definition: att_api.h:108
attClientAwareStates
attClientAwareStates
client&#39;s awareness to database change.
Definition: att_api.h:138
ATTC_MULT_VALUE_NTF
Read multiple value notification.
Definition: att_api.h:117
AttcCancelReq
void AttcCancelReq(dmConnId_t connId)
Cancel an attribute protocol request in progress.
ATT_EATT_CONN_CMPL_IND
EATT Connect channels complete.
Definition: att_api.h:125
AttsCalculateDbHash
void AttsCalculateDbHash(void)
Calculate database hash from the GATT database.
AttsHashDatabaseString
bool_t AttsHashDatabaseString(uint8_t *pKey, uint8_t *pMsg, uint16_t msgLen)
Create hash from the database string.
pEattCfg
eattCfg_t * pEattCfg
Enhanced configuration pointer.
AttcFindInfoReq
void AttcFindInfoReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle, bool_t continuing)
Initiate an attribute protocol Find Information Request.
AttcDiscIncSvcStart
void AttcDiscIncSvcStart(dmConnId_t connId, attcDiscCb_t *pCb)
This utility function starts service include discovery for a service on a peer device. The service must have been previously discovered by calling AttcDiscService() and AttcDiscServiceCmpl().
AttcDiscConfigCmpl
uint8_t AttcDiscConfigCmpl(dmConnId_t connId, attcDiscCb_t *pCb)
This utility function initiates the next characteristic configuration procedure. It should be called ...
AttsCccEnabled
uint16_t AttsCccEnabled(dmConnId_t connId, uint8_t idx)
Check if a client characteristic configuration descriptor is enabled and if the characteristic&#39;s secu...
AttsGetAttr
uint8_t AttsGetAttr(uint16_t handle, uint16_t *pLen, uint8_t **pValue)
Get an attribute value in the attribute server.
attsCccEvt_t
ATTS client characteristic configuration callback structure.
Definition: att_api.h:331
AttsHandleValueInd
void AttsHandleValueInd(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Send an attribute protocol Handle Value Indication.
AttsCsfConnOpen
void AttsCsfConnOpen(dmConnId_t connId, uint8_t changeAwareState, uint8_t *pCsf)
Initialize the client supported features for a connection.
ATTC_FIND_BY_TYPE_VALUE_RSP
Find by type value response.
Definition: att_api.h:104
attsGroup_tag::pNext
struct attsGroup_tag * pNext
For internal use only.
Definition: att_api.h:314
dmCback_t
void(* dmCback_t)(dmEvt_t *pDmEvt)
Callback type.
Definition: dm_api.h:868
AttsDynAddAttrConst
void AttsDynAddAttrConst(void *pSvcHandle, const uint8_t *pUuid, const uint8_t *pValue, const uint16_t len, uint8_t settings, uint8_t permissions)
Dynamically add an attribute with a constant value to a dynamic ATT Services at runtime.
attsCccSet_t
Client characteristc configuration settings.
Definition: att_api.h:323
ATTC_HANDLE_VALUE_NTF
Handle value notification.
Definition: att_api.h:114
AttsDynCreateGroup
void * AttsDynCreateGroup(uint16_t startHandle, uint16_t endHandle)
Dynamically create an ATT Service at runtime.
attcDiscCb_t
ATT client discovery control block.
Definition: att_api.h:363
attsAttr_t
Attribute structure.
Definition: att_api.h:214
AttcWriteReq
void AttcWriteReq(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Initiate an attribute protocol Write Request.
dm_api.h
Device Manager subsystem API.
ATTS_HANDLE_VALUE_CNF
Handle value confirmation.
Definition: att_api.h:119
AttsHandleValueIndZeroCpy
void AttsHandleValueIndZeroCpy(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Send an attribute protocol Handle Value Indication without copying the attribute value data...
AttcMtuReq
void AttcMtuReq(dmConnId_t connId, uint16_t mtu)
Initiate an attribute protocol Exchange MTU Request.
ATTS_CLIENT_CHANGE_AWARE_DB_READ_PENDING
Definition: att_api.h:142
ATTS_CLIENT_CHANGE_UNAWARE
Definition: att_api.h:143
AttGetMtu
uint16_t AttGetMtu(dmConnId_t connId)
Get the attribute protocol MTU of a connection.
ATTS_MULT_VALUE_CNF
Handle multiple value confirmation.
Definition: att_api.h:120
AttsIndInit
void AttsIndInit(void)
Initialize ATT server for indications/notifications.
attsReadCback_t
uint8_t(* attsReadCback_t)(dmConnId_t connId, uint16_t handle, uint8_t operation, uint16_t offset, attsAttr_t *pAttr)
Attribute group read callback.
Definition: att_api.h:253
AttMsgAlloc
void * AttMsgAlloc(uint16_t len, uint8_t opcode)
Allocate an ATT message buffer to be sent with the ATT attribute protocol zero-copy APIs...
attsGroup_tag::pAttr
attsAttr_t * pAttr
Pointer to attribute list for this group.
Definition: att_api.h:315
attsCsfRec_t
Client supported features record structure.
Definition: att_api.h:225
AttcReadByTypeReq
void AttcReadByTypeReq(dmConnId_t connId, uint16_t startHandle, uint16_t endHandle, uint8_t uuidLen, uint8_t *pUuid, bool_t continuing)
Initiate an attribute protocol Read By Type Request.
AttcDiscConfigResume
uint8_t AttcDiscConfigResume(dmConnId_t connId, attcDiscCb_t *pCb)
This utility function resumes the characteristic configuration procedure. It can be called when an AT...
AttsSetAttr
uint8_t AttsSetAttr(uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Set an attribute value in the attribute server.
AttcPrepareWriteReq
void AttcPrepareWriteReq(dmConnId_t connId, uint16_t handle, uint16_t offset, uint16_t valueLen, uint8_t *pValue, bool_t valueByRef, bool_t continuing)
Initiate an attribute protocol Prepare Write Request.
AttsGetCccTableLen
uint8_t AttsGetCccTableLen(void)
Get number of CCC entries in table.
wsf_timer.h
Timer service.
AttsDynRegister
void AttsDynRegister(void *pSvcHandle, attsReadCback_t readCback, attsWriteCback_t writeCback)
Register callback functions for a dynamic ATT Service at runtime.
att_defs.h
Attribute protocol constants and definitions from the Bluetooth specification.
att_uuid.h
Attribute protocol UUIDs from the Bluetooth specification.
wsfTimerTicks_t
uint32_t wsfTimerTicks_t
Timer ticks data type.
Definition: wsf_timer.h:50
AttcDiscIncSvcCmpl
uint8_t AttcDiscIncSvcCmpl(attcDiscCb_t *pCb, attEvt_t *pMsg)
This utility function processes a service include discovery result. It should be called when an ATTC_...
ATTC_READ_BY_GROUP_TYPE_RSP
Read group type response.
Definition: att_api.h:109
attsCsfWriteCback_t
void(* attsCsfWriteCback_t)(dmConnId_t connId, uint8_t changeAwareState, uint8_t *pCsf)
ATTS client supported features write callback type.
Definition: att_api.h:303
attcDiscCfg_t
ATT client structure for characteristic and descriptor configuration.
Definition: att_api.h:355
attsGroup_tag::endHandle
uint16_t endHandle
The handle of the last attribute in this group.
Definition: att_api.h:319
AttsSetCsrk
void AttsSetCsrk(dmConnId_t connId, uint8_t *pCsrk, bool_t authenticated)
Set the peer&#39;s data signing key on this connection. This function is typically called from the ATT co...
attcDiscChar_t
struct attcDiscChar_tag attcDiscChar_t
ATT client structure for characteristic and descriptor discovery.
wsfMsgHdr_t
Common message structure passed to event handler.
Definition: wsf_os.h:106
ATTC_PREPARE_WRITE_RSP
Prepare write response.
Definition: att_api.h:112
ATTS_CLIENT_CHANGE_AWARE
Definition: att_api.h:140
AttsCccSet
void AttsCccSet(dmConnId_t connId, uint8_t idx, uint16_t value)
Set the value of a client characteristic configuration descriptor by its index.
AttsCsfInit
void AttsCsfInit(void)
Initialize ATTS client supported features module.
AttsCsfGetClientChangeAwareState
uint8_t AttsCsfGetClientChangeAwareState(dmConnId_t connId)
Get client state of awareness to a change in the database.
AttcReadReq
void AttcReadReq(dmConnId_t connId, uint16_t handle)
Initiate an attribute protocol Read Request.
ATT_EATT_RECONFIG_CMPL_IND
EATT Reconfigure complete.
Definition: att_api.h:126
ATTC_READ_BY_TYPE_RSP
Read by type value response.
Definition: att_api.h:105
AttConnRegister
void AttConnRegister(dmCback_t cback)
Register a connection callback with ATT. The callback is typically used to manage the attribute serve...
ATTC_READ_RSP
Read response.
Definition: att_api.h:106
AttsHandleValueNtfZeroCpy
void AttsHandleValueNtfZeroCpy(dmConnId_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue)
Send an attribute protocol Handle Value Notification without copying the attribute value data...
cfg_stack.h
Stack configuration.
AttsErrorTest
void AttsErrorTest(uint8_t status)
For testing purposes only.
ATTC_READ_MULT_VAR_RSP
Read multiple variable length response.
Definition: att_api.h:116
AttcDiscService
void AttcDiscService(dmConnId_t connId, attcDiscCb_t *pCb, uint8_t uuidLen, uint8_t *pUuid)
This utility function discovers the given service on a peer device. Function AttcFindByTypeValueReq()...
AttsCccInitTable
void AttsCccInitTable(dmConnId_t connId, uint16_t *pCccTbl)
Initialize the client characteristic configuration descriptor value table for a connection. The table is initialized with the values from pCccTbl. If pCccTbl is NULL the table will be initialized to zero.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.