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 Disconnects the GATT server from the client. 426 * 427 * @param serverId Indicates the ID of the GATT server. 428 * @param bdAddr Indicates the address of the client. 429 * @param connId Indicates the connection ID, which is returned during the server registration. 430 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the GATT server is disconnected from the client; 431 * returns an error code defined in {@link BtStatus} otherwise. 432 * @since 6 433 */ 434 int BleGattsDisconnect(int serverId, BdAddr bdAddr, int connId); 435 436 /** 437 * @brief Adds a service. 438 * 439 * This function adds the service, its characteristics, and descriptors separately in sequence.\n 440 * A service is a collection of data and related behavior that enable a specific capability or feature.\n 441 * It consists of a service declaration and one or more included services and characteristics. 442 * 443 * @param serverId Indicates the ID of the GATT server. 444 * @param srvcUuid Indicates the UUID of the service. 445 * @param isPrimary Specifies whether the service is primary or secondary. 446 * Value <b>true</b> indicates that the service is primary, and <b>false</b> indicates that the service is secondary. 447 * @param number Indicates the number of attribute handles. 448 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is added; 449 * returns an error code defined in {@link BtStatus} otherwise. 450 * @since 6 451 */ 452 int BleGattsAddService(int serverId, BtUuid srvcUuid, bool isPrimary, int number); 453 454 /** 455 * @brief Adds an included service to a specified service. 456 * 457 * An included service is referenced to define another service on the GATT server. 458 * 459 * @param serverId Indicates the ID of the GATT server. 460 * @param srvcHandle Indicates the handle ID of the service. 461 * @param includedHandle Indicates the attribute handle ID of the included service. 462 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the included service is added to the service; 463 * returns an error code defined in {@link BtStatus} otherwise. 464 * @since 6 465 */ 466 int BleGattsAddIncludedService(int serverId, int srvcHandle, int includedHandle); 467 468 /** 469 * @brief Adds a characteristic to a specified service. 470 * 471 * A characteristic consists of data, the data access method, data format, and how the data manifests itself. 472 * 473 * @param serverId Indicates the ID of the GATT server. 474 * @param srvcHandle Indicates the handle ID of the service. 475 * @param characUuid Indicates the UUID of the characteristic to add. 476 * @param properties Indicates the access methods supported by the characteristic, 477 * as enumerated in {@link GattCharacteristicProperty}. 478 * @param permissions Indicates the access permissions supported by the characteristic, 479 * as enumerated in {@link GattAttributePermission}. 480 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the characteristic is added to the service; 481 * returns an error code defined in {@link BtStatus} otherwise. 482 * @since 6 483 */ 484 int BleGattsAddCharacteristic(int serverId, int srvcHandle, BtUuid characUuid, 485 int properties, int permissions); 486 487 /** 488 * @brief Adds a descriptor to a specified characteristic. 489 * 490 * A descriptor contains the description, configuration, and format of a characteristic. 491 * 492 * @param serverId Indicates the ID of the GATT server. 493 * @param srvcHandle Indicates the handle ID of the service to which the characteristic belongs. 494 * @param descUuid Indicates the UUID of the descriptor to add. 495 * @param permissions Indicates the access permissions supported by the descriptor, 496 * as enumerated in {@link GattAttributePermission}. 497 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the descriptor is added to the characteristic; 498 * returns an error code defined in {@link BtStatus} otherwise. 499 * @since 6 500 */ 501 int BleGattsAddDescriptor(int serverId, int srvcHandle, BtUuid descUuid, int permissions); 502 503 /** 504 * @brief Starts a service. 505 * 506 * @param serverId Indicates the ID of the GATT server. 507 * @param srvcHandle Indicates the handle ID of the service. 508 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the service is started; 509 * returns an error code defined in {@link BtStatus} otherwise. 510 * @since 6 511 */ 512 int BleGattsStartService(int serverId, int srvcHandle); 513 514 /** 515 * @brief Stops 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 stopped; 520 * returns an error code defined in {@link BtStatus} otherwise. 521 * @since 6 522 */ 523 int BleGattsStopService(int serverId, int srvcHandle); 524 525 /** 526 * @brief Deletes 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 deleted; 531 * returns an error code defined in {@link BtStatus} otherwise. 532 * @since 6 533 */ 534 int BleGattsDeleteService(int serverId, int srvcHandle); 535 536 /** 537 * @brief Clears all services. 538 * 539 * @param serverId Indicates the ID of the GATT server. 540 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the services are cleared; 541 * returns an error code defined in {@link BtStatus} otherwise. 542 * @since 6 543 */ 544 int BleGattsClearServices(int serverId); 545 546 /** 547 * @brief Sends a response to the client from which a read or write request has been received. 548 * 549 * @param serverId Indicates the ID of the GATT server. 550 * @param param Indicates the pointer to the response parameters. For details, see {@link GattsSendRspParam}. 551 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the response is sent; 552 * returns an error code defined in {@link BtStatus} otherwise. 553 * @since 6 554 */ 555 int BleGattsSendResponse(int serverId, GattsSendRspParam *param); 556 557 /** 558 * @brief Sends an indication or notification to the client. 559 * 560 * The <b>confirm</b> field in <b>param</b> determines whether to send an indication or a notification. 561 * 562 * @param serverId Indicates the ID of the GATT server. 563 * @param param Indicates the pointer to the sending parameters. For details, see {@link GattsSendIndParam}. 564 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the indication or notification is sent; 565 * returns an error code defined in {@link BtStatus} otherwise. 566 * @since 6 567 */ 568 int BleGattsSendIndication(int serverId, GattsSendIndParam *param); 569 570 /** 571 * @brief Sets the encryption type for the GATT connection. 572 * 573 * @param bdAddr Indicates the address of the client. 574 * @param secAct Indicates the encryption type, as enumerated in {@link BleSecAct}. 575 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the encryption type is set; 576 * returns an error code defined in {@link BtStatus} otherwise. 577 * @since 6 578 */ 579 int BleGattsSetEncryption(BdAddr bdAddr, BleSecAct secAct); 580 581 /** 582 * @brief Registers GATT server callbacks. 583 * 584 * @param func Indicates the pointer to the callbacks to register, as enumerated in {@link BtGattServerCallbacks}. 585 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the callbacks are registered; 586 * returns an error code defined in {@link BtStatus} otherwise. 587 * @since 6 588 */ 589 int BleGattsRegisterCallbacks(BtGattServerCallbacks *func); 590 591 /** 592 * @brief Adds a service, its characteristics, and descriptors and starts the service. 593 * 594 * This function is available for system applications only. 595 * 596 * @param srvcHandle Indicates the pointer to the handle ID of the service, 597 * which is returned by whoever implements this function. 598 * @param srvcInfo Indicates the pointer to the service information. 599 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 600 * returns an error code defined in {@link BtStatus} otherwise. 601 * @since 6 602 */ 603 int BleGattsStartServiceEx(int *srvcHandle, BleGattService *srvcInfo); 604 605 /** 606 * @brief Stops a service. 607 * 608 * This function is available for system applications only. 609 * 610 * @param srvcHandle Indicates the handle ID of the service. 611 * @return Returns {@link OHOS_BT_STATUS_SUCCESS} if the operation is successful; 612 * returns an error code defined in {@link BtStatus} otherwise. 613 * @since 6 614 */ 615 int BleGattsStopServiceEx(int srvcHandle); 616 617 #ifdef __cplusplus 618 } 619 #endif 620 #endif 621 /** @} */