chrome.sockets.udp

说明

使用 chrome.sockets.udp API 通过 UDP 连接在网络上发送和接收数据。此 API 取代了之前在“socket”API 中找到的 UDP 功能。

清单

如需使用此 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

    数值

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

  • socketId

    数值

    插槽 ID。

ReceiveInfo

属性

  • 数据

    ArrayBuffer

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

  • remoteAddress

    字符串

    数据包的来源主机的地址。

  • remotePort

    数值

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

  • socketId

    数值

    插槽 ID。

SendInfo

属性

  • bytesSent

    number 可选

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

  • resultCode

    数值

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

SocketInfo

属性

  • bufferSize

    number 可选

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

  • localAddress

    字符串（选填）

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

  • localPort

    number 可选

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

  • name

    字符串（选填）

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

  • 已暂停

    布尔值

    一个标志，用于指示套接字是否被阻止触发 onReceive 事件。

  • 持久性

    布尔值

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

  • socketId

    数值

    套接字标识符。

SocketProperties

属性

  • bufferSize

    number 可选

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

  • name

    字符串（选填）

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

  • 持久性

    布尔值（可选）

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

方法

bind()

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

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

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

参数

  • socketId

    数值

    插槽 ID。

  • 地址

    字符串

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

  • 端口

    数值

    本地机器的端口。使用“0”绑定到空闲端口。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

close()

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

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

参数

  • socketId

    数值

    插槽 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

create()

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

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

参数

  • 媒体资源

    SocketProperties 可选

    套接字属性（可选）。

  • callback

    函数 可选

    callback 参数如下所示： 

    (createInfo: CreateInfo) => void

返回

  • Promise<CreateInfo>

    Chrome 121 及更高版本

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

getInfo()

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

检索给定套接字的状态。

参数

  • socketId

    数值

    插槽 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含套接字信息的对象。

返回

  • Promise<SocketInfo>

    Chrome 121 及更高版本

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

getJoinedGroups()

Promise 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
): Promise<string[]>

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

参数

  • socketId

    数值

    插槽 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (groups: string[]) => void

    • 群组

      字符串[]

      套接字已加入的群组的数组。

返回

  • Promise<string[]>

    Chrome 121 及更高版本

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

getSockets()

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

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

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

返回

  • Promise<SocketInfo[]>

    Chrome 121 及更高版本

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

joinGroup()

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

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

参数

  • socketId

    数值

    插槽 ID。

  • 地址

    字符串

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

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

leaveGroup()

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

退出之前使用 joinGroup 加入的多播群组。如果您计划在之后继续使用套接字，才需要调用此方法，因为当套接字关闭时，操作系统会自动执行此操作。

离开群组后，路由器将无法再向本地主机发送多播数据报，前提是主机上没有其他进程仍加入该群组。

参数

  • socketId

    数值

    插槽 ID。

  • 地址

    字符串

    要离开的群组地址。域名不受支持。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

send()

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

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

参数

  • socketId

    数值

    插槽 ID。

  • 数据

    ArrayBuffer

    要发送的数据。

  • 地址

    字符串

    远程机器的地址。

  • 端口

    数值

    远程机器的端口。

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

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

参数

  • socketId

    数值

    插槽 ID。

  • 已启用

    布尔值

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

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

setMulticastLoopbackMode()

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

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

注意：setMulticastLoopbackMode 在 Windows 和类 Unix 系统中的行为略有不同。只有当同一主机上有多个应用加入同一多播群组，但多播环回模式的设置不同时，才会出现不一致的情况。在 Windows 上，关闭环回的应用不会接收环回数据包；而在类 Unix 系统上，关闭环回的应用不会将环回数据包发送到同一主机上的其他应用。请参阅 MSDN：https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

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

参数

  • socketId

    数值

    插槽 ID。

  • 已启用

    布尔值

    指示是否启用环回模式。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

setMulticastTimeToLive()

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

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

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

参数

  • socketId

    数值

    插槽 ID。

  • ttl

    数值

    存留时间值。

  • callback

    函数

    callback 参数如下所示： 

    (result: number) => void

    • 结果

      数值

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

setPaused()

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

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

参数

  • socketId

    数值

  • 已暂停

    布尔值

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

update()

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

更新套接字属性。

参数

  • socketId

    数值

    插槽 ID。

  • 媒体资源

    SocketProperties

    要更新的属性。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 121 及更高版本

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

事件

onReceive

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

当给定套接字收到 UDP 数据包时引发的事件。

参数

onReceiveError

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

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

参数