chrome.socket

说明

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

权限

socket

类型

AcceptInfo

属性

  • resultCode

    数值

  • socketId

    number 可选

    已接受套接字的 ID。

CreateInfo

属性

  • socketId

    数值

    新创建的套接字的 ID。

CreateOptions

NetworkInterface

属性

  • 地址

    字符串

    可用的 IPv4/6 地址。

  • name

    字符串

    适配器的底层名称。在 *nix 上，这通常是“eth0”“lo”等。

  • prefixLength

    数值

    前缀长度

ReadInfo

属性

  • 数据

    ArrayBuffer

  • resultCode

    数值

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

RecvFromInfo

属性

  • 地址

    字符串

    远程机器的地址。

  • 数据

    ArrayBuffer

  • 端口

    数值

  • resultCode

    数值

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

SecureOptions

属性

SocketInfo

属性

  • 已连接

    布尔值

    底层套接字是否已连接。

    对于 tcp 套接字，即使远程对等方已断开连接，此值仍将保持为 true。然后，读取或写入套接字可能会导致错误，表明应通过 disconnect() 断开此套接字的连接。

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

  • localAddress

    字符串（选填）

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

  • localPort

    number 可选

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

  • peerAddress

    字符串（选填）

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

  • peerPort

    number 可选

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

  • socketType

    SocketType

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

SocketType

枚举

“tcp”

“udp”

TLSVersionConstraints

属性

  • max

    字符串（选填）

  • 分钟

    字符串（选填）

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

    不再支持值 tls1 和 tls1.1。如果 min 设置为上述值之一，系统会将其静默钳制为 tls1.2。如果 max 设置为这些值之一或任何其他无法识别的值，系统会默默忽略该值。

WriteInfo

属性

  • bytesWritten

    数值

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

方法

accept()

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

此方法仅适用于 TCP 套接字。注册一个回调函数，当此监听服务器套接字上接受连接时，系统会调用该函数。必须先调用 Listen。如果已存在有效的接受回调，则会立即调用此回调，并将错误作为 resultCode。

参数

  • socketId

    数值

    socketId。

  • callback

    函数

    callback 参数如下所示： 

    (acceptInfo: AcceptInfo) => void

bind()

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

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

参数

  • socketId

    数值

    socketId。

  • 地址

    字符串

    本地计算机的地址。

  • 端口

    数值

    本地机器的端口。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

connect()

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

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

参数

  • socketId

    数值

    socketId。

  • 主机名

    字符串

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

  • 端口

    数值

    远程机器的端口。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

create()

Promise 
chrome.socket.create(
  type: SocketType,
  options?: CreateOptions,
  callback?: function,
): Promise<CreateInfo>

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

参数

  • 类型

    SocketType

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

  • 选项

    CreateOptions 可选

    套接字选项。

  • callback

    函数 可选

    callback 参数如下所示： 

    (createInfo: CreateInfo) => void

返回

  • Promise<CreateInfo>

    Chrome 121 及更高版本

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

destroy()

chrome.socket.destroy(
  socketId: number,
): void

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

参数

  • socketId

    数值

    socketId。

disconnect()

chrome.socket.disconnect(
  socketId: number,
): void

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

参数

  • socketId

    数值

    socketId。

getInfo()

Promise 
chrome.socket.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

检索给定套接字的状态。

参数

  • socketId

    数值

    socketId。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: SocketInfo) => void

返回

  • Promise<SocketInfo>

    Chrome 121 及更高版本

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

getJoinedGroups()

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

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

参数

  • socketId

    数值

    socketId。

  • callback

    函数

    callback 参数如下所示： 

    (groups: string[]) => void

    • 群组

      字符串[]

getNetworkList()

Promise 
chrome.socket.getNetworkList(
  callback?: function,
): Promise<NetworkInterface[]>

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

参数

返回

  • Promise<NetworkInterface[]>

    Chrome 121 及更高版本

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

joinGroup()

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

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

参数

  • socketId

    数值

    socketId。

  • 地址

    字符串

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

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

leaveGroup()

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

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

离开群组后，路由器将无法再向本地主机发送多播数据报，前提是主机上没有其他进程仍加入该群组。

参数

  • socketId

    数值

    socketId。

  • 地址

    字符串

    要离开的群组地址。域名不受支持。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

listen()

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

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

参数

  • socketId

    数值

    socketId。

  • 地址

    字符串

    本地计算机的地址。

  • 端口

    数值

    本地机器的端口。

  • backlog

    number 可选

    套接字侦听队列的长度。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

read()

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

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

参数

  • socketId

    数值

    socketId。

  • bufferSize

    number 可选

    读取缓冲区大小。

  • callback

    函数

    callback 参数如下所示： 

    (readInfo: ReadInfo) => void

recvFrom()

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

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

参数

  • socketId

    数值

    socketId。

  • bufferSize

    number 可选

    接收缓冲区大小。

  • callback

    函数

    callback 参数如下所示： 

    (recvFromInfo: RecvFromInfo) => void

secure()

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

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

参数

  • socketId

    数值

    要使用的已连接套接字。

  • 选项

    SecureOptions 可选

    TLS 连接的限制和参数。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

sendTo()

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

通过给定的 UDP 套接字将数据发送到给定的地址和端口。

参数

  • socketId

    数值

    socketId。

  • 数据

    ArrayBuffer

    要写入的数据。

  • 地址

    字符串

    远程机器的地址。

  • 端口

    数值

    远程机器的端口。

  • callback

    函数

    callback 参数如下所示： 

    (writeInfo: WriteInfo) => void

setKeepAlive()

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

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

参数

  • socketId

    数值

    socketId。

  • 启用

    布尔值

    如果为 true，则启用 keep-alive 功能。

  • delay

    number 可选

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

  • callback

    函数

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

setMulticastLoopbackMode()

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

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

注意：setMulticastLoopbackMode 在 Windows 和类 Unix 系统中的行为略有不同。只有当同一主机上有多个应用加入同一多播群组，但多播环回模式的设置不同时，才会出现不一致的情况。在 Windows 上，关闭环回的应用不会接收环回数据包；而在类 Unix 系统上，关闭环回的应用不会将环回数据包发送到同一主机上的其他应用。请参阅 MSDN：https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

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

参数

  • socketId

    数值

    socketId。

  • 已启用

    布尔值

    指示是否启用环回模式。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

setMulticastTimeToLive()

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

设置发送到多播组的多播数据包的 TTL。

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

参数

  • socketId

    数值

    socketId。

  • ttl

    数值

    存留时间值。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

setNoDelay()

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

为 TCP 连接设置或清除 TCP_NODELAY。设置 TCP_NODELAY 时，系统会停用 Nagle 算法。

参数

  • socketId

    数值

    socketId。

  • noDelay

    布尔值

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

  • callback

    函数

    callback 参数如下所示： 

    (result: boolean) => void

    • 结果

      布尔值

write()

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

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

参数

  • socketId

    数值

    socketId。

  • 数据

    ArrayBuffer

    要写入的数据。

  • callback

    函数

    callback 参数如下所示： 

    (writeInfo: WriteInfo) => void