chrome.socket

描述 使用 chrome.socket API 通过 TCP 和 UDP 连接在网络中发送和接收数据。注意:从 Chrome 33 开始该 API 弃用,您应该改用 sockets.udpsockets.tcpsockets.tcpServer API。
可用版本 从 Chrome 24 开始支持。
权限 {"socket": ["rule1", "rule2"]}
例如:{"socket": ["tcp-connect:*:*"]} 表示可以连接任意主机的任意端口。有关规则的语法请参见网络通信
了解更多 网络通信
用 Sencha ExtJS 建立应用
Chrome 应用办公时间:网络通信 API
Chrome 应用办公时间:控制 AR ParrotDrone

摘要

类型
SocketType
WriteInfo
方法
create chrome.socket.create( SocketType type, object options, function callback)
destroy chrome.socket.destroy(integer socketId)
connect chrome.socket.connect(integer socketId, string hostname, integer port, function callback)
bind chrome.socket.bind(integer socketId, string address, integer port, function callback)
disconnect chrome.socket.disconnect(integer socketId)
read chrome.socket.read(integer socketId, integer bufferSize, function callback)
write chrome.socket.write(integer socketId, ArrayBuffer data, function callback)
recvFrom chrome.socket.recvFrom(integer socketId, integer bufferSize, function callback)
sendTo chrome.socket.sendTo(integer socketId, ArrayBuffer data, string address, integer port, function callback)
listen chrome.socket.listen(integer socketId, string address, integer port, integer backlog, function callback)
accept chrome.socket.accept(integer socketId, function callback)
setKeepAlive chrome.socket.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)
setNoDelay chrome.socket.setNoDelay(integer socketId, boolean noDelay, function callback)
getInfo chrome.socket.getInfo(integer socketId, function callback)
getNetworkList chrome.socket.getNetworkList(function callback)
joinGroup chrome.socket.joinGroup(integer socketId, string address, function callback)
leaveGroup chrome.socket.leaveGroup(integer socketId, string address, function callback)
setMulticastTimeToLive chrome.socket.setMulticastTimeToLive(integer socketId, integer ttl, function callback)
setMulticastLoopbackMode chrome.socket.setMulticastLoopbackMode(integer socketId, boolean enabled, function callback)
getJoinedGroups chrome.socket.getJoinedGroups(integer socketId, function callback)
secure chrome.socket.secure(integer socketId, object options, function callback)

类型

SocketType

枚举
"tcp", or "udp"

WriteInfo

属性
integer bytesWritten

发送的字节数,或者为负数,表示错误代码。

方法

create

chrome.socket.create( SocketType type, object options, function callback)

创建指定类型的套接字,以便用来连接到远程计算机。

参数
SocketType type

要创建的套接字类型,必须为 "tcp""udp"

object (可选)
options

套接字选项。

function callback

套接字创建后调用。

callback 参数应该是一个如下形式的函数:

function(object createInfo) {...};
object createInfo
integer socketId

新创建套接字的标识符。

destroy

chrome.socket.destroy(integer socketId)

释放套接字,创建的套接字使用完后应该释放。

参数
integer socketId

套接字标识符。

connect

chrome.socket.connect(integer socketId, string hostname, integer port, function callback)

将套接字连接至远程计算机(用于 tcp 套接字)。对于 udp 套接字,该函数设置 read()write() 调用时数据包发送至的默认地址。

参数
integer socketId

套接字标识符。

string hostname

远程计算机的主机名或 IP 地址。

integer port

远程计算机的端口。

function callback

连接尝试完成后调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

bind

chrome.socket.bind(integer socketId, string address, integer port, function callback)

为套接字绑定本机地址。当前还不支持 TCP 套接字。

参数
integer socketId

套接字标识符。

string address

本机地址。

integer port

本机端口

function callback

绑定尝试完成后调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

disconnect

chrome.socket.disconnect(integer socketId)

断开套接字的连接。对于 UDP 套接字来说,断开连接并不会执行任何操作,但是可以安全地调用。

参数
integer socketId

套接字标识符。

read

chrome.socket.read(integer socketId, integer bufferSize, function callback)

从指定的已连接套接字读取数据。

参数
integer socketId

套接字标识符。

integer (可选)
bufferSize

读取缓冲区大小。

function callback

以非阻塞的方式传递可以读取的数据

callback 参数应该是一个如下形式的函数:

function(object readInfo) {...};
object readInfo
integer resultCode

read() 调用返回的结果代码。

ArrayBuffer data

write

chrome.socket.write(integer socketId, ArrayBuffer data, function callback)

向已连接的指定套接字写入数据。

参数
integer socketId

套接字标识符。

ArrayBuffer data

要写入的数据。

function callback

以非阻塞的方式在写入操作完成或发生错误时调用。

callback 参数应该是一个如下形式的函数:

function( WriteInfo writeInfo) {...};
WriteInfo writeInfo

recvFrom

chrome.socket.recvFrom(integer socketId, integer bufferSize, function callback)

从指定 UDP 套接字接收数据。

参数
integer socketId

套接字标识符。

integer (可选)
bufferSize

接收缓冲区大小。

function callback

返回接收操作的结果。

callback 参数应该是一个如下形式的函数:

function(object recvFromInfo) {...};
object recvFromInfo
integer resultCode

recvFrom() 调用返回的结果代码。

ArrayBuffer data
string address

远程计算机的地址。

integer port

sendTo

chrome.socket.sendTo(integer socketId, ArrayBuffer data, string address, integer port, function callback)

在指定 UDP 套接字上向指定地址与端口发送数据。

参数
integer socketId

套接字标识符。

ArrayBuffer data

要写入的数据。

string address

远程计算机的地址。

integer port

远程计算机的端口。

function callback

以非阻塞的方式在发送操作完成或产生错误时调用。

callback 参数应该是一个如下形式的函数:

function( WriteInfo writeInfo) {...};
WriteInfo writeInfo

listen

chrome.socket.listen(integer socketId, string address, integer port, integer backlog, function callback)

该方法仅适用于 TCP 套接字,监听指定端口与地址上的连接,这样的结果是使该套接字成为服务器套接字,客户端套接字函数(connect、read、write)就不能再在该套接字上使用。

参数
integer socketId

套接字标识符。

string address

本地计算机的地址。

integer port

本地计算机的端口。

integer (可选)
backlog

套接字监听队列的长度。

function callback

监听操作完成时调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

accept

chrome.socket.accept(integer socketId, function callback)

该方法仅适用于 TCP 套接字,注册一个回调函数,当正在监听的服务器套接字接受连接时调用。必须首先调用 listen。如果已经有活动的接受回调函数,该回调函数将立即执行,resultCode 包含错误。

参数
integer socketId

套接字标识符。

function callback

新的套接字接受时调用该回调函数。

callback 参数应该是一个如下形式的函数:

function(object acceptInfo) {...};
object acceptInfo
integer resultCode
integer (可选)
socketId

已接受套接字的标识符。

setKeepAlive

chrome.socket.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)

启用或禁用 TCP 连接保持活动状态的功能。

参数
integer socketId

套接字标识符。

boolean enable

如果为 true 的话,启用保持活动状态的功能。

integer (可选)
delay

设置最后一次数据包接收与第一次活动状态检测之间的时间延迟,默认为 0。

function callback

操作完成后调用。

callback 参数应该是一个如下形式的函数:

function(boolean result) {...};
boolean result

setNoDelay

chrome.socket.setNoDelay(integer socketId, boolean noDelay, function callback)

设置或清除 TCP 连接的 TCP_NODELAY标志,当设置 TCP_NODELAY 标志时将禁用纳格算法

参数
integer socketId

套接字标识符。

boolean noDelay

如果为 true 的话,禁用纳格算法。

function callback

操作完成后调用。

callback 参数应该是一个如下形式的函数:

function(boolean result) {...};
boolean result

getInfo

chrome.socket.getInfo(integer socketId, function callback)

获取指定套接字的状态。

参数
integer socketId

套接字标识符。

function callback

状态可用时调用。

callback 参数应该是一个如下形式的函数:

function(object result) {...};
object result
SocketType socketType

传递的套接字类型,为 "tcp" 或 "udp"。

boolean connected

指定套接字是否已连接。对于 tcp 套接字,即使远程计算机已经断开连接,该属性仍然为 true。读取或写入套接字可能会导致错误,表示该套接字应该通过 disconnect() 断开连接。对于 udp 套接字,该属性只是表示读取和写入数据包的默认远程地址是否已经指定。

string (可选)
peerAddress

如果套接字已连接,则包含对方的 IPv4/6 地址。

integer (可选)
peerPort

如果套接字已连接,则包含对方的端口号。

string (可选)
localAddress

如果套接字已绑定或连接,则包含本机 IPv4/6 地址。

integer (可选)
localPort

如果套接字已绑定或连接,则包含本机端口。

getNetworkList

chrome.socket.getNetworkList(function callback)

获取当前系统中本地适配器的有关信息。

参数
function callback

本地适配器信息可用时调用。

callback 参数应该是一个如下形式的函数:

function(array of object result) {...};
array of object result

每一个对象的属性

string name

适配器的名称,在 *nix 上通常为"eth0"、"lo" 等等。

string address

可用的 IPv4/6 地址。

integer prefixLength

前缀长度。

joinGroup

chrome.socket.joinGroup(integer socketId, string address, function callback)

从 Chrome 28 开始支持。

加入多播组,并开始接收数据包。调用该方法之前,套接字的类型必须是 UDP,并且已经绑定至本机端口。

参数
integer socketId

套接字标识符。

string address

要加入的多播组地址,不支持域名。

function callback

加入多播组的操作完成后调用,并传递一个整型参数,表示平台无关的错误代码。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

leaveGroup

chrome.socket.leaveGroup(integer socketId, string address, function callback)

从 Chrome 28 开始支持。

离开之前使用 joinGroup 加入的多播组。释放套接字或退出前不用离开多播组,这会由操作系统自动调用。

离开多播组后,如果没有其他进程仍然加入多播组,路由器不会继续向本机发送多播数据包。

参数
integer socketId

套接字标识符。

string address

要离开的多播组地址,不支持域名。

function callback

离开多播组的操作完成后调用,并传递一个整型参数,表示平台无关的错误代码。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

setMulticastTimeToLive

chrome.socket.setMulticastTimeToLive(integer socketId, integer ttl, function callback)

从 Chrome 28 开始支持。

设置发送至多播组的多播数据包的 TTL 值。

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

参数
integer socketId

套接字标识符。

integer ttl

TTL 值。

function callback

配置操作完成后调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

setMulticastLoopbackMode

chrome.socket.setMulticastLoopbackMode(integer socketId, boolean enabled, function callback)

从 Chrome 28 开始支持。

设置主机向多播组发送的多播包是否要回环至主机。

注意:setMulticastLookbackMode 在 Windows 与类 Unix 系统上的行为不同。只有当同一主机上不止一个应用程序加入了同一个多播组,并且多播回环模式的设置不同时才会出现这一不一致性。在 Windows 中,关闭回环的应用程序不会接受到回环包;而在类 Unix 系统中,关闭回环的应用程序不会向同一主机上的其他应用程序发送回环包。请参见 MSDN:http://goo.gl/6vqbj

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

参数
integer socketId

套接字标识符。

boolean enabled

表示是否启用回环模式。

function callback

配置操作完成后调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result

getJoinedGroups

chrome.socket.getJoinedGroups(integer socketId, function callback)

从 Chrome 28 开始支持。

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

参数
integer socketId

套接字标识符。

function callback

调用时传递字符串数据,表示结果。

callback 参数应该是一个如下形式的函数:

function(array of string groups) {...};
array of string groups

secure

chrome.socket.secure(integer socketId, object options, function callback)

从 Chrome 38 开始支持。警告:目前为 Dev 分支。了解更多内容

在已连接的 TCP 客户端套接字上启动 TLS 客户端连接。

参数
integer socketId

要使用的套接字(已连接)。

object (可选)
options

TLS 连接的约束和参数。

object (可选)
tlsVersion
string (可选)
min

可以接受的最低和最高 TLS 版本,可以为 ssl3tls1tls1.1tls1.2

string (可选)
max
function callback

尝试连接完成后调用。

callback 参数应该是一个如下形式的函数:

function(integer result) {...};
integer result