chrome.sockets.tcp

描述：	使用 `chrome.sockets.tcp` API 通过 TCP 连接在网络中发送和接收数据。该 API 增强了原来 `chrome.socket` API 中的 TCP 功能。
可用版本：	从 Chrome 33 开始支持。
清单文件：	"sockets": {...}

摘要

类型
SocketProperties
SocketInfo
方法
create − `chrome.sockets.tcp.create( SocketProperties properties, function callback)`
update − `chrome.sockets.tcp.update(integer socketId, SocketProperties properties, function callback)`
setPaused − `chrome.sockets.tcp.setPaused(integer socketId, boolean paused, function callback)`
setKeepAlive − `chrome.sockets.tcp.setKeepAlive(integer socketId, boolean enable, integer delay, function callback)`
setNoDelay − `chrome.sockets.tcp.setNoDelay(integer socketId, boolean noDelay, function callback)`
connect − `chrome.sockets.tcp.connect(integer socketId, string peerAddress, integer peerPort, function callback)`
disconnect − `chrome.sockets.tcp.disconnect(integer socketId, function callback)`
secure − `chrome.sockets.tcp.secure(integer socketId, object options, function callback)`
send − `chrome.sockets.tcp.send(integer socketId, ArrayBuffer data, function callback)`
close − `chrome.sockets.tcp.close(integer socketId, function callback)`
getInfo − `chrome.sockets.tcp.getInfo(integer socketId, function callback)`
getSockets − `chrome.sockets.tcp.getSockets(function callback)`
事件
onReceive
onReceiveError

类型

SocketProperties

属性
boolean	（可选） persistent	应用的事件页面卸载（参见管理应用的生命周期）时是否使套接字保持打开状态，默认值为 `false`。应用加载时，之前使用 `persistent: true` 打开的套接字可以通过 `getSockets` 获取。
string	（可选） name	与套接字相关联的字符串，由应用定义。
integer	（可选） bufferSize	用于接收数据的缓冲区大小，默认值为 4096。

SocketInfo

属性
integer	socketId	应用关闭时（参见 `SocketProperties.persistent`）套接字是否保持打开状态。
string	（可选） name	与套接字相关联的字符串，由应用定义。
integer	（可选） bufferSize	用于接收数据的缓冲区大小。如果没有明确指定缓冲区大小，则不提供该属性的值。
boolean	paused	表示连接的套接字是否阻止对方发送更多数据（请参见 `setPaused`）。
boolean	connected	表示套接字是否已经连接到远程计算机。
string	（可选） localAddress	如果下层套接字已连接，则包含它的本机 IPv4/6 地址。
integer	（可选） localPort	如果下层套接字已连接，则包含它的本机端口。
string	（可选） peerAddress	如果下层套接字已连接，则包含它的远程 IPv4/6 地址。
integer	（可选） peerPort	如果下层套接字已连接，则包含它的远程端口。

方法

create


              chrome.sockets.tcp.create(    SocketProperties properties, function callback)

创建 TCP 套接字。

参数

SocketProperties

（可选）
properties

套接字属性（可选）。

function

callback

套接字创建后调用。

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

function(object createInfo) {...};

object

createInfo

套接字创建的结果。

integer

socketId

新创建套接字的标识符。注意，该 API 中创建的套接字标识符和其他 API 中创建的套接字标识符不兼容，例如弃用的 socket API。

update


              chrome.sockets.tcp.update(integer socketId,     SocketProperties properties, function callback)

更新套接字属性。

参数

integer

socketId

套接字标识符。

SocketProperties

properties

要更新的属性。

function

（可选）
callback

属性更新后调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

setPaused


              chrome.sockets.tcp.setPaused(integer socketId, boolean paused, function callback)

允许或阻止应用从远程计算机接收消息，默认值为 false。应用通常使用暂停套接字的方式限制远程计算机发送的数据。套接字暂停后不会产生 onReceive 事件，套接字已连接并且取消暂停时，接收到消息后就会产生 onReceive 事件。

参数

integer socketId

boolean paused

function

参数
integer	socketId
boolean	paused
function	（可选） callback	`setPaused` 方法的回调函数。如果您指定了 callback 参数，它应该是一个如下形式的函数： `function() {...};`

（可选）
callback

setPaused 方法的回调函数。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

setKeepAlive


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

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

参数

integer

socketId

套接字标识符。

boolean

enable

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

integer

（可选）
delay

设置接收到最后一个数据包以及第一次保持活动状态探测之间间隔的秒数，默认为 0。

function

callback

setKeepAlive 尝试完成后调用。

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

function(integer result) {...};

integer

result

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

setNoDelay


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

设置 TCP 连接的 TCP_NODELAY 标志，设置 TCP_NODELAY 标志后会禁用纳格算法。

参数

integer

socketId

套接字标识符。

boolean

noDelay

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

function

callback

setNoDelay 尝试完成后调用。

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

function(integer result) {...};

integer

result

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

connect


              chrome.sockets.tcp.connect(integer socketId, string peerAddress, integer peerPort, function callback)

将套接字连接到远程计算机。connect 操作成功完成后，从对方接收到数据时就会产生 onReceive 事件。如果运行时接收数据包时发生网络错误，则会产生 onReceiveError 事件，并且从这时候开始不会再次产生 onReceive 事件，直到您调用 setPaused(false) 方法。

参数

integer

socketId

套接字标识符。

string

peerAddress

远程计算机的地址，支持 DNS 名称、IPv4 和 IPv6 格式的地址。

integer

peerPort

远程计算机的端口。

function

callback

连接完成后调用。

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

function(integer result) {...};

integer

result

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

disconnect


              chrome.sockets.tcp.disconnect(integer socketId, function callback)

断开套接字的连接。

参数

integer

socketId

套接字标识符。

function

（可选）
callback

连接断开后调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

secure


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

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

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

参数

integer

socketId

现有的已连接的套接字。

object

（可选）
options

TLS 连接的约束和参数。

object

（可选）
tlsVersion

string	（可选） min	可以接受的最低和最高 TLS 版本，可以为 `ssl3`、`tls1`、`tls1.1` 或 `tls1.2`。
string	（可选） max

function

callback

尝试连接完成后调用。

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

function(integer result) {...};

integer

result

send


              chrome.sockets.tcp.send(integer socketId, ArrayBuffer data, function callback)

在指定 TCP 套接字上发送数据。

参数

integer

socketId

套接字标识符。

ArrayBuffer

data

要发送的数据。

function

callback

send 操作完成时调用。

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

function(object sendInfo) {...};

object

sendInfo

send 方法的结果。

integer	resultCode	底层网络调用返回的结果代码，负值表示错误。
integer	（可选） bytesSent	发送的字节数（如果 result == 0 的话）。

close


              chrome.sockets.tcp.close(integer socketId, function callback)

关闭套接字，并释放套接字绑定的地址/端口。每一个创建的套接字在使用完成后都必须关闭。该函数调用后套接字标识符就失效，但是调用回调函数时才能保证套接字已经关闭。

参数

integer

socketId

套接字标识符。

function

（可选）
callback

close 操作完成时调用。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function() {...};

getInfo


              chrome.sockets.tcp.getInfo(integer socketId, function callback)

获取指定套接字的状态。

参数

integer

socketId

套接字标识符。

function

callback

套接字状态可用时调用。

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

function( SocketInfo socketInfo) {...};

SocketInfo

socketInfo

包含套接字信息的对象。

getSockets


              chrome.sockets.tcp.getSockets(function callback)

获取应用拥有的当前打开的套接字列表。

参数

function

callback

套接字列表可用时调用。

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

function(array of SocketInfo socketInfos) {...};

array of SocketInfo

socketInfos

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

事件

onReceive

套接字接收到数据时产生该事件。

addListener


                    chrome.sockets.tcp.onReceive.addListener(function callback)

参数

function

callback

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

function(object info) {...};

object

info

事件数据。

integer	socketId	套接字标识符。
ArrayBuffer	data	接收到的数据，最大大小为 `bufferSize`。

onReceiveError

运行时等待该套接字地址和端口上的数据时如果发生网络错误则产生该事件。一旦产生该事件后，套接字将设置为 paused（暂停）状态，不再产生 onReceive 事件。

addListener


                    chrome.sockets.tcp.onReceiveError.addListener(function callback)

参数

function

callback

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

function(object info) {...};

object

info

事件数据。

integer	socketId	套接字标识符。
integer	resultCode	底层网络调用返回的结果代码。