chrome.sockets.tcp

说明

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

清单

如需使用此 API，必须在清单中声明以下键。

"sockets"

类型

CreateInfo

属性

  • socketId

    数值

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

DnsQueryType

Chrome 103 及更高版本

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

枚举

“any”

“ipv4”

"ipv6"

ReceiveErrorInfo

属性

  • resultCode

    数值

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

  • socketId

    数值

    套接字标识符。

ReceiveInfo

属性

  • 数据

    ArrayBuffer

    接收的数据，最大大小为 bufferSize。

  • socketId

    数值

    套接字标识符。

SecureOptions

属性

SendInfo

属性

  • bytesSent

    number 可选

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

  • resultCode

    数值

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

SocketInfo

属性

  • bufferSize

    number 可选

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

  • 已连接

    布尔值

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

  • localAddress

    字符串（选填）

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

  • localPort

    number 可选

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

  • name

    字符串（选填）

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

  • 已暂停

    布尔值

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

  • peerAddress

    字符串（选填）

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

  • peerPort

    number 可选

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

  • 持久性

    布尔值

    一个标志，用于指示应用暂停时套接字是否保持打开状态（请参阅 SocketProperties.persistent）。

  • socketId

    数值

    套接字标识符。

SocketProperties

属性

  • bufferSize

    number 可选

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

  • name

    字符串（选填）

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

  • 持久性

    布尔值（可选）

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

TLSVersionConstraints

属性

  • max

    字符串（选填）

  • 分钟

    字符串（选填）

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

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

方法

close()

Promise 
chrome.sockets.tcp.close(
  socketId: number,
  callback?: function,
): Promise<void>

关闭套接字并释放套接字绑定的地址/端口。创建的每个套接字都应在使用后关闭。一旦调用该函数，套接字 ID 就会立即失效。不过，只有在调用回调时，才能保证套接字已关闭。

参数

  • socketId

    数值

    套接字标识符。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

connect()

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

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

参数

  • socketId

    数值

    套接字标识符。

  • peerAddress

    字符串

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

  • peerPort

    数值

    远程机器的端口。

  • dnsQueryType

    DnsQueryType 可选

    Chrome 103 及更高版本

    地址解析偏好设置。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

create()

Promise 
chrome.sockets.tcp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

创建 TCP 套接字。

参数

  • 媒体资源

    SocketProperties 可选

    套接字属性（可选）。

  • callback

    函数 可选

    callback 参数如下所示： 

    (createInfo: CreateInfo) => void

返回

  • Promise<CreateInfo>

    Chrome 121 及更高版本

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

disconnect()

Promise 
chrome.sockets.tcp.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>

断开套接字连接。

参数

  • socketId

    数值

    套接字标识符。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

getInfo()

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

检索给定套接字的状态。

参数

  • socketId

    数值

    套接字标识符。

  • callback

    函数 可选

    callback 参数如下所示： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含套接字信息的对象。

返回

  • Promise<SocketInfo>

    Chrome 121 及更高版本

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

getSockets()

Promise 
chrome.sockets.tcp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

返回

  • Promise<SocketInfo[]>

    Chrome 121 及更高版本

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

secure()

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

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

参数

  • socketId

    数值

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

  • 选项

    SecureOptions 可选

    TLS 连接的限制和参数。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

send()

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

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

参数

  • socketId

    数值

    套接字标识符。

  • 数据

    ArrayBuffer

    要发送的数据。

  • callback

    函数

    callback 参数如下所示： 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      send 方法的结果。

setKeepAlive()

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

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

参数

  • socketId

    数值

    套接字标识符。

  • 启用

    布尔值

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

  • delay

    number 可选

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

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

setNoDelay()

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

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

参数

  • socketId

    数值

    套接字标识符。

  • noDelay

    布尔值

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

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

setPaused()

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

启用或停用应用接收来自对等方的消息。默认值为“false”。应用通常会暂停套接字，以限制对等方发送的数据。当套接字暂停时，不会引发 onReceive 事件。当套接字连接并取消暂停后，在收到消息时会再次引发 onReceive 事件。

参数

  • socketId

    数值

  • 已暂停

    布尔值

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

update()

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

更新套接字属性。

参数

  • socketId

    数值

    套接字标识符。

  • 媒体资源

    SocketProperties

    要更新的属性。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

事件

onReceive

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

在已接收到给定套接字的数据时引发的事件。

参数

onReceiveError

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

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

参数