GATT Server#

GATT Server(Generic Attribute Profile)提供蓝牙低功耗(Bluetooth Low Energy)服务端的属性服务管理能力,支持服务、特征与描述符的注册与同步注册,服务的启动、停止、删除,以及对客户端读写请求的响应、通知(Notification)与指示(Indication)的发送,并通过回调机制向应用层上报服务注册、特征注册、读写请求、MTU(Maximum Transmission Unit)变化与指示确认等事件。

模块公共头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

接口清单#

接口名称

功能简述

gatts_register_server

注册 GATT 服务端,分配服务端 ID

gatts_unregister_server

注销 GATT 服务端

gatts_add_service

异步添加一个 GATT 服务

gatts_add_characteristic

异步添加一个 GATT 特征

gatts_add_descriptor

异步添加一个 GATT 特征描述符

gatts_add_service_sync

同步添加一个 GATT 服务,返回服务句柄

gatts_add_characteristic_sync

同步添加一个 GATT 特征,返回特征句柄

gatts_add_descriptor_sync

同步添加一个 GATT 特征描述符,返回描述符句柄

gatts_start_service

启动一个 GATT 服务

gatts_stop_service

停止一个 GATT 服务

gatts_delete_service

删除一个 GATT 服务

gatts_delete_all_services

删除指定服务端的全部 GATT 服务

gatts_send_response

对需要用户回复的读/写请求发送响应

gatts_notify_indicate

向对端发送通知或指示

gatts_notify_indicate_by_uuid

通过特征 UUID 向对端发送通知或指示

gatts_set_mtu_size

在连接前设置服务端接收 MTU 大小

gatts_register_callbacks

注册 GATT 服务端回调函数

gatts_exchange_mtu_req

发送交换 MTU 请求

Functions#

gatts_register_server #

errcode_t gatts_register_server(bt_uuid_t *app_uuid, uint8_t *server_id)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 注册一个 GATT 服务端,向上层应用分配唯一的服务端 ID。

  • 服务端 ID 是后续添加服务、特征、描述符及收发数据等操作的关键标识。

  • 成功注册后服务端进入可用状态,可继续调用服务/特征注册相关接口。

前置条件

  • 调用时序约束:调用本模块服务端相关接口前必须先调用本接口完成服务端注册。

入参

名称

参数类型

说明

约束取值范围

app_uuid

bt_uuid_t *

上层应用 UUID,用于标识当前应用

不为 NULL

出参

名称

数据类型

输出说明

server_id

uint8_t *

成功注册后分配的服务端 ID,由调用方分配内存、函数填充

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功注册

服务端注册成功

Other

其他错误码,参考 errcode_t

注册失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_unregister_server #

errcode_t gatts_unregister_server(uint8_t server_id)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 注销已注册的 GATT 服务端,释放对应服务端 ID 及其关联资源。

  • 注销后该服务端 ID 不再有效,禁止继续使用该 ID 进行后续操作。

  • 与 gatts_register_server 配对使用,用于服务端生命周期的收尾。

前置条件

  • 调用时序约束:必须在 gatts_register_server 成功返回后再调用本接口。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

已注册的服务端 ID

由 gatts_register_server 分配的有效 ID

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功注销

服务端注销成功

Other

其他错误码,参考 errcode_t

注销失败

gatts_add_service #

errcode_t gatts_add_service(uint8_t server_id, bt_uuid_t *service_uuid, bool is_primary)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 向指定服务端异步添加一个 GATT 服务。

  • 通过 is_primary 指定该服务为主服务或次服务。

  • 服务添加结果及服务句柄通过 gatts_add_service_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在 gatts_register_server 成功返回后调用,且需先通过 gatts_register_callbacks 注册服务添加回调以接收服务句柄。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_uuid

bt_uuid_t *

服务的 UUID

不为 NULL

is_primary

bool

是否为主服务

true;
false。

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

添加服务请求成功发起,服务句柄将在回调中返回

Other

其他错误码,参考 errcode_t

添加服务请求失败

gatts_add_characteristic #

errcode_t gatts_add_characteristic(uint8_t server_id, uint16_t service_handle, gatts_add_chara_info_t *character)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 向指定服务下异步添加一个 GATT 特征。

  • 特征信息包含特征 UUID、权限、特性、初始值等,由 gatts_add_chara_info_t 描述。

  • 特征添加结果及特征句柄通过 gatts_add_characteristic_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在对应服务添加完成(gatts_add_service 回调返回服务句柄)后调用,且需先注册特征添加回调以接收特征句柄。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

所属服务的属性句柄

gatts_add_service 回调返回的有效服务句柄

character

gatts_add_chara_info_t *

特征信息

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

添加特征请求成功发起,特征句柄将在回调中返回

Other

其他错误码,参考 errcode_t

添加特征请求失败

gatts_add_descriptor #

errcode_t gatts_add_descriptor(uint8_t server_id, uint16_t service_handle, gatts_add_desc_info_t *descriptor)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 向指定服务下异步添加一个 GATT 特征描述符。

  • 描述符信息包含描述符 UUID、权限、初始值等,由 gatts_add_desc_info_t 描述。

  • 描述符添加结果及描述符句柄通过 gatts_add_descriptor_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在对应服务添加完成后调用,且需先注册描述符添加回调以接收描述符句柄。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

所属服务的属性句柄

gatts_add_service 回调返回的有效服务句柄

descriptor

gatts_add_desc_info_t *

特征描述符信息

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

添加描述符请求成功发起,描述符句柄将在回调中返回

Other

其他错误码,参考 errcode_t

添加描述符请求失败

gatts_add_service_sync #

errcode_t gatts_add_service_sync(uint8_t server_id, bt_uuid_t *service_uuid, bool is_primary, uint16_t *handle)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 同步方式向指定服务端添加一个 GATT 服务。

  • 通过 is_primary 指定该服务为主服务或次服务。

  • 服务句柄通过出参 handle 同步返回,调用方可直接获取结果。

前置条件

  • 调用时序约束:必须在 gatts_register_server 成功返回后调用。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_uuid

bt_uuid_t *

服务的 UUID

不为 NULL

is_primary

bool

是否为主服务

true;
false。

出参

名称

数据类型

输出说明

handle

uint16_t *

添加成功后的服务属性句柄,由调用方分配内存、函数填充

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

添加成功

服务添加成功,服务句柄通过 handle 返回

Other

其他错误码,参考 errcode_t

添加服务失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_add_characteristic_sync #

errcode_t gatts_add_characteristic_sync(uint8_t server_id, uint16_t service_handle, gatts_add_chara_info_t *character, gatts_add_character_result_t *result)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 同步方式向指定服务下添加一个 GATT 特征。

  • 特征信息由 gatts_add_chara_info_t 描述,包含特征 UUID、权限、特性、初始值等。

  • 特征句柄信息通过出参 result 同步返回。

前置条件

  • 调用时序约束:必须在对应服务添加完成(已获取服务句柄)后调用。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

所属服务的属性句柄

gatts_add_service;
gatts_add_service_sync 返回的有效服务句柄。

character

gatts_add_chara_info_t *

特征信息

不为 NULL

出参

名称

数据类型

输出说明

result

gatts_add_character_result_t *

特征句柄信息,包含特征声明句柄与特征值句柄,由调用方分配内存、函数填充

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

添加成功

特征添加成功,特征句柄通过 result 返回

Other

其他错误码,参考 errcode_t

添加特征失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_add_descriptor_sync #

errcode_t gatts_add_descriptor_sync(uint8_t server_id, uint16_t service_handle, gatts_add_desc_info_t *descriptor, uint16_t *handle)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 同步方式向指定服务下添加一个 GATT 特征描述符。

  • 描述符信息由 gatts_add_desc_info_t 描述,包含描述符 UUID、权限、初始值等。

  • 描述符句柄通过出参 handle 同步返回。

前置条件

  • 调用时序约束:必须在对应服务添加完成(已获取服务句柄)后调用。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

所属服务的属性句柄

gatts_add_service;
gatts_add_service_sync 返回的有效服务句柄。

descriptor

gatts_add_desc_info_t *

特征描述符信息

不为 NULL

出参

名称

数据类型

输出说明

handle

uint16_t *

添加成功后的描述符属性句柄,由调用方分配内存、函数填充

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

添加成功

描述符添加成功,描述符句柄通过 handle 返回

Other

其他错误码,参考 errcode_t

添加描述符失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_start_service #

errcode_t gatts_start_service(uint8_t server_id, uint16_t service_handle)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 启动指定服务端下的一个 GATT 服务。

  • 启动后该服务对外可见,可被客户端发现与访问。

  • 服务启动结果通过 gatts_start_service_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在对应服务及其下的特征、描述符全部添加完成后调用,且需先注册启动服务回调以接收启动结果。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

待启动服务的属性句柄

gatts_add_service;
gatts_add_service_sync 返回的有效服务句柄。

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

启动服务请求成功发起,启动结果将在回调中返回

Other

其他错误码,参考 errcode_t

启动服务请求失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_stop_service #

errcode_t gatts_stop_service(uint8_t server_id, uint16_t service_handle)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 停止指定服务端下的一个已启动 GATT 服务。

  • 停止后该服务对外不可见,客户端无法继续发现与访问。

  • 服务停止结果通过 gatts_stop_service_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在对应服务已通过 gatts_start_service 启动后调用,且需先注册停止服务回调以接收停止结果。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

待停止服务的属性句柄

已启动服务的有效服务句柄

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

停止服务请求成功发起,停止结果将在回调中返回

Other

其他错误码,参考 errcode_t

停止服务请求失败

gatts_delete_service #

errcode_t gatts_delete_service(uint8_t server_id, uint16_t service_handle)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 删除指定服务端下的一个 GATT 服务及其下全部特征与描述符。

  • 删除后该服务句柄失效,对应属性资源被释放。

  • 服务删除结果通过 gatts_delete_service_callback 回调异步返回。

前置条件

  • 调用时序约束:建议在服务已停止后调用,且需先注册删除服务回调以接收删除结果。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

service_handle

uint16_t

待删除服务的属性句柄

有效服务句柄

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

删除服务请求成功发起,删除结果将在回调中返回

Other

其他错误码,参考 errcode_t

删除服务请求失败

gatts_delete_all_services #

errcode_t gatts_delete_all_services(uint8_t server_id)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 删除指定服务端下的全部 GATT 服务及其下全部特征与描述符。

  • 删除后该服务端的所有服务句柄失效,对应属性资源被释放。

  • 删除结果通过 gatts_delete_service_callback 回调异步返回。

前置条件

  • 调用时序约束:必须在 gatts_register_server 成功返回后调用,且需先注册删除服务回调以接收删除结果。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

删除全部服务请求成功发起,删除结果将在回调中返回

Other

其他错误码,参考 errcode_t

删除全部服务请求失败

gatts_send_response #

errcode_t gatts_send_response(uint8_t server_id, uint16_t conn_id, gatts_send_rsp_t *param)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 当收到需要用户回复响应的读/写请求时,向对端发送响应。

  • 响应参数由 gatts_send_rsp_t 描述,包含请求 ID、状态码、偏移、响应数据等。

  • 与 gatts_read_request_callback、gatts_write_request_callback 回调配合使用。

前置条件

  • 调用时序约束:必须在收到读/写请求回调(且该回调中 need_rsp 为真)后调用,以响应对应请求。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

conn_id

uint16_t

连接 ID

有效连接 ID

param

gatts_send_rsp_t *

响应参数

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功发送

响应发送成功

Other

其他错误码,参考 errcode_t

响应发送失败

gatts_notify_indicate #

errcode_t gatts_notify_indicate(uint8_t server_id, uint16_t conn_id, gatts_ntf_ind_t *param)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 向对端设备发送通知或指示。

  • 发送参数由 gatts_ntf_ind_t 描述,包含属性句柄、数据长度与数据。

  • 具体发送状态(通知或指示)取决于特征描述符:客户端特征配置的值。

前置条件

  • 调用时序约束:必须在对应服务已启动、连接已建立后调用,且目标特征的客户端特征配置描述符已使能对应的通知或指示。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

conn_id

uint16_t

连接 ID

有效连接 ID

param

gatts_ntf_ind_t *

通知或指示参数

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功发送

通知/指示发送成功

Other

其他错误码,参考 errcode_t

通知/指示发送失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_notify_indicate_by_uuid #

errcode_t gatts_notify_indicate_by_uuid(uint8_t server_id, uint16_t conn_id, gatts_ntf_ind_by_uuid_t *param)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 通过特征 UUID 向对端设备发送通知或指示。

  • 发送参数由 gatts_ntf_ind_by_uuid_t 描述,包含特征 UUID、起止句柄范围、数据长度与数据。

  • 具体发送状态取决于客户端特征配置描述符的值:0 不允许通知和指示,1 允许通知,2 允许指示。

前置条件

  • 调用时序约束:必须在对应服务已启动、连接已建立后调用,且目标特征的客户端特征配置描述符已配置为允许对应的通知或指示。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

conn_id

uint16_t

连接 ID

有效连接 ID

param

gatts_ntf_ind_by_uuid_t *

通知或指示参数

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功发送

通过 UUID 发送通知/指示成功

Other

其他错误码,参考 errcode_t

通过 UUID 发送通知/指示失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_set_mtu_size #

errcode_t gatts_set_mtu_size(uint8_t server_id, uint16_t mtu_size)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 在连接建立之前设置服务端接收 MTU 大小。

  • 设置的 MTU 大小影响后续连接建立后的数据收发最大长度。

前置条件

  • 调用时序约束:必须在 gatts_register_server 成功返回后、连接建立之前调用。

入参

名称

参数类型

说明

约束取值范围

server_id

uint8_t

服务端 ID

由 gatts_register_server 分配的有效 ID

mtu_size

uint16_t

服务端接收 MTU 大小

SDK_BLE_MTU_MIN:23 ~ SDK_BLE_MTU_MAX:517

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功设置

MTU 大小设置成功

Other

其他错误码,参考 errcode_t

MTU 大小设置失败

gatts_register_callbacks #

errcode_t gatts_register_callbacks(gatts_callbacks_t *func)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 注册 GATT 服务端回调函数集合。

  • 回调集合由 gatts_callbacks_t 描述,覆盖服务/特征/描述符注册结果、读写请求、MTU 变化、指示确认等事件。

  • 注册后相关事件将通过所注册的回调异步通知应用层。

前置条件

  • 调用时序约束:建议在 gatts_register_server 之前或之后、但在发起任何会产生回调的操作(如添加服务、启动服务)之前调用。

入参

名称

参数类型

说明

约束取值范围

func

gatts_callbacks_t *

回调函数集合

不为 NULL

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

成功注册

回调函数注册成功

Other

其他错误码,参考 errcode_t

回调函数注册失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

  • src/application/samples/bt/ble/ble_wifi_cfg_server/src/ble_wifi_cfg_server.c

gatts_exchange_mtu_req #

errcode_t gatts_exchange_mtu_req(uint16_t conn_id, uint16_t mtu_size)

声明头文件

#include "include/middleware/services/bts/ble/bts_gatt_server.h"

功能说明

  • 向对端发送交换 MTU 请求,协商连接的 MTU 大小。

  • 协商结果通过 gatts_mtu_changed_callback 回调异步通知应用层。

前置条件

  • 调用时序约束:必须在连接已建立后调用,且需先注册 MTU 变化回调以接收协商结果。

入参

名称

参数类型

说明

约束取值范围

conn_id

uint16_t

连接 ID

有效连接 ID

mtu_size

uint16_t

服务端接收 MTU

SDK_BLE_MTU_MIN:23 ~ SDK_BLE_MTU_MAX:517

返回值

返回类型:errcode_t

返回值

文字含义

触发场景

ERRCODE_SUCC:0

请求成功

交换 MTU 请求发送成功

Other

其他错误码,参考 errcode_t

交换 MTU 请求发送失败

参考案例

  • src/application/samples/bt/ble/ble_speed_server/src/ble_speed_server.c

Type definitions#

errcode_t #

typedef uint32_t errcode_t;

使用说明

本模块全部对外接口的返回值类型,表示接口执行结果。ERRCODE_SUCC 表示成功,其余值表示失败,具体错误码见 SDK 公共 errcode.h。

gatts_add_service_callback #

typedef void (*gatts_add_service_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t handle, errcode_t status);

使用说明

服务添加完成的回调函数指针类型。回调说明:在服务添加完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,uuid 为服务 UUID,handle 为服务属性句柄,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_add_characteristic_callback #

typedef void (*gatts_add_characteristic_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t service_handle,
    gatts_add_character_result_t *result, errcode_t status);

使用说明

特征添加完成的回调函数指针类型。回调说明:在特征添加完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,uuid 为特征 UUID,service_handle 为所属服务属性句柄,result 为特征句柄信息,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_add_descriptor_callback #

typedef void (*gatts_add_descriptor_callback)(uint8_t server_id, bt_uuid_t *uuid, uint16_t service_handle,
    uint16_t handle, errcode_t status);

使用说明

特征描述符添加完成的回调函数指针类型。回调说明:在特征描述符添加完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,uuid 为特征 UUID,service_handle 为所属服务属性句柄,handle 为描述符属性句柄,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_start_service_callback #

typedef void (*gatts_start_service_callback)(uint8_t server_id, uint16_t handle, errcode_t status);

使用说明

服务启动完成的回调函数指针类型。回调说明:在服务启动完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,handle 为服务属性句柄,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_stop_service_callback #

typedef void (*gatts_stop_service_callback)(uint8_t server_id, uint16_t handle, errcode_t status);

使用说明

服务停止完成的回调函数指针类型。回调说明:在服务停止完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,handle 为服务属性句柄,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_delete_service_callback #

typedef void (*gatts_delete_service_callback)(uint8_t server_id, errcode_t status);

使用说明

服务删除完成的回调函数指针类型。回调说明:在服务删除完成时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_read_request_callback #

typedef void (*gatts_read_request_callback)(uint8_t server_id, uint16_t conn_id, gatts_req_read_cb_t *read_cb_para,
    errcode_t status);

使用说明

收到远端读请求的回调函数指针类型。回调说明:在收到远端读请求时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,conn_id 为连接 ID,read_cb_para 为读请求参数,status 为执行结果错误码;若 read_cb_para 中 need_rsp 为真,应用层需通过 gatts_send_response 发送响应;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_write_request_callback #

typedef void (*gatts_write_request_callback)(uint8_t server_id, uint16_t conn_id, gatts_req_write_cb_t *write_cb_para,
    errcode_t status);

使用说明

收到远端写请求的回调函数指针类型。回调说明:在收到远端写请求时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,conn_id 为连接 ID,write_cb_para 为写请求参数,status 为执行结果错误码;若 write_cb_para 中 need_rsp 为真,应用层需通过 gatts_send_response 发送响应;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_mtu_changed_callback #

typedef void (*gatts_mtu_changed_callback)(uint8_t server_id, uint16_t conn_id, uint16_t mtu_size, errcode_t status);

使用说明

MTU 大小更新的回调函数指针类型。回调说明:在连接 MTU 协商完成或 MTU 大小变化时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,conn_id 为连接 ID,mtu_size 为协商后的 MTU 大小,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

gatts_indication_confirm_callback #

typedef void (*gatts_indication_confirm_callback)(uint8_t server_id, uint16_t conn_id, errcode_t status);

使用说明

收到对端指示确认(Indication Confirm)的回调函数指针类型。回调说明:在对端确认收到指示时由 BTS 上下文异步调用;参数 server_id 为服务端 ID,conn_id 为连接 ID,status 为执行结果错误码;该回调运行于 BTS 线程,不能阻塞或长时间等待。

Structures#

gatts_add_chara_info_t #

typedef struct {
    bt_uuid_t chara_uuid;   /*!< UUID of GATT characteristic. */
    uint8_t permissions;    /*!< Characteristic permissions, { gatt_attribute_permission_t }. */
    uint8_t properties;    /*!< Characteristic properties, { gatt_characteristic_property_t }. */
    uint16_t value_len;     /*!< Length of reponse data. */
    uint8_t *value;         /*!< Reponse data. */
} gatts_add_chara_info_t;

成员说明

成员名称

数据类型

描述

chara_uuid

bt_uuid_t

GATT 特征 UUID

permissions

uint8_t

特征权限,取值参考 gatt_attribute_permission_t

properties

uint8_t

特征特性,取值参考 gatt_characteristic_property_t

value_len

uint16_t

响应的数据长度

value

uint8_t *

响应的数据

gatts_add_desc_info_t #

typedef struct {
    bt_uuid_t desc_uuid;   /*!< UUID of GATT descriptor. */
    uint8_t permissions;   /*!< Descriptor permissions, { gatt_attribute_permission_t }. */
    uint16_t value_len;    /*!< Length of reponse data. */
    uint8_t *value;        /*!< Reponse data. */
} gatts_add_desc_info_t;

成员说明

成员名称

数据类型

描述

desc_uuid

bt_uuid_t

GATT 描述符 UUID

permissions

uint8_t

描述符权限,取值参考 gatt_attribute_permission_t

value_len

uint16_t

响应的数据长度

value

uint8_t *

响应的数据

gatts_req_read_cb_t #

typedef struct {
    uint16_t request_id;  /*!< Request id. */
    uint16_t handle;      /*!< Attribute handle of the read request. */
    uint16_t offset;      /*!< Offset of the read request in bytes. */
    bool need_rsp;        /*!< Whether response is needed. */
    bool need_authorize;  /*!< Whether authorization is needed. */
    bool is_long;         /*!< Whether request is Long Read. */
} gatts_req_read_cb_t;

成员说明

成员名称

数据类型

描述

request_id

uint16_t

请求 ID

handle

uint16_t

请求读的属性句柄

offset

uint16_t

请求读的字节偏移

need_rsp

bool

是否需要发送响应

need_authorize

bool

是否需要授权

is_long

bool

请求是否是读长特征

gatts_req_write_cb_t #

typedef struct {
    uint16_t request_id;  /*!< Request id. */
    uint16_t handle;      /*!< Attribute handle of the write request. */
    uint16_t offset;      /*!< Offset of the write request in bytes. */
    bool need_rsp;        /*!< Whether response is needed. */
    bool need_authorize;  /*!< Whether authorization is needed. */
    bool is_prep;         /*!< Whether request is Prepare Write. */
    uint16_t length;      /*!< Length of write request data. */
    uint8_t *value;       /*!< Write request data. */
} gatts_req_write_cb_t;

成员说明

成员名称

数据类型

描述

request_id

uint16_t

请求 ID

handle

uint16_t

请求写的属性句柄

offset

uint16_t

请求写的字节偏移

need_rsp

bool

是否需要发送响应

need_authorize

bool

是否需要授权

is_prep

bool

请求是否是准备写

length

uint16_t

请求写的数据长度

value

uint8_t *

请求写的数据

gatts_send_rsp_t #

typedef struct {
    uint16_t request_id; /*!< Request ID. */
    uint8_t status;      /*!< Status code of read/write, { gatt_status_t }. */
    uint16_t offset;     /*!< Offset. */
    uint16_t value_len;  /*!< Length of reponse data. */
    uint8_t *value;      /*!< Reponse data. */
} gatts_send_rsp_t;

成员说明

成员名称

数据类型

描述

request_id

uint16_t

请求 ID

status

uint8_t

读写结果的状态,取值参考 gatt_status_t

offset

uint16_t

属性偏移

value_len

uint16_t

响应的数据长度

value

uint8_t *

响应的数据

gatts_ntf_ind_t #

typedef struct {
    uint16_t attr_handle; /*!< Attribute handle. */
    uint16_t value_len;   /*!< Length of notification/indication data. */
    uint8_t *value;       /*!< Notification/indication data. */
} gatts_ntf_ind_t;

成员说明

成员名称

数据类型

描述

attr_handle

uint16_t

属性句柄

value_len

uint16_t

通知/指示数据长度

value

uint8_t *

发送的通知/指示数据

gatts_ntf_ind_by_uuid_t #

typedef struct {
    bt_uuid_t chara_uuid;  /*!< Characteristic UUID. */
    uint16_t start_handle; /*!< start handle. */
    uint16_t end_handle;   /*!< end handle. */
    uint16_t value_len;    /*!< Length of notification/indication data. */
    uint8_t *value;        /*!< Notification/indication data. */
} gatts_ntf_ind_by_uuid_t;

成员说明

成员名称

数据类型

描述

chara_uuid

bt_uuid_t

特征 UUID

start_handle

uint16_t

起始句柄

end_handle

uint16_t

结束句柄

value_len

uint16_t

通知/指示数据长度

value

uint8_t *

发送的通知/指示数据

gatts_add_character_result_t #

typedef struct {
    uint16_t handle;         /*!< decl handle. */
    uint16_t value_handle;   /*!< value handle. */
} gatts_add_character_result_t;

成员说明

成员名称

数据类型

描述

handle

uint16_t

特征声明句柄

value_handle

uint16_t

特征值句柄

gatts_callbacks_t #

typedef struct {
    gatts_add_service_callback add_service_cb;               /*!< Service added callback. */
    gatts_add_characteristic_callback add_characteristic_cb; /*!< Characteristc added callback. */
    gatts_add_descriptor_callback add_descriptor_cb;         /*!< Descriptor added callback. */
    gatts_start_service_callback start_service_cb;           /*!< Service started callback. */
    gatts_stop_service_callback stop_service_cb;             /*!< Service stoped callback. */
    gatts_delete_service_callback delete_service_cb;         /*!< All service deleted callback. */
    gatts_read_request_callback read_request_cb;             /*!< Read request received callback. */
    gatts_write_request_callback write_request_cb;           /*!< Write request received callback. */
    gatts_mtu_changed_callback mtu_changed_cb;               /*!< Mtu changed callback. */
    gatts_indication_confirm_callback indicate_confirm_cb;   /*!< Indication confirm callback. */
} gatts_callbacks_t;

成员说明

成员名称

数据类型

描述

add_service_cb

gatts_add_service_callback

添加服务回调函数

add_characteristic_cb

gatts_add_characteristic_callback

添加特征回调函数

add_descriptor_cb

gatts_add_descriptor_callback

添加描述符回调函数

start_service_cb

gatts_start_service_callback

启动服务回调函数

stop_service_cb

gatts_stop_service_callback

停止服务回调函数

delete_service_cb

gatts_delete_service_callback

删除所有服务回调函数

read_request_cb

gatts_read_request_callback

收到远端读请求回调函数

write_request_cb

gatts_write_request_callback

收到远端写请求回调函数

mtu_changed_cb

gatts_mtu_changed_callback

MTU 大小更新回调函数

indicate_confirm_cb

gatts_indication_confirm_callback

Indication Confirm 回调函数

Macros#

SDK_BLE_MTU_MIN #

#define SDK_BLE_MTU_MIN 23

SDK_BLE_MTU_MAX #

#define SDK_BLE_MTU_MAX 517

ERRCODE_SUCC #

#define ERRCODE_SUCC                                        0UL