1 /* 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 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. * Description: BTS GATT SERVER module. 14 */ 15 16 /** 17 * @defgroup bluetooth_bts_gatt_server BTS GATT SERVER API 18 * @ingroup bluetooth 19 * @{ 20 */ 21 22 #ifndef BTS_GATT_SERVER_H 23 #define BTS_GATT_SERVER_H 24 25 #include <stdbool.h> 26 #include <stdint.h> 27 #include "errcode.h" 28 #include "bts_def.h" 29 #include "bts_gatt_stru.h" 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * @if Eng 37 * @brief Struct of add characteristic information. 38 * @else 39 * @brief 添加特征信息。 40 * @endif 41 */ 42 typedef struct { 43 bt_uuid_t chara_uuid; /*!< @if Eng UUID of GATT characteristic. 44 @else GATT 特征 UUID。 @endif */ 45 uint8_t permissions; /*!< @if Eng Characteristic permissions, { @ref gatt_attribute_permission_t }. 46 @else 特征权限， { @ref gatt_attribute_permission_t }。 @endif */ 47 uint8_t properties; /*!< @if Eng Characteristic properties, { @ref gatt_characteristic_property_t }. 48 @else 特征特性， { @ref gatt_characteristic_property_t } 。 @endif */ 49 uint16_t value_len; /*!< @if Eng Length of reponse data. 50 @else 响应的数据长度。 @endif */ 51 uint8_t *value; /*!< @if Eng Reponse data. 52 @else 响应的数据。 @endif */ 53 } gatts_add_chara_info_t; 54 55 /** 56 * @if Eng 57 * @brief Struct of add characteristic descriptor information. 58 * @else 59 * @brief 添加特征描述符信息。 60 * @endif 61 */ 62 typedef struct { 63 bt_uuid_t desc_uuid; /*!< @if Eng UUID of GATT descriptor. 64 @else GATT 描述符 UUID。 @endif */ 65 uint8_t permissions; /*!< @if Eng Descriptor permissions, { @ref gatt_attribute_permission_t }. 66 @else 特征权限， { @ref gatt_attribute_permission_t }。 @endif */ 67 uint16_t value_len; /*!< @if Eng Length of reponse data. 68 @else 响应的数据长度。 @endif */ 69 uint8_t *value; /*!< @if Eng Reponse data. 70 @else 响应的数据。 @endif */ 71 } gatts_add_desc_info_t; 72 73 /** 74 * @if Eng 75 * @brief Struct of read request information. 76 * @else 77 * @brief 读请求信息。 78 * @endif 79 */ 80 typedef struct { 81 uint16_t request_id; /*!< @if Eng Request id. 82 @else 请求id。 @endif */ 83 uint16_t handle; /*!< @if Eng Attribute handle of the read request. 84 @else 请求读的属性句柄。 @endif */ 85 uint16_t offset; /*!< @if Eng Offset of the read request in bytes. 86 @else 请求读的字节偏移。 @endif */ 87 bool need_rsp; /*!< @if Eng Whether response is needed. 88 @else 是否需要发送响应。 @endif */ 89 bool need_authorize; /*!< @if Eng Whether authorization is needed. 90 @else 是否需要授权。 @endif */ 91 bool is_long; /*!< @if Eng Whether request is Long Read. 92 @else 请求是否是读长特征。 @endif */ 93 } gatts_req_read_cb_t; 94 95 /** 96 * @if Eng 97 * @brief Struct of write request information. 98 * @else 99 * @brief 写请求信息。 100 * @endif 101 */ 102 typedef struct { 103 uint16_t request_id; /*!< @if Eng Request id. 104 @else 请求id。 @endif */ 105 uint16_t handle; /*!< @if Eng Attribute handle of the write request. 106 @else 请求写的属性句柄。 @endif */ 107 uint16_t offset; /*!< @if Eng Offset of the write request in bytes. 108 @else 请求写的字节偏移。 @endif */ 109 bool need_rsp; /*!< @if Eng Whether response is needed. 110 @else 是否需要发送响应。 @endif */ 111 bool need_authorize; /*!< @if Eng Whether authorization is needed. 112 @else 是否需要授权。 @endif */ 113 bool is_prep; /*!< @if Eng Whether request is Prepare Write. 114 @else 请求是否是准备写。 @endif */ 115 uint16_t length; /*!< @if Eng Length of write request data. 116 @else 请求写的数据长度。 @endif */ 117 uint8_t *value; /*!< @if Eng Write request data. 118 @else 请求写的数据。 @endif */ 119 } gatts_req_write_cb_t; 120 121 /** 122 * @if Eng 123 * @brief Struct of send response information. 124 * @else 125 * @brief 发送响应信息。 126 * @endif 127 */ 128 typedef struct { 129 uint16_t request_id; /*!< @if Eng Request ID. 130 @else 请求 ID。 @endif */ 131 uint8_t status; /*!< @if Eng Status code of read/write, { @ref gatt_status_t }. 132 @else 读写结果的状态， { @ref gatt_status_t }。 @endif */ 133 uint16_t offset; /*!< @if Eng Offset. 134 @else 属偏移。 @endif */ 135 uint16_t value_len; /*!< @if Eng Length of reponse data. 136 @else 响应的数据长度。 @endif */ 137 uint8_t *value; /*!< @if Eng Reponse data. 138 @else 响应的数据。 @endif */ 139 } gatts_send_rsp_t; 140 141 /** 142 * @if Eng 143 * @brief Struct of send notification/indication information. 144 * @else 145 * @brief 发送通知/指示信息。 146 * @endif 147 */ 148 typedef struct { 149 uint16_t attr_handle; /*!< @if Eng Attribute handle. 150 @else 属性句柄。 @endif */ 151 uint16_t value_len; /*!< @if Eng Length of notification/indication data. 152 @else 通知/指示数据长度。 @endif */ 153 uint8_t *value; /*!< @if Eng Notification/indication data. 154 @else 发送的通知/指示数据。 @endif */ 155 } gatts_ntf_ind_t; 156 157 /** 158 * @if Eng 159 * @brief Struct of send notification/indication by uuid information. 160 * @else 161 * @brief 通过uuid发送通知/指示信息。 162 * @endif 163 */ 164 typedef struct { 165 bt_uuid_t chara_uuid; /*!< @if Eng Characteristic UUID. 166 @else 特征UUID。 @endif */ 167 uint16_t start_handle; /*!< @if Eng start handle. 168 @else 起始句柄。 @endif */ 169 uint16_t end_handle; /*!< @if Eng end handle. 170 @else 结束句柄。 @endif */ 171 uint16_t value_len; /*!< @if Eng Length of notification/indication data. 172 @else 通知/指示数据长度。 @endif */ 173 uint8_t *value; /*!< @if Eng Notification/indication data. 174 @else 发送的通知/指示数据。 @endif */ 175 } gatts_ntf_ind_by_uuid_t; 176 177 /** 178 * @if Eng 179 * @brief Struct of add character callback. 180 * @else 181 * @brief 添加特征回调信息。 182 * @endif 183 */ 184 typedef struct { 185 uint16_t handle; /*!< @if Eng decl handle. 186 @else 特征句柄。 @endif */ 187 uint16_t value_handle; /*!< @if Eng value handle. 188 @else 特征值句柄。 @endif */ 189 } gatts_add_character_result_t; 190 191 /** 192 * @if Eng 193 * @brief Callback invoked when service add. 194 * @par Callback invoked when service add. 195 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 196 * @attention 2. The memories of devices are requested and freed by the bts automatically. 197 * @param [in] server_id server ID. 198 * @param [in] uuid service uuid. 199 * @param [in] handle service attribute handle. 200 * @param [in] status error code. 201 * @par Dependency: 202 * @li bts_def.h 203 * @see gap_ble_callbacks_t 204 * @else 205 * @brief 服务注册的回调函数。 206 * @par 服务注册的回调函数。 207 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 208 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 209 * @param [in] server_id 服务端 ID。 210 * @param [in] uuid 服务uuid。 211 * @param [in] handle 服务属性句柄。 212 * @param [in] status 执行结果错误码。 213 * @par 依赖: 214 * @li bts_def.h 215 * @see gap_ble_callbacks_t 216 * @endif 217 */ 218 typedef void (*gatts_add_service_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t handle, errcode_t status); 219 220 /** 221 * @if Eng 222 * @brief Callback invoked when characteristic add. 223 * @par Callback invoked when characteristic add. 224 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 225 * @attention 2. The memories of devices are requested and freed by the bts automatically. 226 * @param [in] server_id server ID. 227 * @param [in] uuid characteristic uuid. 228 * @param [in] service_handle service attribute handle. 229 * @param [in] handle character attribute handle. 230 * @param [in] status error code. 231 * @par Dependency: 232 * @li bts_def.h 233 * @see gap_ble_callbacks_t 234 * @else 235 * @brief 特征注册的回调函数。 236 * @par 特征注册的回调函数。 237 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 238 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 239 * @param [in] server_id 服务端 ID。 240 * @param [in] uuid 特征 uuid。 241 * @param [in] service_handle 服务属性句柄。 242 * @param [in] handle 特征属性句柄。 243 * @param [in] status 执行结果错误码。 244 * @par 依赖: 245 * @li bts_def.h 246 * @see gap_ble_callbacks_t 247 * @endif 248 */ 249 typedef void (*gatts_add_characteristic_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t service_handle, 250 gatts_add_character_result_t *result, errcode_t status); 251 252 /** 253 * @if Eng 254 * @brief Callback invoked when characteristic descriptor add. 255 * @par Callback invoked when characteristic descriptor add. 256 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 257 * @attention 2. The memories of devices are requested and freed by the bts automatically. 258 * @param [in] server_id server ID. 259 * @param [in] uuid characteristic uuid. 260 * @param [in] service_handle service attribute handle. 261 * @param [in] handle character descriptor attribute handle. 262 * @param [in] status error code. 263 * @par Dependency: 264 * @li bts_def.h 265 * @see gap_ble_callbacks_t 266 * @else 267 * @brief 特征描述符注册的回调函数。 268 * @par 特征描述符注册的回调函数。 269 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 270 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 271 * @param [in] server_id 服务端 ID。 272 * @param [in] uuid 特征 uuid。 273 * @param [in] service_handle 服务属性句柄。 274 * @param [in] handle 特征描述符属性句柄。 275 * @param [in] status 执行结果错误码。 276 * @par 依赖: 277 * @li bts_def.h 278 * @see gap_ble_callbacks_t 279 * @endif 280 */ 281 typedef void (*gatts_add_descriptor_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t service_handle, 282 uint16_t handle, errcode_t status); 283 284 /** 285 * @if Eng 286 * @brief Callback invoked when service started. 287 * @par Callback invoked when service started. 288 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 289 * @attention 2. The memories of devices are requested and freed by the bts automatically. 290 * @param [in] server_id server ID. 291 * @param [in] handle service attribute handle. 292 * @param [in] status error code. 293 * @par Dependency: 294 * @li bts_def.h 295 * @see gap_ble_callbacks_t 296 * @else 297 * @brief 开始服务的回调函数。 298 * @par 开始服务的回调函数。 299 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 300 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 301 * @param [in] server_id 服务端 ID。 302 * @param [in] handle 服务属性句柄。 303 * @param [in] status 执行结果错误码。 304 * @par 依赖: 305 * @li bts_def.h 306 * @see gap_ble_callbacks_t 307 * @endif 308 */ 309 typedef void (*gatts_start_service_callback)(uint8_t server_id, uint16_t handle, errcode_t status); 310 311 /** 312 * @if Eng 313 * @brief Callback invoked when service stoped. 314 * @par Callback invoked when service stoped. 315 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 316 * @attention 2. The memories of devices are requested and freed by the bts automatically. 317 * @param [in] server_id server ID. 318 * @param [in] handle service attribute handle. 319 * @param [in] status error code. 320 * @par Dependency: 321 * @li bts_def.h 322 * @see gap_ble_callbacks_t 323 * @else 324 * @brief 停止服务的回调函数。 325 * @par 停止服务的回调函数。 326 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 327 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 328 * @param [in] server_id 服务端 ID。 329 * @param [in] handle 服务属性句柄。 330 * @param [in] status 执行结果错误码。 331 * @par 依赖: 332 * @li bts_def.h 333 * @see gap_ble_callbacks_t 334 * @endif 335 */ 336 typedef void (*gatts_stop_service_callback)(uint8_t server_id, uint16_t handle, errcode_t status); 337 338 /** 339 * @if Eng 340 * @brief Callback invoked when service deleted. 341 * @par Callback invoked when service deleted. 342 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 343 * @attention 2. The memories of devices are requested and freed by the bts automatically. 344 * @param [in] server_id server ID. 345 * @param [in] handle service attribute handle. 346 * @param [in] status error code. 347 * @par Dependency: 348 * @li bts_def.h 349 * @see gap_ble_callbacks_t 350 * @else 351 * @brief 删除服务的回调函数。 352 * @par 删除服务的回调函数。 353 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 354 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 355 * @param [in] server_id 服务端 ID。 356 * @param [in] handle 服务属性句柄。 357 * @param [in] status 执行结果错误码。 358 * @par 依赖: 359 * @li bts_def.h 360 * @see gap_ble_callbacks_t 361 * @endif 362 */ 363 typedef void (*gatts_delete_service_callback)(uint8_t server_id, errcode_t status); 364 365 /** 366 * @if Eng 367 * @brief Callback invoked when receive read request. 368 * @par Callback invoked when receive read request. 369 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 370 * @attention 2. The memories of devices are requested and freed by the bts automatically. 371 * @param [in] server_id server ID. 372 * @param [in] conn_id connection ID. 373 * @param [in] read_cb_para read request parameter. 374 * @param [in] status error code. 375 * @par Dependency: 376 * @li bts_def.h 377 * @see gap_ble_callbacks_t 378 * @else 379 * @brief 收到读请求的回调函数。 380 * @par 收到读请求的回调函数。 381 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 382 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 383 * @param [in] server_id 服务端 ID。 384 * @param [in] conn_id 连接 ID。 385 * @param [in] read_cb_para 读请求参数。 386 * @param [in] status 执行结果错误码。 387 * @par 依赖: 388 * @li bts_def.h 389 * @see gap_ble_callbacks_t 390 * @endif 391 */ 392 typedef void (*gatts_read_request_callback)(uint8_t server_id, uint16_t conn_id, gatts_req_read_cb_t *read_cb_para, 393 errcode_t status); 394 395 /** 396 * @if Eng 397 * @brief Callback invoked when receive write request. 398 * @par Callback invoked when receive write request. 399 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 400 * @attention 2. The memories of devices are requested and freed by the bts automatically. 401 * @param [in] server_id server ID. 402 * @param [in] conn_id connection ID. 403 * @param [in] write_cb_para write request parameter. 404 * @param [in] status error code. 405 * @par Dependency: 406 * @li bts_def.h 407 * @see gap_ble_callbacks_t 408 * @else 409 * @brief 收到写请求的回调函数。 410 * @par 收到写请求的回调函数。 411 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 412 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 413 * @param [in] server_id 服务端 ID。 414 * @param [in] conn_id 连接 ID。 415 * @param [in] write_cb_para 写请求参数。 416 * @param [in] status 执行结果错误码。 417 * @par 依赖: 418 * @li bts_def.h 419 * @see gap_ble_callbacks_t 420 * @endif 421 */ 422 typedef void (*gatts_write_request_callback)(uint8_t server_id, uint16_t conn_id, gatts_req_write_cb_t *write_cb_para, 423 errcode_t status); 424 425 /** 426 * @if Eng 427 * @brief Callback invoked when mtu size changed. 428 * @par Callback invoked when mtu size changed. 429 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 430 * @attention 2. The memories of devices are requested and freed by the bts automatically. 431 * @param [in] server_id server ID. 432 * @param [in] conn_id connection ID. 433 * @param [in] mtu_size mtu size. 434 * @param [in] status error code. 435 * @par Dependency: 436 * @li bts_def.h 437 * @see gap_ble_callbacks_t 438 * @else 439 * @brief mtu大小改变的回调函数。 440 * @par mtu大小改变的回调函数。 441 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 442 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 443 * @param [in] server_id 服务端 ID。 444 * @param [in] conn_id 连接 ID。 445 * @param [in] mtu_size mtu 大小。 446 * @param [in] status 执行结果错误码。 447 * @par 依赖: 448 * @li bts_def.h 449 * @see gap_ble_callbacks_t 450 * @endif 451 */ 452 typedef void (*gatts_mtu_changed_callback)(uint8_t server_id, uint16_t conn_id, uint16_t mtu_size, errcode_t status); 453 454 /** 455 * @if Eng 456 * @brief Struct of GATT server callback function. 457 * @else 458 * @brief GATT server回调函数接口定义。 459 * @endif 460 */ 461 typedef struct { 462 gatts_add_service_callback add_service_cb; /*!< @if Eng Service added callback. 463 @else 添加服务回调函数。 @endif */ 464 gatts_add_characteristic_callback add_characteristic_cb; /*!< @if Eng Characteristc added callback. 465 @else 添加特征回调函数。 @endif */ 466 gatts_add_descriptor_callback add_descriptor_cb; /*!< @if Eng Descriptor added callback. 467 @else 添加描述符回调函数。 @endif */ 468 gatts_start_service_callback start_service_cb; /*!< @if Eng Service started callback. 469 @else 启动服务回调函数。 @endif */ 470 gatts_stop_service_callback stop_service_cb; /*!< @if Eng Service stoped callback. 471 @else 停止服务回调函数。 @endif */ 472 gatts_delete_service_callback delete_service_cb; /*!< @if Eng All service deleted callback. 473 @else 删除所有服务回调函数。 @endif */ 474 gatts_read_request_callback read_request_cb; /*!< @if Eng Read request received callback. 475 @else 收到远端读请求回调函数。 @endif */ 476 gatts_write_request_callback write_request_cb; /*!< @if Eng Write request received callback. 477 @else 收到远端写请求回调函数。 @endif */ 478 gatts_mtu_changed_callback mtu_changed_cb; /*!< @if Eng Mtu changed callback. 479 @else mtu 大小更新回调函数。 @endif */ 480 } gatts_callbacks_t; 481 482 /** 483 * @if Eng 484 * @brief Register gatt server. 485 * @par Description: Register gatt server. 486 * @param [in] app_uuid App uuid. 487 * @param [out] server_id Server ID. 488 * @retval ERRCODE_SUCC Success. 489 * @retval Other Failure. For details, see @ref errcode_t 490 * @par Depends: 491 * @li bts_def.h 492 * @else 493 * @brief 注册gatt服务端。 494 * @par Description: 注册gatt服务端。 495 * @param [in] app_uuid 上层应用uuid。 496 * @param [out] server_id 服务端ID。 497 * @retval ERRCODE_SUCC 成功。 498 * @retval Other 失败。参考 @ref errcode_t 499 * @par 依赖： 500 * @li bts_def.h 501 * @endif 502 */ 503 errcode_t gatts_register_server(bt_uuid_t *app_uuid, uint8_t *server_id); 504 505 /** 506 * @if Eng 507 * @brief Unregister gatt server. 508 * @par Description: Unregister gatt server. 509 * @param [in] server_id Server ID. 510 * @retval ERRCODE_SUCC Success. 511 * @retval Other Failure. For details, see @ref errcode_t 512 * @par Depends: 513 * @li bts_def.h 514 * @else 515 * @brief 注销gatt服务端。 516 * @par Description: 注销gatt服务端。 517 * @param [in] server_id 服务端ID。 518 * @retval ERRCODE_SUCC 成功。 519 * @retval Other 失败。参考 @ref errcode_t 520 * @par 依赖： 521 * @li bts_def.h 522 * @endif 523 */ 524 errcode_t gatts_unregister_server(uint8_t server_id); 525 526 /** 527 * @if Eng 528 * @brief Add a gatt service. 529 * @par Description: Add a gatt service. 530 * @param [in] server_id Server ID. 531 * @param [in] service_uuid Service uuid. 532 * @param [in] is_primary is primary service or not. 533 * @retval error code, the service handle will be returned in { @ref gatts_add_service_callback }. 534 * @par Depends: 535 * @li bts_def.h 536 * @else 537 * @brief 添加一个gatt服务。 538 * @par Description: 添加一个gatt服务。 539 * @param [in] server_id 服务端 ID。 540 * @param [in] service_uuid 服务uuid。 541 * @param [in] is_primary 是否是首要服务。 542 * @retval 执行结果错误码，服务句柄将在 { @ref gatts_add_service_callback }中返回。 543 * @par 依赖： 544 * @li bts_def.h 545 * @endif 546 */ 547 errcode_t gatts_add_service(uint8_t server_id, bt_uuid_t *service_uuid, bool is_primary); 548 549 /** 550 * @if Eng 551 * @brief Add a gatt characteristic. 552 * @par Description: Add a gatt characteristic. 553 * @param [in] server_id Server ID. 554 * @param [in] service_handle Service handle. 555 * @param [in] character Characteristic. 556 * @retval error code, the character handle will be returned in { @ref gatts_add_characteristic_callback }. 557 * @par Depends: 558 * @li bts_def.h 559 * @else 560 * @brief 添加一个gatt特征。 561 * @par Description: 添加一个gatt特征。 562 * @param [in] server_id 服务端 ID。 563 * @param [in] service_handle 服务句柄。 564 * @param [in] character GATT 特征。 565 * @retval 执行结果错误码，特征句柄将在 { @ref gatts_add_characteristic_callback } 中返回。 566 * @par 依赖： 567 * @li bts_def.h 568 * @endif 569 */ 570 errcode_t gatts_add_characteristic(uint8_t server_id, uint16_t service_handle, gatts_add_chara_info_t *character); 571 572 /** 573 * @if Eng 574 * @brief Add a gatt characteristic descriptor. 575 * @par Description: Add a gatt characteristic descriptor. 576 * @param [in] server_id Server ID. 577 * @param [in] service_handle Service handle. 578 * @param [in] descriptor Characteristic descriptor. 579 * @retval error code, the descriptor handle will be returned in { @ref gatts_add_descriptor_callback }. 580 * @par Depends: 581 * @li bts_def.h 582 * @else 583 * @brief 添加一个gatt特征描述符。 584 * @par Description: 添加一个gatt特征描述符。 585 * @param [in] server_id 服务端 ID。 586 * @param [in] service_handle 服务句柄。 587 * @param [in] descriptor GATT 特征描述符。 588 * @retval 执行结果错误码，特征句柄将在 { @ref gatts_add_descriptor_callback } 中返回。 589 * @par 依赖： 590 * @li bts_def.h 591 * @endif 592 */ 593 errcode_t gatts_add_descriptor(uint8_t server_id, uint16_t service_handle, gatts_add_desc_info_t *descriptor); 594 595 /** 596 * @if Eng 597 * @brief Add a gatt service. 598 * @par Description: Add a gatt service. 599 * @param [in] server_id Server ID. 600 * @param [in] service_uuid Service uuid. 601 * @param [in] is_primary is primary service or not. 602 * @param [out] handle service handle. 603 * @retval ERRCODE_SUCC Success. 604 * @retval Other Failure. For details, see @ref errcode_t 605 * @par Depends: 606 * @li bts_def.h 607 * @else 608 * @brief 添加一个gatt服务。 609 * @par Description: 添加一个gatt服务。 610 * @param [in] server_id 服务端 ID。 611 * @param [in] service_uuid 服务uuid。 612 * @param [in] is_primary 是否是首要服务。 613 * @param [out] handle 服务句柄。 614 * @retval ERRCODE_SUCC 成功。 615 * @retval Other 失败。参考 @ref errcode_t 616 * @par 依赖： 617 * @li bts_def.h 618 * @endif 619 */ 620 errcode_t gatts_add_service_sync(uint8_t server_id, bt_uuid_t *service_uuid, bool is_primary, uint16_t *handle); 621 622 /** 623 * @if Eng 624 * @brief Add a gatt characteristic. 625 * @par Description: Add a gatt characteristic. 626 * @param [in] server_id Server ID. 627 * @param [in] service_handle Service handle. 628 * @param [in] character Characteristic. 629 * @param [out] result Characteristic handle. 630 * @retval ERRCODE_SUCC Success. 631 * @retval Other Failure. For details, see @ref errcode_t 632 * @par Depends: 633 * @li bts_def.h 634 * @else 635 * @brief 添加一个gatt特征。 636 * @par Description: 添加一个gatt特征。 637 * @param [in] server_id 服务端 ID。 638 * @param [in] service_handle 服务句柄。 639 * @param [in] character GATT 特征。 640 * @param [out] result 特征句柄。 641 * @retval ERRCODE_SUCC 成功。 642 * @retval Other 失败。参考 @ref errcode_t 643 * @par 依赖： 644 * @li bts_def.h 645 * @endif 646 */ 647 errcode_t gatts_add_characteristic_sync(uint8_t server_id, uint16_t service_handle, gatts_add_chara_info_t *character, 648 gatts_add_character_result_t *result); 649 650 /** 651 * @if Eng 652 * @brief Add a gatt characteristic descriptor. 653 * @par Description: Add a gatt characteristic descriptor. 654 * @param [in] server_id Server ID. 655 * @param [in] service_handle Service handle. 656 * @param [in] descriptor Characteristic descriptor. 657 * @param [out] handle Characteristic descriptor handle. 658 * @retval ERRCODE_SUCC Success. 659 * @retval Other Failure. For details, see @ref errcode_t 660 * @par Depends: 661 * @li bts_def.h 662 * @else 663 * @brief 添加一个gatt特征描述符。 664 * @par Description: 添加一个gatt特征描述符。 665 * @param [in] server_id 服务端 ID。 666 * @param [in] service_handle 服务句柄。 667 * @param [in] descriptor 特征描述符。 668 * @param [out] handle 特征描述符句柄。 669 * @retval ERRCODE_SUCC 成功。 670 * @retval Other 失败。参考 @ref errcode_t 671 * @par 依赖： 672 * @li bts_def.h 673 * @endif 674 */ 675 errcode_t gatts_add_descriptor_sync(uint8_t server_id, uint16_t service_handle, gatts_add_desc_info_t *descriptor, 676 uint16_t *handle); 677 678 /** 679 * @if Eng 680 * @brief Start a GATT service. 681 * @par Description: Start a GATT service. 682 * @param [in] server_id server ID. 683 * @param [in] service_handle service handle. 684 * @retval error code, the service start result will be returned at { @ref gatts_start_service_callback }. 685 * @par Depends: 686 * @li bts_def.h 687 * @else 688 * @brief 开始一个GATT服务。 689 * @par Description: 开始一个GATT服务。 690 * @param [in] server_id 服务端 ID。 691 * @param [in] service_handle 服务句柄。 692 * @retval 执行结果错误码，服务开启结果将在 { @ref gatts_start_service_callback } 中返回。 693 * @par 依赖： 694 * @li bts_def.h 695 * @endif 696 */ 697 errcode_t gatts_start_service(uint8_t server_id, uint16_t service_handle); 698 699 /** 700 * @if Eng 701 * @brief Stop a GATT service. 702 * @par Description: Stop a GATT service. 703 * @param [in] server_id server ID. 704 * @param [in] service_handle service handle. 705 * @retval error code, the service stop result will be returned at { @ref gatts_stop_service_callback }. 706 * @par Depends: 707 * @li bts_def.h 708 * @else 709 * @brief 停止一个GATT服务。 710 * @par Description: 停止一个GATT服务。 711 * @param [in] server_id 服务端 ID。 712 * @param [in] service_handle 服务句柄。 713 * @retval 执行结果错误码，服务停止结果将在 { @ref gatts_stop_service_callback } 中返回。 714 * @par 依赖： 715 * @li bts_def.h 716 * @endif 717 */ 718 errcode_t gatts_stop_service(uint8_t server_id, uint16_t service_handle); 719 720 /** 721 * @if Eng 722 * @brief Delete a GATT service. 723 * @par Description: Delete a GATT service. 724 * @param [in] server_id server ID. 725 * @param [in] service_handle service handle. 726 * @retval error code, the service delete result will be returned at { @ref gatts_delete_service_callback }. 727 * @par Depends: 728 * @li bts_def.h 729 * @else 730 * @brief 删除一个GATT服务。 731 * @par Description: 删除一个GATT服务。 732 * @param [in] server_id 服务端 ID。 733 * @param [in] service_handle 服务句柄。 734 * @retval 执行结果错误码，服务删除结果将在 { @ref gatts_delete_service_callback } 中返回。 735 * @par 依赖： 736 * @li bts_def.h 737 * @endif 738 */ 739 errcode_t gatts_delete_service(uint8_t server_id, uint16_t service_handle); 740 741 /** 742 * @if Eng 743 * @brief Delete all GATT service. 744 * @par Description: Delete all GATT service. 745 * @param [in] server_id server ID. 746 * @retval error code, the service delete result will be returned at { @ref gatts_delete_service_callback }. 747 * @par Depends: 748 * @li bts_def.h 749 * @else 750 * @brief 删除所有GATT服务。 751 * @par Description: 删除所有GATT服务。 752 * @param [in] server_id 服务端 ID。 753 * @retval 执行结果错误码，服务删除结果将在 { @ref gatts_delete_service_callback } 中返回。 754 * @par 依赖： 755 * @li bts_def.h 756 * @endif 757 */ 758 errcode_t gatts_delete_all_services(uint8_t server_id); 759 760 /** 761 * @if Eng 762 * @brief Send response when receive the request need to response by user. 763 * @par Description: Send response when receive the request need to response by user 764 { @ref gatts_read_request_callback } { @ref gatts_write_request_callback }. 765 * @param [in] server_id server ID. 766 * @param [in] conn_id connection ID. 767 * @param [in] param response parameter. 768 * @retval ERRCODE_SUCC Success. 769 * @retval Other Failure. For details, see @ref errcode_t 770 * @par Depends: 771 * @li bts_def.h 772 * @else 773 * @brief 当收到需要用户回复响应的请求时发送响应。 774 * @par Description: 当收到需要用户回复响应的请求时发送响应 775 { @ref gatts_read_request_callback } { @ref gatts_write_request_callback }。 776 * @param [in] server_id 服务端 ID. 777 * @param [in] conn_id 连接ID。 778 * @param [in] param 响应参数. 779 * @retval ERRCODE_SUCC 成功。 780 * @retval Other 失败。参考 @ref errcode_t 781 * @par 依赖： 782 * @li bts_def.h 783 * @endif 784 */ 785 errcode_t gatts_send_response(uint8_t server_id, uint16_t conn_id, gatts_send_rsp_t *param); 786 787 /** 788 * @if Eng 789 * @brief Send indication or notification to remote device. 790 * @par Description: Send indication or notification to remote device, 791 send status depend on character descriptor: client characteristic configuration. 792 * @param [in] server_id server ID. 793 * @param [in] conn_id connection ID. 794 * @param [in] param notify/indicate parameter. 795 * @retval ERRCODE_SUCC Success. 796 * @retval Other Failure. For details, see @ref errcode_t 797 * @par Depends: 798 * @li bts_def.h 799 * @else 800 * @brief 向对端发送通知或指示。 801 * @par Description: 向对端发送通知或指示，具体发送状态取决于特征描述符：客户端特征配置。 802 * @param [in] server_id 服务端 ID。 803 * @param [in] conn_id 连接ID。 804 * @param [in] param 通知或指示参数。 805 * @retval ERRCODE_SUCC 成功。 806 * @retval Other 失败。参考 @ref errcode_t 807 * @par 依赖： 808 * @li bts_def.h 809 * @endif 810 */ 811 errcode_t gatts_notify_indicate(uint8_t server_id, uint16_t conn_id, gatts_ntf_ind_t *param); 812 813 /** 814 * @if Eng 815 * @brief Send indication or notification to remote device by uuid. 816 * @par Description: Send indication or notification to remote device by uuid, 817 send status depend on client characteristic configuration descriptor value, 818 value = 0x0000: notification and indication not allowed, 819 value = 0x0001: notification allowed, 820 value = 0x0002: indication allowed. 821 * @param [in] server_id server ID. 822 * @param [in] conn_id connection ID. 823 * @param [in] param notify/indicate parameter. 824 * @retval ERRCODE_SUCC Success. 825 * @retval Other Failure. For details, see @ref errcode_t 826 * @par Depends: 827 * @li bts_def.h 828 * @else 829 * @brief 向对端发送通知或指示。 830 * @par Description: 通过uuid向对端发送通知或指示，具体发送状态取决于客户端特征配置描述符值， 831 value = 0x0000：不允许通知和指示， 832 value = 0x0001：允许通知， 833 value = 0x0002：允许指示。 834 * @param [in] server_id 服务端 ID。 835 * @param [in] conn_id 连接ID。 836 * @param [in] param 通知或指示参数。 837 * @retval ERRCODE_SUCC 成功。 838 * @retval Other 失败。参考 @ref errcode_t 839 * @par 依赖： 840 * @li bts_def.h 841 * @endif 842 */ 843 errcode_t gatts_notify_indicate_by_uuid(uint8_t server_id, uint16_t conn_id, gatts_ntf_ind_by_uuid_t *param); 844 845 /** 846 * @if Eng 847 * @brief Set server rx mtu before connected. 848 * @par Description: Set server rx mtu before connected. 849 * @param [in] server_id server ID. 850 * @param [in] mtu_size server rx mtu size. 851 * @retval ERRCODE_SUCC Success. 852 * @retval Other Failure. For details, see @ref errcode_t 853 * @par Depends: 854 * @li bts_def.h 855 * @else 856 * @brief 在连接之前设置服务端接收mtu。 857 * @par Description: 在连接之前设置服务端接收mtu。 858 * @param [in] server_id 服务端ID。 859 * @param [in] mtu_size 服务端接收mtu。 860 * @retval ERRCODE_SUCC 成功。 861 * @retval Other 失败。参考 @ref errcode_t 862 * @par 依赖： 863 * @li bts_def.h 864 * @endif 865 */ 866 errcode_t gatts_set_mtu_size(uint8_t server_id, uint16_t mtu_size); 867 868 /** 869 * @if Eng 870 * @brief Register callbacks. 871 * @par Description: Register callbacks. 872 * @param [in] func callback function. 873 * @retval ERRCODE_SUCC Success. 874 * @retval Other Failure. For details, see @ref errcode_t 875 876 * @par Depends: 877 * @li bts_def.h 878 * @else 879 * @brief 注册回调函数。 880 * @par Description: 注册回调函数。 881 * @param [in] func 回调函数 882 * @retval ERRCODE_SUCC 成功。 883 * @retval Other 失败。参考 @ref errcode_t 884 * @par 依赖： 885 * @li bts_def.h 886 * @endif 887 */ 888 errcode_t gatts_register_callbacks(gatts_callbacks_t *func); 889 890 891 /** 892 * @} 893 */ 894 895 #ifdef __cplusplus 896 } 897 #endif 898 #endif 899 900