chrome.bluetoothSocket

说明

使用 chrome.bluetoothSocket API，通过 RFCOMM 和 L2CAP 连接向蓝牙设备发送和接收数据。

清单

必须在清单中声明以下键才能使用此 API。

"bluetooth"

类型

AcceptError

枚举

"system_error"
发生了系统错误，连接可能无法恢复。

"not_listening"
套接字未监听。

AcceptErrorInfo

属性

  • 错误

    AcceptError

    一个错误代码，指示出了什么问题。

  • 错误消息

    字符串

    错误消息。

  • socketId

    number

    服务器套接字标识符。

AcceptInfo

属性

  • clientSocketId

    number

    客户端套接字标识符，即新建立的连接的套接字标识符。此套接字标识符只能与 chrome.bluetoothSocket 命名空间中的函数一起使用。请注意，客户端套接字最初处于暂停状态，必须由应用明确取消暂停，然后才能开始接收数据。

  • socketId

    number

    服务器套接字标识符。

CreateInfo

属性

  • socketId

    number

    新创建的套接字的 ID。请注意，通过此 API 创建的套接字 ID 与通过其他 API（例如 [sockets.tcp](../sockets_tcp/) API）创建的套接字 ID 不兼容。

ListenOptions

属性

  • 积压

    编号（选填）

    套接字的监听队列的长度。默认值取决于操作系统的主机子系统。

  • 频道

    编号（选填）

    listenUsingRfcomm 使用的 RFCOMM 通道。如果已指定，则之前不得使用该渠道，否则方法调用将失败。如果未指定，系统会自动分配未使用的通道。

  • PSM

    编号（选填）

    listenUsingL2cap 使用的 L2CAP PSM。如果指定，则该 PSM 之前必须未被使用过，否则方法调用会失败。如果未指定，系统将自动分配未使用的 PSM。

ReceiveError

枚举

"disconnect"
连接已断开。

"system_error"
发生了系统错误，连接可能无法恢复。

"not_connection"
套接字尚未连接。

ReceiveErrorInfo

属性

  • 错误

    ReceiveError

    一个错误代码，指示出了什么问题。

  • 错误消息

    字符串

    错误消息。

  • socketId

    number

    套接字标识符。

ReceiveInfo

属性

  • 数据

    数组缓冲区

    接收的数据，大小上限为 bufferSize。

  • socketId

    number

    套接字标识符。

SocketInfo

属性

  • 地址

    字符串（可选）

    如果底层套接字已连接，则包含它所连接的设备的蓝牙地址。

  • bufferSize

    编号（选填）

    用于接收数据的缓冲区大小。如果未明确指定缓冲区空间，则不提供该值。

  • 已连接

    布尔值

    指示套接字是否已连接到远程对等方的标志。

  • name

    字符串（可选）

    与套接字关联的应用定义的字符串。

  • 已暂停

    布尔值

    一个标志，指示已连接的套接字是否阻止其对等方发送更多数据，或者监听套接字上的连接请求是通过 onAccept 事件分派还是在监听队列积压中排队。请参阅 setPaused。默认值为 “False”。

  • 持久性

    布尔值

    此标记指示在卸载应用的事件页面时套接字是否保持打开状态（请参阅 SocketProperties.persistent）。默认值为“false”。

  • socketId

    number

    套接字标识符。

  • uuid

    字符串（可选）

    如果底层套接字已连接，则包含有关其所连接的服务 UUID 的信息，否则，如果底层套接字正在监听，则包含有关其所监听的服务 UUID 的信息。

SocketProperties

属性

  • bufferSize

    编号（选填）

    用于接收数据的缓冲区大小。默认值为 4096。

  • name

    字符串（可选）

    与套接字关联的应用定义的字符串。

  • 持久性

    布尔值（可选）

    此标记指示在应用的事件页面卸载时套接字是否保持打开状态（请参阅管理应用生命周期）。默认值为 false.。加载应用时，可以使用 getSockets 提取之前使用 persistent=true 打开的任何套接字。

方法

close()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.close(
  socketId: number,
  callback?: function,
)

断开并销毁套接字。创建的每个套接字都应在使用后关闭。调用函数后，套接字 ID 立即失效。但是，可以保证仅在调用回调函数时关闭套接字。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

connect()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.connect(
  socketId: number,
  address: string,
  uuid: string,
  callback?: function,
)

将套接字连接到远程蓝牙设备。如果 connect 操作成功完成，系统会在从对等端接收数据时引发 onReceive 事件。如果在运行时接收数据包时发生网络错误，将引发 onReceiveError 事件，此时不会再针对此套接字引发 onReceive 事件，直到调用 setPaused(false) 方法。

参数

  • socketId

    number

    套接字标识符。

  • 地址

    字符串

    蓝牙设备的地址。

  • uuid

    字符串

    要连接的服务的 UUID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

create()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.create(
  properties?: SocketProperties,
  callback?: function,
)

创建蓝牙套接字。

参数

  • 媒体资源

    SocketProperties 可选

    套接字属性（可选）。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      套接字创建的结果。

返回

  • Promise&lt;CreateInfo&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

disconnect()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.disconnect(
  socketId: number,
  callback?: function,
)

断开套接字。套接字标识符仍然有效。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getInfo()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.getInfo(
  socketId: number,
  callback?: function,
)

检索给定套接字的状态。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含套接字信息的对象。

返回

  • Promise&lt;SocketInfo&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getSockets()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.getSockets(
  callback?: function,
)

检索应用拥有的当前打开的套接字的列表。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (sockets: SocketInfo[]) => void

返回

  • Promise&lt;SocketInfo[]&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

listenUsingL2cap()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.listenUsingL2cap(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
)

监听使用 L2CAP 协议的连接。

参数

  • socketId

    number

    套接字标识符。

  • uuid

    字符串

    要监听的服务 UUID。

  • 选项

    ListenOptions 可选

    可选的服务的其他选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

listenUsingRfcomm()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.listenUsingRfcomm(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
)

监听使用 RFCOMM 协议的连接。

参数

  • socketId

    number

    套接字标识符。

  • uuid

    字符串

    要监听的服务 UUID。

  • 选项

    ListenOptions 可选

    可选的服务的其他选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

send()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.send(
  socketId: number,
  data: ArrayBuffer,
  callback?: function,
)

在指定的蓝牙套接字上发送数据。

参数

  • socketId

    number

    套接字标识符。

  • 数据

    数组缓冲区

    要发送的数据。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (bytesSent: number) => void

    • bytesSent

      number

      发送的字节数。

返回

  • Promise&lt;number&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setPaused()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

启用或停用已连接的套接字从其对等方接收消息，或允许或禁止监听套接字接受新连接。默认值为“false”。暂停已连接的套接字通常由应用用于限制其对等方发送的数据。当连接的套接字暂停时，不会引发 onReceive 事件。连接并取消暂停套接字后，系统会在收到消息时再次引发 onReceive 事件。当监听套接字暂停时，系统会接受新的连接，直到其积压的容量已满，然后其他连接请求会被拒绝。只有当套接字取消暂停时，才会引发 onAccept 事件。

参数

  • socketId

    number

  • 已暂停

    布尔值

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.bluetoothSocket.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

更新套接字属性。

参数

  • socketId

    number

    套接字标识符。

  • 媒体资源

    SocketProperties

    要更新的属性。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onAccept

chrome.bluetoothSocket.onAccept.addListener(
  callback: function,
)

为指定套接字建立连接时触发的事件。

参数

onAcceptError

chrome.bluetoothSocket.onAcceptError.addListener(
  callback: function,
)

运行时在等待指定套接字上的新连接时发生网络错误时引发的事件。引发此事件后，套接字将设置为 paused，并且不会再针对此套接字引发 onAccept 事件。

参数

onReceive

chrome.bluetoothSocket.onReceive.addListener(
  callback: function,
)

收到指定套接字的数据时触发的事件。

参数

onReceiveError

chrome.bluetoothSocket.onReceiveError.addListener(
  callback: function,
)

运行时在等待套接字上的数据时发生网络错误时引发的事件。引发此事件后，套接字将设置为 paused，并且不会再针对此套接字引发 onReceive 事件。

参数