Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nRF51822 by
ble_gattc.h
00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is confidential property of Nordic Semiconductor. The use, 00004 * copying, transfer or disclosure of such information is prohibited except by express written 00005 * agreement with Nordic Semiconductor. 00006 * 00007 */ 00008 /** 00009 @addtogroup BLE_GATTC Generic Attribute Profile (GATT) Client 00010 @{ 00011 @brief Definitions and prototypes for the GATT Client interface. 00012 */ 00013 00014 #ifndef BLE_GATTC_H__ 00015 #define BLE_GATTC_H__ 00016 00017 #include "nordic_global.h" 00018 #include "ble_gatt.h" 00019 #include "ble_types.h" 00020 #include "ble_ranges.h" 00021 #include "nrf_svc.h" 00022 00023 00024 /**@brief GATTC API SVC numbers. */ 00025 enum BLE_GATTC_SVCS 00026 { 00027 SD_BLE_GATTC_PRIMARY_SERVICES_DISCOVER = BLE_GATTC_SVC_BASE, /**< Primary Service Discovery. */ 00028 SD_BLE_GATTC_RELATIONSHIPS_DISCOVER, /**< Relationship Discovery. */ 00029 SD_BLE_GATTC_CHARACTERISTICS_DISCOVER, /**< Characteristic Discovery. */ 00030 SD_BLE_GATTC_DESCRIPTORS_DISCOVER, /**< Characteristic Descriptor Discovery. */ 00031 SD_BLE_GATTC_CHAR_VALUE_BY_UUID_READ, /**< Read Characteristic Value by UUID. */ 00032 SD_BLE_GATTC_READ, /**< Generic read. */ 00033 SD_BLE_GATTC_CHAR_VALUES_READ, /**< Read multiple Characteristic Values. */ 00034 SD_BLE_GATTC_WRITE, /**< Generic write. */ 00035 SD_BLE_GATTC_HV_CONFIRM /**< Handle Value Confirmation. */ 00036 }; 00037 00038 /** @addtogroup BLE_GATTC_DEFINES Defines 00039 * @{ */ 00040 00041 /** @defgroup BLE_ERRORS_GATTC SVC return values specific to GATTC 00042 * @{ */ 00043 #define BLE_ERROR_GATTC_PROC_NOT_PERMITTED (NRF_GATTC_ERR_BASE + 0x000) 00044 /** @} */ 00045 00046 /**@brief Last Attribute Handle. */ 00047 #define BLE_GATTC_HANDLE_END 0xFFFF 00048 00049 /** @} */ 00050 00051 /**@brief Operation Handle Range. */ 00052 typedef struct 00053 { 00054 uint16_t start_handle; /**< Start Handle. */ 00055 uint16_t end_handle; /**< End Handle. */ 00056 } ble_gattc_handle_range_t; 00057 00058 00059 /**@brief GATT service. */ 00060 typedef struct 00061 { 00062 ble_uuid_t uuid; /**< Service UUID. */ 00063 ble_gattc_handle_range_t handle_range; /**< Service Handle Range. */ 00064 } ble_gattc_service_t; 00065 00066 00067 /**@brief GATT include. */ 00068 typedef struct 00069 { 00070 uint16_t handle; /**< Include Handle. */ 00071 ble_gattc_service_t included_srvc; /**< Handle of the included service. */ 00072 } ble_gattc_include_t; 00073 00074 00075 /**@brief GATT characteristic. */ 00076 typedef struct 00077 { 00078 ble_uuid_t uuid; /**< Characteristic UUID. */ 00079 ble_gatt_char_props_t char_props; /**< Characteristic Properties. */ 00080 uint8_t char_ext_props : 1; /**< Extended properties present. */ 00081 uint16_t handle_decl; /**< Handle of the Characteristic Declaration. */ 00082 uint16_t handle_value; /**< Handle of the Characteristic Value. */ 00083 } ble_gattc_char_t; 00084 00085 00086 /**@brief GATT descriptor. */ 00087 typedef struct 00088 { 00089 uint16_t handle; /**< Descriptor Handle. */ 00090 ble_uuid_t uuid; /**< Descriptor UUID. */ 00091 } ble_gattc_desc_t; 00092 00093 00094 /**@brief Write Parameters. */ 00095 typedef struct 00096 { 00097 uint8_t write_op; /**< Write Operation to be performed, see BLE_GATT_WRITE_OPS. */ 00098 uint16_t handle; /**< Handle to the attribute to be written. */ 00099 uint16_t offset; /**< Offset in bytes. */ 00100 uint16_t len; /**< Length of data in bytes. */ 00101 uint8_t* p_value; /**< Pointer to the value data. */ 00102 uint8_t flags; /**< Flags, see @ref BLE_GATT_EXEC_WRITE_FLAGS. */ 00103 } ble_gattc_write_params_t; 00104 00105 00106 /** 00107 * @brief GATT Client Event IDs. 00108 */ 00109 enum BLE_GATTC_EVTS 00110 { 00111 BLE_GATTC_EVT_PRIM_SRVC_DISC_RSP = BLE_GATTC_EVT_BASE, /**< Primary Service Discovery Response event. */ 00112 BLE_GATTC_EVT_REL_DISC_RSP, /**< Relationship Discovery Response event. */ 00113 BLE_GATTC_EVT_CHAR_DISC_RSP, /**< Characteristic Discovery Response event. */ 00114 BLE_GATTC_EVT_DESC_DISC_RSP, /**< Descriptor Discovery Response event. */ 00115 BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP, /**< Read By UUID Response event. */ 00116 BLE_GATTC_EVT_READ_RSP, /**< Read Response event. */ 00117 BLE_GATTC_EVT_CHAR_VALS_READ_RSP, /**< Read multiple Response event. */ 00118 BLE_GATTC_EVT_WRITE_RSP, /**< Write Response event. */ 00119 BLE_GATTC_EVT_HVX, /**< Handle Value Notification or Indication event. */ 00120 BLE_GATTC_EVT_TIMEOUT /**< Timeout event. */ 00121 }; 00122 00123 /**@brief Event structure for BLE_GATTC_EVT_PRIM_SRVC_DISC_RSP. */ 00124 typedef struct 00125 { 00126 uint16_t count; /**< Service count. */ 00127 ble_gattc_service_t services[1]; /**< Service data, variable length. */ 00128 } ble_gattc_evt_prim_srvc_disc_rsp_t; 00129 00130 /**@brief Event structure for BLE_GATTC_EVT_REL_DISC_RSP. */ 00131 typedef struct 00132 { 00133 uint16_t count; /**< Include count. */ 00134 ble_gattc_include_t includes[1]; /**< Include data, variable length. */ 00135 } ble_gattc_evt_rel_disc_rsp_t; 00136 00137 /**@brief Event structure for BLE_GATTC_EVT_CHAR_DISC_RSP. */ 00138 typedef struct 00139 { 00140 uint16_t count; /**< Characteristic count. */ 00141 ble_gattc_char_t chars[1]; /**< Characteristic data, variable length. */ 00142 } ble_gattc_evt_char_disc_rsp_t; 00143 00144 /**@brief Event structure for BLE_GATTC_EVT_DESC_DISC_RSP. */ 00145 typedef struct 00146 { 00147 uint16_t count; /**< Descriptor count. */ 00148 ble_gattc_desc_t descs[1]; /**< Descriptor data, variable length. */ 00149 } ble_gattc_evt_desc_disc_rsp_t; 00150 00151 /**@brief GATT read by UUID handle value pair. */ 00152 typedef struct 00153 { 00154 uint16_t handle; /**< Attribute Handle. */ 00155 uint8_t *p_value; /**< Pointer to value, variable length (length available as value_len in ble_gattc_evt_read_by_uuid_rsp_t). 00156 Please note that this pointer is absolute to the memory provided by the user when retrieving the event, 00157 so it will effectively point to a location inside the handle_value array. */ 00158 } ble_gattc_handle_value_t; 00159 00160 /**@brief Event structure for BLE_GATTC_EVT_CHAR_VAL_BY_UUID_READ_RSP. */ 00161 typedef struct 00162 { 00163 uint16_t count; /**< Handle-Value Pair Count. */ 00164 uint16_t value_len; /**< Length of the value in Handle-Value(s) list. */ 00165 ble_gattc_handle_value_t handle_value[1]; /**< Handle-Value(s) list, variable length. */ 00166 } ble_gattc_evt_char_val_by_uuid_read_rsp_t; 00167 00168 /**@brief Event structure for BLE_GATTC_EVT_READ_RSP. */ 00169 typedef struct 00170 { 00171 uint16_t handle; /**< Attribute Handle. */ 00172 uint16_t offset; /**< Offset of the attribute data. */ 00173 uint16_t len; /**< Attribute data length. */ 00174 uint8_t data[1]; /**< Attribute data, variable length. */ 00175 } ble_gattc_evt_read_rsp_t; 00176 00177 /**@brief Event structure for BLE_GATTC_EVT_CHAR_VALS_READ_RSP. */ 00178 typedef struct 00179 { 00180 uint16_t len; /**< Concatenated Attribute values length. */ 00181 uint8_t values[1]; /**< Attribute values, variable length. */ 00182 } ble_gattc_evt_char_vals_read_rsp_t; 00183 00184 /**@brief Event structure for BLE_GATTC_EVT_WRITE_RSP. */ 00185 typedef struct 00186 { 00187 uint16_t handle; /**< Attribute Handle. */ 00188 uint8_t write_op; /**< Type of write operation, see @ref BLE_GATT_WRITE_OPS. */ 00189 uint16_t offset; /**< Data Offset. */ 00190 uint16_t len; /**< Data length. */ 00191 uint8_t data[1]; /**< Data, variable length. */ 00192 } ble_gattc_evt_write_rsp_t; 00193 00194 /**@brief Event structure for BLE_GATTC_EVT_HVX. */ 00195 typedef struct 00196 { 00197 uint16_t handle; /**< Handle to which the HVx operation applies. */ 00198 uint8_t type; /**< Indication or Notification, see @ref BLE_GATT_HVX_TYPES. */ 00199 uint16_t len; /**< Attribute data length. */ 00200 uint8_t data[1]; /**< Attribute data, variable length. */ 00201 } ble_gattc_evt_hvx_t; 00202 00203 /**@brief Event structure for BLE_GATTC_EVT_TIMEOUT. */ 00204 typedef struct 00205 { 00206 uint8_t src; /**< Timeout source, see @ref BLE_GATT_TIMEOUT_SOURCES. */ 00207 } ble_gattc_evt_timeout_t; 00208 00209 /**@brief GATTC event type. */ 00210 typedef struct 00211 { 00212 uint16_t conn_handle; /**< Connection Handle on which event occured. */ 00213 uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */ 00214 uint16_t error_handle; /**< In case of error: The handle causing the error. In all other cases BLE_GATT_HANDLE_INVALID. */ 00215 union 00216 { 00217 ble_gattc_evt_prim_srvc_disc_rsp_t prim_srvc_disc_rsp; /**< Primary Service Discovery Response Event Parameters. */ 00218 ble_gattc_evt_rel_disc_rsp_t rel_disc_rsp; /**< Relationship Discovery Response Event Parameters. */ 00219 ble_gattc_evt_char_disc_rsp_t char_disc_rsp; /**< Characteristic Discovery Response Event Parameters. */ 00220 ble_gattc_evt_desc_disc_rsp_t desc_disc_rsp; /**< Descriptor Discovery Response Event Parameters. */ 00221 ble_gattc_evt_char_val_by_uuid_read_rsp_t char_val_by_uuid_read_rsp; /**< Characteristic Value Read by UUID Response Event Parameters. */ 00222 ble_gattc_evt_read_rsp_t read_rsp; /**< Read Response Event Parameters. */ 00223 ble_gattc_evt_char_vals_read_rsp_t char_vals_read_rsp; /**< Characteristic Values Read Response Event Parameters. */ 00224 ble_gattc_evt_write_rsp_t write_rsp; /**< Write Response Event Parameters. */ 00225 ble_gattc_evt_hvx_t hvx; /**< Handle Value Notification/Indication Event Parameters. */ 00226 ble_gattc_evt_timeout_t timeout; /**< Timeout Event Parameters. */ 00227 } params; /**< Event Parameters. @note Only valid if @ref gatt_status == BLE_GATT_STATUS_SUCCESS. */ 00228 } ble_gattc_evt_t; 00229 00230 00231 /**@brief Initiate or continue a GATT Primary Service Discovery procedure. 00232 * 00233 * @details This function initiates a Primary Service discovery, starting from the supplied handle. 00234 * If the last service has not been reached, this must be called again with an updated start handle value to continue the search. 00235 * 00236 * @note If any of the discovered services have 128-bit UUIDs which are not present in the table provided to ble_vs_uuids_assign, a UUID structure with 00237 * type BLE_UUID_TYPE_UNKNOWN will be received in the corresponding event. 00238 * 00239 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00240 * @param[in] start_handle Handle to start searching from. 00241 * @param[in] p_srvc_uuid Pointer to the service UUID to be found. If it is NULL, all primary services will be returned. 00242 * 00243 * @return @ref NRF_SUCCESS Successfully started or resumed the Primary Service Discovery procedure. 00244 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00245 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00246 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00247 */ 00248 SVCALL(SD_BLE_GATTC_PRIMARY_SERVICES_DISCOVER, uint32_t, sd_ble_gattc_primary_services_discover(uint16_t conn_handle, uint16_t start_handle, ble_uuid_t const * const p_srvc_uuid)); 00249 00250 00251 /**@brief Initiate or continue a GATT Relationship Discovery procedure. 00252 * 00253 * @details This function initiates the Find Included Services sub-procedure. If the last included service has not been reached, 00254 * this must be called again with an updated handle range to continue the search. 00255 * 00256 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00257 * @param[in] p_handle_range A pointer to the range of handles of the Service to perform this procedure on. 00258 * 00259 * @return @ref NRF_SUCCESS Successfully started or resumed the Relationship Discovery procedure. 00260 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00261 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00262 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00263 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00264 */ 00265 SVCALL(SD_BLE_GATTC_RELATIONSHIPS_DISCOVER, uint32_t, sd_ble_gattc_relationships_discover(uint16_t conn_handle, ble_gattc_handle_range_t const * const p_handle_range)); 00266 00267 00268 /**@brief Initiate or continue a GATT Characteristic Discovery procedure. 00269 * 00270 * @details This function initiates a Characteristic discovery procedure. If the last Characteristic has not been reached, 00271 * this must be called again with an updated handle range to continue the discovery. 00272 * 00273 * @note If any of the discovered characteristics have 128-bit UUIDs which are not present in the table provided to ble_vs_uuids_assign, a UUID structure with 00274 * type BLE_UUID_TYPE_UNKNOWN will be received in the corresponding event. 00275 * 00276 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00277 * @param[in] p_handle_range A pointer to the range of handles of the Service to perform this procedure on. 00278 * 00279 * @return @ref NRF_SUCCESS Successfully started or resumed the Characteristic Discovery procedure. 00280 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00281 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00282 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00283 */ 00284 SVCALL(SD_BLE_GATTC_CHARACTERISTICS_DISCOVER, uint32_t, sd_ble_gattc_characteristics_discover(uint16_t conn_handle, ble_gattc_handle_range_t const * const p_handle_range)); 00285 00286 00287 /**@brief Initiate or continue a GATT Characteristic Descriptor Discovery procedure. 00288 * 00289 * @details This function initiates the Characteristic Descriptor discovery procedure. If the last Descriptor has not been reached, 00290 * this must be called again with an updated handle range to continue the discovery. 00291 * 00292 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00293 * @param[in] p_handle_range A pointer to the range of handles of the Characteristic to perform this procedure on. 00294 * 00295 * @return @ref NRF_SUCCESS Successfully started or resumed the Descriptor Discovery procedure. 00296 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00297 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00298 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00299 */ 00300 SVCALL(SD_BLE_GATTC_DESCRIPTORS_DISCOVER, uint32_t, sd_ble_gattc_descriptors_discover(uint16_t conn_handle, ble_gattc_handle_range_t const * const p_handle_range)); 00301 00302 00303 /**@brief Initiate or continue a GATT Read using Characteristic UUID procedure. 00304 * 00305 * @details This function initiates the Read using Characteristic UUID procedure. If the last Characteristic has not been reached, 00306 * this must be called again with an updated handle range to continue the discovery. 00307 * 00308 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00309 * @param[in] p_uuid Pointer to a Characteristic value UUID to read. 00310 * @param[in] p_handle_range A pointer to the range of handles to perform this procedure on. 00311 * 00312 * @return @ref NRF_SUCCESS Successfully started or resumed the Read using Characteristic UUID procedure. 00313 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00314 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00315 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00316 */ 00317 SVCALL(SD_BLE_GATTC_CHAR_VALUE_BY_UUID_READ, uint32_t, sd_ble_gattc_char_value_by_uuid_read(uint16_t conn_handle, ble_uuid_t const * const p_uuid, ble_gattc_handle_range_t const * const p_handle_range)); 00318 00319 00320 /**@brief Initiate or continue a GATT Read (Long) Characteristic or Descriptor procedure. 00321 * 00322 * @details This function initiates a GATT Read (Long) Characteristic or Descriptor procedure. If the Characteristic or Descriptor 00323 * to be read is longer than GATT_MTU - 1, this function must be called multiple times with appropriate offset to read the 00324 * complete value. 00325 * 00326 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00327 * @param[in] handle The handle of the attribute to be read. 00328 * @param[in] offset Offset into the attribute value to be read. 00329 * 00330 * @return @ref NRF_SUCCESS Successfully started or resumed the Read (Long) procedure. 00331 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00332 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00333 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00334 */ 00335 SVCALL(SD_BLE_GATTC_READ, uint32_t, sd_ble_gattc_read(uint16_t conn_handle, uint16_t handle, uint16_t offset)); 00336 00337 00338 /**@brief Initiate a GATT Read Multiple Characteristic Values procedure. 00339 * 00340 * @details This function initiates a GATT Read Multiple Characteristic Values procedure. 00341 * 00342 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00343 * @param[in] p_handles A pointer to the handle(s) of the attribute(s) to be read. 00344 * @param[in] handle_count The number of handles in p_handles. 00345 * 00346 * @return @ref NRF_SUCCESS Successfully started the Read Multiple Characteristic Values procedure. 00347 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00348 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00349 * @return @ref NRF_ERROR_BUSY Client procedure already in progress. 00350 */ 00351 SVCALL(SD_BLE_GATTC_CHAR_VALUES_READ, uint32_t, sd_ble_gattc_char_values_read(uint16_t conn_handle, uint16_t const * const p_handles, uint16_t handle_count)); 00352 00353 00354 /**@brief Perform a Write (Characteristic Value or Descriptor, with or without response, signed or not, long or reliable) procedure. 00355 * 00356 * @details This function can perform all write procedures described in GATT. 00357 * 00358 * @note It is important to note that a write without response will <b>consume an application buffer</b>, and will therefore 00359 * generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. A write on the other hand will use the 00360 * standard client internal buffer and thus will only generate a @ref BLE_GATTC_EVT_WRITE_RSP event as soon as the write response 00361 * has been received from the peer. Please see the documentation of @ref sd_ble_tx_buffer_count_get for more details. 00362 * 00363 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00364 * @param[in] p_write_params A pointer to a write parameters structure. 00365 * 00366 * @return @ref NRF_SUCCESS Successfully started the Write procedure. 00367 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00368 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00369 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00370 * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied. 00371 * @return @ref NRF_ERROR_BUSY Procedure already in progress. 00372 * @return @ref BLE_ERROR_NO_TX_BUFFERS There are no available buffers left. 00373 */ 00374 SVCALL(SD_BLE_GATTC_WRITE, uint32_t, sd_ble_gattc_write(uint16_t conn_handle, ble_gattc_write_params_t const * const p_write_params)); 00375 00376 00377 /**@brief Send a Handle Value Confirmation to the GATT Server. 00378 * 00379 * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. 00380 * @param[in] handle The handle of the attribute in the indication. 00381 * 00382 * @return @ref NRF_SUCCESS Successfully queued the Handle Value Confirmation for transmission. 00383 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00384 * @return @ref NRF_ERROR_INVALID_STATE No Indication pending to be confirmed. 00385 * @return @ref BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle. 00386 * @return @ref BLE_ERROR_NO_TX_BUFFERS There are no available buffers left. 00387 */ 00388 SVCALL(SD_BLE_GATTC_HV_CONFIRM, uint32_t, sd_ble_gattc_hv_confirm(uint16_t conn_handle, uint16_t handle)); 00389 00390 00391 #endif /* BLE_GATTC_H__ */ 00392 00393 /** 00394 @} 00395 @} 00396 */
Generated on Tue Jul 12 2022 18:44:25 by
