dis_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file dis_c.h
5 *
6 * @brief Device Information Service Client API
7 *
8 *****************************************************************************************
9 */
10 
11 /**
12  * @addtogroup BLE_SRV BLE Services
13  * @{
14  * @attention
15  #####Copyright (c) 2019 GOODIX
16  All rights reserved.
17 
18  Redistribution and use in source and binary forms, with or without
19  modification, are permitted provided that the following conditions are met:
20  * Redistributions of source code must retain the above copyright
21  notice, this list of conditions and the following disclaimer.
22  * Redistributions in binary form must reproduce the above copyright
23  notice, this list of conditions and the following disclaimer in the
24  documentation and/or other materials provided with the distribution.
25  * Neither the name of GOODIX nor the names of its contributors may be used
26  to endorse or promote products derived from this software without
27  specific prior written permission.
28 
29  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
30  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
31  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
32  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
33  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
34  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
35  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
36  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
37  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
39  POSSIBILITY OF SUCH DAMAGE.
40  *****************************************************************************************
41  */
42 
43 /**
44  * @defgroup BLE_SDK_DIS_C Device Information Service Client (DIS_C)
45  * @{
46  * @brief Device Information Service Client module.
47  *
48  * @details The Device Information Service Client contains the APIs and types, which can be used by the
49  * application to discover Device Information Service of peer and interact with it.
50  *
51  * The application must provide an event handler to register, then call \ref dis_client_init().
52  * After Device Information Service Client discovers peer Device Information Service,
53  * application calls \ref dis_c_char_value_read() and get peer device information.
54  */
55 
56 #ifndef __DIS_C_H__
57 #define __DIS_C_H__
58 
59 #include "gr_includes.h"
60 #include "ble_prf_types.h"
61 #include "custom_config.h"
62 #include <stdint.h>
63 #include <stdbool.h>
64 
65 /**
66  * @defgroup DIS_C_MACRO Defines
67  * @{
68  */
69 #define DIS_C_CONNECTION_MAX 10 /**< Maximum number of DIS Client connections. */
70 #define DIS_C_STRING_LEN_MAX 128 /**< Maximal length for Characteristic values - 128 bytes. */
71 
72 /**
73  * @defgroup DIS_IEEE_11073_BODY IEEE 11073-20601 Authoritative Body Type
74  * @{
75  */
76 #define DIS_C_11073_BODY_EMPTY 0 /**< Empty body type. */
77 #define DIS_C_11073_BODY_IEEE 1 /**< IEEE body type. */
78 #define DIS_C_11073_BODY_CONTINUA 2 /**< Continua body type. */
79 #define DIS_C_11073_BODY_EXP 254 /**< Exp body type. */
80 /** @} */
81 
82 /** @} */
83 
84 /**
85  * @defgroup DIS_C_ENUM Enumerations
86  * @{
87  */
88 /**@brief Device Information Service Client event type. */
89 typedef enum
90 {
91  DIS_C_EVT_INVALID, /**< DIS Client invalid event. */
92  DIS_C_EVT_DISCOVERY_COMPLETE, /**< DIS Client has found Device Information Service and its characteristics. */
93  DIS_C_EVT_DISCOVERY_FAIL, /**< DIS Client found DIS service failed because of invalid operation or no found at the peer. */
94  DIS_C_EVT_DEV_INFORMATION_READ_RSP, /**< DIS Client has received device information value read response. */
96 
97 /**@brief Device Information Service Client characteristic type. */
98 typedef enum
99 {
100  DIS_C_SYS_ID, /**< System ID characteristic. */
101  DIS_C_MODEL_NUM, /**< Model Number String characteristic. */
102  DIS_C_SERIAL_NUM, /**< Serial Number String characteristic. */
103  DIS_C_HW_REV, /**< Hardware Revision String characteristic. */
104  DIS_C_FW_REV, /**< Firmware Revision String characteristic. */
105  DIS_C_SW_REV, /**< Software Revision String characteristic. */
106  DIS_C_MANUF_NAME, /**< Manufacturer Name String characteristic. */
107  DIS_C_CERT_LIST, /**< IEEE 11073-20601 Regulatory Certification Data List characteristic. */
108  DIS_C_PNP_ID, /**< PnP ID characteristic. */
109  DIS_C_CHARACTER_NB /**< Number of all Device Information Service characteristics. */
111 /** @} */
112 
113 /**
114  * @defgroup DIS_C_STRUCT Structures
115  * @{
116  */
117 /**@brief Handles on the connected peer device needed to interact with it. */
118 typedef struct
119 {
120  uint16_t dis_srvc_start_handle; /**< DIS Serivce start handle. */
121  uint16_t dis_srvc_end_handle; /**< DIS Service end handle. */
122  uint16_t dis_char_handle[DIS_C_CHARACTER_NB]; /**< DIS characteristic handle. */
124 
125 /**@brief Response data for string-based DIS characteristics. */
126 typedef struct
127 {
128  uint8_t *p_data; /**< Pointer to response data. */
129  uint16_t length; /**< Response data length. */
131 
132 /**@brief Response data for System ID parameters. */
133 typedef struct
134 {
135  uint8_t manufacturer_id[5]; /**< Manufacturer-defined ID. */
136  uint8_t org_unique_id[3]; /**< Organizationally unique ID (OUI) which is issued by IEEE. */
138 
139 /**@brief Response data for IEEE 11073-20601 Regulatory Certification Data List Structure. */
140 typedef struct
141 {
142  uint8_t *p_list; /**< Pointer to the list which contains the encoded opaque structure based on IEEE 11073-20601 specification. */
143  uint16_t list_length; /**< Length of the list. */
145 
146 /**@brief Response data for PnP ID parameters */
147 typedef struct
148 {
149  uint8_t vendor_id_source; /**< Vendor ID Source. */
150  uint16_t vendor_id; /**< Vendor ID. */
151  uint16_t product_id; /**< Product ID. */
152  uint16_t product_version; /**< Product Version. */
154 
155 /**@brief Device Information Service Client Read Response encode structure. */
156 typedef struct
157 {
158  dis_c_char_type_t char_type; /**< Characteristic type. */
159  union
160  {
161  dis_c_sys_id_t sys_id; /**< System ID characteristic response data. */
162  dis_c_string_t string_data; /**< Model Number, Serial Number, Hardware Revision, Firmware Revision, Software Revision, Manufacturer Name String characteristic response data. */
163  dis_c_reg_cert_data_list_t cert_list; /**< IEEE 11073-20601 Regulatory Certification Data List characteristic response data. */
164  dis_c_pnp_id_t pnp_id; /**< PnP ID characteristic response data. */
165  } encode_rst; /**< Result of encoding. */
167 
168 /**@brief Device Information Service Client event. */
169 typedef struct
170 {
171  uint8_t conn_idx; /**< The connection index. */
172  dis_c_evt_type_t evt_type; /**< DIS Client event type. */
173  ble_dis_c_read_rsp_t read_rsp; /**< DIS Client characteristic Read Response encode. */
174 } dis_c_evt_t;
175 /** @} */
176 
177 /**
178  * @defgroup DIS_C_TYPEDEF Typedefs
179  * @{
180  */
181 /**@brief Device Information Service Client event handler type. */
182 typedef void (*dis_c_evt_handler_t)(dis_c_evt_t *p_evt);
183 /** @} */
184 
185 /**
186  * @defgroup DIS_C_FUNCTION Functions
187  * @{
188  */
189 /**
190  *****************************************************************************************
191  * @brief Register DIS Client event handler.
192  *
193  * @param[in] evt_handler: Device Information Service Client event handler.
194  *
195  * @return Result of initialization.
196  *****************************************************************************************
197  */
199 
200 /**
201  *****************************************************************************************
202  * @brief Discovery Device Information Service on peer.
203  *
204  * @param[in] conn_idx: Index of connection.
205  *
206  * @return Operation result.
207  *****************************************************************************************
208  */
210 
211 /**
212  *****************************************************************************************
213  * @brief Read Device Information Service characteristic value.
214  *
215  * @param[in] conn_idx: Index of connection.
216  * @param[in] char_read_type: Type of characteristic read.
217  *
218  * @return Operation result.
219  *****************************************************************************************
220  */
221 sdk_err_t dis_c_char_value_read(uint8_t conn_idx, dis_c_char_type_t char_read_type);
222 /** @} */
223 
224 #endif
225 
226 /** @} */
227 /** @} */
228 
DIS_C_EVT_DISCOVERY_COMPLETE
@ DIS_C_EVT_DISCOVERY_COMPLETE
Definition: dis_c.h:92
DIS_C_EVT_DISCOVERY_FAIL
@ DIS_C_EVT_DISCOVERY_FAIL
Definition: dis_c.h:93
ble_dis_c_read_rsp_t
Device Information Service Client Read Response encode structure.
Definition: dis_c.h:157
DIS_C_EVT_DEV_INFORMATION_READ_RSP
@ DIS_C_EVT_DEV_INFORMATION_READ_RSP
Definition: dis_c.h:94
ble_dis_c_read_rsp_t::pnp_id
dis_c_pnp_id_t pnp_id
Definition: dis_c.h:164
DIS_C_MANUF_NAME
@ DIS_C_MANUF_NAME
Definition: dis_c.h:106
dis_c_pnp_id_t::vendor_id_source
uint8_t vendor_id_source
Definition: dis_c.h:149
dis_c_evt_t::evt_type
dis_c_evt_type_t evt_type
Definition: dis_c.h:172
dis_c_evt_handler_t
void(* dis_c_evt_handler_t)(dis_c_evt_t *p_evt)
Device Information Service Client event handler type.
Definition: dis_c.h:182
ble_dis_c_read_rsp_t::sys_id
dis_c_sys_id_t sys_id
Definition: dis_c.h:161
dis_c_disc_srvc_start
sdk_err_t dis_c_disc_srvc_start(uint8_t conn_idx)
Discovery Device Information Service on peer.
DIS_C_PNP_ID
@ DIS_C_PNP_ID
Definition: dis_c.h:108
ble_dis_c_read_rsp_t::string_data
dis_c_string_t string_data
Definition: dis_c.h:162
dis_c_reg_cert_data_list_t
Response data for IEEE 11073-20601 Regulatory Certification Data List Structure.
Definition: dis_c.h:141
dis_c_reg_cert_data_list_t::p_list
uint8_t * p_list
Definition: dis_c.h:142
gr_includes.h
Include Files API.
DIS_C_SERIAL_NUM
@ DIS_C_SERIAL_NUM
Definition: dis_c.h:102
dis_c_string_t::length
uint16_t length
Definition: dis_c.h:129
dis_c_string_t::p_data
uint8_t * p_data
Definition: dis_c.h:128
dis_c_pnp_id_t::product_id
uint16_t product_id
Definition: dis_c.h:151
DIS_C_FW_REV
@ DIS_C_FW_REV
Definition: dis_c.h:104
dis_c_reg_cert_data_list_t::list_length
uint16_t list_length
Definition: dis_c.h:143
dis_c_pnp_id_t::vendor_id
uint16_t vendor_id
Definition: dis_c.h:150
dis_c_evt_type_t
dis_c_evt_type_t
Device Information Service Client event type.
Definition: dis_c.h:90
DIS_C_SYS_ID
@ DIS_C_SYS_ID
Definition: dis_c.h:100
dis_c_pnp_id_t::product_version
uint16_t product_version
Definition: dis_c.h:152
dis_client_init
sdk_err_t dis_client_init(dis_c_evt_handler_t evt_handler)
Register DIS Client event handler.
ble_prf_types.h
Profile/Service Common Types.
dis_c_sys_id_t
Response data for System ID parameters.
Definition: dis_c.h:134
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:290
DIS_C_MODEL_NUM
@ DIS_C_MODEL_NUM
Definition: dis_c.h:101
dis_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: dis_c.h:119
DIS_C_CERT_LIST
@ DIS_C_CERT_LIST
Definition: dis_c.h:107
dis_c_pnp_id_t
Response data for PnP ID parameters.
Definition: dis_c.h:148
DIS_C_SW_REV
@ DIS_C_SW_REV
Definition: dis_c.h:105
dis_c_string_t
Response data for string-based DIS characteristics.
Definition: dis_c.h:127
DIS_C_EVT_INVALID
@ DIS_C_EVT_INVALID
Definition: dis_c.h:91
dis_c_evt_t::conn_idx
uint8_t conn_idx
Definition: dis_c.h:171
dis_c_handles_t::dis_srvc_start_handle
uint16_t dis_srvc_start_handle
Definition: dis_c.h:120
dis_c_evt_t
Device Information Service Client event.
Definition: dis_c.h:170
DIS_C_CHARACTER_NB
@ DIS_C_CHARACTER_NB
Definition: dis_c.h:109
DIS_C_HW_REV
@ DIS_C_HW_REV
Definition: dis_c.h:103
ble_dis_c_read_rsp_t::cert_list
dis_c_reg_cert_data_list_t cert_list
Definition: dis_c.h:163
ble_dis_c_read_rsp_t::char_type
dis_c_char_type_t char_type
Definition: dis_c.h:158
dis_c_handles_t::dis_srvc_end_handle
uint16_t dis_srvc_end_handle
Definition: dis_c.h:121
dis_c_char_type_t
dis_c_char_type_t
Device Information Service Client characteristic type.
Definition: dis_c.h:99
dis_c_evt_t::read_rsp
ble_dis_c_read_rsp_t read_rsp
Definition: dis_c.h:173
dis_c_char_value_read
sdk_err_t dis_c_char_value_read(uint8_t conn_idx, dis_c_char_type_t char_read_type)
Read Device Information Service characteristic value.