chrome.sockets.tcp

说明

使用 chrome.sockets.tcp API，通过 TCP 连接通过网络发送和接收数据。此 API 会取代之前在 chrome.socket API 中提供的 TCP 功能。

清单

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

"sockets"

类型

CreateInfo

属性

• socketId

  number

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

DnsQueryType

Chrome 浏览器 103 或更高版本

DNS 解析偏好设置。默认值为 any，并使用可能返回 IPv4 或 IPv6 的当前操作系统配置。ipv4 强制使用 IPv4，ipv6 强制使用 IPv6。

枚举

“any”

"ipv4"

"ipv6"

ReceiveErrorInfo

属性

• resultCode

  number

  从底层网络调用返回的结果代码。

• socketId

  number

  套接字标识符。

ReceiveInfo

属性

• 数据

  数组缓冲区

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

• socketId

  number

  套接字标识符。

SecureOptions

属性

• tlsVersion

  TLSVersionConstraints 可选

SendInfo

属性

• bytesSent

  编号（选填）

  发送的字节数（如果结果 == 0）

• resultCode

  number

  从底层网络调用返回的结果代码。负值表示存在错误。

SocketInfo

属性

• bufferSize

  编号（选填）

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

• 已连接

  布尔值

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

• localAddress

  字符串（可选）

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

• localPort

  编号（选填）

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

• name

  字符串（可选）

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

• 已暂停

  布尔值

  此标记指示已连接的套接字是否阻止其对等方发送更多数据（请参阅 setPaused）。

• peerAddress

  字符串（可选）

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

• peerPort

  编号（选填）

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

• 持久性

  布尔值

  此标记指示当应用挂起时，套接字是否保持打开状态（请参阅 SocketProperties.persistent）。

• socketId

  number

  套接字标识符。

SocketProperties

属性

• bufferSize

  编号（选填）

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

• name

  字符串（可选）

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

• 持久性

  布尔值（可选）

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

TLSVersionConstraints

属性

• max

  字符串（可选）

• 分钟

  字符串（可选）

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

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

方法

close()

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

chrome.sockets.tcp.close(
  socketId: number,
  callback?: function,
)

关闭套接字并释放套接字绑定到的地址/端口。创建的每个套接字都应在使用后关闭。调用函数后，套接字 ID 将不再有效。但是，可以保证仅在调用回调函数时关闭套接字。

参数

• socketId

  number

  套接字标识符。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

connect()

chrome.sockets.tcp.connect(
  socketId: number,
  peerAddress: string,
  peerPort: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
)

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

参数

• socketId

  number

  套接字标识符。

• peerAddress

  字符串

  远程机器的地址。支持 DNS 名称、IPv4 和 IPv6 格式。

• peerPort

  number

  远程机器的端口。

• dnsQueryType

  DnsQueryType 可选

  Chrome 浏览器 103 或更高版本

  地址分辨率偏好设置。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

    从底层网络调用返回的结果代码。负值表示存在错误。

create()

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

chrome.sockets.tcp.create(
  properties?: SocketProperties,
  callback?: function,
)

创建 TCP 套接字。

参数

• 媒体资源

  SocketProperties 可选

  套接字属性（可选）。

• callback

  函数（可选）

  callback 参数如下所示：

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

    套接字创建的结果。

返回

• Promise&lt;CreateInfo&gt;

  Chrome 121 及更高版本

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

disconnect()

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

chrome.sockets.tcp.disconnect(
  socketId: number,
  callback?: function,
)

断开套接字。

参数

• socketId

  number

  套接字标识符。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

getInfo()

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

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

检索给定套接字的状态。

参数

• socketId

  number

  套接字标识符。

• callback

  函数（可选）

  callback 参数如下所示：

  (socketInfo: SocketInfo) => void

  • socketInfo

    SocketInfo

    包含套接字信息的对象。

返回

• Promise&lt;SocketInfo&gt;

  Chrome 121 及更高版本

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

getSockets()

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

chrome.sockets.tcp.getSockets(
  callback?: function,
)

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (socketInfos: SocketInfo[]) => void

  • socketInfos

    SocketInfo[]

    包含套接字信息的对象数组。

返回

• Promise&lt;SocketInfo[]&gt;

  Chrome 121 及更高版本

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

secure()

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

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

参数

• socketId

  number

  要使用的现有已连接套接字。

• 选项

  SecureOptions（可选）

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

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

send()

chrome.sockets.tcp.send(
  socketId: number,
  data: ArrayBuffer,
  callback: function,
)

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

参数

• socketId

  number

  套接字标识符。

• 数据

  数组缓冲区

  要发送的数据。

• callback

  函数

  callback 参数如下所示：

  (sendInfo: SendInfo) => void

  • sendInfo

    SendInfo

    send 方法的结果。

setKeepAlive()

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

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

参数

• socketId

  number

  套接字标识符。

• 启用

  布尔值

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

• delay

  编号（选填）

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

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

    从底层网络调用返回的结果代码。负值表示存在错误。

setNoDelay()

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

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

参数

• socketId

  number

  套接字标识符。

• noDelay

  布尔值

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

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

    从底层网络调用返回的结果代码。负值表示存在错误。

setPaused()

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

chrome.sockets.tcp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

允许或禁止应用接收来自对等设备的消息。默认值为“false”。暂停套接字通常由应用用于限制其对等方发送的数据。暂停套接字时，不会引发 onReceive 事件。连接并取消暂停套接字后，系统会在收到消息时再次引发 onReceive 事件。

参数

• socketId

  number

• 已暂停

  布尔值

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

update()

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

chrome.sockets.tcp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

更新套接字属性。

参数

• socketId

  number

  套接字标识符。

• 媒体资源

  SocketProperties

  要更新的属性。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

事件

onReceive

chrome.sockets.tcp.onReceive.addListener(
  callback: function,
)

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

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveInfo) => void

  • 资讯

    ReceiveInfo

onReceiveError

chrome.sockets.tcp.onReceiveError.addListener(
  callback: function,
)

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

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveErrorInfo) => void

  • 资讯

    ReceiveErrorInfo