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

属性

  • data

    ArrayBuffer

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

  • socketId

    number

    套接字标识符。

SecureOptions

属性

SendInfo

属性

  • bytesSent

    数字可选

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

  • resultCode

    number

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

SocketInfo

属性

  • bufferSize

    数字可选

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

  • 已连接

    boolean

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

  • localAddress

    字符串（可选）

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

  • localPort

    数字可选

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

  • name

    字符串（可选）

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

  • 已暂停

    boolean

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

  • peerAddress

    字符串（可选）

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

  • peerPort

    数字可选

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

  • 持久性

    boolean

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

  • socketId

    number

    套接字标识符。

SocketProperties

属性

  • bufferSize

    数字可选

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

  • name

    字符串（可选）

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

  • 持久性

    布尔值 选填

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

TLSVersionConstraints

属性

  • 最大值

    字符串（可选）

  • 分钟

    字符串（可选）

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

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

方法

close()

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

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

参数

  • socketId

    number

    套接字标识符。

  • 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,
)

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

参数

  • socketId

    number

    套接字标识符。

  • peerAddress

    string

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

  • peerPort

    number

    远程计算机的端口。

  • dnsQueryType

    DnsQueryType（可选）

    Chrome 103 及更高版本

    地址解析偏好设置。

  • callback

    功能

    callback 参数如下所示：

    (result: number)=>void

    • 结果

      number

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

create()

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

创建 TCP 套接字。

参数

  • 媒体资源

    SocketProperties 可选

    套接字属性（可选）。

  • callback

    函数（可选）

    callback 参数如下所示：

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

      套接字创建的结果。

返回

  • Promise<CreateInfo>

    Chrome 121 及更高版本

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

disconnect()

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

断开套接字。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

getInfo()

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

检索指定套接字的状态。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示：

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

      包含套接字信息的对象。

返回

  • Promise<SocketInfo>

    Chrome 121 及更高版本

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

getSockets()

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

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

参数

  • 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,
)

通过已连接的 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

    套接字标识符。

  • data

    ArrayBuffer

    要发送的数据。

  • 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

    套接字标识符。

  • enable

    boolean

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

  • 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

    boolean

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

  • callback

    功能

    callback 参数如下所示：

    (result: number)=>void

    • 结果

      number

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

setPaused()

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

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

参数

  • socketId

    number

  • 已暂停

    boolean

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

update()

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

更新套接字属性。

参数

  • socketId

    number

    套接字标识符。

  • 媒体资源

    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 事件。

参数