fb14ac8e创建于 2025年1月20日历史提交

@ohos.bluetooth.socket (蓝牙socket模块)

socket模块提供了操作和管理蓝牙socket的方法。

说明：

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { socket } from '@kit.ConnectivityKit';

socket.sppListen

sppListen(name: string, options: SppOptions, callback: AsyncCallback<number>): void

创建一个服务端监听Socket。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
name	string	是	服务的名称。
options	SppOptions	是	spp监听配置参数。
callback	AsyncCallback<number>	是	表示回调函数的入参，服务端Socket的id。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900004	Profile not supported.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let serverNumber = -1;
let serverSocket = (code: BusinessError, number: number) => {
  if (code) {
    console.error('sppListen error, code is ' + code);
    return;
  } else {
    serverNumber = number;
    console.info('sppListen success, serverNumber = ' + serverNumber);
  }
}

let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
try {
    socket.sppListen('server1', sppOption, serverSocket);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.sppAccept

sppAccept(serverSocket: number, callback: AsyncCallback<number>): void

服务端监听socket等待客户端连接。使用Callback异步回调。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
serverSocket	number	是	服务端socket的id。
callback	AsyncCallback<number>	是	表示回调函数的入参，客户端socket的id。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900004	Profile not supported.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1;
let serverNumber = -1;
let acceptClientSocket = (code: BusinessError, number: number) => {
  if (code) {
    console.error('sppListen error, code is ' + code);
    return;
  } else {
    clientNumber = number; // 获取的clientNumber用作客户端后续读/写操作socket的id。
    console.info('sppListen success, serverNumber = ' + clientNumber);
  }
}
try {
    socket.sppAccept(serverNumber, acceptClientSocket); // serverNumber是sppListen回调中得到的serverNumber。
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.sppConnect

sppConnect(deviceId: string, options: SppOptions, callback: AsyncCallback<number>): void

客户端向远端设备发起spp连接。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
deviceId	string	是	对端设备地址，例如："XX:XX:XX:XX:XX:XX"。
options	SppOptions	是	spp客户端连接配置参数。
callback	AsyncCallback<number>	是	表示回调函数的入参，客户端socket的id。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900004	Profile not supported.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';

let clientSocket = (code: BusinessError, number: number) => {
  if (code) {
    console.error('sppListen error, code is ' + code);
    return;
  } else {
    // 获取的number用作客户端后续读/写操作socket的id。
    console.info('bluetooth serverSocket Number: ' + number);
  }
}
let sppOption:socket.SppOptions = {uuid: '00001810-0000-1000-8000-00805F9B34FB', secure: false, type: 0};
try {
    socket.sppConnect('XX:XX:XX:XX:XX:XX', sppOption, clientSocket);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.sppCloseServerSocket

sppCloseServerSocket(socket: number): void

关闭服务端监听Socket，入参socket由sppListen接口返回。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
socket	number	是	服务端监听socket的id。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let serverNumber = -1; // 此处serverNumber需赋值为调用sppListen接口后，回调中得到的serverNumber。
try {
    socket.sppCloseServerSocket(serverNumber);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.sppCloseClientSocket

sppCloseClientSocket(socket: number): void

关闭客户端socket，入参socket由sppAccept或sppConnect接口获取。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
socket	number	是	客户端socket的id。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2900001	Service stopped.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
try {
    socket.sppCloseClientSocket(clientNumber);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.sppWrite

sppWrite(clientSocket: number, data: ArrayBuffer): void

通过socket向远端发送数据，入参clientSocket由sppAccept或sppConnect接口获取。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
clientSocket	number	是	客户端socket的id。
data	ArrayBuffer	是	写入的数据。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2901054	IO error.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
let arrayBuffer = new ArrayBuffer(8);
let data = new Uint8Array(arrayBuffer);
data[0] = 123;
try {
    socket.sppWrite(clientNumber, arrayBuffer);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.on('sppRead')

on(type: 'sppRead', clientSocket: number, callback: Callback<ArrayBuffer>): void

订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。使用Callback异步回调。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
type	string	是	填写"sppRead"字符串，表示spp读请求事件。
clientSocket	number	是	客户端socket的id。
callback	Callback<ArrayBuffer>	是	表示回调函数的入参，读取到的数据。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.
2901054	IO error.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
let dataRead = (dataBuffer: ArrayBuffer) => {
    let data = new Uint8Array(dataBuffer);
    console.info('bluetooth data is: ' + data[0]);
}
try {
    socket.on('sppRead', clientNumber, dataRead);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

socket.off('sppRead')

off(type: 'sppRead', clientSocket: number, callback?: Callback<ArrayBuffer>): void

取消订阅spp读请求事件，入参clientSocket由sppAccept或sppConnect接口获取。

系统能力：SystemCapability.Communication.Bluetooth.Core。

参数：

参数名	类型	必填	说明
type	string	是	填写"sppRead"字符串，表示spp读请求事件。
clientSocket	number	是	客户端Socket的id。
callback	Callback<ArrayBuffer>	否	表示取消订阅spp读请求事件上报。不填该参数则取消订阅该type对应的所有回调。

错误码：

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID	错误信息
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801	Capability not supported.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
try {
    socket.off('sppRead', clientNumber);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

SppOptions

描述spp的配置参数。

系统能力：SystemCapability.Communication.Bluetooth.Core。

名称	类型	可读	可写	说明
uuid	string	是	是	spp单据的uuid。
secure	boolean	是	是	是否是安全通道。true表示是安全通道，false表示非安全通道。
type	SppType	是	是	Spp链路类型。

SppType

枚举，Spp链路类型。

系统能力：SystemCapability.Communication.Bluetooth.Core。

名称	值	说明
SPP_RFCOMM	0	表示rfcomm链路类型。