1 /****************************************************************************** 2 * 3 * Copyright (C) 1999-2012 Broadcom Corporation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 #ifndef GATT_API_H 19 #define GATT_API_H 20 21 #include "bt_target.h" 22 #include "gattdefs.h" 23 24 /***************************************************************************** 25 ** Constants 26 *****************************************************************************/ 27 /* Success code and error codes */ 28 #define GATT_SUCCESS 0x0000 29 #define GATT_INVALID_HANDLE 0x0001 30 #define GATT_READ_NOT_PERMIT 0x0002 31 #define GATT_WRITE_NOT_PERMIT 0x0003 32 #define GATT_INVALID_PDU 0x0004 33 #define GATT_INSUF_AUTHENTICATION 0x0005 34 #define GATT_REQ_NOT_SUPPORTED 0x0006 35 #define GATT_INVALID_OFFSET 0x0007 36 #define GATT_INSUF_AUTHORIZATION 0x0008 37 #define GATT_PREPARE_Q_FULL 0x0009 38 #define GATT_NOT_FOUND 0x000a 39 #define GATT_NOT_LONG 0x000b 40 #define GATT_INSUF_KEY_SIZE 0x000c 41 #define GATT_INVALID_ATTR_LEN 0x000d 42 #define GATT_ERR_UNLIKELY 0x000e 43 #define GATT_INSUF_ENCRYPTION 0x000f 44 #define GATT_UNSUPPORT_GRP_TYPE 0x0010 45 #define GATT_INSUF_RESOURCE 0x0011 46 47 48 #define GATT_ILLEGAL_PARAMETER 0x0087 49 #define GATT_NO_RESOURCES 0x0080 50 #define GATT_INTERNAL_ERROR 0x0081 51 #define GATT_WRONG_STATE 0x0082 52 #define GATT_DB_FULL 0x0083 53 #define GATT_BUSY 0x0084 54 #define GATT_ERROR 0x0085 55 #define GATT_CMD_STARTED 0x0086 56 #define GATT_PENDING 0x0088 57 #define GATT_AUTH_FAIL 0x0089 58 #define GATT_MORE 0x008a 59 #define GATT_INVALID_CFG 0x008b 60 #define GATT_SERVICE_STARTED 0x008c 61 #define GATT_ENCRYPED_MITM GATT_SUCCESS 62 #define GATT_ENCRYPED_NO_MITM 0x008d 63 #define GATT_NOT_ENCRYPTED 0x008e 64 65 66 typedef UINT8 tGATT_STATUS; 67 68 69 #define GATT_RSP_ERROR 0x01 70 #define GATT_REQ_MTU 0x02 71 #define GATT_RSP_MTU 0x03 72 #define GATT_REQ_FIND_INFO 0x04 73 #define GATT_RSP_FIND_INFO 0x05 74 #define GATT_REQ_FIND_TYPE_VALUE 0x06 75 #define GATT_RSP_FIND_TYPE_VALUE 0x07 76 #define GATT_REQ_READ_BY_TYPE 0x08 77 #define GATT_RSP_READ_BY_TYPE 0x09 78 #define GATT_REQ_READ 0x0A 79 #define GATT_RSP_READ 0x0B 80 #define GATT_REQ_READ_BLOB 0x0C 81 #define GATT_RSP_READ_BLOB 0x0D 82 #define GATT_REQ_READ_MULTI 0x0E 83 #define GATT_RSP_READ_MULTI 0x0F 84 #define GATT_REQ_READ_BY_GRP_TYPE 0x10 85 #define GATT_RSP_READ_BY_GRP_TYPE 0x11 86 #define GATT_REQ_WRITE 0x12 /* 0001-0010 (write)*/ 87 #define GATT_RSP_WRITE 0x13 88 #define GATT_CMD_WRITE 0x52 /* changed in V4.0 01001-0010(write cmd)*/ 89 #define GATT_REQ_PREPARE_WRITE 0x16 90 #define GATT_RSP_PREPARE_WRITE 0x17 91 #define GATT_REQ_EXEC_WRITE 0x18 92 #define GATT_RSP_EXEC_WRITE 0x19 93 #define GATT_HANDLE_VALUE_NOTIF 0x1B 94 #define GATT_HANDLE_VALUE_IND 0x1D 95 #define GATT_HANDLE_VALUE_CONF 0x1E 96 #define GATT_SIGN_CMD_WRITE 0xD2 /* changed in V4.0 1101-0010 (signed write) see write cmd above*/ 97 #define GATT_OP_CODE_MAX GATT_HANDLE_VALUE_CONF + 1 /* 0x1E = 30 + 1 = 31*/ 98 99 100 #define GATT_HANDLE_IS_VALID(x) ((x) != 0) 101 102 #define GATT_CONN_UNKNOWN 0 103 #define GATT_CONN_NO_RESOURCES L2CAP_CONN_NO_RESOURCES /* connection fail for l2cap resource failure */ 104 #define GATT_CONN_TIMEOUT HCI_ERR_CONNECTION_TOUT /* 0x08 connection timeout */ 105 #define GATT_CONN_TERMINATE_PEER_USER HCI_ERR_PEER_USER /* 0x13 connection terminate by peer user */ 106 #define GATT_CONN_TERMINATE_LOCAL_HOST HCI_ERR_CONN_CAUSE_LOCAL_HOST /* 0x16 connectionterminated by local host */ 107 #define GATT_CONN_FAIL_ESTABLISH HCI_ERR_CONN_FAILED_ESTABLISHMENT/* 0x03E connection fail to establish */ 108 #define GATT_CONN_LMP_TIMEOUT HCI_ERR_LMP_RESPONSE_TIMEOUT /* 0x22 connection fail for LMP response tout */ 109 #define GATT_CONN_CANCEL L2CAP_CONN_CANCEL /* 0x0100 L2CAP connection cancelled */ 110 typedef UINT16 tGATT_DISCONN_REASON; 111 112 /* MAX GATT MTU size 113 */ 114 #ifndef GATT_MAX_MTU_SIZE 115 #define GATT_MAX_MTU_SIZE 517 116 #endif 117 118 /* max legth of an attribute value 119 */ 120 #ifndef GATT_MAX_ATTR_LEN 121 #define GATT_MAX_ATTR_LEN 600 122 #endif 123 124 /* default GATT MTU size over LE link 125 */ 126 #define GATT_DEF_BLE_MTU_SIZE 23 127 128 /* invalid connection ID 129 */ 130 #define GATT_INVALID_CONN_ID 0xFFFF 131 132 #ifndef GATT_CL_MAX_LCB 133 #define GATT_CL_MAX_LCB 22 134 #endif 135 136 #ifndef GATT_MAX_SCCB 137 #define GATT_MAX_SCCB 10 138 #endif 139 140 #ifndef GATTP_TRANSPORT_SUPPORTED 141 #define GATTP_TRANSPORT_SUPPORTED GATT_TRANSPORT_LE_BR_EDR 142 #endif 143 144 145 /* GATT notification caching timer, default to be three seconds 146 */ 147 #ifndef GATTC_NOTIF_TIMEOUT 148 #define GATTC_NOTIF_TIMEOUT 3 149 #endif 150 151 /***************************************************************************** 152 ** GATT Structure Definition 153 *****************************************************************************/ 154 155 /* Attribute permissions 156 */ 157 #define GATT_PERM_READ (1 << 0) /* bit 0 */ 158 #define GATT_PERM_READ_ENCRYPTED (1 << 1) /* bit 1 */ 159 #define GATT_PERM_READ_ENC_MITM (1 << 2) /* bit 2 */ 160 #define GATT_PERM_WRITE (1 << 4) /* bit 4 */ 161 #define GATT_PERM_WRITE_ENCRYPTED (1 << 5) /* bit 5 */ 162 #define GATT_PERM_WRITE_ENC_MITM (1 << 6) /* bit 6 */ 163 #define GATT_PERM_WRITE_SIGNED (1 << 7) /* bit 7 */ 164 #define GATT_PERM_WRITE_SIGNED_MITM (1 << 8) /* bit 8 */ 165 typedef UINT16 tGATT_PERM; 166 167 #define GATT_ENCRYPT_KEY_SIZE_MASK (0xF000) /* the MS nibble of tGATT_PERM; key size 7=0; size 16=9 */ 168 169 #define GATT_READ_ALLOWED (GATT_PERM_READ | GATT_PERM_READ_ENCRYPTED | GATT_PERM_READ_ENC_MITM) 170 #define GATT_READ_AUTH_REQUIRED (GATT_PERM_READ_ENCRYPTED) 171 #define GATT_READ_MITM_REQUIRED (GATT_PERM_READ_ENC_MITM) 172 #define GATT_READ_ENCRYPTED_REQUIRED (GATT_PERM_READ_ENCRYPTED | GATT_PERM_READ_ENC_MITM) 173 174 175 #define GATT_WRITE_ALLOWED (GATT_PERM_WRITE | GATT_PERM_WRITE_ENCRYPTED | GATT_PERM_WRITE_ENC_MITM | \ 176 GATT_PERM_WRITE_SIGNED | GATT_PERM_WRITE_SIGNED_MITM) 177 178 #define GATT_WRITE_AUTH_REQUIRED (GATT_PERM_WRITE_ENCRYPTED | GATT_PERM_WRITE_SIGNED) 179 180 #define GATT_WRITE_MITM_REQUIRED (GATT_PERM_WRITE_ENC_MITM | GATT_PERM_WRITE_SIGNED_MITM) 181 182 #define GATT_WRITE_ENCRYPTED_PERM (GATT_PERM_WRITE_ENCRYPTED | GATT_PERM_WRITE_ENC_MITM) 183 184 #define GATT_WRITE_SIGNED_PERM (GATT_PERM_WRITE_SIGNED | GATT_PERM_WRITE_SIGNED_MITM) 185 186 187 /* Characteristic properties 188 */ 189 #define GATT_CHAR_PROP_BIT_BROADCAST (1 << 0) 190 #define GATT_CHAR_PROP_BIT_READ (1 << 1) 191 #define GATT_CHAR_PROP_BIT_WRITE_NR (1 << 2) 192 #define GATT_CHAR_PROP_BIT_WRITE (1 << 3) 193 #define GATT_CHAR_PROP_BIT_NOTIFY (1 << 4) 194 #define GATT_CHAR_PROP_BIT_INDICATE (1 << 5) 195 #define GATT_CHAR_PROP_BIT_AUTH (1 << 6) 196 #define GATT_CHAR_PROP_BIT_EXT_PROP (1 << 7) 197 typedef UINT8 tGATT_CHAR_PROP; 198 199 200 /* Format of the value of a characteristic. enumeration type 201 */ 202 enum 203 { 204 GATT_FORMAT_RES, /* rfu */ 205 GATT_FORMAT_BOOL, /* 0x01 boolean */ 206 GATT_FORMAT_2BITS, /* 0x02 2 bit */ 207 GATT_FORMAT_NIBBLE, /* 0x03 nibble */ 208 GATT_FORMAT_UINT8, /* 0x04 uint8 */ 209 GATT_FORMAT_UINT12, /* 0x05 uint12 */ 210 GATT_FORMAT_UINT16, /* 0x06 uint16 */ 211 GATT_FORMAT_UINT24, /* 0x07 uint24 */ 212 GATT_FORMAT_UINT32, /* 0x08 uint32 */ 213 GATT_FORMAT_UINT48, /* 0x09 uint48 */ 214 GATT_FORMAT_UINT64, /* 0x0a uint64 */ 215 GATT_FORMAT_UINT128, /* 0x0B uint128 */ 216 GATT_FORMAT_SINT8, /* 0x0C signed 8 bit integer */ 217 GATT_FORMAT_SINT12, /* 0x0D signed 12 bit integer */ 218 GATT_FORMAT_SINT16, /* 0x0E signed 16 bit integer */ 219 GATT_FORMAT_SINT24, /* 0x0F signed 24 bit integer */ 220 GATT_FORMAT_SINT32, /* 0x10 signed 32 bit integer */ 221 GATT_FORMAT_SINT48, /* 0x11 signed 48 bit integer */ 222 GATT_FORMAT_SINT64, /* 0x12 signed 64 bit integer */ 223 GATT_FORMAT_SINT128, /* 0x13 signed 128 bit integer */ 224 GATT_FORMAT_FLOAT32, /* 0x14 float 32 */ 225 GATT_FORMAT_FLOAT64, /* 0x15 float 64*/ 226 GATT_FORMAT_SFLOAT, /* 0x16 IEEE-11073 16 bit SFLOAT */ 227 GATT_FORMAT_FLOAT, /* 0x17 IEEE-11073 32 bit SFLOAT */ 228 GATT_FORMAT_DUINT16, /* 0x18 IEEE-20601 format */ 229 GATT_FORMAT_UTF8S, /* 0x19 UTF-8 string */ 230 GATT_FORMAT_UTF16S, /* 0x1a UTF-16 string */ 231 GATT_FORMAT_STRUCT, /* 0x1b Opaque structure*/ 232 GATT_FORMAT_MAX /* 0x1c or above reserved */ 233 }; 234 typedef UINT8 tGATT_FORMAT; 235 236 /* Characteristic Presentation Format Descriptor value 237 */ 238 typedef struct 239 { 240 UINT16 unit; /* as UUIUD defined by SIG */ 241 UINT16 descr; /* as UUID as defined by SIG */ 242 tGATT_FORMAT format; 243 INT8 exp; 244 UINT8 name_spc; /* The name space of the description */ 245 } tGATT_CHAR_PRES; 246 247 #define GATT_VALID_RANGE_MAX_SIZE 16 248 typedef struct 249 { 250 UINT8 format; 251 UINT16 len; 252 UINT8 lower_range[GATT_VALID_RANGE_MAX_SIZE]; /* in little endian format */ 253 UINT8 upper_range[GATT_VALID_RANGE_MAX_SIZE]; 254 } tGATT_VALID_RANGE; 255 256 /* Characteristic Aggregate Format attribute value 257 */ 258 #define GATT_AGGR_HANDLE_NUM_MAX 10 259 typedef struct 260 { 261 UINT8 num_handle; 262 UINT16 handle_list[GATT_AGGR_HANDLE_NUM_MAX]; 263 } tGATT_CHAR_AGGRE; 264 265 /* Characteristic descriptor: Extended Properties value 266 */ 267 #define GATT_CHAR_BIT_REL_WRITE 0x0001 /* permits reliable writes of the Characteristic Value */ 268 #define GATT_CHAR_BIT_WRITE_AUX 0x0002 /* permits writes to the characteristic descriptor */ 269 270 271 /* characteristic descriptor: client configuration value 272 */ 273 #define GATT_CLT_CONFIG_NONE 0x0000 274 #define GATT_CLT_CONFIG_NOTIFICATION 0x0001 275 #define GATT_CLT_CONFIG_INDICATION 0x0002 276 typedef UINT16 tGATT_CLT_CHAR_CONFIG; 277 278 279 /* characteristic descriptor: server configuration value 280 */ 281 #define GATT_SVR_CONFIG_NONE 0x0000 282 #define GATT_SVR_CONFIG_BROADCAST 0x0001 283 typedef UINT16 tGATT_SVR_CHAR_CONFIG; 284 285 /* Characteristic descriptor: Extended Properties value 286 */ 287 #define GATT_CHAR_BIT_REL_WRITE 0x0001 /* permits reliable writes of the Characteristic Value */ 288 #define GATT_CHAR_BIT_WRITE_AUX 0x0002 /* permits writes to the characteristic descriptor */ 289 290 /* authentication requirement 291 */ 292 #define GATT_AUTH_REQ_NONE 0 293 #define GATT_AUTH_REQ_NO_MITM 1 /* unauthenticated encryption */ 294 #define GATT_AUTH_REQ_MITM 2 /* authenticated encryption */ 295 #define GATT_AUTH_REQ_SIGNED_NO_MITM 3 296 #define GATT_AUTH_REQ_SIGNED_MITM 4 297 typedef UINT8 tGATT_AUTH_REQ; 298 299 /* Attribute Value structure 300 */ 301 typedef struct 302 { 303 UINT16 conn_id; 304 UINT16 handle; /* attribute handle */ 305 UINT16 offset; /* attribute value offset, if no offfset is needed for the command, ignore it */ 306 UINT16 len; /* length of attribute value */ 307 tGATT_AUTH_REQ auth_req; /* authentication request */ 308 UINT8 value[GATT_MAX_ATTR_LEN]; /* the actual attribute value */ 309 } tGATT_VALUE; 310 311 /* Union of the event data which is used in the server respond API to carry the server response information 312 */ 313 typedef union 314 { 315 /* data type member event */ 316 tGATT_VALUE attr_value; /* READ, HANDLE_VALUE_IND, PREPARE_WRITE */ 317 /* READ_BLOB, READ_BY_TYPE */ 318 UINT16 handle; /* WRITE, WRITE_BLOB */ 319 320 } tGATTS_RSP; 321 322 /* Transports for the primary service */ 323 enum 324 { 325 GATT_TRANSPORT_LE, 326 GATT_TRANSPORT_BR_EDR, 327 GATT_TRANSPORT_LE_BR_EDR 328 }; 329 typedef UINT8 tGATT_TRANSPORT; 330 331 #define GATT_PREP_WRITE_CANCEL 0x00 332 #define GATT_PREP_WRITE_EXEC 0x01 333 typedef UINT8 tGATT_EXEC_FLAG; 334 335 /* read request always based on UUID */ 336 typedef struct 337 { 338 UINT16 handle; 339 UINT16 offset; 340 BOOLEAN is_long; 341 } tGATT_READ_REQ; 342 343 /* write request data */ 344 typedef struct 345 { 346 UINT16 handle; /* attribute handle */ 347 UINT16 offset; /* attribute value offset, if no offfset is needed for the command, ignore it */ 348 UINT16 len; /* length of attribute value */ 349 UINT8 value[GATT_MAX_ATTR_LEN]; /* the actual attribute value */ 350 BOOLEAN need_rsp; /* need write response */ 351 BOOLEAN is_prep; /* is prepare write */ 352 } tGATT_WRITE_REQ; 353 354 /* callback data for server access request from client */ 355 typedef union 356 { 357 tGATT_READ_REQ read_req; /* read request, read by Type, read blob */ 358 359 tGATT_WRITE_REQ write_req; /* write */ 360 /* prepare write */ 361 /* write blob */ 362 UINT16 handle; /* handle value confirmation */ 363 UINT16 mtu; /* MTU exchange request */ 364 tGATT_EXEC_FLAG exec_write; /* execute write */ 365 } tGATTS_DATA; 366 367 typedef UINT8 tGATT_SERV_IF; /* GATT Service Interface */ 368 369 enum 370 { 371 GATTS_REQ_TYPE_READ = 1, /* Attribute read request */ 372 GATTS_REQ_TYPE_WRITE, /* Attribute write request */ 373 GATTS_REQ_TYPE_WRITE_EXEC, /* Execute write */ 374 GATTS_REQ_TYPE_MTU, /* MTU exchange information */ 375 GATTS_REQ_TYPE_CONF /* handle value confirmation */ 376 }; 377 typedef UINT8 tGATTS_REQ_TYPE; 378 379 380 381 /* Client Used Data Structure 382 */ 383 /* definition of different discovery types */ 384 enum 385 { 386 GATT_DISC_SRVC_ALL = 1, /* discover all services */ 387 GATT_DISC_SRVC_BY_UUID, /* discover service of a special type */ 388 GATT_DISC_INC_SRVC, /* discover the included service within a service */ 389 GATT_DISC_CHAR, /* discover characteristics of a service with/without type requirement */ 390 GATT_DISC_CHAR_DSCPT, /* discover characteristic descriptors of a character */ 391 GATT_DISC_MAX /* maximnun discover type */ 392 }; 393 typedef UINT8 tGATT_DISC_TYPE; 394 395 /* Discover parameters of different discovery types 396 */ 397 typedef struct 398 { 399 tBT_UUID service; 400 UINT16 s_handle; 401 UINT16 e_handle; 402 }tGATT_DISC_PARAM; 403 404 /* GATT read type enumeration 405 */ 406 enum 407 { 408 GATT_READ_BY_TYPE = 1, 409 GATT_READ_BY_HANDLE, 410 GATT_READ_MULTIPLE, 411 GATT_READ_CHAR_VALUE, 412 GATT_READ_PARTIAL, 413 GATT_READ_MAX 414 }; 415 typedef UINT8 tGATT_READ_TYPE; 416 417 /* Read By Type Request (GATT_READ_BY_TYPE) Data 418 */ 419 typedef struct 420 { 421 tGATT_AUTH_REQ auth_req; 422 UINT16 s_handle; 423 UINT16 e_handle; 424 tBT_UUID uuid; 425 } tGATT_READ_BY_TYPE; 426 427 /* GATT_READ_MULTIPLE request data 428 */ 429 #define GATT_MAX_READ_MULTI_HANDLES 10 /* Max attributes to read in one request */ 430 typedef struct 431 { 432 tGATT_AUTH_REQ auth_req; 433 UINT16 num_handles; /* number of handles to read */ 434 UINT16 handles[GATT_MAX_READ_MULTI_HANDLES]; /* handles list to be read */ 435 } tGATT_READ_MULTI; 436 437 /* Read By Handle Request (GATT_READ_BY_HANDLE) data */ 438 typedef struct 439 { 440 tGATT_AUTH_REQ auth_req; 441 UINT16 handle; 442 } tGATT_READ_BY_HANDLE; 443 444 /* READ_BT_HANDLE_Request data */ 445 typedef struct 446 { 447 tGATT_AUTH_REQ auth_req; 448 UINT16 handle; 449 UINT16 offset; 450 } tGATT_READ_PARTIAL; 451 452 /* Read Request Data 453 */ 454 typedef union 455 { 456 tGATT_READ_BY_TYPE service; 457 tGATT_READ_BY_TYPE char_type; /* characterisitc type */ 458 tGATT_READ_MULTI read_multiple; 459 tGATT_READ_BY_HANDLE by_handle; 460 tGATT_READ_PARTIAL partial; 461 } tGATT_READ_PARAM; 462 463 /* GATT write type enumeration */ 464 enum 465 { 466 GATT_WRITE_NO_RSP = 1, 467 GATT_WRITE , 468 GATT_WRITE_PREPARE 469 }; 470 typedef UINT8 tGATT_WRITE_TYPE; 471 472 /* Client Operation Complete Callback Data 473 */ 474 typedef union 475 { 476 tGATT_VALUE att_value; 477 UINT16 mtu; 478 UINT16 handle; 479 } tGATT_CL_COMPLETE; 480 481 /* GATT client operation type, used in client callback function 482 */ 483 #define GATTC_OPTYPE_NONE 0 484 #define GATTC_OPTYPE_DISCOVERY 1 485 #define GATTC_OPTYPE_READ 2 486 #define GATTC_OPTYPE_WRITE 3 487 #define GATTC_OPTYPE_EXE_WRITE 4 488 #define GATTC_OPTYPE_CONFIG 5 489 #define GATTC_OPTYPE_NOTIFICATION 6 490 #define GATTC_OPTYPE_INDICATION 7 491 typedef UINT8 tGATTC_OPTYPE; 492 493 /* characteristic declaration 494 */ 495 typedef struct 496 { 497 tGATT_CHAR_PROP char_prop; /* characterisitc properties */ 498 UINT16 val_handle; /* characteristic value attribute handle */ 499 tBT_UUID char_uuid; /* characteristic UUID type */ 500 } tGATT_CHAR_DCLR_VAL; 501 502 /* primary service group data 503 */ 504 typedef struct 505 { 506 UINT16 e_handle; /* ending handle of the group */ 507 tBT_UUID service_type; /* group type */ 508 } tGATT_GROUP_VALUE; 509 510 511 /* included service attribute value 512 */ 513 typedef struct 514 { 515 tBT_UUID service_type; /* included service UUID */ 516 UINT16 s_handle; /* starting handle */ 517 UINT16 e_handle; /* ending handle */ 518 } tGATT_INCL_SRVC; 519 520 typedef union 521 { 522 tGATT_INCL_SRVC incl_service; /* include service value */ 523 tGATT_GROUP_VALUE group_value; /* Service UUID type. 524 This field is used with GATT_DISC_SRVC_ALL 525 type of discovery result callback. */ 526 527 UINT16 handle; /* When used with GATT_DISC_SRVC_BY_UUID type 528 discovery result, it is the ending handle of a 529 known service to be discovered. When used with 530 GATT_DISC_INC_SRVC type discovery result, 531 it is the included service starting handle.*/ 532 533 tGATT_CHAR_DCLR_VAL dclr_value; /* Characteristic declaration value. 534 This field is used with GATT_DISC_CHAR type discovery.*/ 535 } tGATT_DISC_VALUE; 536 537 /* discover result record 538 */ 539 typedef struct 540 { 541 tBT_UUID type; 542 UINT16 handle; 543 tGATT_DISC_VALUE value; 544 } tGATT_DISC_RES; 545 546 547 typedef UINT8 tGATT_IF; 548 #define GATT_LINK_IDLE_TIMEOUT_WHEN_NO_APP 0 /* start a idle timer for this duration when no application 549 need to use the link */ 550 551 #define GATT_LINK_NO_IDLE_TIMEOUT 0xFFFF 552 553 #define GATT_INVALID_ACL_HANDLE 0xFFFF 554 /* discover result callback function */ 555 typedef void (tGATT_DISC_RES_CB) (UINT16 conn_id, tGATT_DISC_TYPE disc_type, tGATT_DISC_RES *p_data); 556 557 /* discover complete callback function */ 558 typedef void (tGATT_DISC_CMPL_CB) (UINT16 conn_id, tGATT_DISC_TYPE disc_type, tGATT_STATUS status); 559 560 /* Define a callback function for when read/write/disc/config operation is completed. */ 561 typedef void (tGATT_CMPL_CBACK) (UINT16 conn_id, tGATTC_OPTYPE op, tGATT_STATUS status, tGATT_CL_COMPLETE *p_data); 562 563 /* Define a callback function when an initialized connection is established. */ 564 typedef void (tGATT_CONN_CBACK) (tGATT_IF gatt_if, BD_ADDR bda, UINT16 conn_id, BOOLEAN connected, tGATT_DISCONN_REASON reason); 565 566 /* attribute request callback for ATT server */ 567 typedef void (tGATT_REQ_CBACK )(UINT16 conn_id, UINT32 trans_id, tGATTS_REQ_TYPE type, tGATTS_DATA *p_data); 568 569 570 571 572 /* Define the structure that applications use to register with 573 ** GATT. This structure includes callback functions. All functions 574 ** MUST be provided. 575 */ 576 typedef struct 577 { 578 tGATT_CONN_CBACK *p_conn_cb; 579 tGATT_CMPL_CBACK *p_cmpl_cb; 580 tGATT_DISC_RES_CB *p_disc_res_cb; 581 tGATT_DISC_CMPL_CB *p_disc_cmpl_cb; 582 tGATT_REQ_CBACK *p_req_cb; 583 } tGATT_CBACK; 584 585 /*********************** Start Handle Management Definitions ********************** 586 */ 587 588 589 typedef struct 590 { 591 tBT_UUID app_uuid128; 592 tBT_UUID svc_uuid; 593 UINT16 svc_inst; 594 UINT16 s_handle; 595 UINT16 e_handle; 596 BOOLEAN is_primary; /* primary service or secondary */ 597 } tGATTS_HNDL_RANGE; 598 599 600 601 #define GATTS_SRV_CHG_CMD_ADD_CLIENT 1 602 #define GATTS_SRV_CHG_CMD_UPDATE_CLIENT 2 603 #define GATTS_SRV_CHG_CMD_REMOVE_CLIENT 3 604 #define GATTS_SRV_CHG_CMD_READ_NUM_CLENTS 4 605 #define GATTS_SRV_CHG_CMD_READ_CLENT 5 606 typedef UINT8 tGATTS_SRV_CHG_CMD; 607 608 typedef struct 609 { 610 BD_ADDR bda; 611 BOOLEAN srv_changed; 612 } tGATTS_SRV_CHG; 613 614 615 typedef union 616 { 617 tGATTS_SRV_CHG srv_chg; 618 UINT8 client_read_index; /* only used for sequential reading client srv chg info */ 619 } tGATTS_SRV_CHG_REQ; 620 621 typedef union 622 { 623 tGATTS_SRV_CHG srv_chg; 624 UINT8 num_clients; 625 } tGATTS_SRV_CHG_RSP; 626 627 628 629 typedef struct 630 { 631 tGATTS_HNDL_RANGE *p_new_srv_start; 632 } tGATTS_PENDING_NEW_SRV_START; 633 634 /* Attibute server handle ranges NV storage callback functions 635 */ 636 typedef void (tGATTS_NV_SAVE_CBACK)(BOOLEAN is_saved, tGATTS_HNDL_RANGE *p_hndl_range); 637 typedef BOOLEAN (tGATTS_NV_SRV_CHG_CBACK)(tGATTS_SRV_CHG_CMD cmd, tGATTS_SRV_CHG_REQ *p_req, tGATTS_SRV_CHG_RSP *p_rsp); 638 639 typedef struct 640 { 641 tGATTS_NV_SAVE_CBACK *p_nv_save_callback; 642 tGATTS_NV_SRV_CHG_CBACK *p_srv_chg_callback; 643 } tGATT_APPL_INFO; 644 645 /* 646 *********************** End Handle Management Definitions **********************/ 647 648 /***************************************************************************** 649 ** External Function Declarations 650 *****************************************************************************/ 651 #ifdef __cplusplus 652 extern "C" 653 { 654 #endif 655 656 /******************************************************************************* 657 ** 658 ** Function GATT_SetTraceLevel 659 ** 660 ** Description This function sets the trace level. If called with 661 ** a value of 0xFF, it simply returns the current trace level. 662 ** 663 ** Returns The new or current trace level 664 ** 665 *******************************************************************************/ 666 GATT_API extern UINT8 GATT_SetTraceLevel (UINT8 new_level); 667 668 669 /*******************************************************************************/ 670 /* GATT Profile API Functions */ 671 /*******************************************************************************/ 672 /* GATT Profile Server Functions */ 673 /*******************************************************************************/ 674 /******************************************************************************* 675 ** 676 ** Function GATTS_AddHandleRange 677 ** 678 ** Description This function add the allocated handles range for the specifed 679 ** application UUID, service UUID and service instance 680 ** 681 ** Parameter p_hndl_range: pointer to allocated handles information 682 ** 683 ** Returns TRUE if handle range is added sucessfully; otherwise FALSE. 684 ** 685 *******************************************************************************/ 686 687 GATT_API extern BOOLEAN GATTS_AddHandleRange(tGATTS_HNDL_RANGE *p_hndl_range); 688 689 /******************************************************************************* 690 ** 691 ** Function GATTS_NVRegister 692 ** 693 ** Description Application manager calls this function to register for 694 ** NV save callback function. There can be one and only one 695 ** NV save callback function. 696 ** 697 ** Parameter p_cb_info : callback informaiton 698 ** 699 ** Returns TRUE if registered OK, else FALSE 700 ** 701 *******************************************************************************/ 702 GATT_API extern BOOLEAN GATTS_NVRegister (tGATT_APPL_INFO *p_cb_info); 703 704 705 /******************************************************************************* 706 ** 707 ** Function GATTS_CreateService 708 ** 709 ** Description This function is called to reserve a block of handles for a service. 710 ** 711 ** *** It should be called only once per service instance *** 712 ** 713 ** Parameter gatt_if : application if 714 ** p_svc_uuid : service UUID 715 ** svc_inst : instance of the service inside the application 716 ** num_handles : number of handles needed by the service. 717 ** is_pri : is a primary service or not. 718 ** 719 ** Returns service handle if sucessful, otherwise 0. 720 ** 721 *******************************************************************************/ 722 GATT_API extern UINT16 GATTS_CreateService (tGATT_IF gatt_if, tBT_UUID *p_svc_uuid, 723 UINT16 svc_inst, UINT16 num_handles, BOOLEAN is_pri); 724 725 726 /******************************************************************************* 727 ** 728 ** Function GATTS_AddIncludeService 729 ** 730 ** Description This function is called to add an included service. 731 ** 732 ** Parameter service_handle : To which service this included service is added to. 733 ** include_svc_handle : included service handle. 734 ** 735 ** Returns included service attribute handle. If 0, add included service 736 ** fail. 737 ** 738 *******************************************************************************/ 739 GATT_API extern UINT16 GATTS_AddIncludeService (UINT16 service_handle, 740 UINT16 include_svc_handle); 741 742 743 /******************************************************************************* 744 ** 745 ** Function GATTS_AddCharacteristic 746 ** 747 ** Description This function is called to add a characteristic into a service. 748 ** It will add a characteristic declaration and characteristic 749 ** value declaration into the service database identified by the 750 ** service handle. 751 ** 752 ** Parameter service_handle : To which service this included service is added to. 753 ** char_uuid : Characteristic UUID. 754 ** perm : Characteristic value declaration attribute permission. 755 ** property : Characteristic Properties 756 ** 757 ** Returns Characteristic value declaration attribute handle. 0 if add 758 ** characteristic failed. 759 ** 760 *******************************************************************************/ 761 GATT_API extern UINT16 GATTS_AddCharacteristic (UINT16 service_handle, tBT_UUID *char_uuid, 762 tGATT_PERM perm,tGATT_CHAR_PROP property); 763 764 /******************************************************************************* 765 ** 766 ** Function GATTS_AddCharDescriptor 767 ** 768 ** Description This function is called to add a characteristic descriptor 769 ** into a service database. Add descriptor should follow add char 770 ** to which it belongs, and next add char should be done only 771 ** after all add descriptors for the previous char. 772 ** 773 ** Parameter service_handle : To which service this characteristic descriptor 774 ** is added to. 775 ** perm : Characteristic value declaration attribute 776 ** permission. 777 ** p_descr_uuid : Characteristic descriptor UUID. 778 ** 779 ** Returns Characteristic descriptor attribute handle. 0 if add 780 ** characteristic descriptor failed. 781 ** 782 *******************************************************************************/ 783 GATT_API extern UINT16 GATTS_AddCharDescriptor (UINT16 service_handle, tGATT_PERM perm, 784 tBT_UUID * p_descr_uuid); 785 786 /******************************************************************************* 787 ** 788 ** Function GATTS_DeleteService 789 ** 790 ** Description This function is called to delete a service. 791 ** 792 ** Parameter gatt_if : application interface 793 ** p_svc_uuid : service UUID 794 ** svc_inst : instance of the service inside the application 795 ** 796 ** Returns TRUE if operation succeed, FALSE if handle block was not found. 797 ** 798 *******************************************************************************/ 799 GATT_API extern BOOLEAN GATTS_DeleteService (tGATT_IF gatt_if, tBT_UUID *p_svc_uuid, UINT16 svc_inst); 800 801 /******************************************************************************* 802 ** 803 ** Function GATTS_StartService 804 ** 805 ** Description This function is called to start a service with GATT 806 ** 807 ** Parameter gatt_if : service handle. 808 ** p_cback : application service callback functions. 809 ** sup_transport : supported transport(s) for this primary service 810 ** 811 ** return GATT_SUCCESS if sucessfully started; otherwise error code. 812 ** 813 *******************************************************************************/ 814 GATT_API extern tGATT_STATUS GATTS_StartService (tGATT_IF gatt_if, UINT16 service_handle, 815 tGATT_TRANSPORT sup_transport); 816 817 818 /******************************************************************************* 819 ** 820 ** Function GATTS_StopService 821 ** 822 ** Description This function is called to stop a service 823 ** 824 ** Parameter service_handle : this is the start handle of a service 825 ** 826 ** Returns None. 827 ** 828 *******************************************************************************/ 829 GATT_API extern void GATTS_StopService (UINT16 service_handle); 830 831 832 /******************************************************************************* 833 ** 834 ** Function GATTs_HandleValueIndication 835 ** 836 ** Description This function sends a handle value indication to a client. 837 ** 838 ** Parameter conn_id: connection identifier. 839 ** attr_handle: Attribute handle of this handle value indication. 840 ** val_len: Length of the indicated attribute value. 841 ** p_val: Pointer to the indicated attribute value data. 842 ** 843 ** Returns GATT_SUCCESS if sucessfully sent or queued; otherwise error code. 844 ** 845 *******************************************************************************/ 846 GATT_API extern tGATT_STATUS GATTS_HandleValueIndication (UINT16 conn_id, 847 UINT16 attr_handle, 848 UINT16 val_len, UINT8 *p_val); 849 850 /******************************************************************************* 851 ** 852 ** Function GATTS_HandleValueNotification 853 ** 854 ** Description This function sends a handle value notification to a client. 855 ** 856 ** Parameter conn_id: connection identifier. 857 ** attr_handle: Attribute handle of this handle value indication. 858 ** val_len: Length of the indicated attribute value. 859 ** p_val: Pointer to the indicated attribute value data. 860 ** 861 ** Returns GATT_SUCCESS if sucessfully sent; otherwise error code. 862 ** 863 *******************************************************************************/ 864 GATT_API extern tGATT_STATUS GATTS_HandleValueNotification (UINT16 conn_id, UINT16 attr_handle, 865 UINT16 val_len, UINT8 *p_val); 866 867 868 /******************************************************************************* 869 ** 870 ** Function GATTS_SendRsp 871 ** 872 ** Description This function sends the server response to client. 873 ** 874 ** Parameter conn_id: connection identifier. 875 ** trans_id: transaction id 876 ** status: response status 877 ** p_msg: pointer to message parameters structure. 878 ** 879 ** Returns GATT_SUCCESS if sucessfully sent; otherwise error code. 880 ** 881 *******************************************************************************/ 882 GATT_API extern tGATT_STATUS GATTS_SendRsp (UINT16 conn_id, UINT32 trans_id, 883 tGATT_STATUS status, tGATTS_RSP *p_msg); 884 885 886 /*******************************************************************************/ 887 /* GATT Profile Client Functions */ 888 /*******************************************************************************/ 889 890 /******************************************************************************* 891 ** 892 ** Function GATTC_ConfigureMTU 893 ** 894 ** Description This function is called to configure the ATT MTU size for 895 ** a connection on an LE transport. 896 ** 897 ** Parameters conn_id: connection identifier. 898 ** mtu - attribute MTU size.. 899 ** 900 ** Returns GATT_SUCCESS if command started successfully. 901 ** 902 *******************************************************************************/ 903 GATT_API extern tGATT_STATUS GATTC_ConfigureMTU (UINT16 conn_id, UINT16 mtu); 904 905 /******************************************************************************* 906 ** 907 ** Function GATTC_Discover 908 ** 909 ** Description This function is called to do a discovery procedure on ATT server. 910 ** 911 ** Parameters conn_id: connection identifier. 912 ** disc_type:discovery type. 913 ** p_param: parameters of discovery requirement. 914 ** 915 ** Returns GATT_SUCCESS if command received/sent successfully. 916 ** 917 *******************************************************************************/ 918 GATT_API extern tGATT_STATUS GATTC_Discover (UINT16 conn_id, 919 tGATT_DISC_TYPE disc_type, 920 tGATT_DISC_PARAM *p_param ); 921 /******************************************************************************* 922 ** 923 ** Function GATTC_Read 924 ** 925 ** Description This function is called to read the value of an attribute from 926 ** the server. 927 ** 928 ** Parameters conn_id: connection identifier. 929 ** type - attribute read type. 930 ** p_read - read operation parameters. 931 ** 932 ** Returns GATT_SUCCESS if command started successfully. 933 ** 934 *******************************************************************************/ 935 GATT_API extern tGATT_STATUS GATTC_Read (UINT16 conn_id, tGATT_READ_TYPE type, 936 tGATT_READ_PARAM *p_read); 937 938 /******************************************************************************* 939 ** 940 ** Function GATTC_Write 941 ** 942 ** Description This function is called to read the value of an attribute from 943 ** the server. 944 ** 945 ** Parameters conn_id: connection identifier. 946 ** type - attribute write type. 947 ** p_write - write operation parameters. 948 ** 949 ** Returns GATT_SUCCESS if command started successfully. 950 ** 951 *******************************************************************************/ 952 GATT_API extern tGATT_STATUS GATTC_Write (UINT16 conn_id, tGATT_WRITE_TYPE type, 953 tGATT_VALUE *p_write); 954 955 956 /******************************************************************************* 957 ** 958 ** Function GATTC_ExecuteWrite 959 ** 960 ** Description This function is called to send an Execute write request to 961 ** the server. 962 ** 963 ** Parameters conn_id: connection identifier. 964 ** is_execute - to execute or cancel the prepare write requet(s) 965 ** 966 ** Returns GATT_SUCCESS if command started successfully. 967 ** 968 *******************************************************************************/ 969 GATT_API extern tGATT_STATUS GATTC_ExecuteWrite (UINT16 conn_id, BOOLEAN is_execute); 970 971 /******************************************************************************* 972 ** 973 ** Function GATTC_SendHandleValueConfirm 974 ** 975 ** Description This function is called to send a handle value confirmation 976 ** as response to a handle value notification from server. 977 ** 978 ** Parameters conn_id: connection identifier. 979 ** handle: the handle of the attribute confirmation. 980 ** 981 ** Returns GATT_SUCCESS if command started successfully. 982 ** 983 *******************************************************************************/ 984 GATT_API extern tGATT_STATUS GATTC_SendHandleValueConfirm (UINT16 conn_id, UINT16 handle); 985 986 987 /******************************************************************************* 988 ** 989 ** Function GATT_SetIdleTimeout 990 ** 991 ** Description This function (common to both client and server) sets the idle 992 ** timeout for a tansport connection 993 ** 994 ** Parameter bd_addr: target device bd address. 995 ** idle_tout: timeout value in seconds. 996 ** 997 ** Returns void 998 ** 999 *******************************************************************************/ 1000 GATT_API extern void GATT_SetIdleTimeout (BD_ADDR bd_addr, UINT16 idle_tout); 1001 1002 1003 /******************************************************************************* 1004 ** 1005 ** Function GATT_Register 1006 ** 1007 ** Description This function is called to register an application 1008 ** with GATT 1009 ** 1010 ** Parameter p_app_uuid128: Application UUID 1011 ** p_cb_info: callback functions. 1012 ** 1013 ** Returns 0 for error, otherwise the index of the client registered with GATT 1014 ** 1015 *******************************************************************************/ 1016 GATT_API extern tGATT_IF GATT_Register (tBT_UUID *p_app_uuid128, tGATT_CBACK *p_cb_info); 1017 1018 /******************************************************************************* 1019 ** 1020 ** Function GATT_Deregister 1021 ** 1022 ** Description This function deregistered the application from GATT. 1023 ** 1024 ** Parameters gatt_if: applicaiton interface. 1025 ** 1026 ** Returns None. 1027 ** 1028 *******************************************************************************/ 1029 GATT_API extern void GATT_Deregister (tGATT_IF gatt_if); 1030 1031 /******************************************************************************* 1032 ** 1033 ** Function GATT_StartIf 1034 ** 1035 ** Description This function is called after registration to start receiving 1036 ** callbacks for registered interface. Function may call back 1037 ** with connection status and queued notifications 1038 ** 1039 ** Parameter gatt_if: applicaiton interface. 1040 ** 1041 ** Returns None 1042 ** 1043 *******************************************************************************/ 1044 GATT_API extern void GATT_StartIf (tGATT_IF gatt_if); 1045 1046 /******************************************************************************* 1047 ** 1048 ** Function GATT_Connect 1049 ** 1050 ** Description This function initiate a connecttion to a ATT server. 1051 ** 1052 ** Parameters gatt_if: applicaiton interface 1053 ** bd_addr: peer device address. 1054 ** is_direct: is a direct conenection or a background auto connection 1055 ** 1056 ** Returns TRUE if connection started; FALSE if connection start failure. 1057 ** 1058 *******************************************************************************/ 1059 GATT_API extern BOOLEAN GATT_Connect (tGATT_IF gatt_if, BD_ADDR bd_addr, BOOLEAN is_direct); 1060 1061 1062 /******************************************************************************* 1063 ** 1064 ** Function GATT_CancelConnect 1065 ** 1066 ** Description This function initiate a cancel connecttion to a ATT server. 1067 ** 1068 ** Parameters gatt_if: client interface. If 0 used as unconditionally disconnect, 1069 ** typically used for direct connection cancellation. 1070 ** bd_addr: peer device address. 1071 ** is_direct: is a direct conenection or a background auto connection 1072 ** 1073 ** Returns TRUE if connection started; FALSE if connection start failure. 1074 ** 1075 *******************************************************************************/ 1076 GATT_API extern BOOLEAN GATT_CancelConnect (tGATT_IF gatt_if, BD_ADDR bd_addr, BOOLEAN is_direct); 1077 1078 /******************************************************************************* 1079 ** 1080 ** Function GATT_Disconnect 1081 ** 1082 ** Description This function disconnect a logic channel. 1083 ** 1084 ** Parameters conn_id: connection identifier. 1085 ** 1086 ** Returns GATT_SUCCESS if disconnected. 1087 ** 1088 *******************************************************************************/ 1089 GATT_API extern tGATT_STATUS GATT_Disconnect (UINT16 conn_id); 1090 1091 1092 1093 /******************************************************************************* 1094 ** 1095 ** Function GATT_GetConnectionInfor 1096 ** 1097 ** Description This function use conn_id to find its associated BD address and applciation 1098 ** interface 1099 ** 1100 ** Parameters conn_id: connection id (input) 1101 ** p_gatt_if: applicaiton interface (output) 1102 ** bd_addr: peer device address. (output) 1103 ** 1104 ** Returns TRUE the ligical link information is found for conn_id 1105 ** 1106 *******************************************************************************/ 1107 GATT_API extern BOOLEAN GATT_GetConnectionInfor(UINT16 conn_id, tGATT_IF *p_gatt_if, BD_ADDR bd_addr); 1108 1109 1110 /******************************************************************************* 1111 ** 1112 ** Function GATT_GetConnIdIfConnected 1113 ** 1114 ** Description This function find the conn_id if the logical link for BD address 1115 ** and applciation interface is connected 1116 ** 1117 ** Parameters gatt_if: applicaiton interface (input) 1118 ** bd_addr: peer device address. (input) 1119 ** p_conn_id: connection id (output) 1120 ** 1121 ** Returns TRUE the ligical link is connected 1122 ** 1123 *******************************************************************************/ 1124 GATT_API extern BOOLEAN GATT_GetConnIdIfConnected(tGATT_IF gatt_if, BD_ADDR bd_addr, UINT16 *p_conn_id); 1125 1126 1127 /******************************************************************************* 1128 ** 1129 ** Function GATT_Listen 1130 ** 1131 ** Description This function start or stop LE advertisement and listen for 1132 ** connection. 1133 ** 1134 ** Parameters gatt_if: applicaiton interface 1135 ** p_bd_addr: listen for specific address connection, or NULL for 1136 ** listen to all device connection. 1137 ** start: is a direct conenection or a background auto connection 1138 ** 1139 ** Returns TRUE if advertisement is started; FALSE if adv start failure. 1140 ** 1141 *******************************************************************************/ 1142 GATT_API extern BOOLEAN GATT_Listen (tGATT_IF gatt_if, BOOLEAN start, BD_ADDR_PTR bd_addr); 1143 1144 1145 #ifdef __cplusplus 1146 1147 } 1148 #endif 1149 1150 #endif /* GATT_API_H */ 1151