chrome.sockets.udp

说明

使用 chrome.sockets.udp API，使用 UDP 连接通过网络发送和接收数据。此 API 取代了之前在“套接字”中提供的 UDP 功能API。

清单

必须在清单中声明以下键才能使用此 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

  从底层 recvfrom() 调用返回的结果代码。

• socketId

  number

  套接字 ID。

ReceiveInfo

属性

• 数据

  数组缓冲区

  UDP 数据包内容（截断至当前缓冲区大小）。

• remoteAddress

  字符串

  发送数据包的主机地址。

• remotePort

  number

  数据包的来源主机的端口。

• socketId

  number

  套接字 ID。

SendInfo

属性

• bytesSent

  编号（选填）

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

• resultCode

  number

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

SocketInfo

属性

• bufferSize

  编号（选填）

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

• localAddress

  字符串（可选）

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

• localPort

  编号（选填）

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

• name

  字符串（可选）

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

• 已暂停

  布尔值

  此标记指示是否禁止套接字触发 onReceive 事件。

• 持久性

  布尔值

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

• socketId

  number

  套接字标识符。

SocketProperties

属性

• bufferSize

  编号（选填）

  用于接收数据的缓冲区大小。如果缓冲区太小，无法接收 UDP 数据包，数据将会丢失。默认值为 4096。

• name

  字符串（可选）

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

• 持久性

  布尔值（可选）

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

方法

bind()

chrome.sockets.udp.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
)

绑定套接字的本地地址和端口。对于客户端套接字，建议使用端口 0，让平台选择一个可用端口。

bind 操作成功完成后，系统会在 UDP 数据包到达指定的地址/端口时引发 onReceive 事件（除非套接字已暂停）。

参数

• socketId

  number

  套接字 ID。

• 地址

  字符串

  本地计算机的地址。支持 DNS 名称、IPv4 和 IPv6 格式。请使用“0.0.0.0”可接受来自所有本地可用网络接口的数据包。

• 端口

  number

  本地计算机的端口。使用“0”绑定至可用端口

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

close()

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

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

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

参数

• socketId

  number

  套接字 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

create()

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

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

创建具有指定属性的 UDP 套接字。

参数

• 媒体资源

  SocketProperties 可选

  套接字属性（可选）。

• callback

  函数（可选）

  callback 参数如下所示：

  (createInfo: CreateInfo) => void

  • createInfo

    CreateInfo

    套接字创建的结果。

返回

• Promise&lt;CreateInfo&gt;

  Chrome 121 及更高版本

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

getInfo()

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

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

检索给定套接字的状态。

参数

• socketId

  number

  套接字 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (socketInfo: SocketInfo) => void

  • socketInfo

    SocketInfo

    包含套接字信息的对象。

返回

• Promise&lt;SocketInfo&gt;

  Chrome 121 及更高版本

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

getJoinedGroups()

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

chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
)

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

参数

• socketId

  number

  套接字 ID。

• callback

  函数（可选）

  callback 参数如下所示：

  (groups: string[]) => void

  • 群组

    字符串[]

    套接字联接的组数组。

返回

• Promise&lt;string[]&gt;

  Chrome 121 及更高版本

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

getSockets()

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

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

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (socketInfos: SocketInfo[]) => void

  • socketInfos

    SocketInfo[]

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

返回

• Promise&lt;SocketInfo[]&gt;

  Chrome 121 及更高版本

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

joinGroup()

chrome.sockets.udp.joinGroup(
  socketId: number,
  address: string,
  callback: function,
)

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

参数

• socketId

  number

  套接字 ID。

• 地址

  字符串

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

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

leaveGroup()

chrome.sockets.udp.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
)

退出之前使用 joinGroup 加入的多播组。只有当您打算以后继续使用套接字时才需要调用此函数，因为当套接字关闭时，操作将由操作系统自动完成。

退出该组将阻止路由器向本地主机发送多播数据报，假设主机上没有其他进程仍加入该组。

参数

• socketId

  number

  套接字 ID。

• 地址

  字符串

  要退出的群组地址。不支持域名。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

send()

chrome.sockets.udp.send(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
)

将指定套接字上的数据发送到指定地址和端口。在调用此方法之前，套接字必须绑定到本地端口。

参数

• socketId

  number

  套接字 ID。

• 数据

  数组缓冲区

  要发送的数据。

• 地址

  字符串

  远程机器的地址。

• 端口

  number

  远程机器的端口。

• dnsQueryType

  DnsQueryType 可选

  Chrome 浏览器 103 或更高版本

  地址分辨率偏好设置。

• callback

  函数

  callback 参数如下所示：

  (sendInfo: SendInfo) => void

  • sendInfo

    SendInfo

    send 方法的结果。

setBroadcast()

Chrome 44 及更高版本

chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
)

启用或停用此套接字上的广播数据包。

参数

• socketId

  number

  套接字 ID。

• 已启用

  布尔值

  true 用于启用广播数据包，false 用于停用广播数据包。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

setMulticastLoopbackMode()

chrome.sockets.udp.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
)

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

注意：setMulticastLoopbackMode 的行为在 Windows 和类似 Unix 的系统之间略有不同。仅当同一主机上有多个应用加入同一多播组，而多播环回模式下的设置不同时，才会出现不一致的情况。在 Windows 上，关闭环回的应用将不会接收环回数据包；而在类似 Unix 的系统上，关闭环回的应用不会将环回数据包发送到同一主机上的其他应用。请参阅 MSDN：http://goo.gl/6vqbj

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

参数

• socketId

  number

  套接字 ID。

• 已启用

  布尔值

  指示是否启用环回模式。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

setMulticastTimeToLive()

chrome.sockets.udp.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
)

设置发送到多播组的多播数据包的存留时间。

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

参数

• socketId

  number

  套接字 ID。

• ttl

  number

  存留时间值。

• callback

  函数

  callback 参数如下所示：

  (result: number) => void

  • 结果

    number

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

setPaused()

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

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

暂停或取消暂停套接字。已暂停的套接字被阻止触发 onReceive 事件。

参数

• socketId

  number

• 已暂停

  布尔值

  指示是暂停还是取消暂停的标志。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

update()

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

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

更新套接字属性。

参数

• socketId

  number

  套接字 ID。

• 媒体资源

  SocketProperties

  要更新的属性。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• 承诺<void>

  Chrome 121 及更高版本

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

事件

onReceive

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

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

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveInfo) => void

  • 资讯

    ReceiveInfo

onReceiveError

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

运行时在等待套接字地址和端口上的数据时发生网络错误时引发的事件。引发此事件后，套接字会暂停，并且不会再针对此套接字引发 onReceive 事件，直到套接字恢复为止。

参数

• callback

  函数

  callback 参数如下所示：

  (info: ReceiveErrorInfo) => void

  • 资讯

    ReceiveErrorInfo