chrome.sockets.tcpServer

说明

借助 chrome.sockets.tcpServer API，您可以创建使用 TCP 连接的服务器应用。此 API 会取代之前在 chrome.socket API 中提供的 TCP 功能。

清单

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

"sockets"

类型

AcceptErrorInfo

属性

  • resultCode

    number

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

  • socketId

    number

    服务器套接字标识符。

AcceptInfo

属性

  • clientSocketId

    number

    客户端套接字标识符，即新建立的连接的套接字标识符。此套接字标识符只能与 chrome.sockets.tcp 命名空间中的函数一起使用。请注意，客户端套接字最初处于暂停状态，必须由应用明确取消暂停，然后才能开始接收数据。

  • socketId

    number

    服务器套接字标识符。

CreateInfo

属性

  • socketId

    number

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

SocketInfo

属性

  • localAddress

    字符串（可选）

    如果套接字正在监听，则包含其本地 IPv4/6 地址。

  • localPort

    编号（选填）

    如果套接字正在监听，则包含其本地端口。

  • name

    字符串（可选）

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

  • 已暂停

    布尔值

    此标记指示监听套接字上的连接请求是通过 onAccept 事件分派，还是在监听队列积压中排队。请参阅 setPaused。默认值为 “False”。

  • 持久性

    布尔值

    此标记指示在卸载应用的事件页面时套接字是否保持打开状态（请参阅 SocketProperties.persistent）。默认值为“false”。

  • socketId

    number

    套接字标识符。

SocketProperties

属性

  • name

    字符串（可选）

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

  • 持久性

    布尔值（可选）

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

方法

close()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sockets.tcpServer.close(
  socketId: number,
  callback?: function,
)

断开并销毁套接字。创建的每个套接字都应在使用后关闭。调用函数后，套接字 ID 立即失效。但是，可以保证仅在调用回调函数时关闭套接字。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 121 及更高版本

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

create()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sockets.tcpServer.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.tcpServer.disconnect(
  socketId: number,
  callback?: function,
)

断开监听套接字的连接，即停止接受新连接并释放套接字绑定到的地址/端口。套接字标识符仍然有效，例如它可与 listen 搭配使用，以接受新端口和地址上的连接。

参数

  • socketId

    number

    套接字标识符。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 121 及更高版本

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

getInfo()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sockets.tcpServer.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.tcpServer.getSockets(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

返回

  • Promise&lt;SocketInfo[]&gt;

    Chrome 121 及更高版本

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

listen()

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

监听指定端口和地址上的连接。如果端口/地址已被使用，则回调表示失败。

参数

  • socketId

    number

    套接字标识符。

  • 地址

    字符串

    本地计算机的地址。

  • 端口

    number

    本地计算机的端口。如果设置为 0，系统会动态选择可用端口。可通过调用 getInfo 找到动态分配的端口。

  • 积压

    编号（选填）

    套接字的监听队列的长度。默认值取决于操作系统 (SOMAXCONN)，这可确保对大多数应用而言合理的队列长度。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      number

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

setPaused()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sockets.tcpServer.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

启用或停用监听套接字以接受新连接。暂停后，监听套接字会接受新连接，直到其积压（请参阅 listen 函数）已满，然后会拒绝其他连接请求。只有当套接字取消暂停时，才会引发 onAccept 事件。

参数

  • socketId

    number

  • 已暂停

    布尔值

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 121 及更高版本

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

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.sockets.tcpServer.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

更新套接字属性。

参数

  • socketId

    number

    套接字标识符。

  • 媒体资源

    SocketProperties

    要更新的属性。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 121 及更高版本

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

事件

onAccept

chrome.sockets.tcpServer.onAccept.addListener(
  callback: function,
)

与服务器套接字建立连接时引发的事件。

参数

onAcceptError

chrome.sockets.tcpServer.onAcceptError.addListener(
  callback: function,
)

运行时在等待套接字地址和端口上的新连接时发生网络错误时引发的事件。引发此事件后，套接字将设置为 paused，并且不会再针对此套接字引发 onAccept 事件，直到套接字恢复为止。

参数