gatt_api.h revision 5738f83aeb59361a0a2eda2460113f6dc9194271
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 66typedef 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 */ 110typedef 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 */ 162typedef 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) 194typedef UINT8 tGATT_CHAR_PROP; 195 196 197/* Format of the value of a characteristic. enumeration type 198*/ 199enum 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}; 231typedef UINT8 tGATT_FORMAT; 232 233/* Characteristic Presentation Format Descriptor value 234*/ 235typedef 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 245typedef 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 256typedef 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 273typedef 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 280typedef 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 294typedef UINT8 tGATT_AUTH_REQ; 295 296/* Attribute Value structure 297*/ 298typedef 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*/ 310typedef 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 */ 320enum 321{ 322 GATT_TRANSPORT_LE, 323 GATT_TRANSPORT_BR_EDR, 324 GATT_TRANSPORT_LE_BR_EDR 325}; 326typedef UINT8 tGATT_TRANSPORT; 327 328#define GATT_PREP_WRITE_CANCEL 0x00 329#define GATT_PREP_WRITE_EXEC 0x01 330typedef UINT8 tGATT_EXEC_FLAG; 331 332/* read request always based on UUID */ 333typedef struct 334{ 335 UINT16 handle; 336 UINT16 offset; 337 BOOLEAN is_long; 338} tGATT_READ_REQ; 339 340/* write request data */ 341typedef 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 */ 352typedef 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 364typedef UINT8 tGATT_SERV_IF; /* GATT Service Interface */ 365 366enum 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}; 374typedef UINT8 tGATTS_REQ_TYPE; 375 376 377 378/* Client Used Data Structure 379*/ 380/* definition of different discovery types */ 381enum 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}; 390typedef UINT8 tGATT_DISC_TYPE; 391 392/* Discover parameters of different discovery types 393*/ 394typedef 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*/ 403enum 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}; 412typedef UINT8 tGATT_READ_TYPE; 413 414/* Read By Type Request (GATT_READ_BY_TYPE) Data 415*/ 416typedef 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 */ 427typedef 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 */ 435typedef struct 436{ 437 tGATT_AUTH_REQ auth_req; 438 UINT16 handle; 439} tGATT_READ_BY_HANDLE; 440 441/* READ_BT_HANDLE_Request data */ 442typedef struct 443{ 444 tGATT_AUTH_REQ auth_req; 445 UINT16 handle; 446 UINT16 offset; 447} tGATT_READ_PARTIAL; 448 449/* Read Request Data 450*/ 451typedef 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 */ 461enum 462{ 463 GATT_WRITE_NO_RSP = 1, 464 GATT_WRITE , 465 GATT_WRITE_PREPARE 466}; 467typedef UINT8 tGATT_WRITE_TYPE; 468 469/* Client Operation Complete Callback Data 470*/ 471typedef 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 488typedef UINT8 tGATTC_OPTYPE; 489 490/* characteristic declaration 491*/ 492typedef 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*/ 501typedef 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*/ 510typedef 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 517typedef 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*/ 536typedef struct 537{ 538 tBT_UUID type; 539 UINT16 handle; 540 tGATT_DISC_VALUE value; 541} tGATT_DISC_RES; 542 543 544typedef 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 */ 552typedef void (tGATT_DISC_RES_CB) (UINT16 conn_id, tGATT_DISC_TYPE disc_type, tGATT_DISC_RES *p_data); 553 554/* discover complete callback function */ 555typedef 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. */ 558typedef 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. */ 561typedef 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 */ 564typedef 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*/ 573typedef 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 586typedef 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 603typedef UINT8 tGATTS_SRV_CHG_CMD; 604 605typedef struct 606{ 607 BD_ADDR bda; 608 BOOLEAN srv_changed; 609} tGATTS_SRV_CHG; 610 611 612typedef 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 618typedef union 619{ 620 tGATTS_SRV_CHG srv_chg; 621 UINT8 num_clients; 622} tGATTS_SRV_CHG_RSP; 623 624 625 626typedef 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*/ 633typedef void (tGATTS_NV_SAVE_CBACK)(BOOLEAN is_saved, tGATTS_HNDL_RANGE *p_hndl_range); 634typedef BOOLEAN (tGATTS_NV_SRV_CHG_CBACK)(tGATTS_SRV_CHG_CMD cmd, tGATTS_SRV_CHG_REQ *p_req, tGATTS_SRV_CHG_RSP *p_rsp); 635 636typedef 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 649extern "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