1 /* 2 * Copyright (C) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Bluetooth 18 * @{ 19 * 20 * @brief Provides basic Bluetooth capabilities. 21 * 22 * This module allows you to enable and disable Bluetooth, and access basic Bluetooth capabilities.\n 23 * Bluetooth uses profiles such as BT-GAP, BLE, BLE-GATT, BT-data transmission, HFP, A2DP, AVRCP, MAP, and PBAP. 24 * 25 * @since 6 26 */ 27 28 /** 29 * @file ohos_bt_gatt_server.h 30 * 31 * @brief Declares basic data structures and functions of the GATT server. 32 * 33 * @since 6 34 */ 35 36 #ifndef OHOS_BT_GATT_SERVER_H 37 #define OHOS_BT_GATT_SERVER_H 38 39 #include "ohos_bt_def.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 /** 45 * @brief Enumerates security encryption types. 46 * 47 * @since 6 48 */ 49 typedef enum { 50 /** No encryption */ 51 OHOS_BLE_SEC_NONE = 0x00, 52 /** Encryption */ 53 OHOS_BLE_SEC_ENCRYPT, 54 /** Encryption without MITM */ 55 OHOS_BLE_SEC_ENCRYPT_NO_MITM, 56 /** Encryption with MITM */ 57 OHOS_BLE_SEC_ENCRYPT_MITM 58 } BleSecAct; 59 60 /** 61 * @brief Defines the parameters in the response to a read or write request from the client. 62 * 63 * @since 6 64 */ 65 typedef struct { 66 /** Connection ID */ 67 int connectId; 68 /** Read/write status, as enumerated in {@link GattStatus} */ 69 int status; 70 /** Attribute handle ID */ 71 int attrHandle; // attrHandle is used as requestId now 72 /** Length of the response data */ 73 int valueLen; 74 /** Response data */ 75 char *value; 76 } GattsSendRspParam; 77 78 /** 79 * @brief Defines the parameters in the indication or notification sent to the client when a characteristic change 80 * occurs on the GATT server. 81 * 82 * @since 6 83 */ 84 typedef struct { 85 /** Connection ID */ 86 int connectId; 87 /** Attribute handle ID */ 88 int attrHandle; 89 /** 90 * Whether to send an indication or notification. Value <b>1</b> means to send an indication that requires 91 * a response from the client, and <b>0</b> means to send a notification. 92 */ 93 int confirm; 94 /** Length of the data to be sent */ 95 int valueLen; 96 /** Data to be sent */ 97 char *value; 98 } GattsSendIndParam; 99 100 /** 101 * @brief Defines the parameters in the callback that is invoked 102 * when the GATT server receives a read request from the client. 103 * 104 * @since 6 105 */ 106 typedef struct { 107 /** Connection ID */ 108 int connId; 109 /** Transport ID, as enumerated in {@link BtTransportId} */ 110 int transId; 111 /** Device address */ 112 BdAddr *bdAddr; 113 /** Handle ID of the attribute to be read */ 114 int attrHandle; 115 /** 116 * Offset to the first byte, from where the data reading starts. 117 * If data is to be read from the beginning, the value is <b>0</b>. 118 */ 119 int offset; 120 /** Whether the read request is a long read. Value <b>true</b> indicates a long read. */ 121 bool isLong; 122 } BtReqReadCbPara; 123 124 /** 125 * @brief Defines the parameters in the callback that is invoked when the GATT server 126 * receives a write request from the client. 127 * 128 * @since 6 129 */ 130 typedef struct { 131 /** Connection ID */ 132 int connId; 133 /** Transport ID, as enumerated in {@link BtTransportId} */ 134 int transId; 135 /** Device address */ 136 BdAddr *bdAddr; 137 /** Handle ID of the attribute to be written */ 138 int attrHandle; 139 /** 140 * Offset to the first byte, from where the data writing starts. 141 * If data is to be written from the beginning, the value is <b>0</b>. 142 */ 143 int offset; 144 /** Length of the data to be written */ 145 int length; 146 /** 147 * Whether the GATT server needs to send a response to the client. 148 * Value <b>true</b> indicates that a response to the client is required, 149 * and <b>false</b> indicates the opposite. 150 */ 151 bool needRsp; 152 /** 153 * Whether a prepare write is required. 154 * Value <b>true</b> indicates that it is required, and <b>false</b> indicates the opposite. 155 */ 156 bool isPrep; 157 /** Data to be written */ 158 unsigned char *value; 159 } BtReqWriteCbPara; 160 161 /** 162 * @brief Called when a GATT server is registered via {@link BleGattsRegister}. 163 * 164 * @since 6 165 */ 166 typedef void (*RegisterServerCallback)(int status, int serverId, BtUuid *appUuid); 167 168 /** 169 * @brief Called when the GATT server is connected to the client. 170 * 171 * @since 6 172 */ 173 typedef void (*ConnectServerCallback)(int connId, int serverId, const BdAddr *bdAddr); 174 175 /** 176 * @brief Called when the GATT server is disconnected from the client. 177 * 178 * @since 6 179 */ 180 typedef void (*DisconnectServerCallback)(int connId, int serverId, const BdAddr *bdAddr); 181 182 /** 183 * @brief Called when a service is added via {@link BleGattsAddService}. 184 * 185 * @since 6 186 */ 187 typedef void (*ServiceAddCallback)(int status, int serverId, BtUuid *uuid, int srvcHandle); 188 189 /** 190 * @brief Called when an included service is added to a service via {@link BleGattsAddIncludedService}. 191 * 192 * @since 6 193 */ 194 typedef void (*IncludeServiceAddCallback)(int status, int serverId, int srvcHandle, int includeSrvcHandle); 195 196 /** 197 * @brief Called when a characteristic is added to a service via {@link BleGattsAddCharacteristic}. 198 * 199 * @since 6 200 */ 201 typedef void (*CharacteristicAddCallback)(int status, int serverId, BtUuid *uuid, 202 int srvcHandle, int characteristicHandle); 203 204 /** 205 * @brief Called when a descriptor is added to a characteristic via {@link BleGattsAddDescriptor}. 206 * 207 * @since 6 208 */ 209 typedef void (*DescriptorAddCallback)(int status, int serverId, BtUuid *uuid, 210 int srvcHandle, int descriptorHandle); 211 212 /** 213 * @brief Called when a service is started via {@link BleGattsStartService}. 214 * 215 * @since 6 216 */ 217 typedef void (*ServiceStartCallback)(int status, int serverId, int srvcHandle); 218 219 /** 220 * @brief Called when a service is stopped via {@link BleGattsStopService}. 221 * 222 * @since 6 223 */ 224 typedef void (*ServiceStopCallback)(int status, int serverId, int srvcHandle); 225 226 /** 227 * @brief Called when a service is deleted via {@link BleGattsDeleteService}. 228 * 229 * @since 6 230 */ 231 typedef void (*ServiceDeleteCallback)(int status, int serverId, int srvcHandle); 232 233 /** 234 * @brief Called when the GATT server receives a read request from the client. 235 * 236 * You need to call {@link BleGattsSendResponse} to send a response to the client. \n 237 * 238 * @since 6 239 */ 240 typedef void (*RequestReadCallback)(BtReqReadCbPara readCbPara); 241 242 /** 243 * @brief Called when the GATT server receives a write request from the client. 244 * 245 * You can determine whether to send a response to the client based on the <b>needRsp</b> parameter\n 246 * in {@link BtReqWriteCbPara}.\n 247 * If a response is needed, you can call {@link BleGattsSendResponse} to send a response to the client. 248 * 249 * @since 6 250 */ 251 typedef void (*RequestWriteCallback)(BtReqWriteCbPara writeCbPara); 252 253 /** 254 * @brief Called when the GATT server sends a response to the client via {@link BleGattsSendResponse}. 255 * 256 * @since 6 257 */ 258 typedef void (*ResponseConfirmationCallback)(int status, int handle); 259 260 /** 261 * @brief Called when the GATT server sends an indication or notification to the client 262 * via {@link BleGattsSendIndication}. 263 * 264 * Upon receiving an indication, the client returns a confirmation.\n 265 * When the GATT server receives the confirmation, this callback is invoked. 266 * 267 * Upon receiving a notification, the client does not respond. 268 * 269 * @since 6 270 */ 271 typedef void (*IndicationSentCallback)(int connId, int status); 272 273 /** 274 * @brief Called when the MTU changes. 275 * 276 * @since 6 277 */ 278 typedef void (*MtuChangeCallback)(int connId, int mtu); 279 280 /** 281 * @brief Defines callbacks for the GATT server. 282 * 283 * @since 6 284 */ 285 typedef struct { 286 /** Callback that is invoked when a GATT server is registered */ 287 RegisterServerCallback registerServerCb; 288 /** Callback that is invoked when the GATT server is connected to the client */ 289 ConnectServerCallback connectServerCb; 290 /** Callback that is invoked when the GATT server is disconnected from the client */ 291 DisconnectServerCallback disconnectServerCb; 292 /** Callback that is invoked when a service is added */ 293 ServiceAddCallback serviceAddCb; 294 /** Callback that is invoked when an included service is added */ 295 IncludeServiceAddCallback includeServiceAddCb; 296 /** Callback that is invoked when a characteristic is added */ 297 CharacteristicAddCallback characteristicAddCb; 298 /** Callback that is invoked when a descriptor is added */ 299 DescriptorAddCallback descriptorAddCb; 300 /** Callback that is invoked when a service is started */ 301 ServiceStartCallback serviceStartCb; 302 /** Callback that is invoked when a service is stopped */ 303 ServiceStopCallback serviceStopCb; 304 /** Callback that is invoked when a service is deleted */ 305 ServiceDeleteCallback serviceDeleteCb; 306 /** Callback that is invoked when the GATT server receives a read request from the client */ 307 RequestReadCallback requestReadCb; 308 /** Callback that is invoked when the GATT server receives a write request from the client */ 309 RequestWriteCallback requestWriteCb; 310 /** Callback that is invoked when the GATT server sends a response to the client */ 311 ResponseConfirmationCallback responseConfirmationCb; 312 /** Callback that is invoked when the GATT server sends an indication or notification to the client */ 313 IndicationSentCallback indicationSentCb; 314 /** Callback that is invoked when the MTU changes */ 315 MtuChangeCallback mtuChangeCb; 316 } BtGattServerCallbacks; 317 318 /** 319 * @brief Called when the GATT client requests to read data from the GATT server. 320 * 321 * This callback is available for system applications only. 322 * 323 * @since 6 324 */ 325 typedef int (*BleGattServiceRead)(unsigned char *buff, unsigned int *len); 326 327 /** 328 * @brief Called when the GATT client requests to write data to the GATT server. 329 * 330 * This callback is available for system applications only. 331 * 332 * @since 6 333 */ 334 typedef int (*BleGattServiceWrite)(unsigned char *buff, unsigned int len); 335 336 /** 337 * @brief Called when an indication or notification is sent to a service. 338 * 339 * This callback is available for system applications only. 340 * 341 * @since 6 342 */ 343 typedef int (*BleGattServiceIndicate)(unsigned char *buff, unsigned int len); 344 345 /** 346 * @brief Defines callbacks for the operations performed by the GATT client on the GATT server. 347 * 348 * This structure is available for system applications only. 349 * 350 * @since 6 351 */ 352 typedef struct { 353 /** Callback that is invoked when the GATT client requests to read data from the GATT server */ 354 BleGattServiceRead read; 355 /** Callback that is invoked when the GATT client requests to write data to the GATT server */ 356 BleGattServiceWrite write; 357 /** Callback that is invoked when an indication or notification is sent to a service */ 358 BleGattServiceIndicate indicate; 359 } BleGattOperateFunc; 360 361 /** 362 * @brief Defines a GATT attribute. 363 * 364 * This structure is available for system applications only. 365 * 366 * @since 6 367 */ 368 typedef struct { 369 /** Attribute type */ 370 BleAttribType attrType; 371 /** Operation permission. For details, see {@link GattAttributePermission}. */ 372 unsigned int permission; 373 /** UUID type */ 374 UuidType uuidType; 375 /** UUID */ 376 unsigned char uuid[OHOS_BLE_UUID_MAX_LEN]; 377 /** Data */ 378 unsigned char *value; 379 /** Data length */ 380 unsigned char valLen; 381 /** Property. For details, see {@link GattCharacteristicProperty}. */ 382 unsigned char properties; 383 /** Operation callback */ 384 BleGattOperateFunc func; 385 } BleGattAttr; 386 387 /** 388 * @brief Defines a GATT service. 389 * 390 * This structure is available for system applications only. 391 * 392 * @since 6 393 */ 394 typedef struct { 395 /** Number of attributes */ 396 unsigned int attrNum; 397 /** Attribute list */ 398 BleGattAttr *attrList; 399 } BleGattService; 400 401 /** 402 * @brief Registers a GATT server with a specified application UUID. 403 * 404 * The <b>RegisterServerCallback</b> is invoked to return the GATT server ID. 405 * 406 * @param appUuid Indicates the UUID of the application for which the GATT server is to be registered. 407 * The UUID is defined by the application. 408 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT server is registered; 409 * returns an error code defined in {@link BtStatus} otherwise. 410 * @since 6 411 */ 412 int BleGattsRegister(BtUuid appUuid); 413 414 /** 415 * @brief Unregisters a GATT server with a specified ID. 416 * 417 * @param serverId Indicates the ID of the GATT server. 418 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT server is unregistered; 419 * returns an error code defined in {@link BtStatus} otherwise. 420 * @since 6 421 */ 422 int BleGattsUnRegister(int serverId); 423 424 /** 425 * @brief GATT server connect the client. 426 * 427 * @param serverId Indicates the ID of the GATT server. 428 * @param bdAddr Indicates the address of the client. 429 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT server is disconnected from the client; 430 * returns an error code defined in {@link BtStatus} otherwise. 431 * @since 6 432 */ 433 int BleGattsConnect(int serverId, BdAddr bdAddr); 434 435 /** 436 * @brief Disconnects the GATT server from the client. 437 * 438 * @param serverId Indicates the ID of the GATT server. 439 * @param bdAddr Indicates the address of the client. 440 * @param connId Indicates the connection ID, which is returned during the server registration. 441 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT server is disconnected from the client; 442 * returns an error code defined in {@link BtStatus} otherwise. 443 * @since 6 444 */ 445 int BleGattsDisconnect(int serverId, BdAddr bdAddr, int connId); 446 447 /** 448 * @brief Adds a service. 449 * 450 * This function adds the service, its characteristics, and descriptors separately in sequence.\n 451 * A service is a collection of data and related behavior that enable a specific capability or feature.\n 452 * It consists of a service declaration and one or more included services and characteristics. 453 * 454 * @param serverId Indicates the ID of the GATT server. 455 * @param srvcUuid Indicates the UUID of the service. 456 * @param isPrimary Specifies whether the service is primary or secondary. 457 * Value <b>true</b> indicates that the service is primary, and <b>false</b> indicates that the service is secondary. 458 * @param number Indicates the number of attribute handles. 459 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is added; 460 * returns an error code defined in {@link BtStatus} otherwise. 461 * @since 6 462 */ 463 int BleGattsAddService(int serverId, BtUuid srvcUuid, bool isPrimary, int number); 464 465 /** 466 * @brief Adds an included service to a specified service. 467 * 468 * An included service is referenced to define another service on the GATT server. 469 * 470 * @param serverId Indicates the ID of the GATT server. 471 * @param srvcHandle Indicates the handle ID of the service. 472 * @param includedHandle Indicates the attribute handle ID of the included service. 473 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the included service is added to the service; 474 * returns an error code defined in {@link BtStatus} otherwise. 475 * @since 6 476 */ 477 int BleGattsAddIncludedService(int serverId, int srvcHandle, int includedHandle); 478 479 /** 480 * @brief Adds a characteristic to a specified service. 481 * 482 * A characteristic consists of data, the data access method, data format, and how the data manifests itself. 483 * 484 * @param serverId Indicates the ID of the GATT server. 485 * @param srvcHandle Indicates the handle ID of the service. 486 * @param characUuid Indicates the UUID of the characteristic to add. 487 * @param properties Indicates the access methods supported by the characteristic, 488 * as enumerated in {@link GattCharacteristicProperty}. 489 * @param permissions Indicates the access permissions supported by the characteristic, 490 * as enumerated in {@link GattAttributePermission}. 491 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the characteristic is added to the service; 492 * returns an error code defined in {@link BtStatus} otherwise. 493 * @since 6 494 */ 495 int BleGattsAddCharacteristic(int serverId, int srvcHandle, BtUuid characUuid, 496 int properties, int permissions); 497 498 /** 499 * @brief Adds a descriptor to a specified characteristic. 500 * 501 * A descriptor contains the description, configuration, and format of a characteristic. 502 * 503 * @param serverId Indicates the ID of the GATT server. 504 * @param srvcHandle Indicates the handle ID of the service to which the characteristic belongs. 505 * @param descUuid Indicates the UUID of the descriptor to add. 506 * @param permissions Indicates the access permissions supported by the descriptor, 507 * as enumerated in {@link GattAttributePermission}. 508 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the descriptor is added to the characteristic; 509 * returns an error code defined in {@link BtStatus} otherwise. 510 * @since 6 511 */ 512 int BleGattsAddDescriptor(int serverId, int srvcHandle, BtUuid descUuid, int permissions); 513 514 /** 515 * @brief Starts a service. 516 * 517 * @param serverId Indicates the ID of the GATT server. 518 * @param srvcHandle Indicates the handle ID of the service. 519 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is started; 520 * returns an error code defined in {@link BtStatus} otherwise. 521 * @since 6 522 */ 523 int BleGattsStartService(int serverId, int srvcHandle); 524 525 /** 526 * @brief Stops a service. 527 * 528 * @param serverId Indicates the ID of the GATT server. 529 * @param srvcHandle Indicates the handle ID of the service. 530 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is stopped; 531 * returns an error code defined in {@link BtStatus} otherwise. 532 * @since 6 533 */ 534 int BleGattsStopService(int serverId, int srvcHandle); 535 536 /** 537 * @brief Deletes a service. 538 * 539 * @param serverId Indicates the ID of the GATT server. 540 * @param srvcHandle Indicates the handle ID of the service. 541 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is deleted; 542 * returns an error code defined in {@link BtStatus} otherwise. 543 * @since 6 544 */ 545 int BleGattsDeleteService(int serverId, int srvcHandle); 546 547 /** 548 * @brief Clears all services. 549 * 550 * @param serverId Indicates the ID of the GATT server. 551 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the services are cleared; 552 * returns an error code defined in {@link BtStatus} otherwise. 553 * @since 6 554 */ 555 int BleGattsClearServices(int serverId); 556 557 /** 558 * @brief Sends a response to the client from which a read or write request has been received. 559 * 560 * @param serverId Indicates the ID of the GATT server. 561 * @param param Indicates the pointer to the response parameters. For details, see {@link GattsSendRspParam}. 562 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the response is sent; 563 * returns an error code defined in {@link BtStatus} otherwise. 564 * @since 6 565 */ 566 int BleGattsSendResponse(int serverId, GattsSendRspParam *param); 567 568 /** 569 * @brief Sends an indication or notification to the client. 570 * 571 * The <b>confirm</b> field in <b>param</b> determines whether to send an indication or a notification. 572 * 573 * @param serverId Indicates the ID of the GATT server. 574 * @param param Indicates the pointer to the sending parameters. For details, see {@link GattsSendIndParam}. 575 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the indication or notification is sent; 576 * returns an error code defined in {@link BtStatus} otherwise. 577 * @since 6 578 */ 579 int BleGattsSendIndication(int serverId, GattsSendIndParam *param); 580 581 /** 582 * @brief Sets the encryption type for the GATT connection. 583 * 584 * @param bdAddr Indicates the address of the client. 585 * @param secAct Indicates the encryption type, as enumerated in {@link BleSecAct}. 586 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the encryption type is set; 587 * returns an error code defined in {@link BtStatus} otherwise. 588 * @since 6 589 */ 590 int BleGattsSetEncryption(BdAddr bdAddr, BleSecAct secAct); 591 592 /** 593 * @brief Registers GATT server callbacks. 594 * 595 * @param func Indicates the pointer to the callbacks to register, as enumerated in {@link BtGattServerCallbacks}. 596 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the callbacks are registered; 597 * returns an error code defined in {@link BtStatus} otherwise. 598 * @since 6 599 */ 600 int BleGattsRegisterCallbacks(BtGattServerCallbacks *func); 601 602 /** 603 * @brief Adds a service, its characteristics, and descriptors and starts the service. 604 * 605 * This function is available for system applications only. 606 * 607 * @param srvcHandle Indicates the pointer to the handle ID of the service, 608 * which is returned by whoever implements this function. 609 * @param srvcInfo Indicates the pointer to the service information. 610 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 611 * returns an error code defined in {@link BtStatus} otherwise. 612 * @since 6 613 */ 614 int BleGattsStartServiceEx(int *srvcHandle, BleGattService *srvcInfo); 615 616 /** 617 * @brief Stops a service. 618 * 619 * This function is available for system applications only. 620 * 621 * @param srvcHandle Indicates the handle ID of the service. 622 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 623 * returns an error code defined in {@link BtStatus} otherwise. 624 * @since 6 625 */ 626 int BleGattsStopServiceEx(int srvcHandle); 627 628 #ifdef __cplusplus 629 } 630 #endif 631 #endif 632 /** @} */