Cordio Stack and Cordio Profiles  r2p3-02rel0
udsc_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief User Data Service Collector.
6  *
7  * Copyright (c) 2017-2018 Arm Ltd. All Rights Reserved.
8  * Arm Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact Arm Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef UDSC_API_H
20 #define UDSC_API_H
21 
22 #include "att_api.h"
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /*! \addtogroup USER_DATA_PROFILE
29  * \{ */
30 
31 /**************************************************************************************************
32  Macros
33 **************************************************************************************************/
34 
35 /*! \brief UDSC service enumeration of handle indexes of characteristics to be discovered */
36 enum
37 {
38  UDSC_DBCI_HDL_IDX, /*!< \brief Database Change Interval */
39  UDSC_DCBI_CCC_HDL_IDX, /*!< \brief Database Change Interval CCC descriptor */
40  UDSC_UI_HDL_IDX, /*!< \brief User Index */
41  UDSC_UCP_IDX, /*!< \brief User Control Point */
42  UDSC_UCP_CCC_HDL_IDX, /*!< \brief User Control Point CCC descriptor */
43  UDSC_HDL_LIST_LEN /*!< \brief Handle list length */
44 };
45 
46 /** \name User Control Point Opcodes
47  *
48  */
49 /**@{*/
50 #define UDSC_UCP_OPCODE_RNU 0x01 /*!< \brief Register New User */
51 #define UDSC_UCP_OPCODE_CONSENT 0x02 /*!< \brief Consent */
52 #define UDSC_UCP_OPCODE_DUD 0x03 /*!< \brief Delete User Data */
53 #define UDSC_UCP_OPCODE_RESPONSE 0x20 /*!< \brief Command Response */
54 /**@}*/
55 
56 /** \name User Control Point Response Values
57  *
58  */
59 /**@{*/
60 #define UDSC_UCP_RSP_SUCCESS 0x01 /*!< \brief Success */
61 #define UDSC_UCP_RSP_OP_NOT_SUPPORTED 0x02 /*!< \brief Opcode not supported */
62 #define UDSC_UCP_RSP_INVALID_PARAMETER 0x03 /*!< \brief Invalid Parameter */
63 #define UDSC_UCP_RSP_OP_FAILED 0x04 /*!< \brief Operation Failed */
64 #define UDSC_UCP_RSP_NOT_AUTHORIZED 0x05 /*!< \brief User Not Authorized */
65 /**@}*/
66 
67 /**************************************************************************************************
68  Callback Function Datatypes
69 **************************************************************************************************/
70 
71 /*************************************************************************************************/
72 /*!
73  * \brief UDS Control Point Response Callback.
74  *
75  * \param connId Connection ID.
76  * \param opcode Cmd opcode being responded to.
77  * \param response Response code.
78  * \param index User index (only set when opcode is \ref UDSC_UCP_OPCODE_RNU)
79  *
80  * \return None
81  */
82 /*************************************************************************************************/
83 typedef void (*UdsRspCback_t)(dmConnId_t connId, uint8_t opcode, uint8_t response, uint8_t index);
84 
85 /**************************************************************************************************
86  Function Declarations
87 **************************************************************************************************/
88 
89 /*************************************************************************************************/
90 /*!
91  * \brief Perform service and characteristic discovery for User Data service. Parameter
92  * pHdlList must point to an array of length \ref UDSC_HDL_LIST_LEN. If discovery is
93  * successful the handles of discovered characteristics and descriptors will be set
94  * in pHdlList.
95  *
96  * \param connId Connection identifier.
97  * \param pHdlList Characteristic handle list.
98  *
99  * \return None.
100  */
101 /*************************************************************************************************/
102 void UdscDiscover(dmConnId_t connId, uint16_t *pHdlList);
103 
104 /*************************************************************************************************/
105 /*!
106  * \brief Process a value received in an ATT read response, notification, or indication
107  * message. Parameter pHdlList must point to an array of length \ref UDSC_HDL_LIST_LEN.
108  * If the ATT handle of the message matches a handle in the handle list the value
109  * is processed, otherwise it is ignored.
110  *
111  * \param pHdlList Characteristic handle list.
112  * \param pMsg ATT callback message.
113  *
114  * \return \ref ATT_SUCCESS if handle is found, \ref ATT_ERR_NOT_FOUND otherwise.
115  */
116 /*************************************************************************************************/
117 uint8_t UdscValueUpdate(uint16_t *pHdlList, attEvt_t *pMsg);
118 
119 /*************************************************************************************************/
120 /*!
121  * \brief Read the user index characteristic.
122  *
123  * \param connId Connection identifier.
124  * \param handle Attribute handle.
125  *
126  * \return None.
127  */
128 /*************************************************************************************************/
129 void UdscReadUserIndex(dmConnId_t connId, uint16_t handle);
130 
131 /*************************************************************************************************/
132 /*!
133  * \brief Read the database change increment characteristic.
134  *
135  * \param connId Connection identifier.
136  * \param handle Attribute handle.
137  *
138  * \return None.
139  */
140 /*************************************************************************************************/
142 
143 /*************************************************************************************************/
144 /*!
145  * \brief Write the database change increment characteristic.
146  *
147  * \param connId Connection identifier.
148  * \param handle Attribute handle.
149  * \param increment DB Change Increment
150  *
151  * \return None.
152  */
153 /*************************************************************************************************/
154 void UdscWriteDatabaseChangeIncrement(dmConnId_t connId, uint16_t handle, uint32_t increment);
155 
156 /*************************************************************************************************/
157 /*!
158  * \brief Write to the user control point characteristic - Register New User.
159  *
160  * \param connId Connection identifier.
161  * \param handle Attribute handle.
162  * \param consentCode Consent code (0-9999)
163  *
164  * \return None.
165  */
166 /*************************************************************************************************/
167 void UdscRegisterNewUser(dmConnId_t connId, uint16_t handle, uint16_t consentCode);
168 
169 /*************************************************************************************************/
170 /*!
171  * \brief Write to the user control point characteristic - Consent.
172  *
173  * \param connId Connection identifier.
174  * \param handle Attribute handle.
175  * \param index User Index
176  * \param consentCode Consent code (0-9999 - provided when user was registered)
177  *
178  * \return None.
179  */
180 /*************************************************************************************************/
181 void UdscConsent(dmConnId_t connId, uint16_t handle, uint8_t index, uint16_t consentCode);
182 
183 /*************************************************************************************************/
184 /*!
185  * \brief Write to the user control point characteristic - Delete User Data.
186  *
187  * \param connId Connection identifier.
188  * \param handle Attribute handle.
189  *
190  * \return None.
191  */
192 /*************************************************************************************************/
193 void UdscDeleteUserData(dmConnId_t connId, uint16_t handle);
194 
195 /*************************************************************************************************/
196 /*!
197  * \brief Called by the application when a connection closes.
198  *
199  * \return None.
200  */
201 /*************************************************************************************************/
202 void UdscClose(void);
203 
204 /*************************************************************************************************/
205 /*!
206  * \brief Initialize User Data Service collector callbacks.
207  *
208  * \param handlerId Application task handler ID.
209  * \param timerEvent Application timer event for control point timeout.
210  * \param rspCback Callback to receive control point response messages.
211  *
212  * \return None.
213  */
214 /*************************************************************************************************/
215 void UdscInit(wsfHandlerId_t handlerId, uint8_t timerEvent, UdsRspCback_t rspCback);
216 
217 /*! \} */ /* USER_DATA_PROFILE */
218 
219 #ifdef __cplusplus
220 };
221 #endif
222 
223 #endif /* UDSC_API_H */
void UdscClose(void)
Called by the application when a connection closes.
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:501
ATT callback event.
Definition: att_api.h:154
void UdscReadDatabaseChangeIncrement(dmConnId_t connId, uint16_t handle)
Read the database change increment characteristic.
void UdscDiscover(dmConnId_t connId, uint16_t *pHdlList)
Perform service and characteristic discovery for User Data service. Parameter pHdlList must point to ...
uint8_t UdscValueUpdate(uint16_t *pHdlList, attEvt_t *pMsg)
Process a value received in an ATT read response, notification, or indication message. Parameter pHdlList must point to an array of length UDSC_HDL_LIST_LEN. If the ATT handle of the message matches a handle in the handle list the value is processed, otherwise it is ignored.
Database Change Interval CCC descriptor.
Definition: udsc_api.h:39
void UdscReadUserIndex(dmConnId_t connId, uint16_t handle)
Read the user index characteristic.
User Control Point CCC descriptor.
Definition: udsc_api.h:42
User Control Point.
Definition: udsc_api.h:41
unsigned long uint32_t
Unsigned 32-bit value.
Definition: wsf_types.h:71
User Index.
Definition: udsc_api.h:40
uint8_t wsfHandlerId_t
Event handler ID data type.
Definition: wsf_os.h:74
void(* UdsRspCback_t)(dmConnId_t connId, uint8_t opcode, uint8_t response, uint8_t index)
UDS Control Point Response Callback.
Definition: udsc_api.h:83
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
void UdscRegisterNewUser(dmConnId_t connId, uint16_t handle, uint16_t consentCode)
Write to the user control point characteristic - Register New User.
void UdscWriteDatabaseChangeIncrement(dmConnId_t connId, uint16_t handle, uint32_t increment)
Write the database change increment characteristic.
void UdscConsent(dmConnId_t connId, uint16_t handle, uint8_t index, uint16_t consentCode)
Write to the user control point characteristic - Consent.
Attribute protocol client and server API.
void UdscDeleteUserData(dmConnId_t connId, uint16_t handle)
Write to the user control point characteristic - Delete User Data.
Database Change Interval.
Definition: udsc_api.h:38
void UdscInit(wsfHandlerId_t handlerId, uint8_t timerEvent, UdsRspCback_t rspCback)
Initialize User Data Service collector callbacks.
Handle list length.
Definition: udsc_api.h:43
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63