chrome.sockets.udp

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

摘要

类型
SocketProperties
SocketInfo
方法
create − `chrome.sockets.udp.create( SocketProperties properties, function callback)`
update − `chrome.sockets.udp.update(integer socketId, SocketProperties properties, function callback)`
setPaused − `chrome.sockets.udp.setPaused(integer socketId, boolean paused, function callback)`
bind − `chrome.sockets.udp.bind(integer socketId, string address, integer port, function callback)`
send − `chrome.sockets.udp.send(integer socketId, ArrayBuffer data, string address, integer port, function callback)`
close − `chrome.sockets.udp.close(integer socketId, function callback)`
getInfo − `chrome.sockets.udp.getInfo(integer socketId, function callback)`
getSockets − `chrome.sockets.udp.getSockets(function callback)`
joinGroup − `chrome.sockets.udp.joinGroup(integer socketId, string address, function callback)`
leaveGroup − `chrome.sockets.udp.leaveGroup(integer socketId, string address, function callback)`
setMulticastTimeToLive − `chrome.sockets.udp.setMulticastTimeToLive(integer socketId, integer ttl, function callback)`
setMulticastLoopbackMode − `chrome.sockets.udp.setMulticastLoopbackMode(integer socketId, boolean enabled, function callback)`
getJoinedGroups − `chrome.sockets.udp.getJoinedGroups(integer socketId, function callback)`
事件
onReceive
onReceiveError

类型

SocketProperties

属性
boolean	（可选） persistent	事件页面或应用程序关闭（参见管理应用的生命周期）时套接字是否保持打开，默认值为 false。应用程序加载时，之前以 persistent: true 打开的套接字可以通过 `getSockets` 获取。
string	（可选） name	与该套接字相关联的字符串，由应用定义。
integer	（可选） bufferSize	用于接收数据的缓冲区大小。如果缓冲区太小而无法接收某个 UDP 包，则会丢失数据。默认值为 4096。

SocketInfo

属性
integer	socketId	应用关闭时（参见 `SocketProperties.persistent`）套接字是否保持打开状态。
string	（可选） name	与套接字相关联的字符串，由应用定义。
integer	（可选） bufferSize	用于接收数据的缓冲区大小。如果没有明确指定缓冲区大小，则不提供该属性的值。
boolean	paused	表示是否阻止套接字产生 onReceive 事件。
string	（可选） localAddress	如果套接字已绑定，则包含它的本地 IPv4/6 地址。
integer	（可选） localPort	如果套接字已绑定，则包含它的本地端口。

方法

create


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

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

参数

SocketProperties

（可选）
properties

套接字属性（可选）。

function

callback

套接字创建后调用。

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

function(object createInfo) {...};

object

createInfo

套接字创建的结果。

integer

socketId

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

update


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

更新套接字属性。

参数

integer

socketId

套接字标识符。

SocketProperties

properties

要更新的属性。

function

（可选）
callback

属性更新后调用。

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

function() {...};

setPaused


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

暂停或取消暂停套接字。暂停的套接字不会收到 onReceive 事件。

参数

integer socketId

boolean

paused

参数
integer	socketId
boolean	paused	表示是暂停还是取消暂停的标志。
function	（可选） callback	套接字暂停或取消暂停成功时调用。如果您指定了 callback 参数，它应该是一个如下形式的函数： `function() {...};`

表示是暂停还是取消暂停的标志。

function

（可选）
callback

套接字暂停或取消暂停成功时调用。

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

function() {...};

bind


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

为套接字绑定本机地址和端口。对于客户端套接字来说，建议使用端口 0 以便让平台选择一个空闲的端口。一旦 bind 操作成功完成，只要指定地址/端口上收到 UDP 数据包就会产生 onReceive 事件，除非套接字已暂停。

参数

integer

socketId

套接字标识符。

string

address

本地计算机的地址，支持 DNS 名称、IPv4 和 IPv6 地址。使用 "0.0.0.0" 可以从所有本地可用的网络接口接收数据包。

integer

port

本地计算机的端口，使用 0 可以绑定至某个空闲端口。

function

callback

bind 操作完成时调用。

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

function(integer result) {...};

integer

result

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

send


              chrome.sockets.udp.send(integer socketId, ArrayBuffer data, string address, integer port, function callback)

在指定套接字上向指定的地址和端口发送数据。调用该方法前，套接字必须绑定至某个本机端口。

参数

integer

socketId

套接字标识符。

ArrayBuffer

data

要发送的数据。

string

address

远程计算机的地址。

integer

port

远程计算机的端口。

function

callback

send 操作完成时调用。

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

function(object sendInfo) {...};

object

sendInfo

send 方法的结果。

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

close


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

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

参数

integer

socketId

套接字标识符。

function

（可选）
callback

close 操作完成时调用。

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

function() {...};

getInfo


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

获取指定套接字的状态。

参数

integer

socketId

套接字标识符。

function

callback

套接字状态可用时调用。

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

function( SocketInfo socketInfo) {...};

SocketInfo

socketInfo

包含套接字信息的对象。

getSockets


              chrome.sockets.udp.getSockets(function callback)

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

参数

function

callback

套接字列表可用时调用。

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

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

array of SocketInfo

socketInfos

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

joinGroup


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

加入多播分组，开始接收来自指定分组的数据包。调用该方法前套接字必须绑定至某个本机端口。

参数

integer

socketId

套接字标识符。

string

address

要加入的分组地址，不支持域名。

function

callback

joinGroup 操作完成时调用。

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

function(integer result) {...};

integer

result

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

leaveGroup


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

离开之前通过 joinGroup 加入的多播分组。只有您还需要继续使用该套接字时才需要调用，套接字关闭时操作系统会自动进行该操作。

离开分组后，如果主机上没有其他进程仍然加入该分组，路由器就不会将多播数据包发送至本地主机。

参数

integer

socketId

套接字标识符。

string

address

要离开的分组地址，不支持域名。

function

callback

leaveGroup 操作完成时调用。

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

function(integer result) {...};

integer

result

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

setMulticastTimeToLive


              chrome.sockets.udp.setMulticastTimeToLive(integer socketId, integer ttl, function callback)

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

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

参数

integer

socketId

套接字标识符。

integer

ttl

TTL 值。

function

callback

配置操作完成时调用。

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

function(integer result) {...};

integer

result

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

setMulticastLoopbackMode


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

设置从主机到多播组的数据包是否要回环至主机。

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

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

参数

integer

socketId

套接字标识符。

boolean

enabled

表示是否启用回环模式。

function

callback

配置操作完成后调用。

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

function(integer result) {...};

integer

result

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

getJoinedGroups


              chrome.sockets.udp.getJoinedGroups(integer socketId, function callback)

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

参数

integer

socketId

套接字标识符。

function

callback

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

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

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

array of string

groups

套接字加入的分组。

事件

onReceive

指定套接字接收到 UDP 数据包时产生该事件。

addListener


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

参数

function

callback

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

function(object info) {...};

object

info

事件数据。

integer	socketId	套接字标识符。
ArrayBuffer	data	UDP 数据包内容（可能会根据当前缓冲区大小而截断）。
string	remoteAddress	数据包来源主机的地址。
integer	remotePort	数据包来源主机的端口。

onReceiveError

运行时在套接字地址和端口上等待数据时如果发生网络错误，就会产生该事件。一旦产生该事件后，套接字会暂停，该套接字不再产生 onReceive 事件，直到套接字恢复。

addListener


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

参数

function

callback

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

function(object info) {...};

object

info

事件数据。

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