说明
使用 chrome.sockets.udp
API,借助 UDP 连接通过网络发送和接收数据。此 API 取代了以前在“socket”API 中找到的 UDP 功能。
清单
类型
CreateInfo
属性
-
socketId
number
新创建的套接字的 ID。请注意,通过此 API 创建的套接字 ID 与通过其他 API(例如已废弃的
[
socket](../socket/)
API)创建的套接字 ID 不兼容。
DnsQueryType
DNS 解析偏好设置。默认值为 any
,使用当前的操作系统配置(可能会返回 IPv4 或 IPv6)。ipv4
会强制执行 IPv4,ipv6
则会强制执行 IPv6。
枚举
"any"
"ipv4"
"ipv6"
ReceiveErrorInfo
属性
-
resultCode
number
从底层 recvfrom() 调用返回的结果代码。
-
socketId
number
套接字 ID。
ReceiveInfo
属性
-
data
ArrayBuffer
UDP 数据包内容(截断为当前缓冲区大小)。
-
remoteAddress
string
数据包的来源主机地址。
-
remotePort
number
数据包的来源主机的端口。
-
socketId
number
套接字 ID。
SendInfo
属性
-
bytesSent
数字可选
发送的字节数(如果结果 == 0)
-
resultCode
number
从底层网络调用返回的结果代码。负值表示错误。
SocketInfo
属性
-
bufferSize
数字可选
用于接收数据的缓冲区大小。如果未明确指定缓冲区大小,则不提供值。
-
localAddress
字符串(可选)
如果底层套接字已绑定,则包含其本地 IPv4/6 地址。
-
localPort
数字可选
如果底层套接字已绑定,则包含其本地端口。
-
name
字符串(可选)
与套接字关联的应用定义字符串。
-
已暂停
boolean
此标记指示套接字是否被阻止触发 onReceive 事件。
-
持久性
boolean
此标记指示在应用暂停时套接字是否保持打开状态(请参阅
SocketProperties.persistent
)。 -
socketId
number
套接字标识符。
SocketProperties
属性
-
bufferSize
数字可选
用于接收数据的缓冲区大小。如果缓冲区太小,无法接收 UDP 数据包,数据将丢失。默认值为 4096。
-
name
字符串(可选)
与套接字关联的应用定义的字符串。
-
持久性
布尔值 选填
此标记指示在应用的事件页面卸载时套接字是否保持打开状态(请参阅管理应用生命周期)。默认值为“false”。加载应用时,可以使用
getSockets
提取之前使用永久性磁盘=true 打开的任何套接字。
方法
bind()
chrome.sockets.udp.bind(
socketId: number,
address: string,
port: number,
callback: function,
)
绑定套接字的本地地址和端口。对于客户端套接字,建议使用端口 0 让平台选择一个可用端口。
bind
操作成功完成后,当 UDP 数据包到达指定的地址/端口时,将引发 onReceive
事件(除非套接字已暂停。)
参数
-
socketId
number
套接字 ID。
-
地址
string
本地机器的地址。支持 DNS 名称、IPv4 和 IPv6 格式。使用“0.0.0.0”可接受来自所有本地可用网络接口的数据包。
-
端口
number
本地机器的端口。使用“0”绑定到可用端口。
-
callback
功能
callback
参数如下所示:(result: number) => void
-
结果
number
从底层网络调用返回的结果代码。负值表示错误。
-
close()
chrome.sockets.udp.close(
socketId: number,
callback?: function,
)
关闭套接字并释放套接字绑定到的地址/端口。创建的每个套接字应在使用后关闭。调用该函数时,套接字 ID 会立即失效。不过,套接字只有在调用回调时才会关闭。
参数
-
socketId
number
套接字 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
create()
chrome.sockets.udp.create(
properties?: SocketProperties,
callback?: function,
)
使用指定属性创建 UDP 套接字。
参数
-
媒体资源
套接字属性(可选)。
-
callback
函数(可选)
callback
参数如下所示:(createInfo: CreateInfo) => void
-
createInfo
套接字创建的结果。
-
返回
-
Promise<CreateInfo>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getInfo()
chrome.sockets.udp.getInfo(
socketId: number,
callback?: function,
)
检索指定套接字的状态。
参数
-
socketId
number
套接字 ID。
-
callback
函数(可选)
callback
参数如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含套接字信息的对象。
-
返回
-
Promise<SocketInfo>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getJoinedGroups()
chrome.sockets.udp.getJoinedGroups(
socketId: number,
callback?: function,
)
获取套接字当前已加入的多播组地址。
参数
-
socketId
number
套接字 ID。
-
callback
函数(可选)
callback
参数如下所示:(groups: string[]) => void
-
组
字符串[]
套接字联接的群组数组。
-
返回
-
Promise<string[]>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getSockets()
chrome.sockets.udp.getSockets(
callback?: function,
)
检索应用拥有的当前已打开套接字的列表。
参数
-
callback
函数(可选)
callback
参数如下所示:(socketInfos: SocketInfo[]) => void
-
socketInfos
包含套接字信息的对象数组。
-
返回
-
Promise<SocketInfo[]>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
joinGroup()
chrome.sockets.udp.joinGroup(
socketId: number,
address: string,
callback: function,
)
加入多播组并开始接收来自该组的数据包。在调用此方法之前,必须将套接字绑定到本地端口。
参数
-
socketId
number
套接字 ID。
-
地址
string
要加入的群组地址。不支持域名。
-
callback
功能
callback
参数如下所示:(result: number) => void
-
结果
number
从底层网络调用返回的结果代码。负值表示错误。
-
leaveGroup()
chrome.sockets.udp.leaveGroup(
socketId: number,
address: string,
callback: function,
)
退出之前使用 joinGroup
加入的多播组。只有当您打算以后继续使用套接字时才需要调用此方法,因为在套接字关闭后,操作系统会自动完成该操作。
离开该组将阻止路由器向本地主机发送多播数据报,假定主机上没有其他进程仍加入该组。
参数
-
socketId
number
套接字 ID。
-
地址
string
要退出的群组地址。不支持域名。
-
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。
-
data
ArrayBuffer
要发送的数据。
-
地址
string
远程计算机的地址。
-
端口
number
远程计算机的端口。
-
dnsQueryType
DnsQueryType(可选)
Chrome 103 及更高版本地址解析偏好设置。
-
callback
功能
callback
参数如下所示:(sendInfo: SendInfo) => void
-
sendInfo
send
方法的结果。
-
setBroadcast()
chrome.sockets.udp.setBroadcast(
socketId: number,
enabled: boolean,
callback: function,
)
启用或停用此套接字上的广播数据包。
参数
-
socketId
number
套接字 ID。
-
已启用
boolean
true
可启用广播数据包,false
可停用广播数据包。 -
callback
功能
callback
参数如下所示:(result: number) => void
-
结果
number
从底层网络调用返回的结果代码。
-
setMulticastLoopbackMode()
chrome.sockets.udp.setMulticastLoopbackMode(
socketId: number,
enabled: boolean,
callback: function,
)
设置从主机发送到多播组的多播数据包是否环回主机。
注意:在 Windows 和类似 Unix 的系统之间,setMulticastLoopbackMode
的行为略有不同。只有当同一主机上有多个应用加入同一个多播组,同时在多播环回模式下采用不同的设置时,才会出现不一致的情况。在 Windows 上,已关闭环回功能的应用无法接收环回数据包;而在类似 Unix 的系统上,已关闭环回功能的应用不会将环回数据包发送到同一主机上的其他应用。请访问 MSDN:http://goo.gl/6vqbj
调用此方法不需要多播权限。
参数
-
socketId
number
套接字 ID。
-
已启用
boolean
指示是否启用环回模式。
-
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()
chrome.sockets.udp.setPaused(
socketId: number,
paused: boolean,
callback?: function,
)
暂停或取消暂停套接字。已暂停的套接字被阻止触发 onReceive
事件。
参数
-
socketId
number
-
已暂停
boolean
此标记指示是暂停还是取消暂停。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
update()
chrome.sockets.udp.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
更新套接字属性。
参数
-
socketId
number
套接字 ID。
-
媒体资源
要更新的属性。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onReceive
chrome.sockets.udp.onReceive.addListener(
callback: function,
)
在收到指定套接字的 UDP 数据包时引发的事件。
参数
-
callback
功能
callback
参数如下所示:(info: ReceiveInfo) => void
-
资讯
-
onReceiveError
chrome.sockets.udp.onReceiveError.addListener(
callback: function,
)
运行时等待套接字地址和端口上的数据时发生网络错误时引发的事件。引发此事件后,套接字会暂停,并且不会再针对此套接字引发 onReceive
事件,直到该套接字恢复为止。
参数
-
callback
功能
callback
参数如下所示:(info: ReceiveErrorInfo) => void