跳转至
项目
版本
全文检索

server

SSAP（Service and Application Protocol）服务端模块提供SLE协议栈中SSAP服务端的注册、注销、服务实例管理、读写请求响应、通知/指示发送以及MTU设置等接口。

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

接口清单

接口名称 功能简述
bs_sle_ssaps_register_server 注册SSAP服务端
bs_sle_ssaps_unregister_server 注销SSAP服务端
bs_sle_ssaps_service_instance_init 服务端添加服务实例
bs_sle_ssaps_send_response 发送读写请求响应
bs_sle_ssaps_send_method_response 发送方法请求响应
bs_sle_ssaps_notify_indicate 向对端发送通知或指示
bs_sle_ssaps_event_notify_indicate 向对端发送事件通知或指示
bs_sle_ssaps_set_mtu_size 设置服务端最大MTU

Functions

bs_sle_ssaps_register_server

函数声明

errcode_t bs_sle_ssaps_register_server(bs_sle_uuid_t *app_uuid, uint8_t *server_id);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 注册SSAP服务端，向协议栈注册当前应用作为SSAP服务端
  • 通过应用UUID标识当前服务端身份
  • 注册成功后返回服务端ID，用于后续服务端操作

入参

名称 参数类型 详细说明 约束取值范围
app_uuid bs_sle_uuid_t * 上层应用UUID 非NULL

出参

名称 数据类型 输出说明
server_id uint8_t * 服务端ID

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_unregister_server

函数声明

errcode_t bs_sle_ssaps_unregister_server(uint8_t server_id);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 注销SSAP服务端，释放服务端资源
  • 通过服务端ID标识需要注销的服务端
  • 注销后该服务端ID不再有效

前置条件

  • 调用时序约束：必须在bs_sle_ssaps_register_server()成功返回后调用
  • 依赖关系：server_id须为已注册的有效服务端ID

入参

名称 参数类型 详细说明 约束取值范围
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_service_instance_init

函数声明

errcode_t bs_sle_ssaps_service_instance_init(uint8_t server_id, bs_sle_ssaps_service_template_t *service, uint8_t *inst_id);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 在服务端添加服务实例，配置服务的模板结构
  • 配置服务的模板结构中的item_array数组的下标将作为后续操作时条目的标识符
  • 添加成功后返回服务实例ID

前置条件

  • 调用时序约束：必须在bs_sle_ssaps_register_server()成功返回后调用
  • 依赖关系：server_id须为已注册的有效服务端ID

入参

名称 参数类型 详细说明 约束取值范围
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
service bs_sle_ssaps_service_template_t * 配置服务的模板结构 非NULL

出参

名称 数据类型 输出说明
inst_id uint8_t * 配置服务的实例ID

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_send_response

函数声明

errcode_t bs_sle_ssaps_send_response(uint16_t device_id, uint8_t server_id, bs_sle_ssaps_send_rsp_t *param, uint8_t status);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 当收到需要用户回复响应的读、写请求时，发送响应
  • 通过device_id和server_id标识目标设备和本端服务端
  • 读写结果的状态通过status参数传递，成功时为ERRCODE_SLE_SUCCESS，异常参考bs_sle_ssap_errcode_t

前置条件

  • 调用时序约束：必须在收到读请求或写请求回调且need_rsp为true时调用
  • 依赖关系：需要立即回复响应，否则会阻塞后续SSAP信令交互

入参

名称 参数类型 详细说明 约束取值范围
device_id uint16_t 设备ID 有效设备ID
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
param bs_sle_ssaps_send_rsp_t * 响应参数 非NULL
status uint8_t 读写结果的状态 成功：ERRCODE_SLE_SUCCESS，异常参考bs_sle_ssap_errcode_t

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_send_method_response

函数声明

errcode_t bs_sle_ssaps_send_method_response(uint16_t device_id, uint8_t server_id, bs_sle_ssaps_send_rsp_t *param);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 当收到需要用户回复响应的方法请求时，发送响应
  • 方法的错误响应应在用户定义的方法响应数据中体现
  • 通过device_id和server_id标识目标设备和本端服务端

前置条件

  • 调用时序约束：必须在收到方法调用请求回调且need_rsp为true时调用
  • 依赖关系：需要立即回复响应，否则会阻塞后续SSAP信令交互

入参

名称 参数类型 详细说明 约束取值范围
device_id uint16_t 设备ID 有效设备ID
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
param bs_sle_ssaps_send_rsp_t * 响应参数 非NULL

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_notify_indicate

函数声明

errcode_t bs_sle_ssaps_notify_indicate(uint16_t device_id, uint8_t server_id, bs_sle_ssaps_ntf_ind_t *param);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 向对端设备发送通知或指示
  • 具体发送状态取决于特征描述符中的客户端特征配置值
  • 客户端特征配置值：0x0000不允许通知和指示，0x0001允许通知，0x0002允许指示

前置条件

  • 调用时序约束：必须在bs_sle_ssaps_service_instance_init()成功且服务启动后调用
  • 依赖关系：对端设备需已连接且客户端特征配置描述符已开启相应通知/指示

入参

名称 参数类型 详细说明 约束取值范围
device_id uint16_t 设备ID 有效设备ID
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
param bs_sle_ssaps_ntf_ind_t * 通知或指示参数 非NULL

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_event_notify_indicate

函数声明

errcode_t bs_sle_ssaps_event_notify_indicate(uint16_t device_id, uint8_t server_id, bs_sle_ssaps_event_ntf_ind_t *param);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 向对端设备发送事件通知或指示
  • 通过need_rsp字段区分通知（需要响应）和指示（不需要响应）
  • 通过device_id和server_id标识目标设备和本端服务端

前置条件

  • 调用时序约束：必须在bs_sle_ssaps_service_instance_init()成功且服务启动后调用
  • 依赖关系：对端设备需已连接

入参

名称 参数类型 详细说明 约束取值范围
device_id uint16_t 设备ID 有效设备ID
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
param bs_sle_ssaps_event_ntf_ind_t * 事件通知或指示参数 非NULL

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssaps_set_mtu_size

函数声明

errcode_t bs_sle_ssaps_set_mtu_size(uint8_t server_id, uint16_t mtu_size);

头文件清单

#include "protocol/bt/host/include/sle/sle_service/ssf_ssap_server.h"

功能说明

  • 在连接之前设置服务端最大MTU大小
  • 通过服务端ID标识目标服务端
  • 设置的MTU大小影响后续连接的数据传输单元

前置条件

  • 调用时序约束：必须在连接建立之前调用
  • 依赖关系：server_id须为已注册的有效服务端ID

入参

名称 参数类型 详细说明 约束取值范围
server_id uint8_t 服务端ID 通过bs_sle_ssaps_register_server获取
mtu_size uint16_t MTU大小 有效MTU值

返回值

返回值 文字含义 触发场景
Other 其他错误码，参考errcode_sle_t 执行失败

Type definitions

errcode_t 

typedef unsigned int errcode_t;

使用说明：所有8个对外接口的返回值类型 [SDK公共基础类型]

bs_sle_ssaps_start_service_callback 

typedef void (*bs_sle_ssaps_start_service_callback)(uint8_t server_id, uint8_t inst_id, errcode_t status);

调用时机：添加服务实例后，协议栈启动服务时回调

bs_sle_ssaps_delete_service_callback 

typedef void (*bs_sle_ssaps_delete_service_callback)(uint8_t server_id, uint8_t inst_id, errcode_t status);

调用时机：注销服务端时，删除所有服务实例后回调

bs_sle_ssaps_read_request_callback 

typedef void (*bs_sle_ssaps_read_request_callback)(
    uint16_t device_id, uint8_t server_id, bs_sle_ssaps_req_read_cb_t *read_cb_para, errcode_t status);

调用时机：收到对端设备读请求时回调

bs_sle_ssaps_write_request_callback 

typedef void (*bs_sle_ssaps_write_request_callback)(
    uint16_t device_id, uint8_t server_id, bs_sle_ssaps_req_write_cb_t *write_cb_para, errcode_t status);

调用时机：收到对端设备写请求时回调

bs_sle_ssaps_call_method_request_callback 

typedef void (*bs_sle_ssaps_call_method_request_callback)(
    uint16_t device_id, uint8_t server_id, bs_sle_ssaps_req_call_method_cb_t *call_method_cb_para);

调用时机：收到对端设备方法调用请求时回调

bs_sle_ssaps_indicate_cfm_callback 

typedef void (*bs_sle_ssaps_indicate_cfm_callback)(
    uint16_t device_id, uint8_t server_id, bs_sle_ssaps_indication_cfm_result_t cfm_result);

调用时机：收到对端设备指示确认时回调

bs_sle_ssaps_mtu_changed_callback 

typedef void (*bs_sle_ssaps_mtu_changed_callback)(
    uint16_t device_id, uint8_t server_id, uint16_t mtu_size, errcode_t status);

调用时机：对端设备协商MTU大小变化时回调

Associations

(anonymous union at bs_sle_ssaps_item_info_t) 

union {
    bs_sle_ssaps_property_info_t property;
    bs_sle_ssaps_method_and_event_info_t method_and_event;
};
成员名称 类型 描述 接口使用逻辑
property bs_sle_ssaps_property_info_t 添加属性信息，当条目类型为属性时使用 bs_sle_ssaps_service_instance_init入参间接载体
method_and_event bs_sle_ssaps_method_and_event_info_t 添加方法、事件信息，当条目类型为方法、事件时使用 bs_sle_ssaps_service_instance_init入参间接载体

Enumerations

bs_sle_ssaps_indication_cfm_result_t 

typedef enum {
    BS_SSAP_INDICATION_CFM_FAIL   = 0x00,
    BS_SSAP_INDICATION_CFM_SUCESS = 0x01,
} bs_sle_ssaps_indication_cfm_result_t;
枚举成员 取值 描述
BS_SSAP_INDICATION_CFM_FAIL 0x00 指示确认失败
BS_SSAP_INDICATION_CFM_SUCESS 0x01 指示确认成功

Structures

bs_sle_uuid_t 

typedef struct {
    uint8_t len;
    uint8_t uuid[BS_SLE_UUID_LEN];
} bs_sle_uuid_t;

成员说明

成员名称 数据类型 描述
len uint8_t UUID长度
uuid uint8_t[] UUID字段，长度为BS_SLE_UUID_LEN(16)

bs_sle_ssaps_req_read_cb_t 

typedef struct {
    uint8_t inst_id;
    uint8_t item_id;
    uint16_t request_id;
    uint8_t type;
    bool need_rsp;
} bs_sle_ssaps_req_read_cb_t;

成员说明

成员名称 数据类型 描述
inst_id uint8_t 服务实例ID
item_id uint8_t 条目标识，参考添加条目时的顺序
request_id uint16_t 请求ID
type uint8_t 属性、描述符类型，参考bs_sle_ssap_property_type_t
need_rsp bool 是否需要发送响应，需要回复响应时需调用bs_sle_ssaps_send_response

bs_sle_ssaps_req_write_cb_t 

typedef struct {
    uint8_t inst_id;
    uint8_t item_id;
    uint16_t request_id;
    uint8_t type;
    bool need_rsp;
    uint16_t length;
    uint8_t *value;
} bs_sle_ssaps_req_write_cb_t;

成员说明

成员名称 数据类型 描述
inst_id uint8_t 服务实例ID
item_id uint8_t 条目标识，参考添加条目时的顺序
request_id uint16_t 请求ID
type uint8_t 属性、描述符类型，参考bs_sle_ssap_property_type_t
need_rsp bool 是否需要发送响应，需要回复响应时需调用bs_sle_ssaps_send_response
length uint16_t 请求写的数据长度
value uint8_t * 请求写的数据

bs_sle_ssaps_req_call_method_cb_t 

typedef struct {
    uint8_t inst_id;
    uint8_t item_id;
    uint16_t request_id;
    bool need_rsp;
    uint16_t length;
    uint8_t *value;
} bs_sle_ssaps_req_call_method_cb_t;

成员说明

成员名称 数据类型 描述
inst_id uint8_t 服务实例ID
item_id uint8_t 条目标识，参考添加条目时的顺序
request_id uint16_t 请求ID
need_rsp bool 是否需要发送响应，需要回复响应时需调用bs_sle_ssaps_send_response
length uint16_t 请求传入的数据长度
value uint8_t * 请求传入的数据

bs_sle_ssaps_send_rsp_t 

typedef struct {
    uint16_t request_id;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_send_rsp_t;

成员说明

成员名称 数据类型 描述
request_id uint16_t 请求ID
value_len uint16_t 响应的数据长度
value uint8_t * 响应的数据

bs_sle_ssaps_ntf_ind_t 

typedef struct {
    uint8_t inst_id;
    uint8_t item_id;
    uint8_t type;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_ntf_ind_t;

成员说明

成员名称 数据类型 描述
inst_id uint8_t 服务实例ID
item_id uint8_t 条目标识，参考添加条目时的顺序
type uint8_t 属性类型，参考bs_sle_ssap_property_type_t
value_len uint16_t 通知/指示数据长度
value uint8_t * 发送的通知/指示数据

bs_sle_ssaps_event_ntf_ind_t 

typedef struct {
    uint8_t inst_id;
    uint8_t item_id;
    bool need_rsp;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_event_ntf_ind_t;

成员说明

成员名称 数据类型 描述
inst_id uint8_t 服务实例ID
item_id uint8_t 条目标识，参考添加条目时的顺序
need_rsp bool 需要接收端回复响应，有回复响应为通知，无回复响应为指示
value_len uint16_t 事件通知/指示数据长度
value uint8_t * 发送事件的通知/指示数据

bs_sle_ssaps_descriptor_info_t 

typedef struct {
    bs_sle_uuid_t uuid;
    uint16_t permissions;
    uint32_t operate_indication;
    uint8_t type;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_descriptor_info_t;

成员说明

成员名称 数据类型 描述
uuid bs_sle_uuid_t 该描述符UUID
permissions uint16_t 特征权限，参考bs_sle_ssap_permission_t
operate_indication uint32_t 操作指示，参考bs_sle_ssap_operate_indication_t
type uint8_t 描述符类型，参考bs_sle_ssap_property_type_t
value_len uint16_t 数据长度
value uint8_t * 数据

bs_sle_ssaps_property_info_t 

typedef struct {
    bs_sle_uuid_t uuid;
    uint16_t permissions;
    uint32_t operate_indication;
    uint8_t desc_count;
    bs_sle_ssaps_descriptor_info_t *desc_array;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_property_info_t;

成员说明

成员名称 数据类型 描述
uuid bs_sle_uuid_t 该属性的UUID
permissions uint16_t 特征权限，参考bs_sle_ssap_permission_t
operate_indication uint32_t 操作指示，参考bs_sle_ssap_operate_indication_t
desc_count uint8_t 属性描述符数组desc_array的数量
desc_array bs_sle_ssaps_descriptor_info_t * 属性描述符数组
value_len uint16_t 数据长度
value uint8_t * 数据

bs_sle_ssaps_method_and_event_info_t 

typedef struct {
    bs_sle_uuid_t uuid;
    uint16_t permissions;
    uint32_t operate_indication;
    uint16_t value_len;
    uint8_t *value;
} bs_sle_ssaps_method_and_event_info_t;

成员说明

成员名称 数据类型 描述
uuid bs_sle_uuid_t 该方法、事件的UUID
permissions uint16_t 特征权限，参考bs_sle_ssap_permission_t
operate_indication uint32_t 操作指示，参考bs_sle_ssap_operate_indication_t
value_len uint16_t 数据长度
value uint8_t * 数据

bs_sle_ssaps_item_info_t 

typedef struct {
    uint8_t type;
    union {
        bs_sle_ssaps_property_info_t property;
        bs_sle_ssaps_method_and_event_info_t method_and_event;
    };
} bs_sle_ssaps_item_info_t;

成员说明

成员名称 数据类型 描述
type uint8_t 添加的条目类型，仅包含属性、方法、事件，参考bs_sle_ssap_item_type_t
property bs_sle_ssaps_property_info_t 添加属性信息，当条目类型为属性时使用
method_and_event bs_sle_ssaps_method_and_event_info_t 添加方法、事件信息，当条目类型为方法、事件时使用

bs_sle_ssaps_callbacks_t 

typedef struct {
    bs_sle_ssaps_start_service_callback start_service_cb;
    bs_sle_ssaps_delete_service_callback delete_service_cb;
    bs_sle_ssaps_read_request_callback read_request_cb;
    bs_sle_ssaps_write_request_callback write_request_cb;
    bs_sle_ssaps_call_method_request_callback call_method_cb;
    bs_sle_ssaps_indicate_cfm_callback indicate_cfm_cb;
    bs_sle_ssaps_mtu_changed_callback mtu_changed_cb;
} bs_sle_ssaps_callbacks_t;

成员说明

成员名称 数据类型 描述
start_service_cb bs_sle_ssaps_start_service_callback 添加实例后，开启服务回调函数
delete_service_cb bs_sle_ssaps_delete_service_callback 删除服务端的所有实例回调函数
read_request_cb bs_sle_ssaps_read_request_callback 收到读请求的回调函数
write_request_cb bs_sle_ssaps_write_request_callback 收到写请求的回调函数
call_method_cb bs_sle_ssaps_call_method_request_callback 收到方法调用请求的回调函数
indicate_cfm_cb bs_sle_ssaps_indicate_cfm_callback 指示确认回调函数
mtu_changed_cb bs_sle_ssaps_mtu_changed_callback MTU大小更新回调函数

bs_sle_ssaps_extend_param_t 

typedef struct {
    uint8_t resv;
} bs_sle_ssaps_extend_param_t;

成员说明

成员名称 数据类型 描述
resv uint8_t 预留

bs_sle_ssaps_service_template_t 

typedef struct {
    bs_sle_uuid_t uuid;
    uint8_t is_primary;
    uint8_t item_count;
    bs_sle_ssaps_callbacks_t cbks;
    bs_sle_ssaps_extend_param_t extend_param;
    bs_sle_ssaps_item_info_t item_array[0];
} bs_sle_ssaps_service_template_t;

成员说明

成员名称 数据类型 描述
uuid bs_sle_uuid_t 该服务UUID
is_primary uint8_t 是否是主服务标记
item_count uint8_t item_array中的条目个数
cbks bs_sle_ssaps_callbacks_t 服务端回调函数
extend_param bs_sle_ssaps_extend_param_t 服务端扩展参数
item_array bs_sle_ssaps_item_info_t[] 服务中条目数组

Macros

BS_SLE_UUID_LEN 

#define BS_SLE_UUID_LEN 16