说明
使用 chrome.sockets.tcp
API 可以通过 TCP 连接通过网络发送和接收数据。此 API 取代了之前在 chrome.socket
API 中提供的 TCP 功能。
清单
类型
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
从底层网络调用返回的结果代码。
-
socketId
number
套接字标识符。
ReceiveInfo
属性
-
data
ArrayBuffer
已接收的数据,大小上限为
bufferSize
。 -
socketId
number
套接字标识符。
SecureOptions
属性
-
tlsVersion
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()
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()
chrome.sockets.tcp.create(
properties?: SocketProperties,
callback?: function,
)
创建 TCP 套接字。
参数
-
媒体资源
套接字属性(可选)。
-
callback
函数(可选)
callback
参数如下所示:(createInfo: CreateInfo) => void
-
createInfo
套接字创建的结果。
-
返回
-
Promise<CreateInfo>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
disconnect()
chrome.sockets.tcp.disconnect(
socketId: number,
callback?: function,
)
断开套接字。
参数
-
socketId
number
套接字标识符。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getInfo()
chrome.sockets.tcp.getInfo(
socketId: number,
callback?: function,
)
检索指定套接字的状态。
参数
-
socketId
number
套接字标识符。
-
callback
函数(可选)
callback
参数如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含套接字信息的对象。
-
返回
-
Promise<SocketInfo>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getSockets()
chrome.sockets.tcp.getSockets(
callback?: function,
)
检索应用拥有的当前已打开套接字的列表。
参数
-
callback
函数(可选)
callback
参数如下所示:(socketInfos: SocketInfo[]) => void
-
socketInfos
包含套接字信息的对象数组。
-
返回
-
Promise<SocketInfo[]>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
secure()
chrome.sockets.tcp.secure(
socketId: number,
options?: SecureOptions,
callback: function,
)
通过已连接的 TCP 客户端套接字启动 TLS 客户端连接。
参数
-
socketId
number
要使用的现有已连接套接字。
-
选项
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
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()
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()
chrome.sockets.tcp.update(
socketId: number,
properties: SocketProperties,
callback?: function,
)
更新套接字属性。
参数
-
socketId
number
套接字标识符。
-
媒体资源
要更新的属性。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onReceive
chrome.sockets.tcp.onReceive.addListener(
callback: function,
)
在收到指定套接字的数据时引发的事件。
参数
-
callback
功能
callback
参数如下所示:(info: ReceiveInfo) => void
-
资讯
-
onReceiveError
chrome.sockets.tcp.onReceiveError.addListener(
callback: function,
)
运行时等待套接字地址和端口上的数据时发生网络错误时引发的事件。引发此事件后,套接字会设置为 paused
,并且不会再针对此套接字引发 onReceive
事件。
参数
-
callback
功能
callback
参数如下所示:(info: ReceiveErrorInfo) => void