[UTS蓝牙插件文档] createSPPClient 接口描述文档

createSPPClient

创建 SPP 客户端连接（主动连接目标设备的 RFCOMM 服务）。

所属能力组：经典蓝牙 SPP（Serial Port Profile / RFCOMM）串口通信
支持平台：Android、鸿蒙 NEXT（iOS 不支持，统一回调错误码 10020）

功能说明

以客户端身份主动向目标设备的指定 UUID 服务发起 RFCOMM 连接。连接成功后返回一个自增的 socketId，后续的数据收发（writeSPPValue）、关闭（closeSPPClient）以及事件（onSPPReceiveData、onSPPConnectionStateChange）均以该 socketId 作为索引。

• 客户端连接与服务端（createSPPServer）是两条独立路径，二者连上后产出的都是 socketId，共用同一套收发 / 关闭 / 事件体系。
• 连接前会先取消正在进行的经典蓝牙发现（cancelDiscovery），避免与连接流程争抢资源。
• 连接过程为阻塞 IO，插件内部已放到子线程执行，不会阻塞 UI。

请求参数 CreateSPPClientOptions

参数	类型	必填	默认值	说明
deviceId	string	是	-	目标设备 id（Android 为 MAC 地址；鸿蒙 NEXT 为设备地址，须由经典蓝牙搜索或已配对设备列表获得）
uuid	string	是	-	要连接的 RFCOMM 服务 UUID（支持 16/32/128 位），必须与服务端监听的 UUID 完全一致
secure	boolean	否	true	是否为安全连接（认证 + 加密）；false 表示使用非安全 RFCOMM 通道
timeout	number	否	系统默认	连接超时时间，单位 ms
success	function	否	-	接口调用成功的回调函数
fail	function	否	-	接口调用失败的回调函数
complete	function	否	-	接口调用结束的回调函数（成功、失败都会执行）

不传 success / fail / complete 时，接口返回 Promise。

成功回调结果 CreateSPPClientSuccessCallbackResult

字段	类型	说明
socketId	number	已建立的 SPP 连接（客户端）的唯一标识，后续收发 / 关闭均以此索引
deviceId	string	目标设备 id
errMsg	string	错误信息，成功时为 createSPPClient:ok

返回 Promise

未传任何回调时返回 Promise<CreateSPPClientSuccessCallbackResult>。

错误码

错误码	说明
10013	连接 deviceId 为空或格式不正确
10002	没有找到指定设备
10021	SPP 连接失败
10000	未初始化蓝牙适配器
10001	当前蓝牙适配器不可用
10008	系统异常
10020	当前平台不支持 SPP（iOS）

示例

import * as UTSBLE from '@/uni_modules/xl-uts-bluetooth/jssdk/BLE.js';

// 回调风格
UTSBLE.createSPPClient({
    deviceId: 'AA:BB:CC:DD:EE:FF',
    uuid: '00009999-0000-1000-8000-00805F9B34FB',
    secure: true,
    timeout: 20000,
    success: (res) => {
        console.log('连接成功 socketId =', res.socketId);
    },
    fail: (err) => {
        console.error('连接失败', err.errCode, err.errMsg);
    },
});

// Promise 风格
const res = await UTSBLE.createSPPClient({
    deviceId: 'AA:BB:CC:DD:EE:FF',
    uuid: '00009999-0000-1000-8000-00805F9B34FB',
});
console.log('socketId =', res.socketId);