跳转至
项目
版本
全文检索

client

SSAP (Service and Application Protocol) 客户端提供SLE (Star Flash Low Energy) 协议栈中服务发现、属性读写、方法调用及信息交换等客户端侧操作接口。

头文件清单

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

接口清单

接口名称 功能简述
bs_sle_ssapc_register 注册SSAP客户端
bs_sle_ssapc_unregister 注销SSAP客户端
bs_sle_ssapc_find_all_service 发现远端设备全部服务
bs_sle_ssapc_find_service_by_uuid 基于UUID发现指定服务
bs_sle_ssapc_register_callbacks 注册SSAP客户端多服务回调函数
bs_sle_ssapc_unregister_callbacks 去注册SSAP客户端多服务回调函数
bs_sle_ssapc_read 发起按句柄读取请求
bs_sle_ssapc_write 发起写请求或命令
bs_sle_ssapc_call_method 方法调用请求或命令
bs_sle_ssapc_exchange_info_req 发送交换信息请求

Functions

bs_sle_ssapc_register 

errcode_t bs_sle_ssapc_register(bs_sle_uuid_t *app_uuid, uint8_t *client_id)

头文件清单

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

功能说明

  • 注册SSAP客户端，分配客户端ID
  • 通过上层应用UUID标识客户端身份
  • 注册成功后可使用客户端ID进行服务发现、读写等操作

入参

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

出参

名称 数据类型 输出说明
client_id uint8_t * 客户端ID，注册成功后输出分配的ID

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 注册成功
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_unregister 

errcode_t bs_sle_ssapc_unregister(uint8_t client_id)

头文件清单

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

功能说明

  • 注销SSAP客户端，释放客户端ID资源
  • 注销后该客户端ID不再可用

前置条件

  • 调用时序约束：必须在bs_sle_ssapc_register()成功返回后调用
  • 调用时序约束：注销前应确保已停止该客户端的所有服务操作
  • 依赖关系：client_id须为已注册的有效客户端ID

入参

名称 参数类型 详细说明 约束取值范围
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 注销成功
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_find_all_service 

errcode_t bs_sle_ssapc_find_all_service(uint16_t dev_id, uint8_t client_id, bs_sle_ssapc_find_service_callback find_structure_cbk, bool is_remote)

头文件清单

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

功能说明

  • 发现远端设备的全部服务、属性、方法、事件
  • 通过回调返回服务发现结果
  • 支持选择从远端设备强制获取或从本地缓存获取

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register()成功返回后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
find_structure_cbk bs_sle_ssapc_find_service_callback 服务发现完成回调函数 非NULL
is_remote bool 是否强制从远端设备获取服务 true：强制从远端设备获取；false：本地有缓存则从缓存获取

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起，结果在回调中返回
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_find_service_by_uuid 

errcode_t bs_sle_ssapc_find_service_by_uuid(uint16_t dev_id, uint8_t client_id, uint8_t uuid_num, bs_sle_uuid_t *uuid_list, bs_sle_ssapc_find_service_callback find_structure_cbk)

头文件清单

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

功能说明

  • 基于服务UUID或UUID组发现指定服务
  • 支持同时指定多个UUID进行服务发现
  • 通过回调返回服务发现结果

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register()成功返回后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
uuid_num uint8_t UUID个数 大于0
uuid_list bs_sle_uuid_t * UUID数组 非NULL
find_structure_cbk bs_sle_ssapc_find_service_callback 服务发现完成回调函数 非NULL

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起，结果在回调中返回
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_register_callbacks 

errcode_t bs_sle_ssapc_register_callbacks(uint16_t dev_id, uint8_t client_id, bs_sle_uuid_t *service_uuid, bs_sle_ssapc_operation_cbk_t *func)

头文件清单

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

功能说明

  • 注册SSAP客户端多服务回调函数
  • 针对指定服务UUID注册读写、通知、指示、方法调用等操作回调
  • UUID以小端序输入

前置条件

  • 调用时序约束：当前接口需要在服务发现完成之后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
service_uuid bs_sle_uuid_t * 服务UUID 非NULL，小端序输入
func bs_sle_ssapc_operation_cbk_t * 回调函数结构体指针 非NULL

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 注册成功
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_unregister_callbacks 

errcode_t bs_sle_ssapc_unregister_callbacks(uint16_t dev_id, uint8_t client_id, bs_sle_uuid_t *service_uuid)

头文件清单

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

功能说明

  • 去注册SSAP客户端多服务回调函数
  • 取消指定服务UUID对应的操作回调注册
  • UUID以小端序输入

前置条件

  • 调用时序约束：当前接口需要在服务发现完成之后调用
  • 依赖关系：当前接口依赖已通过bs_sle_ssapc_register_callbacks注册过该服务回调

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
service_uuid bs_sle_uuid_t * 服务UUID 非NULL，小端序输入

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 去注册成功
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_read 

errcode_t bs_sle_ssapc_read(uint16_t dev_id, uint8_t client_id, uint16_t handle, uint8_t type)

头文件清单

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

功能说明

  • 发起按句柄读取请求
  • 读取结果在bs_sle_ssapc_read_cfm_callback回调中返回
  • 通过属性句柄和类型指定读取目标

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register_callbacks()注册读回调后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接且已完成服务发现

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
handle uint16_t 属性句柄 服务发现获取的有效句柄
type uint8_t 特征类型 服务发现获取的属性类型

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起，读取结果在回调中返回
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_write 

errcode_t bs_sle_ssapc_write(uint16_t dev_id, uint8_t client_id, bs_sle_ssapc_write_param_t *param)

头文件清单

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

功能说明

  • 发起写请求或写命令
  • 写结果在bs_sle_ssapc_write_cfm_callback回调中返回
  • 支持设置是否需要对端确认

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register_callbacks()注册写回调后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接且已完成服务发现

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
param bs_sle_ssapc_write_param_t * 写请求或命令参数 非NULL

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起，写结果在回调中返回
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_call_method 

errcode_t bs_sle_ssapc_call_method(uint16_t dev_id, uint8_t client_id, bs_sle_ssapc_method_param_t *param)

头文件清单

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

功能说明

  • 发起方法调用请求或命令
  • 支持设置是否需要对端确认
  • 调用远端设备上指定句柄的方法

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register_callbacks()注册方法回调后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接且已完成服务发现

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
param bs_sle_ssapc_method_param_t * 方法调用参数 非NULL

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起
Other 其他错误码，参考errcode_sle_t 执行失败

bs_sle_ssapc_exchange_info_req 

errcode_t bs_sle_ssapc_exchange_info_req(uint16_t dev_id, uint8_t client_id, bs_sle_ssap_exchange_info_t *param)

头文件清单

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

功能说明

  • 发送交换信息请求
  • 用于客户端与服务端交换MTU大小和版本信息
  • 交换结果通过返回值获取

前置条件

  • 调用时序约束：当前接口必须在bs_sle_ssapc_register()成功返回后调用
  • 依赖关系：当前接口依赖已与远端设备建立SLE连接

入参

名称 参数类型 详细说明 约束取值范围
dev_id uint16_t 设备ID 有效设备ID
client_id uint8_t 客户端ID 通过bs_sle_ssapc_register获取的有效ID
param bs_sle_ssap_exchange_info_t * 客户端交换信息参数 非NULL

返回值

返回值 文字含义 触发场景
ERRCODE_SUCC(0x00) 执行成功 请求成功发起
Other 其他错误码，参考errcode_sle_t 执行失败

Type definitions

bs_sle_ssapc_find_service_callback 

typedef void (*bs_sle_ssapc_find_service_callback)(uint16_t dev_id, uint8_t client_id,
    uint8_t service_count, bs_sle_ssapc_find_service_result_node_t *service, errcode_t status);

使用说明

  • 调用时机：服务发现完成时由协议栈回调，用于bs_sle_ssapc_find_all_service和bs_sle_ssapc_find_service_by_uuid的回调参数类型

bs_sle_ssapc_read_cfm_callback 

typedef void (*bs_sle_ssapc_read_cfm_callback)(uint16_t dev_id, uint8_t client_id,
    bs_sle_ssapc_handle_value_t *read_data, errcode_t status);

使用说明

  • 调用时机：客户端收到服务端读响应时由协议栈回调，作为bs_sle_ssapc_read_write_callbacks_t中read_cfm_cb成员的回调类型

bs_sle_ssapc_write_cfm_callback 

typedef void (*bs_sle_ssapc_write_cfm_callback)(uint16_t dev_id, uint8_t client_id,
    bs_sle_ssapc_handle_value_t *write_result, errcode_t status);

使用说明

  • 调用时机：客户端收到服务端写响应时由协议栈回调，作为bs_sle_ssapc_read_write_callbacks_t中write_cfm_cb成员的回调类型

bs_sle_ssapc_notification_callback 

typedef void (*bs_sle_ssapc_notification_callback)(uint16_t dev_id, uint8_t client_id,
    bs_sle_ssapc_handle_value_t *data, errcode_t status);

使用说明

  • 调用时机：客户端收到服务端通知请求时由协议栈回调，作为bs_sle_ssapc_notication_indication_callbacks_t中notification_cb成员的回调类型

bs_sle_ssapc_indication_callback 

typedef void (*bs_sle_ssapc_indication_callback)(uint16_t dev_id, uint8_t client_id,
    bs_sle_ssapc_handle_value_t *data, errcode_t status);

使用说明

  • 调用时机：客户端收到服务端指示请求时由协议栈回调，作为bs_sle_ssapc_notication_indication_callbacks_t中indication_cb成员的回调类型

bs_sle_ssapc_call_method_cfm_callback 

typedef void (*bs_sle_ssapc_call_method_cfm_callback)(uint16_t dev_id, uint8_t client_id,
    bs_sle_ssapc_method_result_t *call_method_result);

使用说明

  • 调用时机：客户端收到服务端调用方法响应时由协议栈回调，作为bs_sle_ssapc_method_callbacks_t中call_method_cfm_cb成员的回调类型

errcode_t 

typedef uint32_t errcode_t;

使用说明

  • 作为本模块所有对外接口的返回值类型 [SDK公共基础类型]

Structures

bs_sle_uuid_t 

typedef struct {
    uint8_t len;                    /*!< UUID 长度 */
    uint8_t uuid[BS_SLE_UUID_LEN];  /*!< UUID字段 */
} bs_sle_uuid_t;

成员说明

成员名称 数据类型 描述
len uint8_t UUID长度
uuid uint8_t[] UUID字段

bs_sle_ssapc_write_param_t 

typedef struct {
    uint16_t handle;       /*!< 属性句柄 */
    uint8_t  type;         /*!< 属性类型 */
    bool is_need_confirm;  /*!< 是否需要对端确认 */
    uint16_t data_len;     /*!< 数据长度 */
    uint8_t  *data;        /*!< 数据内容 */
} bs_sle_ssapc_write_param_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 属性句柄
type uint8_t 属性类型
is_need_confirm bool 是否需要对端确认，false：无需对端回复，true：对端确认后结果在回调中返回
data_len uint16_t 数据长度
data uint8_t * 数据内容

bs_sle_ssapc_method_param_t 

typedef struct {
    uint16_t handle;       /*!< 属性句柄 */
    uint16_t data_len;     /*!< 数据长度 */
    uint8_t  *data;        /*!< 数据内容 */
    bool is_need_confirm;  /*!< 是否需要对端确认 */
} bs_sle_ssapc_method_param_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 方法句柄
data_len uint16_t 数据长度
data uint8_t * 数据内容
is_need_confirm bool 是否需要对端确认，false：无需对端回复，true：对端确认后结果在回调中返回

bs_sle_ssapc_find_service_result_t 

typedef struct {
    uint16_t   start_hdl;   /*!< 服务起始句柄 */
    uint16_t   end_hdl;     /*!< 服务结束句柄 */
    bs_sle_uuid_t uuid;     /*!< 服务UUID */
} bs_sle_ssapc_find_service_result_t;

成员说明

成员名称 数据类型 描述
start_hdl uint16_t 服务起始句柄
end_hdl uint16_t 服务结束句柄
uuid bs_sle_uuid_t 服务UUID

bs_sle_ssapc_find_property_result_node_t 

typedef struct {
    uint16_t   handle;                                     /*!< 属性句柄 */
    uint32_t   operate_indication;                         /*!< 操作指示 */
    bs_sle_uuid_t uuid;                                    /*!< UUID标识 */
    uint8_t    descriptors_count;                          /*!< 属性描述符类型列表长度 */
    uint8_t    descriptors_type[BS_SLE_DESCRIPTOR_COUNT_MAX]; /*!< 属性描述符类型列表 */
} bs_sle_ssapc_find_property_result_node_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 属性句柄
operate_indication uint32_t 操作指示
uuid bs_sle_uuid_t UUID标识
descriptors_count uint8_t 属性描述符类型列表长度
descriptors_type uint8_t[] 属性描述符类型列表

bs_sle_ssapc_find_method_event_result_t 

typedef struct {
    uint16_t   handle;     /*!< 句柄 */
    bs_sle_uuid_t uuid;    /*!< UUID */
} bs_sle_ssapc_find_method_event_result_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 句柄
uuid bs_sle_uuid_t UUID

bs_sle_ssapc_handle_value_t 

typedef struct {
    uint16_t handle;    /*!< 属性句柄 */
    uint8_t  type;      /*!< 属性类型 */
    uint16_t data_len;  /*!< 数据长度 */
    uint8_t  *data;     /*!< 数据内容 */
} bs_sle_ssapc_handle_value_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 属性句柄
type uint8_t 属性类型
data_len uint16_t 数据长度
data uint8_t * 数据内容

bs_sle_ssapc_method_result_t 

typedef struct {
    uint16_t handle;    /*!< 方法句柄 */
    uint16_t data_len;  /*!< 数据长度 */
    uint8_t *data;      /*!< 数据内容 */
} bs_sle_ssapc_method_result_t;

成员说明

成员名称 数据类型 描述
handle uint16_t 方法句柄
data_len uint16_t 数据长度
data uint8_t * 数据内容

bs_sle_ssap_exchange_info_t 

typedef struct {
    uint32_t mtu_size; /*!< mtu大小 */
    uint16_t version;  /*!< 版本 */
} bs_sle_ssap_exchange_info_t;

成员说明

成员名称 数据类型 描述
mtu_size uint32_t MTU大小
version uint16_t 版本

bs_sle_ssapc_find_service_result_node_t 

typedef struct {
    bs_sle_ssapc_find_service_result_t        service;        /*!< 服务信息 */
    uint8_t                                   property_count; /*!< 服务的属性个数 */
    bs_sle_ssapc_find_property_result_node_t *property_list;  /*!< 属性元素数组 */
    uint8_t                                   method_count;   /*!< 服务的方法个数 */
    bs_sle_ssapc_find_method_event_result_t  *method_list;    /*!< 方法元素数组 */
    uint8_t                                   event_count;    /*!< 服务的事件个数 */
    bs_sle_ssapc_find_method_event_result_t  *event_list;     /*!< 事件元素数组 */
} bs_sle_ssapc_find_service_result_node_t;

成员说明

成员名称 数据类型 描述
service bs_sle_ssapc_find_service_result_t 服务信息
property_count uint8_t 服务的属性个数
property_list bs_sle_ssapc_find_property_result_node_t * 属性元素数组
method_count uint8_t 服务的方法个数
method_list bs_sle_ssapc_find_method_event_result_t * 方法元素数组
event_count uint8_t 服务的事件个数
event_list bs_sle_ssapc_find_method_event_result_t * 事件元素数组

bs_sle_ssapc_read_write_callbacks_t 

typedef struct {
    bs_sle_ssapc_read_cfm_callback              read_cfm_cb;   /*!< 收到读响应回调函数 */
    bs_sle_ssapc_write_cfm_callback              write_cfm_cb;  /*!< 收到写响应回调函数 */
} bs_sle_ssapc_read_write_callbacks_t;

成员说明

成员名称 数据类型 描述
read_cfm_cb bs_sle_ssapc_read_cfm_callback 收到读响应回调函数
write_cfm_cb bs_sle_ssapc_write_cfm_callback 收到写响应回调函数

bs_sle_ssapc_notication_indication_callbacks_t 

typedef struct {
    bs_sle_ssapc_notification_callback           notification_cb; /*!< 通知事件上报钩子 */
    bs_sle_ssapc_indication_callback             indication_cb;   /*!< 指示事件上报钩子 */
} bs_sle_ssapc_notication_indication_callbacks_t;

成员说明

成员名称 数据类型 描述
notification_cb bs_sle_ssapc_notification_callback 通知事件上报钩子
indication_cb bs_sle_ssapc_indication_callback 指示事件上报钩子

bs_sle_ssapc_method_callbacks_t 

typedef struct {
    bs_sle_ssapc_call_method_cfm_callback   call_method_cfm_cb;   /*!< 收到方法调用响应回调函数 */
} bs_sle_ssapc_method_callbacks_t;

成员说明

成员名称 数据类型 描述
call_method_cfm_cb bs_sle_ssapc_call_method_cfm_callback 收到方法调用响应回调函数

bs_sle_ssapc_operation_cbk_t 

typedef struct {
    bs_sle_ssapc_read_write_callbacks_t  read_write_cbk;            /*!< 读写回调函数接口定义 */
    bs_sle_ssapc_notication_indication_callbacks_t notication_indication_cbk; /*!< 通知和指示回调函数接口定义 */
    bs_sle_ssapc_method_callbacks_t method_cbk;                     /*!< 方法回调函数接口定义 */
} bs_sle_ssapc_operation_cbk_t;

成员说明

成员名称 数据类型 描述
read_write_cbk bs_sle_ssapc_read_write_callbacks_t 读写回调函数接口定义
notication_indication_cbk bs_sle_ssapc_notication_indication_callbacks_t 通知和指示回调函数接口定义
method_cbk bs_sle_ssapc_method_callbacks_t 方法回调函数接口定义

Macros

BS_SLE_DESCRIPTOR_COUNT_MAX 

#define BS_SLE_DESCRIPTOR_COUNT_MAX 5

BS_SLE_UUID_LEN 

#define BS_SLE_UUID_LEN 16