port

port 提供 BR (Basic Rate) 蓝牙数据传输通道的创建、连接、数据收发及回调管理功能，支持服务端与客户端模式的 port 操作。

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

接口清单

接口名称	功能简述
bs_br_port_create_server_port	创建服务端port
bs_br_port_create_remote_port	设置服务端固定port
bs_br_port_destroy	服务端删除port
bs_br_port_connect	发起port连接
bs_br_port_connect_by_addr	通过设备地址发起port连接
bs_br_port_send_conn_rsp	发送连接响应
bs_br_port_disconnect	客户端断开连接
bs_br_port_write_data	发送数据
bs_br_port_register_callbacks	注册本端port相关回调
bs_br_port_unregister_callbacks	去注册本端port相关回调
bs_br_port_enable	使能bs port
bs_br_port_disable	去使能bs port

Functions

bs_br_port_create_server_port

errcode_t bs_br_port_create_server_port(bs_br_port_create_info_t *port_create_info, uint8_t channel,
    uint8_t auto_generate_port_flag, uint16_t *port)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

创建服务端port
支持通过uuid、名称等参数指定服务端port属性
支持由profile自动分配port号或指定固定port号

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖已注册port相关回调函数 bs_br_port_register_callbacks

入参

名称	参数类型	详细说明	约束取值范围
port_create_info	bs_br_port_create_info_t *	创建server端port相关参数	非NULL
channel	uint8_t	固定通道标识，和auto_generate_port_flag配合使用	-
auto_generate_port_flag	uint8_t	是否由profile创建port，为0时由profile分配，为1时为指定port	`0` `1`

出参

名称	数据类型	输出说明
port	uint16_t *	分配的port号

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	创建服务端port成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_create_remote_port

errcode_t bs_br_port_create_remote_port(bt_uuid_t *uuid, uint8_t channel, uint16_t port)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

设置服务端固定port
通过uuid和固定通道标识指定对端固定的port号
用于建立与对端固定port的映射关系

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖已注册port相关回调函数 bs_br_port_register_callbacks

入参

名称	参数类型	详细说明	约束取值范围
uuid	bt_uuid_t *	应用uuid	非NULL
channel	uint8_t	固定通道标识	-
port	uint16_t	对端固定的port号	-

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	设置服务端固定port成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_destroy

errcode_t bs_br_port_destroy(uint16_t port)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

服务端删除port
释放指定port号对应的资源
删除后该port不再可用

前置条件

调用时序约束：当前接口必须在 bs_br_port_create_server_port 成功返回后调用
依赖关系：当前接口依赖指定port已创建

入参

名称	参数类型	详细说明	约束取值范围
port	uint16_t	待删除的port	-

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	删除port成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_connect

errcode_t bs_br_port_connect(uint16_t dev_id, bt_uuid_t *uuid, uint8_t find_remote_flag)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

发起port连接
服务发现并创建客户端port，收到响应后在bs_br_port_conn_state_changed_callback中返回本端port和连接状态
支持指定是否需要服务发现对端port

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖已注册port相关回调函数 bs_br_port_register_callbacks

入参

名称	参数类型	详细说明	约束取值范围
dev_id	uint16_t	设备id	-
uuid	bt_uuid_t *	应用uuid	非NULL
find_remote_flag	uint8_t	是否需要服务发现对端port，若为固定port则不需要做服务发现	-

返回值

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

bs_br_port_connect_by_addr

errcode_t bs_br_port_connect_by_addr(bd_addr_t addr, bt_uuid_t *uuid, uint8_t find_remote_flag)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

通过设备地址发起port连接
服务发现并创建客户端port，收到响应后在bs_br_port_conn_state_changed_callback中返回本端port和连接状态
支持指定是否需要服务发现对端port

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖已注册port相关回调函数 bs_br_port_register_callbacks

入参

名称	参数类型	详细说明	约束取值范围
addr	bd_addr_t	设备地址	-
uuid	bt_uuid_t *	应用uuid	非NULL
find_remote_flag	uint8_t	是否需要服务发现对端port，若为固定port则不需要做服务发现	-

返回值

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

bs_br_port_send_conn_rsp

errcode_t bs_br_port_send_conn_rsp(uint16_t port, uint8_t is_accept)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

向远程设备发送连接响应，指示是否接受或拒绝连接请求
在收到bs_br_port_connection_request_callback回调后调用
支持接受或拒绝连接请求
可通过配置该配置项：BR_CONFIG_PORT_CONNECT_MODE，配置服务端自动回复连接

前置条件

调用时序约束：当前接口必须在 bs_br_port_connection_request_callback 回调触发后调用
依赖关系：当前接口依赖已创建服务端port bs_br_port_create_server_port

入参

名称	参数类型	详细说明	约束取值范围
port	uint16_t	要回复的port连接的端口号	-
is_accept	uint8_t	指示是否接受连接请求	`0`（拒绝） `1`（接受）

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	发送连接响应成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_disconnect

errcode_t bs_br_port_disconnect(uint16_t dev_id, uint16_t port)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

客户端断开port连接
断开后连接状态通过bs_br_port_conn_state_changed_callback回调上报
释放该连接对应的客户端port资源

前置条件

调用时序约束：当前接口必须在 bs_br_port_connect 或 bs_br_port_connect_by_addr 成功建立连接后调用
依赖关系：当前接口依赖指定dev_id和port已处于连接状态

入参

名称	参数类型	详细说明	约束取值范围
dev_id	uint16_t	设备ID	-
port	uint16_t	客户端port	-

返回值

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

bs_br_port_write_data

errcode_t bs_br_port_write_data(uint16_t dev_id, uint16_t port, const uint8_t *data, const uint16_t len)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

通过port发送数据
数据长度最大为BR_PORT_SERVICE_MAX_DATA_LEN，超过最大长度会发送失败
发送数据到指定设备的指定port

前置条件

调用时序约束：当前接口必须在 bs_br_port_connect 或 bs_br_port_connect_by_addr 成功建立连接后调用
依赖关系：当前接口依赖指定dev_id和port已处于连接状态

入参

名称	参数类型	详细说明	约束取值范围
dev_id	uint16_t	设备id	-
port	uint16_t	本端port	-
data	const uint8_t *	要发送的业务数据	非NULL
len	const uint16_t	发送的业务数据长度	`0` ~ `990`

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	数据发送成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_register_callbacks

errcode_t bs_br_port_register_callbacks(bt_uuid_t *uuid, bs_br_port_callbacks_t *func)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

注册本端port相关回调
回调包括连接状态变化回调、数据接收回调和连接请求回调
通过uuid关联应用与回调函数

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖uuid和回调函数结构体均已初始化

入参

名称	参数类型	详细说明	约束取值范围
uuid	bt_uuid_t *	应用的uuid	非NULL
func	bs_br_port_callbacks_t *	需要注册的回调函数	非NULL

返回值

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

bs_br_port_unregister_callbacks

errcode_t bs_br_port_unregister_callbacks(bt_uuid_t *uuid)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

去注册本端port相关回调
通过uuid取消已注册的回调函数
去注册后不再接收该uuid对应的连接状态、数据接收和连接请求回调

前置条件

调用时序约束：当前接口必须在 bs_br_port_register_callbacks 成功注册回调后调用
依赖关系：当前接口依赖指定uuid已注册回调函数

入参

名称	参数类型	详细说明	约束取值范围
uuid	bt_uuid_t *	应用的uuid	非NULL

返回值

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

bs_br_port_enable

errcode_t bs_br_port_enable(void)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

使能bs port功能
使能后可进行port的创建、连接、数据收发等操作
调用前需确保蓝牙协议栈已初始化

前置条件

调用时序约束：当前接口必须在蓝牙协议栈初始化完成后调用
依赖关系：当前接口依赖蓝牙BR/EDR协议栈已就绪

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	使能成功
Other	其他错误码，参考errcode_bt_t	执行失败

bs_br_port_disable

errcode_t bs_br_port_disable(void)

头文件清单

#include "protocol/bt/host/include/bs_service/bs_br_service_port_api.h"

功能说明

去使能bs port功能
去使能后port的创建、连接、数据收发等操作将不可用
调用前需确保已断开所有port连接

前置条件

调用时序约束：当前接口必须在 bs_br_port_enable 成功返回后调用
依赖关系：当前接口依赖所有port连接已断开

返回值

返回值	文字含义	触发场景
ERRCODE_BT_SUCCESS(0x00)	执行成功	去使能成功
Other	其他错误码，参考errcode_bt_t	执行失败

Type definitions

bs_br_port_conn_state_changed_callback

typedef void (*bs_br_port_conn_state_changed_callback)(uint16_t dev_id, uint16_t port, uint8_t state);

使用说明

bs_br_port_callbacks_t结构体成员conn_state_cbk的类型，用于上报port连接状态变化事件。调用时机：当port连接状态发生变化时，由协议栈内部调用此回调函数上报给上层应用。

bs_br_port_receive_data_callback

typedef void (*bs_br_port_receive_data_callback)(uint16_t dev_id, uint16_t port, uint8_t *data, uint16_t data_len);

使用说明

bs_br_port_callbacks_t结构体成员receive_data_cbk的类型，用于上报port接收数据事件。调用时机：当通过port接收到远端数据时，由协议栈内部调用此回调函数上报给上层应用。

bs_br_port_connection_request_callback

typedef void (*bs_br_port_connection_request_callback)(uint16_t dev_id, uint16_t port);

使用说明

bs_br_port_callbacks_t结构体成员conn_req_cbk的类型，用于上报port连接请求事件。调用时机：当远端设备发起port连接请求时，由协议栈内部调用此回调函数通知上层应用。

Enumerations

errcode_bt_t

// 来源: bt_errcode.h (SDK公共基础类型)
// ERRCODE_BT_SUCCESS = 0x00, 其余成员参考bt_errcode.h

枚举成员	取值	描述
ERRCODE_BT_SUCCESS	0x00	执行成功 [SDK公共基础类型]

注：errcode_bt_t完整枚举定义位于SDK公共头文件bt_errcode.h中，此处仅列出本模块接口直接引用的成员。

Structures

bs_br_port_callbacks_t

typedef struct {
    bs_br_port_conn_state_changed_callback conn_state_cbk;
    bs_br_port_receive_data_callback receive_data_cbk;
    bs_br_port_connection_request_callback conn_req_cbk;
} bs_br_port_callbacks_t;

成员说明

成员名称	数据类型	描述
conn_state_cbk	bs_br_port_conn_state_changed_callback	bs port连接状态回调函数
receive_data_cbk	bs_br_port_receive_data_callback	bs port数据接收回调函数
conn_req_cbk	bs_br_port_connection_request_callback	bs port连接请求回调函数

bs_br_port_create_info_t

typedef struct {
    bt_uuid_t uuid;
    char *name;
    uint8_t name_len;
} bs_br_port_create_info_t;

成员说明

成员名称	数据类型	描述
uuid	bt_uuid_t	应用uuid，支持2位或16位
name	char *	port Server名称
name_len	uint8_t	port Server名称长度

bt_uuid_t

// 来源: include/middleware/services/bts/common/bts_def.h
typedef struct {
    uint8_t uuid_len;
    uint8_t uuid[BT_UUID_MAX_LEN];
} bt_uuid_t;

成员说明

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

使用说明

本模块多个接口的入参类型（bs_br_port_create_remote_port、bs_br_port_connect、bs_br_port_connect_by_addr、bs_br_port_register_callbacks、bs_br_port_unregister_callbacks），以及bs_br_port_create_info_t结构体成员类型 [SDK公共基础类型]

bd_addr_t

// 来源: include/middleware/services/bts/common/bts_def.h
typedef struct {
    uint8_t addr[BD_ADDR_LEN];
    uint8_t type;
} bd_addr_t;

成员说明

成员名称	数据类型	描述
addr	uint8_t[]	蓝牙地址
type	uint8_t	蓝牙地址类型

使用说明

bs_br_port_connect_by_addr接口入参类型 [SDK公共基础类型]

Macros

BR_PORT_SERVICE_MAX_DATA_LEN

#define BR_PORT_SERVICE_MAX_DATA_LEN 990