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