1 /****************************************************************************** 2 * @file ble_gatt_aci.h 3 * @author MCD Application Team 4 * @date 14 June 2019 5 * @brief Header file for STM32WB (gatt_aci) 6 * Auto-generated file: do not edit! 7 ****************************************************************************** 8 * @attention 9 * 10 * <h2><center>© Copyright (c) 2019 STMicroelectronics. 11 * All rights reserved.</center></h2> 12 * 13 * This software component is licensed by ST under Ultimate Liberty license 14 * SLA0044, the "License"; You may not use this file except in compliance with 15 * the License. You may obtain a copy of the License at: 16 * www.st.com/SLA0044 17 * 18 ****************************************************************************** 19 */ 20 21 #ifndef BLE_GATT_ACI_H__ 22 #define BLE_GATT_ACI_H__ 23 24 25 #include "ble_types.h" 26 27 /** 28 * @brief Initialize the GATT layer for server and client roles. 29 It adds also the GATT service with Service Changed Characteristic. 30 Until this command is issued the GATT channel will not process any commands even if the 31 connection is opened. This command has to be given before using any of the GAP features. 32 * @retval Value indicating success or error code. 33 */ 34 tBleStatus aci_gatt_init(void); 35 36 /** 37 * @brief Add a service to GATT Server. When a service is created in the server, the host needs to 38 reserve the handle ranges for this service using Max_Attribute_Records parameter. This 39 parameter specifies the maximum number of attribute records that can be added to this 40 service (including the service attribute, include attribute, characteristic attribute, 41 characteristic value attribute and characteristic descriptor attribute). Handle of the created 42 service is returned in command complete event. Service declaration is taken from the service pool. 43 The attributes for characteristics and descriptors are allocated from the attribute pool. 44 * @param Service_UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 45 * @param Service_UUID See @ref Service_UUID_t 46 * @param Service_Type Service type. 47 * Values: 48 - 0x01: Primary Service 49 - 0x02: Secondary Service 50 * @param Max_Attribute_Records Maximum number of attribute records that can be added to this service 51 * @param[out] Service_Handle Handle of the Service. 52 When this service is added, a handle is allocated by the server for this service. 53 Server also allocates a range of handles for this service from serviceHandle to <serviceHandle + max_attr_records - 1> 54 * @retval Value indicating success or error code. 55 */ 56 tBleStatus aci_gatt_add_service(uint8_t Service_UUID_Type, 57 Service_UUID_t *Service_UUID, 58 uint8_t Service_Type, 59 uint8_t Max_Attribute_Records, 60 uint16_t *Service_Handle); 61 62 /** 63 * @brief Include a service given by Include_Start_Handle and Include_End_Handle to another 64 service given by Service_Handle. Attribute server creates an INCLUDE definition 65 attribute and return the handle of this attribute in Included_handle. 66 * @param Service_Handle Handle of the Service to which another service has to be included. 67 * @param Include_Start_Handle Start Handle of the Service which has to be included in service 68 * @param Include_End_Handle End Handle of the Service which has to be included in service 69 * @param Include_UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 70 * @param Include_UUID See @ref Include_UUID_t 71 * @param[out] Include_Handle Handle of the include declaration 72 * @retval Value indicating success or error code. 73 */ 74 tBleStatus aci_gatt_include_service(uint16_t Service_Handle, 75 uint16_t Include_Start_Handle, 76 uint16_t Include_End_Handle, 77 uint8_t Include_UUID_Type, 78 Include_UUID_t *Include_UUID, 79 uint16_t *Include_Handle); 80 81 /** 82 * @brief Add a characteristic to a service. 83 * @param Service_Handle Handle of the Service to which the characteristic will be added 84 * @param Char_UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 85 * @param Char_UUID See @ref Char_UUID_t 86 * @param Char_Value_Length Maximum length of the characteristic value. 87 * @param Char_Properties Characteristic Properties (Volume 3, Part G, section 3.3.1.1 of Bluetooth Specification 5.0) 88 * Flags: 89 - 0x00: CHAR_PROP_NONE 90 - 0x01: CHAR_PROP_BROADCAST (Broadcast) 91 - 0x02: CHAR_PROP_READ (Read) 92 - 0x04: CHAR_PROP_WRITE_WITHOUT_RESP (Write w/o resp) 93 - 0x08: CHAR_PROP_WRITE (Write) 94 - 0x10: CHAR_PROP_NOTIFY (Notify) 95 - 0x20: CHAR_PROP_INDICATE (Indicate) 96 - 0x40: CHAR_PROP_SIGNED_WRITE (Authenticated Signed Writes) 97 - 0x80: CHAR_PROP_EXT (Extended Properties) 98 * @param Security_Permissions Security permission flags. 99 * Flags: 100 - 0x00: None 101 - 0x01: AUTHEN_READ (Need authentication to read) 102 - 0x02: AUTHOR_READ (Need authorization to read) 103 - 0x04: ENCRY_READ (Need encryption to read) 104 - 0x08: AUTHEN_WRITE (need authentication to write) 105 - 0x10: AUTHOR_WRITE (need authorization to write) 106 - 0x20: ENCRY_WRITE (need encryption to write) 107 * @param GATT_Evt_Mask GATT event mask. 108 * Flags: 109 - 0x00: GATT_DONT_NOTIFY_EVENTS 110 - 0x01: GATT_NOTIFY_ATTRIBUTE_WRITE 111 - 0x02: GATT_NOTIFY_WRITE_REQ_AND_WAIT_FOR_APPL_RESP 112 - 0x04: GATT_NOTIFY_READ_REQ_AND_WAIT_FOR_APPL_RESP 113 * @param Enc_Key_Size Minimum encryption key size required to read the characteristic. 114 * Values: 115 - 0x07 ... 0x10 116 * @param Is_Variable Specify if the characteristic value has a fixed length or 117 a variable length. 118 * Values: 119 - 0x00: Fixed length 120 - 0x01: Variable length 121 * @param[out] Char_Handle Handle of the Characteristic that has been added. 122 It is the handle of the characteristic declaration. 123 The attribute that holds the characteristic value is allocated at the next handle, 124 followed by the Client Characteristic Configuration descriptor if the characteristic 125 has CHAR_PROP_NOTIFY or CHAR_PROP_INDICATE properties. 126 * @retval Value indicating success or error code. 127 */ 128 tBleStatus aci_gatt_add_char(uint16_t Service_Handle, 129 uint8_t Char_UUID_Type, 130 Char_UUID_t *Char_UUID, 131 uint16_t Char_Value_Length, 132 uint8_t Char_Properties, 133 uint8_t Security_Permissions, 134 uint8_t GATT_Evt_Mask, 135 uint8_t Enc_Key_Size, 136 uint8_t Is_Variable, 137 uint16_t *Char_Handle); 138 139 /** 140 * @brief Add a characteristic descriptor to a service. 141 * @param Service_Handle Handle of service to which the characteristic belongs 142 * @param Char_Handle Handle of the characteristic to which description has to be added 143 * @param Char_Desc_Uuid_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 144 * @param Char_Desc_Uuid See @ref Char_Desc_Uuid_t 145 * @param Char_Desc_Value_Max_Len The maximum length of the descriptor value 146 * @param Char_Desc_Value_Length Current Length of the characteristic descriptor value 147 * @param Char_Desc_Value Value of the characteristic description 148 * @param Security_Permissions Security permission flags. 149 * Flags: 150 - 0x00: None 151 - 0x01: AUTHEN_READ (Need authentication to read) 152 - 0x02: AUTHOR_READ (Need authorization to read) 153 - 0x04: ENCRY_READ (Need encryption to read) 154 - 0x08: AUTHEN_WRITE (need authentication to write) 155 - 0x10: AUTHOR_WRITE (need authorization to write) 156 - 0x20: ENCRY_WRITE (need encryption to write) 157 * @param Access_Permissions Access permission 158 * Flags: 159 - 0x00: None 160 - 0x01: READ 161 - 0x02: WRITE 162 - 0x04: WRITE_WO_RESP 163 - 0x08: SIGNED_WRITE 164 * @param GATT_Evt_Mask GATT event mask. 165 * Flags: 166 - 0x00: GATT_DONT_NOTIFY_EVENTS 167 - 0x01: GATT_NOTIFY_ATTRIBUTE_WRITE 168 - 0x02: GATT_NOTIFY_WRITE_REQ_AND_WAIT_FOR_APPL_RESP 169 - 0x04: GATT_NOTIFY_READ_REQ_AND_WAIT_FOR_APPL_RESP 170 * @param Enc_Key_Size Minimum encryption key size required to read the characteristic. 171 * Values: 172 - 0x07 ... 0x10 173 * @param Is_Variable Specify if the characteristic value has a fixed length or 174 a variable length. 175 * Values: 176 - 0x00: Fixed length 177 - 0x01: Variable length 178 * @param[out] Char_Desc_Handle Handle of the characteristic descriptor 179 * @retval Value indicating success or error code. 180 */ 181 tBleStatus aci_gatt_add_char_desc(uint16_t Service_Handle, 182 uint16_t Char_Handle, 183 uint8_t Char_Desc_Uuid_Type, 184 Char_Desc_Uuid_t *Char_Desc_Uuid, 185 uint8_t Char_Desc_Value_Max_Len, 186 uint8_t Char_Desc_Value_Length, 187 uint8_t Char_Desc_Value[], 188 uint8_t Security_Permissions, 189 uint8_t Access_Permissions, 190 uint8_t GATT_Evt_Mask, 191 uint8_t Enc_Key_Size, 192 uint8_t Is_Variable, 193 uint16_t *Char_Desc_Handle); 194 195 /** 196 * @brief Update a characteristic value in a service. 197 If notifications (or indications) are enabled on that characteristic, 198 a notification (or indication) will be sent to the client after sending 199 this command to the STM32WB. The command is queued into the STM32WB command queue. 200 If the buffer is full, because previous commands could not be still processed, 201 the function will return BLE_STATUS_INSUFFICIENT_RESOURCES. This will happen 202 if notifications (or indications) are enabled and the application calls 203 @ref aci_gatt_update_char_value at an higher rate than what is allowed by the link. 204 Throughput on BLE link depends on connection interval and connection length 205 parameters (decided by the master, see aci_l2cap_connection_parameter_update_request() 206 for more info on how to suggest new connection parameters from a slave). If the 207 application does not want to lose notifications because STM32WB buffer becomes full, 208 it has to retry again till the function returns BLE_STATUS_SUCCESS or any other error code. 209 * @param Service_Handle Handle of service to which the characteristic belongs 210 * @param Char_Handle Handle of the characteristic declaration 211 * @param Val_Offset The offset from which the attribute value has to be updated. 212 If this is set to 0 and the attribute value is of variable length, then the length of the attribute will be set to the Char_Value_Length. 213 If the Val_Offset is set to a value greater than 0, then the length of the attribute will be set to the maximum length as 214 specified for the attribute while adding the characteristic. 215 * @param Char_Value_Length Length of the characteristic value in octets 216 * @param Char_Value Characteristic value 217 * @retval Value indicating success or error code. 218 */ 219 tBleStatus aci_gatt_update_char_value(uint16_t Service_Handle, 220 uint16_t Char_Handle, 221 uint8_t Val_Offset, 222 uint8_t Char_Value_Length, 223 uint8_t Char_Value[]); 224 225 /** 226 * @brief Delete the specified characteristic from the service. 227 * @param Serv_Handle Handle of service to which the characteristic belongs 228 * @param Char_Handle Handle of the characteristic which has to be deleted 229 * @retval Value indicating success or error code. 230 */ 231 tBleStatus aci_gatt_del_char(uint16_t Serv_Handle, 232 uint16_t Char_Handle); 233 234 /** 235 * @brief Delete the specified service from the GATT server database. 236 * @param Serv_Handle Handle of the service to be deleted 237 * @retval Value indicating success or error code. 238 */ 239 tBleStatus aci_gatt_del_service(uint16_t Serv_Handle); 240 241 /** 242 * @brief Delete the Include definition from the service. 243 * @param Serv_Handle Handle of the service to which the include service belongs 244 * @param Include_Handle Handle of the included service which has to be deleted 245 * @retval Value indicating success or error code. 246 */ 247 tBleStatus aci_gatt_del_include_service(uint16_t Serv_Handle, 248 uint16_t Include_Handle); 249 250 /** 251 * @brief Mask events from the GATT. The default configuration is all the events masked. 252 * @param GATT_Evt_Mask GATT/ATT event mask. 253 * Values: 254 - 0x00000001: ACI_GATT_ATTRIBUTE_MODIFIED_EVENT 255 - 0x00000002: ACI_GATT_PROC_TIMEOUT_EVENT 256 - 0x00000004: ACI_ATT_EXCHANGE_MTU_RESP_EVENT 257 - 0x00000008: ACI_ATT_FIND_INFO_RESP_EVENT 258 - 0x00000010: ACI_ATT_FIND_BY_TYPE_VALUE_RESP_EVENT 259 - 0x00000020: ACI_ATT_READ_BY_TYPE_RESP_EVENT 260 - 0x00000040: ACI_ATT_READ_RESP_EVENT 261 - 0x00000080: ACI_ATT_READ_BLOB_RESP_EVENT 262 - 0x00000100: ACI_ATT_READ_MULTIPLE_RESP_EVENT 263 - 0x00000200: ACI_ATT_READ_BY_GROUP_TYPE_RESP_EVENT 264 - 0x00000800: ACI_ATT_PREPARE_WRITE_RESP_EVENT 265 - 0x00001000: ACI_ATT_EXEC_WRITE_RESP_EVENT 266 - 0x00002000: ACI_GATT_INDICATION_EVENT 267 - 0x00004000: ACI_GATT_NOTIFICATION_EVENT 268 - 0x00008000: ACI_GATT_ERROR_RESP_EVENT 269 - 0x00010000: ACI_GATT_PROC_COMPLETE_EVENT 270 - 0x00020000: ACI_GATT_DISC_READ_CHAR_BY_UUID_RESP_EVENT 271 - 0x00040000: ACI_GATT_TX_POOL_AVAILABLE_EVENT 272 - 0x00200000: ACI_GATT_INDICATION_EXT_EVENT 273 - 0x00400000: ACI_GATT_NOTIFICATION_EXT_EVENT 274 * @retval Value indicating success or error code. 275 */ 276 tBleStatus aci_gatt_set_event_mask(uint32_t GATT_Evt_Mask); 277 278 /** 279 * @brief Perform an ATT MTU exchange procedure. 280 When the ATT MTU exchange procedure is completed, a @ref aci_att_exchange_mtu_resp_event 281 event is generated. A @ref aci_gatt_proc_complete_event event is also generated 282 to indicate the end of the procedure. 283 * @param Connection_Handle Connection handle for which the command is given. 284 * Values: 285 - 0x0000 ... 0x0EFF 286 * @retval Value indicating success or error code. 287 */ 288 tBleStatus aci_gatt_exchange_config(uint16_t Connection_Handle); 289 290 /** 291 * @brief Send a Find Information Request. 292 This command is used to obtain the mapping of attribute handles with their associated 293 types. The responses of the procedure are given through the 294 @ref aci_att_find_info_resp_event event. The end of the procedure is indicated by 295 a @ref aci_gatt_proc_complete_event event. 296 * @param Connection_Handle Connection handle for which the command is given. 297 * Values: 298 - 0x0000 ... 0x0EFF 299 * @param Start_Handle First requested handle number 300 * @param End_Handle Last requested handle number 301 * @retval Value indicating success or error code. 302 */ 303 tBleStatus aci_att_find_info_req(uint16_t Connection_Handle, 304 uint16_t Start_Handle, 305 uint16_t End_Handle); 306 307 /** 308 * @brief Send a Find By Type Value Request 309 The Find By Type Value Request is used to obtain the handles of attributes that 310 have a given 16-bit UUID attribute type and a given attribute value. 311 The responses of the procedure are given through the @ref aci_att_find_by_type_value_resp_event event. 312 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event event. 313 * @param Connection_Handle Connection handle for which the command is given. 314 * Values: 315 - 0x0000 ... 0x0EFF 316 * @param Start_Handle First requested handle number 317 * @param End_Handle Last requested handle number 318 * @param UUID 2 octet UUID to find (little-endian) 319 * @param Attribute_Val_Length Length of attribute value (maximum value is ATT_MTU - 7). 320 * @param Attribute_Val Attribute value to find 321 * @retval Value indicating success or error code. 322 */ 323 tBleStatus aci_att_find_by_type_value_req(uint16_t Connection_Handle, 324 uint16_t Start_Handle, 325 uint16_t End_Handle, 326 uint16_t UUID, 327 uint8_t Attribute_Val_Length, 328 uint8_t Attribute_Val[]); 329 330 /** 331 * @brief Send a Read By Type Request. 332 The Read By Type Request is used to obtain the values of attributes where the attribute 333 type is known but the handle is not known. 334 The responses are given through the @ref aci_att_read_by_type_resp_event event. 335 * @param Connection_Handle Connection handle for which the command is given. 336 * Values: 337 - 0x0000 ... 0x0EFF 338 * @param Start_Handle First requested handle number 339 * @param End_Handle Last requested handle number 340 * @param UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 341 * @param UUID See @ref UUID_t 342 * @retval Value indicating success or error code. 343 */ 344 tBleStatus aci_att_read_by_type_req(uint16_t Connection_Handle, 345 uint16_t Start_Handle, 346 uint16_t End_Handle, 347 uint8_t UUID_Type, 348 UUID_t *UUID); 349 350 /** 351 * @brief Send a Read By Group Type Request. 352 The Read By Group Type Request is used to obtain the values of grouping attributes where 353 the attribute type is known but the handle is not known. Grouping attributes are defined 354 at GATT layer. The grouping attribute types are: "Primary Service", "Secondary Service" 355 and "Characteristic". 356 The responses of the procedure are given through the @ref aci_att_read_by_group_type_resp_event event. 357 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event. 358 * @param Connection_Handle Connection handle for which the command is given. 359 * Values: 360 - 0x0000 ... 0x0EFF 361 * @param Start_Handle First requested handle number 362 * @param End_Handle Last requested handle number 363 * @param UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 364 * @param UUID See @ref UUID_t 365 * @retval Value indicating success or error code. 366 */ 367 tBleStatus aci_att_read_by_group_type_req(uint16_t Connection_Handle, 368 uint16_t Start_Handle, 369 uint16_t End_Handle, 370 uint8_t UUID_Type, 371 UUID_t *UUID); 372 373 /** 374 * @brief Send a Prepare Write Request. 375 The Prepare Write Request is used to request the server to prepare to write the value of an attribute. 376 The responses of the procedure are given through the @ref aci_att_prepare_write_resp_event event. 377 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event. 378 * @param Connection_Handle Connection handle for which the command is given. 379 * Values: 380 - 0x0000 ... 0x0EFF 381 * @param Attr_Handle Handle of the attribute to be written 382 * @param Val_Offset The offset of the first octet to be written 383 * @param Attribute_Val_Length Length of attribute value (maximum value is ATT_MTU - 5). 384 * @param Attribute_Val The value of the attribute to be written 385 * @retval Value indicating success or error code. 386 */ 387 tBleStatus aci_att_prepare_write_req(uint16_t Connection_Handle, 388 uint16_t Attr_Handle, 389 uint16_t Val_Offset, 390 uint8_t Attribute_Val_Length, 391 uint8_t Attribute_Val[]); 392 393 /** 394 * @brief Send an Execute Write Request. 395 The Execute Write Request is used to request the server to write or cancel the write 396 of all the prepared values currently held in the prepare queue from this client. 397 The result of the procedure is given through the @ref aci_att_exec_write_resp_event event. 398 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event event. 399 * @param Connection_Handle Connection handle for which the command is given. 400 * Values: 401 - 0x0000 ... 0x0EFF 402 * @param Execute Execute or cancel writes. 403 * Values: 404 - 0x00: Cancel all prepared writes 405 - 0x01: Immediately write all pending prepared values 406 * @retval Value indicating success or error code. 407 */ 408 tBleStatus aci_att_execute_write_req(uint16_t Connection_Handle, 409 uint8_t Execute); 410 411 /** 412 * @brief Start the GATT client procedure to discover all primary services on the server. 413 The responses of the procedure are given through the @ref aci_att_read_by_group_type_resp_event event. 414 * @param Connection_Handle Connection handle for which the command is given. 415 * Values: 416 - 0x0000 ... 0x0EFF 417 * @retval Value indicating success or error code. 418 */ 419 tBleStatus aci_gatt_disc_all_primary_services(uint16_t Connection_Handle); 420 421 /** 422 * @brief Start the procedure to discover the primary services of the specified UUID on the server. 423 The responses of the procedure are given through the @ref aci_att_find_by_type_value_resp_event event. 424 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event event. 425 * @param Connection_Handle Connection handle for which the command is given. 426 * Values: 427 - 0x0000 ... 0x0EFF 428 * @param UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 429 * @param UUID See @ref UUID_t 430 * @retval Value indicating success or error code. 431 */ 432 tBleStatus aci_gatt_disc_primary_service_by_uuid(uint16_t Connection_Handle, 433 uint8_t UUID_Type, 434 UUID_t *UUID); 435 436 /** 437 * @brief Start the procedure to find all included services. 438 The responses of the procedure are given through the @ref aci_att_read_by_type_resp_event event. 439 The end of the procedure is indicated by a @ref aci_gatt_proc_complete_event event. 440 * @param Connection_Handle Connection handle for which the command is given. 441 * Values: 442 - 0x0000 ... 0x0EFF 443 * @param Start_Handle Start attribute handle of the service 444 * @param End_Handle End attribute handle of the service 445 * @retval Value indicating success or error code. 446 */ 447 tBleStatus aci_gatt_find_included_services(uint16_t Connection_Handle, 448 uint16_t Start_Handle, 449 uint16_t End_Handle); 450 451 /** 452 * @brief Start the procedure to discover all the characteristics of a given service. 453 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 454 Before procedure completion the response packets are given through 455 @ref aci_att_read_by_type_resp_event event. 456 * @param Connection_Handle Connection handle for which the command is given. 457 * Values: 458 - 0x0000 ... 0x0EFF 459 * @param Start_Handle Start attribute handle of the service 460 * @param End_Handle End attribute handle of the service 461 * @retval Value indicating success or error code. 462 */ 463 tBleStatus aci_gatt_disc_all_char_of_service(uint16_t Connection_Handle, 464 uint16_t Start_Handle, 465 uint16_t End_Handle); 466 467 /** 468 * @brief Start the procedure to discover all the characteristics specified by a UUID. 469 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 470 Before procedure completion the response packets are given through 471 @ref aci_gatt_disc_read_char_by_uuid_resp_event event. 472 * @param Connection_Handle Connection handle for which the command is given. 473 * Values: 474 - 0x0000 ... 0x0EFF 475 * @param Start_Handle Start attribute handle of the service 476 * @param End_Handle End attribute handle of the service 477 * @param UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 478 * @param UUID See @ref UUID_t 479 * @retval Value indicating success or error code. 480 */ 481 tBleStatus aci_gatt_disc_char_by_uuid(uint16_t Connection_Handle, 482 uint16_t Start_Handle, 483 uint16_t End_Handle, 484 uint8_t UUID_Type, 485 UUID_t *UUID); 486 487 /** 488 * @brief Start the procedure to discover all characteristic descriptors on the server. 489 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 490 Before procedure completion the response packets are given through 491 @ref aci_att_find_info_resp_event event. 492 * @param Connection_Handle Connection handle for which the command is given. 493 * Values: 494 - 0x0000 ... 0x0EFF 495 * @param Char_Handle Handle of the characteristic value 496 * @param End_Handle End handle of the characteristic 497 * @retval Value indicating success or error code. 498 */ 499 tBleStatus aci_gatt_disc_all_char_desc(uint16_t Connection_Handle, 500 uint16_t Char_Handle, 501 uint16_t End_Handle); 502 503 /** 504 * @brief Start the procedure to read the attribute value. 505 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 506 Before procedure completion the response packet is given through @ref aci_att_read_resp_event event. 507 * @param Connection_Handle Connection handle for which the command is given. 508 * Values: 509 - 0x0000 ... 0x0EFF 510 * @param Attr_Handle Handle of the characteristic value to be read 511 * @retval Value indicating success or error code. 512 */ 513 tBleStatus aci_gatt_read_char_value(uint16_t Connection_Handle, 514 uint16_t Attr_Handle); 515 516 /** 517 * @brief This command sends a Read By Type Request packet to the server in order to read the value attribute of the characteristics specified by the UUID. 518 When the procedure is completed, an @ref aci_gatt_proc_complete_event event is generated. 519 Before procedure completion, the response packet is given through one @ref aci_gatt_disc_read_char_by_uuid_resp_event event per reported attribute. 520 Note: the number of bytes of a value reported by @ref aci_gatt_disc_read_char_by_uuid_resp_event event can not exceed BLE_EVT_MAX_PARAM_LEN - 7 i.e. 248 bytes for default value of BLE_EVT_MAX_PARAM_LEN. 521 * @param Connection_Handle Connection handle for which the command is given. 522 * Values: 523 - 0x0000 ... 0x0EFF 524 * @param Start_Handle Starting handle of the range to be searched 525 * @param End_Handle End handle of the range to be searched 526 * @param UUID_Type UUID type: 0x01 = 16 bits UUID while 0x02 = 128 bits UUID 527 * @param UUID See @ref UUID_t 528 * @retval Value indicating success or error code. 529 */ 530 tBleStatus aci_gatt_read_using_char_uuid(uint16_t Connection_Handle, 531 uint16_t Start_Handle, 532 uint16_t End_Handle, 533 uint8_t UUID_Type, 534 UUID_t *UUID); 535 536 /** 537 * @brief Start the procedure to read a long characteristic value. 538 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 539 Before procedure completion the response packets are given through @ref aci_att_read_blob_resp_event event. 540 * @param Connection_Handle Connection handle for which the command is given. 541 * Values: 542 - 0x0000 ... 0x0EFF 543 * @param Attr_Handle Handle of the characteristic value to be read 544 * @param Val_Offset Offset from which the value needs to be read 545 * @retval Value indicating success or error code. 546 */ 547 tBleStatus aci_gatt_read_long_char_value(uint16_t Connection_Handle, 548 uint16_t Attr_Handle, 549 uint16_t Val_Offset); 550 551 /** 552 * @brief Start a procedure to read multiple characteristic values from a server. 553 This sub-procedure is used to read multiple Characteristic Values from a server when the 554 client knows the Characteristic Value Handles. 555 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 556 Before procedure completion the response packets are given through 557 @ref aci_att_read_multiple_resp_event event. 558 * @param Connection_Handle Connection handle for which the command is given. 559 * Values: 560 - 0x0000 ... 0x0EFF 561 * @param Number_of_Handles The number of handles for which the value has to be read 562 * @param Handle_Entry See @ref Handle_Entry_t 563 * @retval Value indicating success or error code. 564 */ 565 tBleStatus aci_gatt_read_multiple_char_value(uint16_t Connection_Handle, 566 uint8_t Number_of_Handles, 567 Handle_Entry_t Handle_Entry[]); 568 569 /** 570 * @brief Start the procedure to write a characteristic value. 571 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 572 * @param Connection_Handle Connection handle for which the command is given. 573 * Values: 574 - 0x0000 ... 0x0EFF 575 * @param Attr_Handle Handle of the characteristic value to be written 576 * @param Attribute_Val_Length Length of the value to be written 577 * @param Attribute_Val Value to be written 578 * @retval Value indicating success or error code. 579 */ 580 tBleStatus aci_gatt_write_char_value(uint16_t Connection_Handle, 581 uint16_t Attr_Handle, 582 uint8_t Attribute_Val_Length, 583 uint8_t Attribute_Val[]); 584 585 /** 586 * @brief Start the procedure to write a long characteristic value. 587 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 588 During the procedure, @ref aci_att_prepare_write_resp_event and @ref aci_att_exec_write_resp_event 589 events are raised. 590 * @param Connection_Handle Connection handle for which the command is given. 591 * Values: 592 - 0x0000 ... 0x0EFF 593 * @param Attr_Handle Handle of the characteristic value to be written 594 * @param Val_Offset Offset at which the attribute has to be written 595 * @param Attribute_Val_Length Length of the value to be written 596 * @param Attribute_Val Value to be written 597 * @retval Value indicating success or error code. 598 */ 599 tBleStatus aci_gatt_write_long_char_value(uint16_t Connection_Handle, 600 uint16_t Attr_Handle, 601 uint16_t Val_Offset, 602 uint8_t Attribute_Val_Length, 603 uint8_t Attribute_Val[]); 604 605 /** 606 * @brief Start the procedure to write a characteristic reliably. 607 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 608 During the procedure, @ref aci_att_prepare_write_resp_event and @ref aci_att_exec_write_resp_event 609 events are raised. 610 * @param Connection_Handle Connection handle for which the command is given. 611 * Values: 612 - 0x0000 ... 0x0EFF 613 * @param Attr_Handle Handle of the attribute to be written 614 * @param Val_Offset Offset at which the attribute has to be written 615 * @param Attribute_Val_Length Length of the value to be written 616 * @param Attribute_Val Value to be written 617 * @retval Value indicating success or error code. 618 */ 619 tBleStatus aci_gatt_write_char_reliable(uint16_t Connection_Handle, 620 uint16_t Attr_Handle, 621 uint16_t Val_Offset, 622 uint8_t Attribute_Val_Length, 623 uint8_t Attribute_Val[]); 624 625 /** 626 * @brief Start the procedure to write a long characteristic descriptor. 627 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 628 During the procedure, @ref aci_att_prepare_write_resp_event and @ref aci_att_exec_write_resp_event 629 events are raised. 630 * @param Connection_Handle Connection handle for which the command is given. 631 * Values: 632 - 0x0000 ... 0x0EFF 633 * @param Attr_Handle Handle of the attribute to be written 634 * @param Val_Offset Offset at which the attribute has to be written 635 * @param Attribute_Val_Length Length of the value to be written 636 * @param Attribute_Val Value to be written 637 * @retval Value indicating success or error code. 638 */ 639 tBleStatus aci_gatt_write_long_char_desc(uint16_t Connection_Handle, 640 uint16_t Attr_Handle, 641 uint16_t Val_Offset, 642 uint8_t Attribute_Val_Length, 643 uint8_t Attribute_Val[]); 644 645 /** 646 * @brief Start the procedure to read a long characteristic value. 647 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is 648 generated. Before procedure completion the response packets are given through 649 @ref aci_att_read_blob_resp_event event. 650 * @param Connection_Handle Connection handle for which the command is given. 651 * Values: 652 - 0x0000 ... 0x0EFF 653 * @param Attr_Handle Handle of the characteristic descriptor 654 * @param Val_Offset Offset from which the value needs to be read 655 * @retval Value indicating success or error code. 656 */ 657 tBleStatus aci_gatt_read_long_char_desc(uint16_t Connection_Handle, 658 uint16_t Attr_Handle, 659 uint16_t Val_Offset); 660 661 /** 662 * @brief Start the procedure to write a characteristic descriptor. 663 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 664 * @param Connection_Handle Connection handle for which the command is given. 665 * Values: 666 - 0x0000 ... 0x0EFF 667 * @param Attr_Handle Handle of the attribute to be written 668 * @param Attribute_Val_Length Length of the value to be written 669 * @param Attribute_Val Value to be written 670 * @retval Value indicating success or error code. 671 */ 672 tBleStatus aci_gatt_write_char_desc(uint16_t Connection_Handle, 673 uint16_t Attr_Handle, 674 uint8_t Attribute_Val_Length, 675 uint8_t Attribute_Val[]); 676 677 /** 678 * @brief Start the procedure to read the descriptor specified. 679 When the procedure is completed, a @ref aci_gatt_proc_complete_event event is generated. 680 Before procedure completion the response packet is given through @ref aci_att_read_resp_event event. 681 * @param Connection_Handle Connection handle for which the command is given. 682 * Values: 683 - 0x0000 ... 0x0EFF 684 * @param Attr_Handle Handle of the descriptor to be read 685 * @retval Value indicating success or error code. 686 */ 687 tBleStatus aci_gatt_read_char_desc(uint16_t Connection_Handle, 688 uint16_t Attr_Handle); 689 690 /** 691 * @brief Start the procedure to write a characteristic value without waiting for any response from the 692 server. No events are generated after this command is executed. 693 * @param Connection_Handle Connection handle for which the command is given. 694 * Values: 695 - 0x0000 ... 0x0EFF 696 * @param Attr_Handle Handle of the characteristic value to be written 697 * @param Attribute_Val_Length Length of the value to be written (maximum value is ATT_MTU - 3) 698 * @param Attribute_Val Value to be written 699 * @retval Value indicating success or error code. 700 */ 701 tBleStatus aci_gatt_write_without_resp(uint16_t Connection_Handle, 702 uint16_t Attr_Handle, 703 uint8_t Attribute_Val_Length, 704 uint8_t Attribute_Val[]); 705 706 /** 707 * @brief Start a signed write without response from the server. 708 The procedure is used to write a characteristic value with an authentication signature without waiting 709 for any response from the server. It cannot be used when the link is encrypted. 710 * @param Connection_Handle Connection handle for which the command is given. 711 * Values: 712 - 0x0000 ... 0x0EFF 713 * @param Attr_Handle Handle of the characteristic value to be written 714 * @param Attribute_Val_Length Length of the value to be written (up to ATT_MTU - 13) 715 * @param Attribute_Val Value to be written 716 * @retval Value indicating success or error code. 717 */ 718 tBleStatus aci_gatt_signed_write_without_resp(uint16_t Connection_Handle, 719 uint16_t Attr_Handle, 720 uint8_t Attribute_Val_Length, 721 uint8_t Attribute_Val[]); 722 723 /** 724 * @brief Allow application to confirm indication. This command has to be sent when the application 725 receives the event @ref aci_gatt_indication_event. 726 * @param Connection_Handle Connection handle for which the command is given. 727 * Values: 728 - 0x0000 ... 0x0EFF 729 * @retval Value indicating success or error code. 730 */ 731 tBleStatus aci_gatt_confirm_indication(uint16_t Connection_Handle); 732 733 /** 734 * @brief Allow or reject a write request from a client. 735 This command has to be sent by the application when it receives the 736 @ref aci_gatt_write_permit_req_event. If the write can be allowed, then the status and error 737 code has to be set to 0. If the write cannot be allowed, then the status has to be set to 1 and 738 the error code has to be set to the error code that has to be passed to the client. 739 * @param Connection_Handle Connection handle for which the command is given. 740 * Values: 741 - 0x0000 ... 0x0EFF 742 * @param Attr_Handle Handle of the attribute that was passed in the event EVT_BLUE_GATT_WRITE_PERMIT_REQ 743 * @param Write_status If the value can be written or not. 744 * Values: 745 - 0x00: The value can be written to the attribute specified by attr_handle 746 - 0x01: The value cannot be written to the attribute specified by the attr_handle 747 * @param Error_Code The error code that has to be passed to the client in case the write has to be rejected 748 * @param Attribute_Val_Length Length of the value to be written as passed in the event EVT_BLUE_GATT_WRITE_PERMIT_REQ 749 * @param Attribute_Val Value as passed in the event EVT_BLUE_GATT_WRITE_PERMIT_REQ 750 * @retval Value indicating success or error code. 751 */ 752 tBleStatus aci_gatt_write_resp(uint16_t Connection_Handle, 753 uint16_t Attr_Handle, 754 uint8_t Write_status, 755 uint8_t Error_Code, 756 uint8_t Attribute_Val_Length, 757 uint8_t Attribute_Val[]); 758 759 /** 760 * @brief Allow the GATT server to send a response to a read request from a client. 761 The application has to send this command when it receives the 762 @ref aci_gatt_read_permit_req_event or @ref aci_gatt_read_multi_permit_req_event. This 763 command indicates to the stack that the response can be sent to the client. So if the 764 application wishes to update any of the attributes before they are read by the client, it has to 765 update the characteristic values using the @ref aci_gatt_update_char_value and then give 766 this command. The application should perform the required operations within 30 seconds. 767 Otherwise the GATT procedure will be timeout. 768 * @param Connection_Handle Connection handle for which the command is given. 769 * Values: 770 - 0x0000 ... 0x0EFF 771 * @retval Value indicating success or error code. 772 */ 773 tBleStatus aci_gatt_allow_read(uint16_t Connection_Handle); 774 775 /** 776 * @brief This command sets the security permission for the attribute handle specified. Currently the 777 setting of security permission is allowed only for client configuration descriptor. 778 * @param Serv_Handle Handle of the service which contains the attribute whose security permission has to be modified 779 * @param Attr_Handle Handle of the attribute whose security permission has to be modified 780 * @param Security_Permissions Security permission flags. 781 * Flags: 782 - 0x00: None 783 - 0x01: AUTHEN_READ (Need authentication to read) 784 - 0x02: AUTHOR_READ (Need authorization to read) 785 - 0x04: ENCRY_READ (Need encryption to read) 786 - 0x08: AUTHEN_WRITE (need authentication to write) 787 - 0x10: AUTHOR_WRITE (need authorization to write) 788 - 0x20: ENCRY_WRITE (need encryption to write) 789 * @retval Value indicating success or error code. 790 */ 791 tBleStatus aci_gatt_set_security_permission(uint16_t Serv_Handle, 792 uint16_t Attr_Handle, 793 uint8_t Security_Permissions); 794 795 /** 796 * @brief This command sets the value of the descriptor specified by charDescHandle. 797 * @param Serv_Handle Handle of the service which contains the characteristic descriptor 798 * @param Char_Handle Handle of the characteristic which contains the descriptor 799 * @param Char_Desc_Handle Handle of the descriptor whose value has to be set 800 * @param Val_Offset Offset from which the descriptor value has to be updated 801 * @param Char_Desc_Value_Length Length of the descriptor value 802 * @param Char_Desc_Value Descriptor value 803 * @retval Value indicating success or error code. 804 */ 805 tBleStatus aci_gatt_set_desc_value(uint16_t Serv_Handle, 806 uint16_t Char_Handle, 807 uint16_t Char_Desc_Handle, 808 uint16_t Val_Offset, 809 uint8_t Char_Desc_Value_Length, 810 uint8_t Char_Desc_Value[]); 811 812 /** 813 * @brief Reads the value of the attribute handle specified from the local GATT database. 814 * @param Attr_Handle Handle of the attribute to read 815 * @param Offset Offset from which the value needs to be read 816 * @param Value_Length_Requested Maximum number of octets to be returned as attribute value 817 * @param[out] Length Length of the attribute value 818 * @param[out] Value_Length Length in octets of the Value parameter 819 * @param[out] Value Attribute value 820 * @retval Value indicating success or error code. 821 */ 822 tBleStatus aci_gatt_read_handle_value(uint16_t Attr_Handle, 823 uint16_t Offset, 824 uint16_t Value_Length_Requested, 825 uint16_t *Length, 826 uint16_t *Value_Length, 827 uint8_t Value[]); 828 829 /** 830 * @brief This command is a more flexible version of @ref aci_gatt_update_char_value 831 to support update of long attribute up to 512 bytes and indicate selectively the generation of Indication/Notification. 832 * @param Conn_Handle_To_Notify Connection handle to notify. Notify all subscribed clients if equal to 0x0000 833 * @param Service_Handle Handle of service to which the characteristic belongs 834 * @param Char_Handle Handle of the characteristic declaration 835 * @param Update_Type Allow Notification or Indication generation, 836 if enabled in the client characteristic configuration descriptor 837 * Flags: 838 - 0x00: Do not notify 839 - 0x01: Notification 840 - 0x02: Indication 841 * @param Char_Length Total length of the characteristic value. 842 In case of a variable size characteristic, this field specifies the new length of the characteristic value after the update; in case of fixed length characteristic this field is ignored. 843 * @param Value_Offset The offset from which the attribute value has to be updated. 844 * @param Value_Length Length of the Value parameter in octets 845 * @param Value Updated characteristic value 846 * @retval Value indicating success or error code. 847 */ 848 tBleStatus aci_gatt_update_char_value_ext(uint16_t Conn_Handle_To_Notify, 849 uint16_t Service_Handle, 850 uint16_t Char_Handle, 851 uint8_t Update_Type, 852 uint16_t Char_Length, 853 uint16_t Value_Offset, 854 uint8_t Value_Length, 855 uint8_t Value[]); 856 857 /** 858 * @brief Deny the GATT server to send a response to a read request from a client. 859 The application may send this command when it receives the @ref aci_gatt_read_permit_req_event or @ref aci_gatt_read_multi_permit_req_event. 860 This command indicates to the stack that the client is not allowed to read the requested characteristic due to e.g. application restrictions. 861 The Error code shall be either 0x08 (Insufficient Authorization) or a value in the range 0x80-0x9F (Application Error). 862 The application should issue the @ref aci_gatt_deny_read or @ref aci_gatt_allow_read command within 30 seconds from the reception of 863 the @ref aci_gatt_read_permit_req_event or @ref aci_gatt_read_multi_permit_req_event events otherwise the GATT procedure will issue a timeout. 864 * @param Connection_Handle Connection handle for which the command is given. 865 * Values: 866 - 0x0000 ... 0x0EFF 867 * @param Error_Code Error code for the command 868 * Values: 869 - 0x08: Insufficient Authorization 870 - 0x80 ... 0x9F: Application Error 871 * @retval Value indicating success or error code. 872 */ 873 tBleStatus aci_gatt_deny_read(uint16_t Connection_Handle, 874 uint8_t Error_Code); 875 876 /** 877 * @brief This command sets the access permission for the attribute handle specified. 878 * @param Serv_Handle Handle of the service which contains the attribute whose access permission has to be modified 879 * @param Attr_Handle Handle of the attribute whose security permission has to be modified 880 * @param Access_Permissions Access permission 881 * Flags: 882 - 0x00: None 883 - 0x01: READ 884 - 0x02: WRITE 885 - 0x04: WRITE_WO_RESP 886 - 0x08: SIGNED_WRITE 887 * @retval Value indicating success or error code. 888 */ 889 tBleStatus aci_gatt_set_access_permission(uint16_t Serv_Handle, 890 uint16_t Attr_Handle, 891 uint8_t Access_Permissions); 892 893 /** 894 * @} 895 */ 896 897 #endif /* ! BLE_GATT_ACI_H__ */ 898