chrome.socket

说明

使用 chrome.socket API，使用 TCP 和 UDP 连接通过网络发送和接收数据。注意：从 Chrome 33 开始，此 API 已被废弃，取而代之的是 sockets.udp、sockets.tcp 和 sockets.tcpServer API。

权限

socket

类型

AcceptInfo

属性

• resultCode

  number

• socketId

  编号（选填）

  已接受的套接字的 ID。

CreateInfo

属性

• socketId

  number

  新创建的套接字的 ID。

CreateOptions

NetworkInterface

属性

• 地址

  字符串

  可用的 IPv4/6 地址。

• name

  字符串

  适配器的基础名称。在 *nix 上，通常为“eth0”、“lo”等。

• prefixLength

  number

  前缀长度

ReadInfo

属性

• 数据

  数组缓冲区

• resultCode

  number

  从底层 read() 调用返回的 resultCode。

RecvFromInfo

属性

• 地址

  字符串

  远程机器的地址。

• 数据

  数组缓冲区

• 端口

  number

• resultCode

  number

  从底层 recvfrom() 调用返回的 resultCode。

SecureOptions

属性

• tlsVersion

  TLSVersionConstraints 可选

SocketInfo

属性

• 已连接

  布尔值

  底层套接字是否已连接。

  对于 tcp 套接字，即使远程对等端已断开连接，此字段仍将保持为 true。读取或写入套接字可能会导致错误，提示应通过 disconnect() 断开此套接字。

  对于 udp 套接字，这仅表示是否已指定用于读取和写入数据包的默认远程地址。

• localAddress

  字符串（可选）

  如果底层套接字已绑定或连接，则包含其本地 IPv4/6 地址。

• localPort

  编号（选填）

  如果底层套接字已绑定或连接，则包含其本地端口。

• peerAddress

  字符串（可选）

  如果底层套接字已连接，则包含对等的 IPv4/6 地址。

• peerPort

  编号（选填）

  如果底层套接字已连接，则包含已连接对等体的端口。

• socketType

  SocketType

  所传递的套接字的类型。其值将为 tcp 或 udp。

SocketType

枚举

"tcp"

“udp”

TLSVersionConstraints

属性

• max

  字符串（可选）

• 分钟

  字符串（可选）

  可接受的最低和最高 TLS 版本。支持的值为 tls1.2 或 tls1.3。

  值 tls1 和 tls1.1 不再受支持。如果 min 设置为其中一个值，系统会静默地将其限制到 tls1.2。如果 max 设置为其中一个值或任何其他无法识别的值，则会被静默忽略。

WriteInfo

属性

• bytesWritten

  number

  已发送的字节数或负数错误代码。

方法

accept()

chrome.socket.accept(
  socketId: number,
  callback: function,
)

此方法仅适用于 TCP 套接字。注册在此监听服务器套接字上接受连接时要调用的回调函数。必须先调用“监听”功能。如果已有有效的接受回调，则将立即调用此回调，并将错误作为 resultCode。

参数

• socketId

  number

  socketId。

• callback

  函数

  callback 参数如下所示：

  (acceptInfo: AcceptInfo) => void

  • acceptInfo

    AcceptInfo

bind()

chrome.socket.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
)

绑定套接字的本地地址。它目前不支持 TCP 套接字。

参数

• socketId

  number

  socketId。

• 地址

  字符串

  本地计算机的地址。

• 端口

  number

  本地计算机的端口。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

connect()

chrome.socket.connect(
  socketId: number,
  hostname: string,
  port: number,
  callback: function,
)

将套接字连接到远程机器（针对 tcp 套接字）。对于 udp 套接字，此设置用于为 read() 和 write() 调用设置接收和读取数据包的默认地址。

参数

• socketId

  number

  socketId。

• 主机名

  字符串

  远程计算机的主机名或 IP 地址。

• 端口

  number

  远程机器的端口。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

create()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.socket.create(
  type: SocketType,
  options?: CreateOptions,
  callback?: function,
)

创建指定类型的套接字，该套接字将连接到指定的远程机器。

参数

• 类型

  SocketType

  要创建的套接字类型。必须为 tcp 或 udp。

• 选项

  CreateOptions 可选

  套接字选项。

• callback

  函数（可选）

  callback 参数如下所示：

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

返回

• Promise&lt;CreateInfo&gt;

  Chrome 121 及更高版本

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

destroy()

chrome.socket.destroy(
  socketId: number,
)

销毁套接字。创建的每个套接字都应在使用后销毁。

参数

• socketId

  number

  socketId。

disconnect()

chrome.socket.disconnect(
  socketId: number,
)

断开套接字。对于 UDP 套接字，disconnect 不是操作，但可以安全调用。

参数

• socketId

  number

  socketId。

getInfo()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.socket.getInfo(
  socketId: number,
  callback?: function,
)

检索给定套接字的状态。

参数

• socketId

  number

  socketId。

• callback

  函数（可选）

  callback 参数如下所示：

  (result: SocketInfo) => void

  • 结果

    SocketInfo

返回

• Promise&lt;SocketInfo&gt;

  Chrome 121 及更高版本

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

getJoinedGroups()

chrome.socket.getJoinedGroups(
  socketId: number,
  callback: function,
)

获取套接字当前加入的多播组地址。

参数

• socketId

  number

  socketId。

• callback

  函数

  callback 参数如下所示：

  (groups: string[]) => void

  • 群组

    字符串[]

getNetworkList()

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.socket.getNetworkList(
  callback?: function,
)

检索此系统上的本地适配器的相关信息。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (result: NetworkInterface[]) => void

  • 结果

    NetworkInterface[]

返回

• Promise&lt;NetworkInterface[]&gt;

  Chrome 121 及更高版本

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

joinGroup()

chrome.socket.joinGroup(
  socketId: number,
  address: string,
  callback: function,
)

加入多播组，并开始接收来自该组的数据包。套接字必须为 UDP 类型，并且在调用此方法之前必须绑定到本地端口。

参数

• socketId

  number

  socketId。

• 地址

  字符串

  要加入的群组地址。不支持域名。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

leaveGroup()

chrome.socket.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
)

退出之前使用 joinGroup 加入的多播群组。在销毁套接字或退出之前，无需离开多播组。操作系统会自动调用该方法。

退出该组将阻止路由器向本地主机发送多播数据报，假设主机上没有其他进程仍加入该组。

参数

• socketId

  number

  socketId。

• 地址

  字符串

  要退出的群组地址。不支持域名。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

listen()

chrome.socket.listen(
  socketId: number,
  address: string,
  port: number,
  backlog?: number,
  callback: function,
)

此方法仅适用于 TCP 套接字。监听指定端口和地址上的连接。这实际上使其成为了服务器套接字，并且无法再对此套接字使用客户端套接字函数（连接、读取、写入）。

参数

• socketId

  number

  socketId。

• 地址

  字符串

  本地计算机的地址。

• 端口

  number

  本地计算机的端口。

• 积压

  编号（选填）

  套接字的监听队列的长度。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

read()

chrome.socket.read(
  socketId: number,
  bufferSize?: number,
  callback: function,
)

从指定的已连接套接字读取数据。

参数

• socketId

  number

  socketId。

• bufferSize

  编号（选填）

  读取缓冲区空间。

• callback

  函数

  callback 参数如下所示：

  (readInfo: ReadInfo) => void

  • readInfo

    ReadInfo

recvFrom()

chrome.socket.recvFrom(
  socketId: number,
  bufferSize?: number,
  callback: function,
)

从指定的 UDP 套接字接收数据。

参数

• socketId

  number

  socketId。

• bufferSize

  编号（选填）

  接收缓冲区空间。

• callback

  函数

  callback 参数如下所示：

  (recvFromInfo: RecvFromInfo) => void

  • recvFromInfo

    RecvFromInfo

secure()

chrome.socket.secure(
  socketId: number,
  options?: SecureOptions,
  callback: function,
)

通过已连接的 TCP 客户端套接字启动 TLS 客户端连接。

参数

• socketId

  number

  要使用的已连接套接字。

• 选项

  SecureOptions（可选）

  TLS 连接的约束条件和参数。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

sendTo()

chrome.socket.sendTo(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  callback: function,
)

将指定 UDP 套接字上的数据发送到指定的地址和端口。

参数

• socketId

  number

  socketId。

• 数据

  数组缓冲区

  要写入的数据。

• 地址

  字符串

  远程机器的地址。

• 端口

  number

  远程机器的端口。

• callback

  函数

  callback 参数如下所示：

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo

setKeepAlive()

chrome.socket.setKeepAlive(
  socketId: number,
  enable: boolean,
  delay?: number,
  callback: function,
)

启用或停用 TCP 连接的 keep-alive 功能。

参数

• socketId

  number

  socketId。

• 启用

  布尔值

  如果为 true，请启用持久连接功能。

• delay

  编号（选填）

  设置接收到的最后一个数据包与首次 keepalive 探测之间的延迟时间（以秒为单位）。默认值为 0。

• callback

  函数

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

setMulticastLoopbackMode()

chrome.socket.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
)

设置是否将从主机发送到多播组的多播数据包环回到主机。

注意：setMulticastLoopbackMode 的行为在 Windows 和类似 Unix 的系统之间略有不同。仅当同一主机上有多个应用加入同一多播组，而多播环回模式下的设置不同时，才会出现不一致的情况。在 Windows 上，关闭环回的应用将不会接收环回数据包；而在类似 Unix 的系统上，关闭环回的应用不会将环回数据包发送到同一主机上的其他应用。请参阅 MSDN：http://goo.gl/6vqbj

调用此方法不需要多播权限。

参数

• socketId

  number

  socketId。

• 已启用

  布尔值

  指示是否启用环回模式。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

setMulticastTimeToLive()

chrome.socket.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
)

设置发送至多播组的多播数据包的存留时间。

调用此方法不需要多播权限。

参数

• socketId

  number

  socketId。

• ttl

  number

  存留时间值。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

setNoDelay()

chrome.socket.setNoDelay(
  socketId: number,
  noDelay: boolean,
  callback: function,
)

针对 TCP 连接设置或清除 TCP_NODELAY。设置 TCP_NODELAY 后，Nagle 的算法将停用。

参数

• socketId

  number

  socketId。

• noDelay

  布尔值

  如果为 true，则停用 Nagle 的算法。

• callback

  函数

  callback 参数如下所示：

  (result: boolean) => void

  • 结果

    布尔值

write()

chrome.socket.write(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
)

在指定的已连接套接字上写入数据。

参数

• socketId

  number

  socketId。

• 数据

  数组缓冲区

  要写入的数据。

• callback

  函数

  callback 参数如下所示：

  (writeInfo: WriteInfo) => void

  • writeInfo

    WriteInfo