openharmony 鸿蒙 js-apis-bluetooth-socket

2025-06-12 浏览 (1)

@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。

参数：

参数名类型必填说明
namestring是服务的名称。
optionsSppOptions是spp监听配置参数。
callbackAsyncCallback<number>是表示回调函数的入参，服务端Socket的id。

错误码：

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

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

参数：

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

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801Capability not supported.
2900001Service stopped.
2900003Bluetooth disabled.
2900004Profile not supported.
2900099Operation 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, clientNumber = ' + 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。

参数：

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

错误码：

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

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

示例：

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

let clientSocket = (code: BusinessError, number: number) => {
  if (code) {
    console.error('sppConnect error, code is ' + code);
    return;
  } else {
    // 获取的number用作客户端后续读/写操作的socket id。
    console.info('bluetooth clientSocket 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.getDeviceId17+

getDeviceId(clientSocket: number): string

通过clientSocket获取对端设备地址。服务端、客户端均可调用，传入非法clientSocket无法获取。

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

参数：

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

返回值：

类型说明
string返回对端设备地址，例如："XX:XX:XX:XX:XX:XX"。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID错误信息
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.

示例：

import { socket } from '@kit.ConnectivityKit';
import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
// 服务端获取客户端设备地址。
let clientSocket = -1; // clientSocket是sppAccept回调中得到的，调getDeviceId接口前需更新clientSocket。
try {
    let deviceAddr: string = socket.getDeviceId(clientSocket);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

// 客户端获取服务端设备地址。
// clientSocket是sppConnect回调中得到的，调getDeviceId接口前需更新clientSocket。
try {
    let deviceAddr: string = socket.getDeviceId(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。

参数：

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

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801Capability not supported.
2900001Service stopped.
2900099Operation 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。

参数：

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

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801Capability not supported.
2900001Service stopped.
2900099Operation 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。

参数：

参数名类型必填说明
clientSocketnumber是客户端socket的id。
dataArrayBuffer是写入的数据。

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801Capability not supported.
2901054IO error.
2900099Operation 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。

参数：

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

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801Capability not supported.
2901054IO error.
2900099Operation 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。

参数：

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

错误码：

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

错误码ID错误信息
401Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.
801Capability 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);
}

socket.sppWriteAsync18+

sppWriteAsync(clientSocket: number, data: ArrayBuffer): Promise<void>

通过socket向远端发送数据的异步接口，该接口支持断开连接时SPP操作异常错误返回。

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

参数：

参数名类型必填说明
clientSocketnumber是客户端Socket的id。
dataArrayBuffer是写入的数据。

返回值：

类型说明
Promise<void>以Promise的形式返回结果。如果成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID错误信息
801Capability not supported.
2901054IO error.
2900099Operation failed.

示例：

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

socket.sppReadAsync18+

sppReadAsync(clientSocket: number): Promise<ArrayBuffer>

通过socket读取对端所发送数据的异步接口，该接口支持断开连接时SPP操作异常错误返回。

注意：

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

参数：

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

返回值：

类型说明
Promise<ArrayBuffer>以Promise的形式返回读取数据结果。如果成功，值在ArrayBuffer中返回，如果失败，返回对应错误码。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID错误信息
801Capability not supported.
2901054IO error.
2900099Operation failed.

示例：

import { socket } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';
let clientNumber = -1; // 入参clientNumber由sppAccept或sppConnect接口获取。
let buffer = new ArrayBuffer(1024);
let data = new Uint8Array(buffer);
let flag = 1;
while (flag) {
  try {
    socket.sppReadAsync(clientNumber).then((outBuffer: ArrayBuffer) => {
      buffer = outBuffer;
    });
    if (buffer != null) {
      console.info('sppRead success, data = ' + JSON.stringify(buffer));
    } else {
      console.error('sppRead error, data is null');
    }
  } catch (err) {
    flag = 0;
    console.error('startSppRead errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
  }
}

SppOptions

描述spp的配置参数。

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

名称类型只读可选说明
uuidstring否否spp单据的uuid。
secureboolean否否是否是安全通道。true表示是安全通道，false表示非安全通道。
typeSppType否否Spp链路类型。

SppType

枚举，Spp链路类型。

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

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Connectivity Kit（短距通信服务）

harmony 鸿蒙Bluetooth

harmony 鸿蒙Wifi

harmony 鸿蒙蓝牙服务子系统错误码

harmony 鸿蒙NFC错误码

harmony 鸿蒙SE(secureElement)错误码

harmony 鸿蒙WIFI错误码

harmony 鸿蒙@ohos.bluetooth.a2dp (蓝牙a2dp模块)(系统接口)

harmony 鸿蒙@ohos.bluetooth.a2dp (蓝牙a2dp模块)

harmony 鸿蒙@ohos.bluetooth.access (蓝牙access模块)(系统接口)

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/H95OZN