BLE temperature profile using digital DS1820 or analog LM35 sensors
Embed:
(wiki syntax)
Show/hide line numbers
ble_gatts.h
00001 /* Copyright (c) 2011 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_GATTS Generic Attribute Profile (GATT) Server 00010 @{ 00011 @brief Definitions and prototypes for the GATTS interface. 00012 */ 00013 00014 #ifndef BLE_GATTS_H__ 00015 #define BLE_GATTS_H__ 00016 00017 #include "nordic_global.h" 00018 #include "ble_types.h" 00019 #include "ble_ranges.h" 00020 #include "ble_l2cap.h" 00021 #include "ble_gap.h" 00022 #include "ble_gatt.h" 00023 #include "nrf_svc.h" 00024 00025 00026 /** 00027 * @brief GATTS API SVC numbers. 00028 */ 00029 enum BLE_GATTS_SVCS 00030 { 00031 SD_BLE_GATTS_SERVICE_ADD = BLE_GATTS_SVC_BASE, /**< Add a service. */ 00032 SD_BLE_GATTS_INCLUDE_ADD, /**< Add an included service. */ 00033 SD_BLE_GATTS_CHARACTERISTIC_ADD, /**< Add a characteristic. */ 00034 SD_BLE_GATTS_DESCRIPTOR_ADD, /**< Add a generic attribute. */ 00035 SD_BLE_GATTS_VALUE_SET, /**< Set an attribute value. */ 00036 SD_BLE_GATTS_VALUE_GET, /**< Get an attribute value. */ 00037 SD_BLE_GATTS_HVX, /**< Handle Value Notification or Indication. */ 00038 SD_BLE_GATTS_SERVICE_CHANGED, /**< Perform a Service Changed Indication to one or more peers. */ 00039 SD_BLE_GATTS_RW_AUTHORIZE_REPLY, /**< Reply to an authorization request for a read or write operation on one or more attributes. */ 00040 SD_BLE_GATTS_SYS_ATTR_SET, /**< Set the persistent system attributes for a connection. */ 00041 SD_BLE_GATTS_SYS_ATTR_GET, /**< Get updated persistent system attributes after terminating a connection. */ 00042 }; 00043 00044 00045 /** @addtogroup BLE_GATTS_DEFINES Defines 00046 * @{ */ 00047 00048 /** @brief Only the default MTU size of 23 is currently supported. */ 00049 #define GATT_RX_MTU 23 00050 00051 /** @defgroup BLE_ERRORS_GATTS SVC return values specific to GATTS 00052 * @{ */ 00053 #define BLE_ERROR_GATTS_INVALID_ATTR_TYPE (NRF_GATTS_ERR_BASE + 0x000) /**< Invalid attribute type. */ 00054 #define BLE_ERROR_GATTS_SYS_ATTR_MISSING (NRF_GATTS_ERR_BASE + 0x001) /**< System Attributes missing. */ 00055 /** @} */ 00056 00057 /** @defgroup BLE_GATTS_ATTR_LENS_MAX Maximum attribute lengths 00058 * @{ */ 00059 #define BLE_GATTS_FIX_ATTR_LEN_MAX (510) /**< Maximum length for fixed length Attribute Values. */ 00060 #define BLE_GATTS_VAR_ATTR_LEN_MAX (512) /**< Maximum length for variable length Attribute Values. */ 00061 /** @} */ 00062 00063 /** @defgroup BLE_GATTS_SRVC_TYPES GATT Server Service Types 00064 * @{ */ 00065 #define BLE_GATTS_SRVC_TYPE_INVALID 0x00 /**< Invalid Service Type. */ 00066 #define BLE_GATTS_SRVC_TYPE_PRIMARY 0x01 /**< Primary Service. */ 00067 #define BLE_GATTS_SRVC_TYPE_SECONDARY 0x02 /**< Secondary Type. */ 00068 /** @} */ 00069 00070 00071 /** @defgroup BLE_GATTS_ATTR_TYPES GATT Server Attribute Types 00072 * @{ */ 00073 #define BLE_GATTS_ATTR_TYPE_INVALID 0x00 /**< Invalid Attribute Type. */ 00074 #define BLE_GATTS_ATTR_TYPE_PRIM_SRVC_DECL 0x01 /**< Primary Service Declaration. */ 00075 #define BLE_GATTS_ATTR_TYPE_SEC_SRVC_DECL 0x02 /**< Secondary Service Declaration. */ 00076 #define BLE_GATTS_ATTR_TYPE_INC_DECL 0x03 /**< Include Declaration. */ 00077 #define BLE_GATTS_ATTR_TYPE_CHAR_DECL 0x04 /**< Characteristic Declaration. */ 00078 #define BLE_GATTS_ATTR_TYPE_CHAR_VAL 0x05 /**< Characteristic Value. */ 00079 #define BLE_GATTS_ATTR_TYPE_DESC 0x06 /**< Descriptor. */ 00080 #define BLE_GATTS_ATTR_TYPE_OTHER 0x07 /**< Other, non-GATT specific type. */ 00081 /** @} */ 00082 00083 00084 /** @defgroup BLE_GATTS_OPS GATT Server Operations 00085 * @{ */ 00086 #define BLE_GATTS_OP_INVALID 0x00 /**< Invalid Operation. */ 00087 #define BLE_GATTS_OP_WRITE_REQ 0x01 /**< Write Request. */ 00088 #define BLE_GATTS_OP_WRITE_CMD 0x02 /**< Write Command. */ 00089 #define BLE_GATTS_OP_SIGN_WRITE_CMD 0x03 /**< Signed Write Command. */ 00090 #define BLE_GATTS_OP_PREP_WRITE_REQ 0x04 /**< Prepare Write Request. */ 00091 #define BLE_GATTS_OP_EXEC_WRITE_REQ_CANCEL 0x05 /**< Execute Write Request: Cancel all prepared writes. */ 00092 #define BLE_GATTS_OP_EXEC_WRITE_REQ_NOW 0x06 /**< Execute Write Request: Immediately execute all prepared writes. */ 00093 /** @} */ 00094 00095 /** @defgroup BLE_GATTS_VLOCS GATT Value Locations 00096 * @{ */ 00097 #define BLE_GATTS_VLOC_INVALID 0x00 /**< Invalid Location. */ 00098 #define BLE_GATTS_VLOC_STACK 0x01 /**< Attribute Value is located in stack memory, no user memory is required. */ 00099 #define BLE_GATTS_VLOC_USER 0x02 /**< Attribute Value is located in user memory. This requires the user to maintain a valid buffer through the lifetime of the attribute, since the stack 00100 will read and write directly to the memory using the pointer provided in the APIs. There are no alignment requirements for the buffer. */ 00101 /** @} */ 00102 00103 /** @defgroup BLE_GATTS_AUTHORIZE_TYPES GATT Server Authorization Types 00104 * @{ */ 00105 #define BLE_GATTS_AUTHORIZE_TYPE_INVALID 0x00 /**< Invalid Type. */ 00106 #define BLE_GATTS_AUTHORIZE_TYPE_READ 0x01 /**< Authorize a Read Operation. */ 00107 #define BLE_GATTS_AUTHORIZE_TYPE_WRITE 0x02 /**< Authorize a Write Request Operation. */ 00108 /** @} */ 00109 00110 00111 /** @} */ 00112 00113 /**@brief Attribute metadata. */ 00114 typedef struct 00115 { 00116 ble_gap_conn_sec_mode_t read_perm; /**< Read permissions. */ 00117 ble_gap_conn_sec_mode_t write_perm; /**< Write permissions. */ 00118 uint8_t vlen :1; /**< Variable length attribute. */ 00119 uint8_t vloc :2; /**< Value location, see @ref BLE_GATTS_VLOCS.*/ 00120 uint8_t rd_auth :1; /**< Read Authorization and value will be requested from the application on every read operation. */ 00121 uint8_t wr_auth :1; /**< Write Authorization will be requested from the application on every Write Request operation (but not Write Command). */ 00122 } ble_gatts_attr_md_t; 00123 00124 00125 /**@brief GATT Attribute. */ 00126 typedef struct 00127 { 00128 ble_uuid_t* p_uuid; /**< Pointer to the attribute UUID. */ 00129 ble_gatts_attr_md_t* p_attr_md; /**< Pointer to the attribute metadata structure. */ 00130 uint16_t init_len; /**< Initial attribute value length in bytes. */ 00131 uint16_t init_offs; /**< Initial attribute value offset in bytes. If different from zero, the first init_offs bytes of the attribute value will be left uninitialized. */ 00132 uint16_t max_len; /**< Maximum attribute value length in bytes, see @ref BLE_GATTS_ATTR_LENS_MAX for maximum values. */ 00133 uint8_t* p_value; /**< Pointer to the attribute data. Please note that if the @ref BLE_GATTS_VLOC_USER value location is selected in the attribute metadata, this will have to point to a buffer 00134 that remains valid through the lifetime of the attribute. This excludes usage of automatic variables that may go out of scope or any other temporary location. 00135 The stack may access that memory directly without the application's knowledge. */ 00136 } ble_gatts_attr_t; 00137 00138 00139 /**@brief GATT Attribute Context. */ 00140 typedef struct 00141 { 00142 ble_uuid_t srvc_uuid; /**< Service UUID. */ 00143 ble_uuid_t char_uuid; /**< Characteristic UUID if applicable (BLE_UUID_TYPE_UNKNOWN if N/A). */ 00144 ble_uuid_t desc_uuid; /**< Descriptor UUID if applicable (BLE_UUID_TYPE_UNKNOWN if N/A). */ 00145 uint16_t srvc_handle; /**< Service Handle. */ 00146 uint16_t value_handle; /**< Characteristic Handle if applicable (BLE_GATT_HANDLE_INVALID if N/A). */ 00147 uint8_t type; /**< Attribute Type, see @ref BLE_GATTS_ATTR_TYPES. */ 00148 } ble_gatts_attr_context_t; 00149 00150 00151 /**@brief GATT Characteristic Presentation Format. */ 00152 typedef struct 00153 { 00154 uint8_t format; /**< Format of the value, see @ref BLE_GATT_CPF_FORMATS. */ 00155 int8_t exponent; /**< Exponent for integer data types. */ 00156 uint16_t unit; /**< UUID from Bluetooth Assigned Numbers. */ 00157 uint8_t name_space; /**< Namespace from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */ 00158 uint16_t desc; /**< Namespace description from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */ 00159 } ble_gatts_char_pf_t; 00160 00161 00162 /**@brief GATT Characteristic metadata. */ 00163 typedef struct 00164 { 00165 ble_gatt_char_props_t char_props; /**< Characteristic Properties. */ 00166 ble_gatt_char_ext_props_t char_ext_props; /**< Characteristic Extended Properties. */ 00167 uint8_t* p_char_user_desc; /**< Pointer to a UTF-8, NULL if the descriptor is not required. */ 00168 uint16_t char_user_desc_max_size; /**< The maximum size in bytes of the user description descriptor. */ 00169 uint16_t char_user_desc_size; /**< The size of the user description, must be smaller or equal to char_user_desc_max_size. */ 00170 ble_gatts_char_pf_t* p_char_pf; /**< Pointer to a presentation format structure or NULL if the descriptor is not required. */ 00171 ble_gatts_attr_md_t* p_user_desc_md; /**< Attribute metadata for the User Description descriptor, or NULL for default values. */ 00172 ble_gatts_attr_md_t* p_cccd_md; /**< Attribute metadata for the Client Characteristic Configuration Descriptor, or NULL for default values. */ 00173 ble_gatts_attr_md_t* p_sccd_md; /**< Attribute metadata for the Server Characteristic Configuration Descriptor, or NULL for default values. */ 00174 } ble_gatts_char_md_t; 00175 00176 00177 /**@brief GATT Characteristic Definition Handles. */ 00178 typedef struct 00179 { 00180 uint16_t value_handle; /**< Handle to the characteristic value. */ 00181 uint16_t user_desc_handle; /**< Handle to the User Description descriptor, or BLE_GATT_HANDLE_INVALID if not present. */ 00182 uint16_t cccd_handle; /**< Handle to the Client Characteristic Configuration Descriptor, or BLE_GATT_HANDLE_INVALID if not present. */ 00183 uint16_t sccd_handle; /**< Handle to the Server Characteristic Configuration Descriptor, or BLE_GATT_HANDLE_INVALID if not present. */ 00184 } ble_gatts_char_handles_t; 00185 00186 00187 /**@brief GATT HVx parameters. */ 00188 typedef struct 00189 { 00190 uint16_t handle; /**< Characteristic Value Handle. */ 00191 uint8_t type; /**< Indication or Notification, see @ref BLE_GATT_HVX_TYPES. */ 00192 uint16_t offset; /**< Offset within the attribute value. */ 00193 uint16_t* p_len; /**< Length in bytes to be written, length in bytes written after successful return. */ 00194 uint8_t* p_data; /**< Actual data content, use NULL to use the current attribute value. */ 00195 } ble_gatts_hvx_params_t; 00196 00197 /**@brief GATT Read Authorization parameters. */ 00198 typedef struct 00199 { 00200 uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */ 00201 uint8_t update : 1; /**< If set, data supplied in p_data will be used in the ATT response. */ 00202 uint16_t offset; /**< Offset of the attribute value being updated. */ 00203 uint16_t len; /**< Length in bytes of the value in p_data pointer, see @ref BLE_GATTS_ATTR_LENS_MAX. */ 00204 uint8_t* p_data; /**< Pointer to new value used to update the attribute value. */ 00205 } ble_gatts_read_authorize_params_t; 00206 00207 /**@brief GATT Write Authorisation parameters. */ 00208 typedef struct 00209 { 00210 uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */ 00211 } ble_gatts_write_authorize_params_t; 00212 00213 /**@brief GATT Read or Write Authorize Reply parameters. */ 00214 typedef struct 00215 { 00216 uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */ 00217 union { 00218 ble_gatts_read_authorize_params_t read; /**< Read authorization parameters. */ 00219 ble_gatts_write_authorize_params_t write; /**< Write authorization parameters. */ 00220 } params; 00221 } ble_gatts_rw_authorize_reply_params_t; 00222 00223 00224 /** 00225 * @brief GATT Server Event IDs. 00226 */ 00227 enum BLE_GATTS_EVTS 00228 { 00229 BLE_GATTS_EVT_WRITE = BLE_GATTS_EVT_BASE, /**< Write operation performed. */ 00230 BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST, /**< Read/Write Authorization request. */ 00231 BLE_GATTS_EVT_SYS_ATTR_MISSING, /**< A persistent system attribute access is pending, awaiting a sd_ble_gatts_sys_attr_set(). */ 00232 BLE_GATTS_EVT_HVC, /**< Handle Value Confirmation. */ 00233 BLE_GATTS_EVT_SC_CONFIRM, /**< Service Changed Confirmation. */ 00234 BLE_GATTS_EVT_TIMEOUT /**< Timeout. */ 00235 }; 00236 00237 00238 /**@brief Event structure for BLE_GATTS_EVT_WRITE. */ 00239 typedef struct 00240 { 00241 uint16_t handle; /**< Attribute Handle. */ 00242 uint8_t op; /**< Type of write operation, see @ref BLE_GATTS_OPS. */ 00243 ble_gatts_attr_context_t context; /**< Attribute Context. */ 00244 uint16_t offset; /**< Offset for the write operation. */ 00245 uint16_t len; /**< Length of the incoming data. */ 00246 uint8_t data[1]; /**< Incoming data, variable length. */ 00247 } ble_gatts_evt_write_t; 00248 00249 /**@brief Event structure for authorize read request. */ 00250 typedef struct 00251 { 00252 uint16_t handle; /**< Attribute Handle. */ 00253 ble_gatts_attr_context_t context; /**< Attribute Context. */ 00254 uint16_t offset; /**< Offset for the read operation. */ 00255 } ble_gatts_evt_read_t; 00256 00257 /**@brief Event structure for BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST. */ 00258 typedef struct 00259 { 00260 uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */ 00261 union { 00262 ble_gatts_evt_read_t read; /**< Attribute Read Parameters. */ 00263 ble_gatts_evt_write_t write; /**< Attribute Write Parameters. */ 00264 } request; 00265 } ble_gatts_evt_rw_authorize_request_t; 00266 00267 /**@brief Event structure for BLE_GATTS_EVT_SYS_ATTR_MISSING. */ 00268 typedef struct 00269 { 00270 uint8_t hint; 00271 } ble_gatts_evt_sys_attr_missing_t; 00272 00273 00274 /**@brief Event structure for BLE_GATTS_EVT_HVC. */ 00275 typedef struct 00276 { 00277 uint16_t handle; /**< Attribute Handle. */ 00278 } ble_gatts_evt_hvc_t; 00279 00280 /**@brief Event structure for BLE_GATTS_EVT_TIMEOUT. */ 00281 typedef struct 00282 { 00283 uint8_t src; /**< Timeout source, see @ref BLE_GATT_TIMEOUT_SOURCES. */ 00284 } ble_gatts_evt_timeout_t; 00285 00286 00287 /**@brief GATT Server event callback event structure. */ 00288 typedef struct 00289 { 00290 uint16_t conn_handle; /**< Connection Handle on which event occurred. */ 00291 union 00292 { 00293 ble_gatts_evt_write_t write; /**< Write Event Parameters. */ 00294 ble_gatts_evt_rw_authorize_request_t authorize_request; /**< Read or Write Authorize Request Parameters. */ 00295 ble_gatts_evt_sys_attr_missing_t sys_attr_missing; /**< System attributes missing. */ 00296 ble_gatts_evt_hvc_t hvc; /**< Handle Value Confirmation Event Parameters. */ 00297 ble_gatts_evt_timeout_t timeout; /**< Timeout Event. */ 00298 } params; 00299 } ble_gatts_evt_t; 00300 00301 00302 /**@brief Add a service declaration to the local server ATT table. 00303 * 00304 * @param[in] type Toggles between primary and secondary services, see @ref BLE_GATTS_SRVC_TYPES. 00305 * @param[in] p_uuid Pointer to service UUID. 00306 * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored. 00307 * 00308 * @note Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to 00309 * add a secondary service declaration that is not referenced by another service later in the ATT table. 00310 * 00311 * @return @ref NRF_SUCCESS Successfully added a service declaration. 00312 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00313 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table. 00314 * @return @ref NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. 00315 * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation. 00316 */ 00317 SVCALL(SD_BLE_GATTS_SERVICE_ADD, uint32_t, sd_ble_gatts_service_add(uint8_t type, ble_uuid_t const*const p_uuid, uint16_t *const p_handle)); 00318 00319 00320 /**@brief Add an include declaration to the local server ATT table. 00321 * 00322 * @note It is currently only possible to add an include declaration to the last added service (i.e. only sequential addition is supported at this time). 00323 * 00324 * @note The included service must already be present in the ATT table prior to this call. 00325 * 00326 * @param[in] service_handle Handle of the service where the included service is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially. 00327 * @param[in] inc_srvc_handle Handle of the included service. 00328 * @param[out] p_include_handle Pointer to a 16-bit word where the assigned handle will be stored. 00329 * 00330 * @return @ref NRF_SUCCESS Successfully added an include declaration. 00331 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00332 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, handle values need to match previously added services. 00333 * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation. 00334 * @return @ref NRF_ERROR_FORBIDDEN Forbidden value supplied, self inclusions are not allowed. 00335 * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation. 00336 * @return @ref NRF_ERROR_NOT_FOUND Attribute not found. 00337 */ 00338 SVCALL(SD_BLE_GATTS_INCLUDE_ADD, uint32_t, sd_ble_gatts_include_add(uint16_t service_handle, uint16_t inc_srvc_handle, uint16_t *const p_include_handle)); 00339 00340 00341 /**@brief Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the local server ATT table. 00342 * 00343 * @note It is currently only possible to add a characteristic to the last added service (i.e. only sequential addition is supported at this time). 00344 * 00345 * @note Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writeable auxiliaries bits, 00346 * readable (no security) and writeable (selectable) CCCDs and SCCDs and valid presentation format values. 00347 * 00348 * @note If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions. 00349 * 00350 * @param[in] service_handle Handle of the service where the characteristic is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially. 00351 * @param[in] p_char_md Characteristic metadata. 00352 * @param[in] p_attr_char_value Pointer to the attribute structure corresponding to the characteristic value. 00353 * @param[out] p_handles Pointer to the structure where the assigned handles will be stored. 00354 * 00355 * @return @ref NRF_SUCCESS Successfully added a characteristic. 00356 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00357 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints. 00358 * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation, a service context is required. 00359 * @return @ref NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. 00360 * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation. 00361 * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. 00362 */ 00363 SVCALL(SD_BLE_GATTS_CHARACTERISTIC_ADD, uint32_t, sd_ble_gatts_characteristic_add(uint16_t service_handle, ble_gatts_char_md_t const*const p_char_md, ble_gatts_attr_t const*const p_attr_char_value, ble_gatts_char_handles_t *const p_handles)); 00364 00365 00366 /**@brief Add a descriptor to the local server ATT table. 00367 * 00368 * @note It is currently only possible to add a descriptor to the last added characteristic (i.e. only sequential addition is supported at this time). 00369 * 00370 * @param[in] char_handle Handle of the characteristic where the descriptor is to be placed, if BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially. 00371 * @param[in] p_attr Pointer to the attribute structure. 00372 * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored. 00373 * 00374 * @return @ref NRF_SUCCESS Successfully added a descriptor. 00375 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00376 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints. 00377 * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation, a characteristic context is required. 00378 * @return @ref NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. 00379 * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation. 00380 * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. 00381 */ 00382 SVCALL(SD_BLE_GATTS_DESCRIPTOR_ADD, uint32_t, sd_ble_gatts_descriptor_add(uint16_t char_handle, ble_gatts_attr_t const * const p_attr, uint16_t* const p_handle)); 00383 00384 /**@brief Set the value of a given attribute. 00385 * 00386 * @param[in] handle Attribute handle. 00387 * @param[in] offset Offset in bytes to write from. 00388 * @param[in,out] p_len Length in bytes to be written, length in bytes written after successful return. 00389 * @param[in] p_value Pointer to a buffer (at least len bytes long) containing the desired attribute value. 00390 * 00391 * @return @ref NRF_SUCCESS Successfully set the value of the attribute. 00392 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00393 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00394 * @return @ref NRF_ERROR_NOT_FOUND Attribute not found. 00395 * @return @ref NRF_ERROR_FORBIDDEN Forbidden handle supplied, certain attributes are not modifiable by the application. 00396 * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. 00397 */ 00398 SVCALL(SD_BLE_GATTS_VALUE_SET, uint32_t, sd_ble_gatts_value_set(uint16_t handle, uint16_t offset, uint16_t* const p_len, uint8_t const * const p_value)); 00399 00400 /**@brief Get the value of a given attribute. 00401 * 00402 * @param[in] handle Attribute handle. 00403 * @param[in] offset Offset in bytes to read from. 00404 * @param[in,out] p_len Length in bytes to be read, total length of attribute value (in bytes, starting from offset) after successful return. 00405 * @param[in,out] p_data Pointer to a buffer (at least len bytes long) where to store the attribute value. Set to NULL to obtain the complete length of attribute value. 00406 * 00407 * @note If the attribute value is longer than the size of the supplied buffer, 00408 * p_len will return the total attribute value length (excluding offset), 00409 * and not the number of bytes actually returned in p_data. 00410 * The application may use this information to allocate a suitable buffer size. 00411 * 00412 * @return @ref NRF_SUCCESS Successfully retrieved the value of the attribute. 00413 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00414 * @return @ref NRF_ERROR_NOT_FOUND Attribute not found. 00415 */ 00416 SVCALL(SD_BLE_GATTS_VALUE_GET, uint32_t, sd_ble_gatts_value_get(uint16_t handle, uint16_t offset, uint16_t *const p_len, uint8_t* const p_data)); 00417 00418 /**@brief Notify or Indicate an attribute value. 00419 * 00420 * @details This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation 00421 * (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that 00422 * the application can atomically perform a value update and a server initiated transaction with a single API call. 00423 * If the application chooses to indicate an attribute value, a @ref BLE_GATTS_EVT_HVC will be sent up as soon as the confirmation arrives from 00424 * the peer. 00425 * 00426 * @note The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution. 00427 * When receiveing the error codes @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and 00428 * @ref BLE_ERROR_NO_TX_BUFFERS the ATT table has been updated. 00429 * The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len). 00430 * 00431 * @note It is important to note that a notification will <b>consume an application buffer</b>, and will therefore 00432 * generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. An indication on the other hand will use the 00433 * standard server internal buffer and thus will only generate a @ref BLE_GATTS_EVT_HVC event as soon as the confirmation 00434 * has been received from the peer. Please see the documentation of @ref sd_ble_tx_buffer_count_get for more details. 00435 * 00436 * @param[in] conn_handle Connection handle. 00437 * @param[in] p_hvx_params Pointer to an HVx parameters structure. If the p_data member contains a non-NULL pointer the attribute value will be updated with 00438 * the contents pointed by it before sending the notification or indication. 00439 * 00440 * @return @ref NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value. 00441 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00442 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00443 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00444 * @return @ref BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate. 00445 * @return @ref BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated. 00446 * @return @ref NRF_ERROR_NOT_FOUND Attribute not found. 00447 * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied. 00448 * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation, notifications or indications must be enabled in the CCCD. 00449 * @return @ref NRF_ERROR_BUSY Procedure already in progress. 00450 * @return @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value. 00451 * @return @ref BLE_ERROR_NO_TX_BUFFERS There are no available buffers to send the data, applies only to notifications. 00452 */ 00453 SVCALL(SD_BLE_GATTS_HVX, uint32_t, sd_ble_gatts_hvx(uint16_t conn_handle, ble_gatts_hvx_params_t const*const p_hvx_params)); 00454 00455 /**@brief Indicate the Service Changed attribute value. 00456 * 00457 * @details This call will send a Handle Value Indication to one or more peers connected to inform them that the attribute 00458 * table layout has changed. As soon as the peer has confirmed the indication, a @ref BLE_GATTS_EVT_SC_CONFIRM event will 00459 * be issued. 00460 * 00461 * @note Some of the restrictions and limitations that apply to @ref sd_ble_gatts_hvx also apply here. 00462 * 00463 * @param[in] conn_handle Connection handle. 00464 * @param[in] start_handle Start of affected attribute handle range. 00465 * @param[in] end_handle End of affected attribute handle range. 00466 * 00467 * @return @ref NRF_SUCCESS Successfully queued the Service Changed indication for transmission. 00468 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00469 * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. 00470 * @return @ref BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied, handles must be in the range populated by the application. 00471 * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation, notifications or indications must be enabled in the CCCD. 00472 * @return @ref NRF_ERROR_BUSY Procedure already in progress. 00473 * @return @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value. 00474 */ 00475 SVCALL(SD_BLE_GATTS_SERVICE_CHANGED, uint32_t, sd_ble_gatts_service_changed(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle)); 00476 00477 /**@brief Respond to a Read/Write authorization request. 00478 * 00479 * @note This call should only be used as a response to a @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application. 00480 * 00481 * @param[in] conn_handle Connection handle. 00482 * @param[in] p_rw_authorize_reply_params Pointer to a structure with the attribute provided by the application. 00483 * 00484 * @return @ref NRF_SUCCESS Successfully queued a response to the peer, and in the case of a write operation, ATT table updated. 00485 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00486 * @return @ref NRF_ERROR_INVALID_STATE No authorization request pending. 00487 * @return @ref NRF_ERROR_INVALID_PARAM Authorization op invalid, 00488 * or for Read Authorization reply: requested handles not replied with, 00489 * or for Write Authorization reply: handle supplied does not match requested handle. 00490 */ 00491 SVCALL(SD_BLE_GATTS_RW_AUTHORIZE_REPLY, uint32_t, sd_ble_gatts_rw_authorize_reply(uint16_t conn_handle, ble_gatts_rw_authorize_reply_params_t const*const p_rw_authorize_reply_params)); 00492 00493 00494 /**@brief Update persistent system attribute information. 00495 * 00496 * @details Supply to the stack information about persistent system attributes. 00497 * This call is legal in the connected state only, and is usually 00498 * made immediately after a connection is established and the bond identified. 00499 * usually as a response to a BLE_GATTS_EVT_SYS_ATTR_MISSING. 00500 * 00501 * p_sysattrs may point directly to the application's stored copy of the struct. 00502 * If the pointer is NULL, the system attribute info is initialized, assuming that 00503 * the application does not have any previously saved data for this bond. 00504 * 00505 * @note The state of persistent system attributes is reset upon connection and then remembered for its duration. 00506 * 00507 * @note If this call returns with an error code different from @ref NRF_SUCCESS, the storage of persistent system attributes may have been completed only partially. 00508 * This means that the state of the attribute table is undefined, and the application should either provide a new set of attributes using this same call or 00509 * reset the SoftDevice to return to a known state. 00510 * 00511 * @param[in] conn_handle Connection handle. 00512 * @param[in] p_sys_attr_data Pointer to a saved copy of system attributes supplied to the stack, or NULL. 00513 * @param[in] len Size of data pointed by p_sys_attr_data, in octets. 00514 * 00515 * @return @ref NRF_SUCCESS Successfully set the system attribute information. 00516 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00517 * @return @ref NRF_ERROR_INVALID_DATA Invalid data supplied, the data should be exactly the same as retrieved with @ref sd_ble_gatts_sys_attr_get. 00518 * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation. 00519 */ 00520 SVCALL(SD_BLE_GATTS_SYS_ATTR_SET, uint32_t, sd_ble_gatts_sys_attr_set(uint16_t conn_handle, uint8_t const*const p_sys_attr_data, uint16_t len)); 00521 00522 00523 /**@brief Retrieve persistent system attribute information from the stack. 00524 * 00525 * @details This call is used to retrieve information about values to be stored perisistently by the application 00526 * after a connection has been terminated. When a new connection is made to the same bond, the values 00527 * should be restored using @ref sd_ble_gatts_sys_attr_set. 00528 * The data should be read before any new advertising is started, or any new connection established. The connection handle for 00529 * the previous now defunct connection will remain valid until a new one is created to allow this API call to refer to it. 00530 * 00531 * @param[in] conn_handle Connection handle of the recently terminated connection. 00532 * @param[in] p_sys_attr_data Pointer to a buffer where updated information about system attributes will be filled in. NULL can be provided to 00533 * obtain the length of the data 00534 * @param[in,out] p_len Size of application buffer if p_sys_attr_data is not NULL. Unconditially updated to actual length of system attribute data. 00535 * 00536 * @return @ref NRF_SUCCESS Successfully retrieved the system attribute information. 00537 * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. 00538 * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied. 00539 * @return @ref NRF_ERROR_DATA_SIZE The system attribute information did not fit into the provided buffer. 00540 */ 00541 SVCALL(SD_BLE_GATTS_SYS_ATTR_GET, uint32_t, sd_ble_gatts_sys_attr_get(uint16_t conn_handle, uint8_t * const p_sys_attr_data, uint16_t* const p_len)); 00542 00543 00544 #endif // BLE_GATTS_H__ 00545 00546 /** 00547 @} 00548 */
Generated on Tue Jul 12 2022 15:07:12 by 1.7.2