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_L2C_FAILURE 1 /* general L2cap 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 /* Characteristic Report reference Descriptor format 248 */ 249 typedef struct 250 { 251 UINT8 rpt_id; /* report ID */ 252 UINT8 rpt_type; /* report type */ 253 } tGATT_CHAR_RPT_REF; 254 255 256 #define GATT_VALID_RANGE_MAX_SIZE 16 257 typedef struct 258 { 259 UINT8 format; 260 UINT16 len; 261 UINT8 lower_range[GATT_VALID_RANGE_MAX_SIZE]; /* in little endian format */ 262 UINT8 upper_range[GATT_VALID_RANGE_MAX_SIZE]; 263 } tGATT_VALID_RANGE; 264 265 /* Characteristic Aggregate Format attribute value 266 */ 267 #define GATT_AGGR_HANDLE_NUM_MAX 10 268 typedef struct 269 { 270 UINT8 num_handle; 271 UINT16 handle_list[GATT_AGGR_HANDLE_NUM_MAX]; 272 } tGATT_CHAR_AGGRE; 273 274 /* Characteristic descriptor: Extended Properties value 275 */ 276 #define GATT_CHAR_BIT_REL_WRITE 0x0001 /* permits reliable writes of the Characteristic Value */ 277 #define GATT_CHAR_BIT_WRITE_AUX 0x0002 /* permits writes to the characteristic descriptor */ 278 279 280 /* characteristic descriptor: client configuration value 281 */ 282 #define GATT_CLT_CONFIG_NONE 0x0000 283 #define GATT_CLT_CONFIG_NOTIFICATION 0x0001 284 #define GATT_CLT_CONFIG_INDICATION 0x0002 285 typedef UINT16 tGATT_CLT_CHAR_CONFIG; 286 287 288 /* characteristic descriptor: server configuration value 289 */ 290 #define GATT_SVR_CONFIG_NONE 0x0000 291 #define GATT_SVR_CONFIG_BROADCAST 0x0001 292 typedef UINT16 tGATT_SVR_CHAR_CONFIG; 293 294 /* Characteristic descriptor: Extended Properties value 295 */ 296 #define GATT_CHAR_BIT_REL_WRITE 0x0001 /* permits reliable writes of the Characteristic Value */ 297 #define GATT_CHAR_BIT_WRITE_AUX 0x0002 /* permits writes to the characteristic descriptor */ 298 299 /* authentication requirement 300 */ 301 #define GATT_AUTH_REQ_NONE 0 302 #define GATT_AUTH_REQ_NO_MITM 1 /* unauthenticated encryption */ 303 #define GATT_AUTH_REQ_MITM 2 /* authenticated encryption */ 304 #define GATT_AUTH_REQ_SIGNED_NO_MITM 3 305 #define GATT_AUTH_REQ_SIGNED_MITM 4 306 typedef UINT8 tGATT_AUTH_REQ; 307 308 /* Attribute Value structure 309 */ 310 typedef struct 311 { 312 UINT16 conn_id; 313 UINT16 handle; /* attribute handle */ 314 UINT16 offset; /* attribute value offset, if no offfset is needed for the command, ignore it */ 315 UINT16 len; /* length of attribute value */ 316 tGATT_AUTH_REQ auth_req; /* authentication request */ 317 UINT8 value[GATT_MAX_ATTR_LEN]; /* the actual attribute value */ 318 } tGATT_VALUE; 319 320 /* Union of the event data which is used in the server respond API to carry the server response information 321 */ 322 typedef union 323 { 324 /* data type member event */ 325 tGATT_VALUE attr_value; /* READ, HANDLE_VALUE_IND, PREPARE_WRITE */ 326 /* READ_BLOB, READ_BY_TYPE */ 327 UINT16 handle; /* WRITE, WRITE_BLOB */ 328 329 } tGATTS_RSP; 330 331 /* Transports for the primary service */ 332 enum 333 { 334 GATT_TRANSPORT_LE, 335 GATT_TRANSPORT_BR_EDR, 336 GATT_TRANSPORT_LE_BR_EDR 337 }; 338 typedef UINT8 tGATT_TRANSPORT; 339 340 #define GATT_PREP_WRITE_CANCEL 0x00 341 #define GATT_PREP_WRITE_EXEC 0x01 342 typedef UINT8 tGATT_EXEC_FLAG; 343 344 /* read request always based on UUID */ 345 typedef struct 346 { 347 UINT16 handle; 348 UINT16 offset; 349 BOOLEAN is_long; 350 } tGATT_READ_REQ; 351 352 /* write request data */ 353 typedef struct 354 { 355 UINT16 handle; /* attribute handle */ 356 UINT16 offset; /* attribute value offset, if no offfset is needed for the command, ignore it */ 357 UINT16 len; /* length of attribute value */ 358 UINT8 value[GATT_MAX_ATTR_LEN]; /* the actual attribute value */ 359 BOOLEAN need_rsp; /* need write response */ 360 BOOLEAN is_prep; /* is prepare write */ 361 } tGATT_WRITE_REQ; 362 363 /* callback data for server access request from client */ 364 typedef union 365 { 366 tGATT_READ_REQ read_req; /* read request, read by Type, read blob */ 367 368 tGATT_WRITE_REQ write_req; /* write */ 369 /* prepare write */ 370 /* write blob */ 371 UINT16 handle; /* handle value confirmation */ 372 UINT16 mtu; /* MTU exchange request */ 373 tGATT_EXEC_FLAG exec_write; /* execute write */ 374 } tGATTS_DATA; 375 376 typedef UINT8 tGATT_SERV_IF; /* GATT Service Interface */ 377 378 enum 379 { 380 GATTS_REQ_TYPE_READ = 1, /* Attribute read request */ 381 GATTS_REQ_TYPE_WRITE, /* Attribute write request */ 382 GATTS_REQ_TYPE_WRITE_EXEC, /* Execute write */ 383 GATTS_REQ_TYPE_MTU, /* MTU exchange information */ 384 GATTS_REQ_TYPE_CONF /* handle value confirmation */ 385 }; 386 typedef UINT8 tGATTS_REQ_TYPE; 387 388 389 390 /* Client Used Data Structure 391 */ 392 /* definition of different discovery types */ 393 enum 394 { 395 GATT_DISC_SRVC_ALL = 1, /* discover all services */ 396 GATT_DISC_SRVC_BY_UUID, /* discover service of a special type */ 397 GATT_DISC_INC_SRVC, /* discover the included service within a service */ 398 GATT_DISC_CHAR, /* discover characteristics of a service with/without type requirement */ 399 GATT_DISC_CHAR_DSCPT, /* discover characteristic descriptors of a character */ 400 GATT_DISC_MAX /* maximnun discover type */ 401 }; 402 typedef UINT8 tGATT_DISC_TYPE; 403 404 /* Discover parameters of different discovery types 405 */ 406 typedef struct 407 { 408 tBT_UUID service; 409 UINT16 s_handle; 410 UINT16 e_handle; 411 }tGATT_DISC_PARAM; 412 413 /* GATT read type enumeration 414 */ 415 enum 416 { 417 GATT_READ_BY_TYPE = 1, 418 GATT_READ_BY_HANDLE, 419 GATT_READ_MULTIPLE, 420 GATT_READ_CHAR_VALUE, 421 GATT_READ_PARTIAL, 422 GATT_READ_MAX 423 }; 424 typedef UINT8 tGATT_READ_TYPE; 425 426 /* Read By Type Request (GATT_READ_BY_TYPE) Data 427 */ 428 typedef struct 429 { 430 tGATT_AUTH_REQ auth_req; 431 UINT16 s_handle; 432 UINT16 e_handle; 433 tBT_UUID uuid; 434 } tGATT_READ_BY_TYPE; 435 436 /* GATT_READ_MULTIPLE request data 437 */ 438 #define GATT_MAX_READ_MULTI_HANDLES 10 /* Max attributes to read in one request */ 439 typedef struct 440 { 441 tGATT_AUTH_REQ auth_req; 442 UINT16 num_handles; /* number of handles to read */ 443 UINT16 handles[GATT_MAX_READ_MULTI_HANDLES]; /* handles list to be read */ 444 } tGATT_READ_MULTI; 445 446 /* Read By Handle Request (GATT_READ_BY_HANDLE) data */ 447 typedef struct 448 { 449 tGATT_AUTH_REQ auth_req; 450 UINT16 handle; 451 } tGATT_READ_BY_HANDLE; 452 453 /* READ_BT_HANDLE_Request data */ 454 typedef struct 455 { 456 tGATT_AUTH_REQ auth_req; 457 UINT16 handle; 458 UINT16 offset; 459 } tGATT_READ_PARTIAL; 460 461 /* Read Request Data 462 */ 463 typedef union 464 { 465 tGATT_READ_BY_TYPE service; 466 tGATT_READ_BY_TYPE char_type; /* characterisitc type */ 467 tGATT_READ_MULTI read_multiple; 468 tGATT_READ_BY_HANDLE by_handle; 469 tGATT_READ_PARTIAL partial; 470 } tGATT_READ_PARAM; 471 472 /* GATT write type enumeration */ 473 enum 474 { 475 GATT_WRITE_NO_RSP = 1, 476 GATT_WRITE , 477 GATT_WRITE_PREPARE 478 }; 479 typedef UINT8 tGATT_WRITE_TYPE; 480 481 /* Client Operation Complete Callback Data 482 */ 483 typedef union 484 { 485 tGATT_VALUE att_value; 486 UINT16 mtu; 487 UINT16 handle; 488 } tGATT_CL_COMPLETE; 489 490 /* GATT client operation type, used in client callback function 491 */ 492 #define GATTC_OPTYPE_NONE 0 493 #define GATTC_OPTYPE_DISCOVERY 1 494 #define GATTC_OPTYPE_READ 2 495 #define GATTC_OPTYPE_WRITE 3 496 #define GATTC_OPTYPE_EXE_WRITE 4 497 #define GATTC_OPTYPE_CONFIG 5 498 #define GATTC_OPTYPE_NOTIFICATION 6 499 #define GATTC_OPTYPE_INDICATION 7 500 typedef UINT8 tGATTC_OPTYPE; 501 502 /* characteristic declaration 503 */ 504 typedef struct 505 { 506 tGATT_CHAR_PROP char_prop; /* characterisitc properties */ 507 UINT16 val_handle; /* characteristic value attribute handle */ 508 tBT_UUID char_uuid; /* characteristic UUID type */ 509 } tGATT_CHAR_DCLR_VAL; 510 511 /* primary service group data 512 */ 513 typedef struct 514 { 515 UINT16 e_handle; /* ending handle of the group */ 516 tBT_UUID service_type; /* group type */ 517 } tGATT_GROUP_VALUE; 518 519 520 /* included service attribute value 521 */ 522 typedef struct 523 { 524 tBT_UUID service_type; /* included service UUID */ 525 UINT16 s_handle; /* starting handle */ 526 UINT16 e_handle; /* ending handle */ 527 } tGATT_INCL_SRVC; 528 529 typedef union 530 { 531 tGATT_INCL_SRVC incl_service; /* include service value */ 532 tGATT_GROUP_VALUE group_value; /* Service UUID type. 533 This field is used with GATT_DISC_SRVC_ALL 534 or GATT_DISC_SRVC_BY_UUID 535 type of discovery result callback. */ 536 537 UINT16 handle; /* When used with GATT_DISC_INC_SRVC type discovery result, 538 it is the included service starting handle.*/ 539 540 tGATT_CHAR_DCLR_VAL dclr_value; /* Characteristic declaration value. 541 This field is used with GATT_DISC_CHAR type discovery.*/ 542 } tGATT_DISC_VALUE; 543 544 /* discover result record 545 */ 546 typedef struct 547 { 548 tBT_UUID type; 549 UINT16 handle; 550 tGATT_DISC_VALUE value; 551 } tGATT_DISC_RES; 552 553 554 typedef UINT8 tGATT_IF; 555 #define GATT_LINK_IDLE_TIMEOUT_WHEN_NO_APP 0 /* start a idle timer for this duration when no application 556 need to use the link */ 557 558 #define GATT_LINK_NO_IDLE_TIMEOUT 0xFFFF 559 560 #define GATT_INVALID_ACL_HANDLE 0xFFFF 561 /* discover result callback function */ 562 typedef void (tGATT_DISC_RES_CB) (UINT16 conn_id, tGATT_DISC_TYPE disc_type, tGATT_DISC_RES *p_data); 563 564 /* discover complete callback function */ 565 typedef void (tGATT_DISC_CMPL_CB) (UINT16 conn_id, tGATT_DISC_TYPE disc_type, tGATT_STATUS status); 566 567 /* Define a callback function for when read/write/disc/config operation is completed. */ 568 typedef void (tGATT_CMPL_CBACK) (UINT16 conn_id, tGATTC_OPTYPE op, tGATT_STATUS status, tGATT_CL_COMPLETE *p_data); 569 570 /* Define a callback function when an initialized connection is established. */ 571 typedef void (tGATT_CONN_CBACK) (tGATT_IF gatt_if, BD_ADDR bda, UINT16 conn_id, BOOLEAN connected, tGATT_DISCONN_REASON reason); 572 573 /* attribute request callback for ATT server */ 574 typedef void (tGATT_REQ_CBACK )(UINT16 conn_id, UINT32 trans_id, tGATTS_REQ_TYPE type, tGATTS_DATA *p_data); 575 576 577 578 579 /* Define the structure that applications use to register with 580 ** GATT. This structure includes callback functions. All functions 581 ** MUST be provided. 582 */ 583 typedef struct 584 { 585 tGATT_CONN_CBACK *p_conn_cb; 586 tGATT_CMPL_CBACK *p_cmpl_cb; 587 tGATT_DISC_RES_CB *p_disc_res_cb; 588 tGATT_DISC_CMPL_CB *p_disc_cmpl_cb; 589 tGATT_REQ_CBACK *p_req_cb; 590 } tGATT_CBACK; 591 592 /*********************** Start Handle Management Definitions ********************** 593 */ 594 595 596 typedef struct 597 { 598 tBT_UUID app_uuid128; 599 tBT_UUID svc_uuid; 600 UINT16 svc_inst; 601 UINT16 s_handle; 602 UINT16 e_handle; 603 BOOLEAN is_primary; /* primary service or secondary */ 604 } tGATTS_HNDL_RANGE; 605 606 607 608 #define GATTS_SRV_CHG_CMD_ADD_CLIENT 1 609 #define GATTS_SRV_CHG_CMD_UPDATE_CLIENT 2 610 #define GATTS_SRV_CHG_CMD_REMOVE_CLIENT 3 611 #define GATTS_SRV_CHG_CMD_READ_NUM_CLENTS 4 612 #define GATTS_SRV_CHG_CMD_READ_CLENT 5 613 typedef UINT8 tGATTS_SRV_CHG_CMD; 614 615 typedef struct 616 { 617 BD_ADDR bda; 618 BOOLEAN srv_changed; 619 } tGATTS_SRV_CHG; 620 621 622 typedef union 623 { 624 tGATTS_SRV_CHG srv_chg; 625 UINT8 client_read_index; /* only used for sequential reading client srv chg info */ 626 } tGATTS_SRV_CHG_REQ; 627 628 typedef union 629 { 630 tGATTS_SRV_CHG srv_chg; 631 UINT8 num_clients; 632 } tGATTS_SRV_CHG_RSP; 633 634 635 636 typedef struct 637 { 638 tGATTS_HNDL_RANGE *p_new_srv_start; 639 } tGATTS_PENDING_NEW_SRV_START; 640 641 /* Attibute server handle ranges NV storage callback functions 642 */ 643 typedef void (tGATTS_NV_SAVE_CBACK)(BOOLEAN is_saved, tGATTS_HNDL_RANGE *p_hndl_range); 644 typedef BOOLEAN (tGATTS_NV_SRV_CHG_CBACK)(tGATTS_SRV_CHG_CMD cmd, tGATTS_SRV_CHG_REQ *p_req, tGATTS_SRV_CHG_RSP *p_rsp); 645 646 typedef struct 647 { 648 tGATTS_NV_SAVE_CBACK *p_nv_save_callback; 649 tGATTS_NV_SRV_CHG_CBACK *p_srv_chg_callback; 650 } tGATT_APPL_INFO; 651 652 /* 653 *********************** End Handle Management Definitions **********************/ 654 655 /***************************************************************************** 656 ** External Function Declarations 657 *****************************************************************************/ 658 #ifdef __cplusplus 659 extern "C" 660 { 661 #endif 662 663 /******************************************************************************* 664 ** 665 ** Function GATT_SetTraceLevel 666 ** 667 ** Description This function sets the trace level. If called with 668 ** a value of 0xFF, it simply returns the current trace level. 669 ** 670 ** Returns The new or current trace level 671 ** 672 *******************************************************************************/ 673 GATT_API extern UINT8 GATT_SetTraceLevel (UINT8 new_level); 674 675 676 /*******************************************************************************/ 677 /* GATT Profile API Functions */ 678 /*******************************************************************************/ 679 /* GATT Profile Server Functions */ 680 /*******************************************************************************/ 681 /******************************************************************************* 682 ** 683 ** Function GATTS_AddHandleRange 684 ** 685 ** Description This function add the allocated handles range for the specifed 686 ** application UUID, service UUID and service instance 687 ** 688 ** Parameter p_hndl_range: pointer to allocated handles information 689 ** 690 ** Returns TRUE if handle range is added sucessfully; otherwise FALSE. 691 ** 692 *******************************************************************************/ 693 694 GATT_API extern BOOLEAN GATTS_AddHandleRange(tGATTS_HNDL_RANGE *p_hndl_range); 695 696 /******************************************************************************* 697 ** 698 ** Function GATTS_NVRegister 699 ** 700 ** Description Application manager calls this function to register for 701 ** NV save callback function. There can be one and only one 702 ** NV save callback function. 703 ** 704 ** Parameter p_cb_info : callback informaiton 705 ** 706 ** Returns TRUE if registered OK, else FALSE 707 ** 708 *******************************************************************************/ 709 GATT_API extern BOOLEAN GATTS_NVRegister (tGATT_APPL_INFO *p_cb_info); 710 711 712 /******************************************************************************* 713 ** 714 ** Function GATTS_CreateService 715 ** 716 ** Description This function is called to reserve a block of handles for a service. 717 ** 718 ** *** It should be called only once per service instance *** 719 ** 720 ** Parameter gatt_if : application if 721 ** p_svc_uuid : service UUID 722 ** svc_inst : instance of the service inside the application 723 ** num_handles : number of handles needed by the service. 724 ** is_pri : is a primary service or not. 725 ** 726 ** Returns service handle if sucessful, otherwise 0. 727 ** 728 *******************************************************************************/ 729 GATT_API extern UINT16 GATTS_CreateService (tGATT_IF gatt_if, tBT_UUID *p_svc_uuid, 730 UINT16 svc_inst, UINT16 num_handles, BOOLEAN is_pri); 731 732 733 /******************************************************************************* 734 ** 735 ** Function GATTS_AddIncludeService 736 ** 737 ** Description This function is called to add an included service. 738 ** 739 ** Parameter service_handle : To which service this included service is added to. 740 ** include_svc_handle : included service handle. 741 ** 742 ** Returns included service attribute handle. If 0, add included service 743 ** fail. 744 ** 745 *******************************************************************************/ 746 GATT_API extern UINT16 GATTS_AddIncludeService (UINT16 service_handle, 747 UINT16 include_svc_handle); 748 749 750 /******************************************************************************* 751 ** 752 ** Function GATTS_AddCharacteristic 753 ** 754 ** Description This function is called to add a characteristic into a service. 755 ** It will add a characteristic declaration and characteristic 756 ** value declaration into the service database identified by the 757 ** service handle. 758 ** 759 ** Parameter service_handle : To which service this included service is added to. 760 ** char_uuid : Characteristic UUID. 761 ** perm : Characteristic value declaration attribute permission. 762 ** property : Characteristic Properties 763 ** 764 ** Returns Characteristic value declaration attribute handle. 0 if add 765 ** characteristic failed. 766 ** 767 *******************************************************************************/ 768 GATT_API extern UINT16 GATTS_AddCharacteristic (UINT16 service_handle, tBT_UUID *char_uuid, 769 tGATT_PERM perm,tGATT_CHAR_PROP property); 770 771 /******************************************************************************* 772 ** 773 ** Function GATTS_AddCharDescriptor 774 ** 775 ** Description This function is called to add a characteristic descriptor 776 ** into a service database. Add descriptor should follow add char 777 ** to which it belongs, and next add char should be done only 778 ** after all add descriptors for the previous char. 779 ** 780 ** Parameter service_handle : To which service this characteristic descriptor 781 ** is added to. 782 ** perm : Characteristic value declaration attribute 783 ** permission. 784 ** p_descr_uuid : Characteristic descriptor UUID. 785 ** 786 ** Returns Characteristic descriptor attribute handle. 0 if add 787 ** characteristic descriptor failed. 788 ** 789 *******************************************************************************/ 790 GATT_API extern UINT16 GATTS_AddCharDescriptor (UINT16 service_handle, tGATT_PERM perm, 791 tBT_UUID * p_descr_uuid); 792 793 /******************************************************************************* 794 ** 795 ** Function GATTS_DeleteService 796 ** 797 ** Description This function is called to delete a service. 798 ** 799 ** Parameter gatt_if : application interface 800 ** p_svc_uuid : service UUID 801 ** svc_inst : instance of the service inside the application 802 ** 803 ** Returns TRUE if operation succeed, FALSE if handle block was not found. 804 ** 805 *******************************************************************************/ 806 GATT_API extern BOOLEAN GATTS_DeleteService (tGATT_IF gatt_if, tBT_UUID *p_svc_uuid, UINT16 svc_inst); 807 808 /******************************************************************************* 809 ** 810 ** Function GATTS_StartService 811 ** 812 ** Description This function is called to start a service with GATT 813 ** 814 ** Parameter gatt_if : service handle. 815 ** p_cback : application service callback functions. 816 ** sup_transport : supported transport(s) for this primary service 817 ** 818 ** return GATT_SUCCESS if sucessfully started; otherwise error code. 819 ** 820 *******************************************************************************/ 821 GATT_API extern tGATT_STATUS GATTS_StartService (tGATT_IF gatt_if, UINT16 service_handle, 822 tGATT_TRANSPORT sup_transport); 823 824 825 /******************************************************************************* 826 ** 827 ** Function GATTS_StopService 828 ** 829 ** Description This function is called to stop a service 830 ** 831 ** Parameter service_handle : this is the start handle of a service 832 ** 833 ** Returns None. 834 ** 835 *******************************************************************************/ 836 GATT_API extern void GATTS_StopService (UINT16 service_handle); 837 838 839 /******************************************************************************* 840 ** 841 ** Function GATTs_HandleValueIndication 842 ** 843 ** Description This function sends a handle value indication to a client. 844 ** 845 ** Parameter conn_id: connection identifier. 846 ** attr_handle: Attribute handle of this handle value indication. 847 ** val_len: Length of the indicated attribute value. 848 ** p_val: Pointer to the indicated attribute value data. 849 ** 850 ** Returns GATT_SUCCESS if sucessfully sent or queued; otherwise error code. 851 ** 852 *******************************************************************************/ 853 GATT_API extern tGATT_STATUS GATTS_HandleValueIndication (UINT16 conn_id, 854 UINT16 attr_handle, 855 UINT16 val_len, UINT8 *p_val); 856 857 /******************************************************************************* 858 ** 859 ** Function GATTS_HandleValueNotification 860 ** 861 ** Description This function sends a handle value notification to a client. 862 ** 863 ** Parameter conn_id: connection identifier. 864 ** attr_handle: Attribute handle of this handle value indication. 865 ** val_len: Length of the indicated attribute value. 866 ** p_val: Pointer to the indicated attribute value data. 867 ** 868 ** Returns GATT_SUCCESS if sucessfully sent; otherwise error code. 869 ** 870 *******************************************************************************/ 871 GATT_API extern tGATT_STATUS GATTS_HandleValueNotification (UINT16 conn_id, UINT16 attr_handle, 872 UINT16 val_len, UINT8 *p_val); 873 874 875 /******************************************************************************* 876 ** 877 ** Function GATTS_SendRsp 878 ** 879 ** Description This function sends the server response to client. 880 ** 881 ** Parameter conn_id: connection identifier. 882 ** trans_id: transaction id 883 ** status: response status 884 ** p_msg: pointer to message parameters structure. 885 ** 886 ** Returns GATT_SUCCESS if sucessfully sent; otherwise error code. 887 ** 888 *******************************************************************************/ 889 GATT_API extern tGATT_STATUS GATTS_SendRsp (UINT16 conn_id, UINT32 trans_id, 890 tGATT_STATUS status, tGATTS_RSP *p_msg); 891 892 893 /*******************************************************************************/ 894 /* GATT Profile Client Functions */ 895 /*******************************************************************************/ 896 897 /******************************************************************************* 898 ** 899 ** Function GATTC_ConfigureMTU 900 ** 901 ** Description This function is called to configure the ATT MTU size for 902 ** a connection on an LE transport. 903 ** 904 ** Parameters conn_id: connection identifier. 905 ** mtu - attribute MTU size.. 906 ** 907 ** Returns GATT_SUCCESS if command started successfully. 908 ** 909 *******************************************************************************/ 910 GATT_API extern tGATT_STATUS GATTC_ConfigureMTU (UINT16 conn_id, UINT16 mtu); 911 912 /******************************************************************************* 913 ** 914 ** Function GATTC_Discover 915 ** 916 ** Description This function is called to do a discovery procedure on ATT server. 917 ** 918 ** Parameters conn_id: connection identifier. 919 ** disc_type:discovery type. 920 ** p_param: parameters of discovery requirement. 921 ** 922 ** Returns GATT_SUCCESS if command received/sent successfully. 923 ** 924 *******************************************************************************/ 925 GATT_API extern tGATT_STATUS GATTC_Discover (UINT16 conn_id, 926 tGATT_DISC_TYPE disc_type, 927 tGATT_DISC_PARAM *p_param ); 928 /******************************************************************************* 929 ** 930 ** Function GATTC_Read 931 ** 932 ** Description This function is called to read the value of an attribute from 933 ** the server. 934 ** 935 ** Parameters conn_id: connection identifier. 936 ** type - attribute read type. 937 ** p_read - read operation parameters. 938 ** 939 ** Returns GATT_SUCCESS if command started successfully. 940 ** 941 *******************************************************************************/ 942 GATT_API extern tGATT_STATUS GATTC_Read (UINT16 conn_id, tGATT_READ_TYPE type, 943 tGATT_READ_PARAM *p_read); 944 945 /******************************************************************************* 946 ** 947 ** Function GATTC_Write 948 ** 949 ** Description This function is called to read the value of an attribute from 950 ** the server. 951 ** 952 ** Parameters conn_id: connection identifier. 953 ** type - attribute write type. 954 ** p_write - write operation parameters. 955 ** 956 ** Returns GATT_SUCCESS if command started successfully. 957 ** 958 *******************************************************************************/ 959 GATT_API extern tGATT_STATUS GATTC_Write (UINT16 conn_id, tGATT_WRITE_TYPE type, 960 tGATT_VALUE *p_write); 961 962 963 /******************************************************************************* 964 ** 965 ** Function GATTC_ExecuteWrite 966 ** 967 ** Description This function is called to send an Execute write request to 968 ** the server. 969 ** 970 ** Parameters conn_id: connection identifier. 971 ** is_execute - to execute or cancel the prepare write requet(s) 972 ** 973 ** Returns GATT_SUCCESS if command started successfully. 974 ** 975 *******************************************************************************/ 976 GATT_API extern tGATT_STATUS GATTC_ExecuteWrite (UINT16 conn_id, BOOLEAN is_execute); 977 978 /******************************************************************************* 979 ** 980 ** Function GATTC_SendHandleValueConfirm 981 ** 982 ** Description This function is called to send a handle value confirmation 983 ** as response to a handle value notification from server. 984 ** 985 ** Parameters conn_id: connection identifier. 986 ** handle: the handle of the attribute confirmation. 987 ** 988 ** Returns GATT_SUCCESS if command started successfully. 989 ** 990 *******************************************************************************/ 991 GATT_API extern tGATT_STATUS GATTC_SendHandleValueConfirm (UINT16 conn_id, UINT16 handle); 992 993 994 /******************************************************************************* 995 ** 996 ** Function GATT_SetIdleTimeout 997 ** 998 ** Description This function (common to both client and server) sets the idle 999 ** timeout for a tansport connection 1000 ** 1001 ** Parameter bd_addr: target device bd address. 1002 ** idle_tout: timeout value in seconds. 1003 ** 1004 ** Returns void 1005 ** 1006 *******************************************************************************/ 1007 GATT_API extern void GATT_SetIdleTimeout (BD_ADDR bd_addr, UINT16 idle_tout); 1008 1009 1010 /******************************************************************************* 1011 ** 1012 ** Function GATT_Register 1013 ** 1014 ** Description This function is called to register an application 1015 ** with GATT 1016 ** 1017 ** Parameter p_app_uuid128: Application UUID 1018 ** p_cb_info: callback functions. 1019 ** 1020 ** Returns 0 for error, otherwise the index of the client registered with GATT 1021 ** 1022 *******************************************************************************/ 1023 GATT_API extern tGATT_IF GATT_Register (tBT_UUID *p_app_uuid128, tGATT_CBACK *p_cb_info); 1024 1025 /******************************************************************************* 1026 ** 1027 ** Function GATT_Deregister 1028 ** 1029 ** Description This function deregistered the application from GATT. 1030 ** 1031 ** Parameters gatt_if: applicaiton interface. 1032 ** 1033 ** Returns None. 1034 ** 1035 *******************************************************************************/ 1036 GATT_API extern void GATT_Deregister (tGATT_IF gatt_if); 1037 1038 /******************************************************************************* 1039 ** 1040 ** Function GATT_StartIf 1041 ** 1042 ** Description This function is called after registration to start receiving 1043 ** callbacks for registered interface. Function may call back 1044 ** with connection status and queued notifications 1045 ** 1046 ** Parameter gatt_if: applicaiton interface. 1047 ** 1048 ** Returns None 1049 ** 1050 *******************************************************************************/ 1051 GATT_API extern void GATT_StartIf (tGATT_IF gatt_if); 1052 1053 /******************************************************************************* 1054 ** 1055 ** Function GATT_Connect 1056 ** 1057 ** Description This function initiate a connecttion to a remote device on GATT 1058 ** channel. 1059 ** 1060 ** Parameters gatt_if: applicaiton interface 1061 ** bd_addr: peer device address. 1062 ** is_direct: is a direct conenection or a background auto connection 1063 ** 1064 ** Returns TRUE if connection started; FALSE if connection start failure. 1065 ** 1066 *******************************************************************************/ 1067 GATT_API extern BOOLEAN GATT_Connect (tGATT_IF gatt_if, BD_ADDR bd_addr, BOOLEAN is_direct); 1068 1069 1070 /******************************************************************************* 1071 ** 1072 ** Function GATT_CancelConnect 1073 ** 1074 ** Description This function terminate the connection initaition to a remote 1075 ** device on GATT channel. 1076 ** 1077 ** Parameters gatt_if: client interface. If 0 used as unconditionally disconnect, 1078 ** typically used for direct connection cancellation. 1079 ** bd_addr: peer device address. 1080 ** is_direct: is a direct conenection or a background auto connection 1081 ** 1082 ** Returns TRUE if connection started; FALSE if connection start failure. 1083 ** 1084 *******************************************************************************/ 1085 GATT_API extern BOOLEAN GATT_CancelConnect (tGATT_IF gatt_if, BD_ADDR bd_addr, BOOLEAN is_direct); 1086 1087 /******************************************************************************* 1088 ** 1089 ** Function GATT_Disconnect 1090 ** 1091 ** Description This function disconnect the GATT channel for this registered 1092 ** application. 1093 ** 1094 ** Parameters conn_id: connection identifier. 1095 ** 1096 ** Returns GATT_SUCCESS if disconnected. 1097 ** 1098 *******************************************************************************/ 1099 GATT_API extern tGATT_STATUS GATT_Disconnect (UINT16 conn_id); 1100 1101 1102 1103 /******************************************************************************* 1104 ** 1105 ** Function GATT_GetConnectionInfor 1106 ** 1107 ** Description This function use conn_id to find its associated BD address and applciation 1108 ** interface 1109 ** 1110 ** Parameters conn_id: connection id (input) 1111 ** p_gatt_if: applicaiton interface (output) 1112 ** bd_addr: peer device address. (output) 1113 ** 1114 ** Returns TRUE the ligical link information is found for conn_id 1115 ** 1116 *******************************************************************************/ 1117 GATT_API extern BOOLEAN GATT_GetConnectionInfor(UINT16 conn_id, tGATT_IF *p_gatt_if, BD_ADDR bd_addr); 1118 1119 1120 /******************************************************************************* 1121 ** 1122 ** Function GATT_GetConnIdIfConnected 1123 ** 1124 ** Description This function find the conn_id if the logical link for BD address 1125 ** and applciation interface is connected 1126 ** 1127 ** Parameters gatt_if: applicaiton interface (input) 1128 ** bd_addr: peer device address. (input) 1129 ** p_conn_id: connection id (output) 1130 ** 1131 ** Returns TRUE the ligical link is connected 1132 ** 1133 *******************************************************************************/ 1134 GATT_API extern BOOLEAN GATT_GetConnIdIfConnected(tGATT_IF gatt_if, BD_ADDR bd_addr, UINT16 *p_conn_id); 1135 1136 1137 /******************************************************************************* 1138 ** 1139 ** Function GATT_Listen 1140 ** 1141 ** Description This function start or stop LE advertisement and listen for 1142 ** connection. 1143 ** 1144 ** Parameters gatt_if: applicaiton interface 1145 ** p_bd_addr: listen for specific address connection, or NULL for 1146 ** listen to all device connection. 1147 ** start: is a direct conenection or a background auto connection 1148 ** 1149 ** Returns TRUE if advertisement is started; FALSE if adv start failure. 1150 ** 1151 *******************************************************************************/ 1152 GATT_API extern BOOLEAN GATT_Listen (tGATT_IF gatt_if, BOOLEAN start, BD_ADDR_PTR bd_addr); 1153 1154 1155 #ifdef __cplusplus 1156 1157 } 1158 #endif 1159 1160 #endif /* GATT_API_H */ 1161
