chrome.sockets.udp

Description:	Use the `chrome.sockets.udp` API to send and receive data over the network using UDP connections. This API supersedes the UDP functionality previously found in the "socket" API.
Availability:	Since Chrome 35.
Manifest:	"sockets": {...}

Summary

Types
SocketProperties
SocketInfo
Methods
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)`
setBroadcast − `chrome.sockets.udp.setBroadcast(integer socketId, boolean enabled, function callback)`
Events
onReceive
onReceiveError

Types

SocketProperties

properties
boolean	(optional) persistent	Flag indicating if the socket is left open when the event page of the application is unloaded (see Manage App Lifecycle). The default value is "false." When the application is loaded, any sockets previously opened with persistent=true can be fetched with `getSockets`.
string	(optional) name	An application-defined string associated with the socket.
integer	(optional) bufferSize	The size of the buffer used to receive data. If the buffer is too small to receive the UDP packet, data is lost. The default value is 4096.

SocketInfo

properties
integer	socketId	The socket identifier.
boolean	persistent	Flag indicating whether the socket is left open when the application is suspended (see `SocketProperties.persistent`).
string	(optional) name	Application-defined string associated with the socket.
integer	(optional) bufferSize	The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
boolean	paused	Flag indicating whether the socket is blocked from firing onReceive events.
string	(optional) localAddress	If the underlying socket is bound, contains its local IPv4/6 address.
integer	(optional) localPort	If the underlying socket is bound, contains its local port.

Methods

create


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

Creates a UDP socket with the given properties.

Parameters

SocketProperties

(optional) properties

The socket properties (optional).

function

callback

Called when the socket has been created.

The callback parameter should be a function that looks like this:

function(object createInfo) {...};

object

createInfo

The result of the socket creation.

integer

socketId

The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the deprecated socket API.

update


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

Updates the socket properties.

Parameters

integer

socketId

The socket ID.

SocketProperties

properties

The properties to update.

function

(optional) callback

Called when the properties are updated.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setPaused


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

Pauses or unpauses a socket. A paused socket is blocked from firing onReceive events.

Parameters

integer socketId

boolean

paused

Parameters
integer	socketId
boolean	paused	Flag to indicate whether to pause or unpause.
function	(optional) callback	Called when the socket has been successfully paused or unpaused. If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

Flag to indicate whether to pause or unpause.

function

(optional) callback

Called when the socket has been successfully paused or unpaused.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

bind


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

Binds the local address and port for the socket. For a client socket, it is recommended to use port 0 to let the platform pick a free port.

Once the bind operation completes successfully, onReceive events are raised when UDP packets arrive on the address/port specified -- unless the socket is paused.

Parameters

integer

socketId

The socket ID.

string

address

The address of the local machine. DNS name, IPv4 and IPv6 formats are supported. Use "0.0.0.0" to accept packets from all local available network interfaces.

integer

port

The port of the local machine. Use "0" to bind to a free port.

function

callback

Called when the bind operation completes.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call. A negative value indicates an error.

send


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

Sends data on the given socket to the given address and port. The socket must be bound to a local port before calling this method.

Parameters

integer

socketId

The socket ID.

ArrayBuffer

data

The data to send.

string

address

The address of the remote machine.

integer

port

The port of the remote machine.

function

callback

Called when the send operation completes.

The callback parameter should be a function that looks like this:

function(object sendInfo) {...};

object

sendInfo

Result of the send method.

integer	resultCode	The result code returned from the underlying network call. A negative value indicates an error.
integer	(optional) bytesSent	The number of bytes sent (if result == 0)

close


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

Closes the socket and releases the address/port the socket is bound to. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked.

Parameters

integer

socketId

The socket ID.

function

(optional) callback

Called when the close operation completes.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

getInfo


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

Retrieves the state of the given socket.

Parameters

integer

socketId

The socket ID.

function

callback

Called when the socket state is available.

The callback parameter should be a function that looks like this:

function( SocketInfo socketInfo) {...};

SocketInfo

socketInfo

Object containing the socket information.

getSockets


              chrome.sockets.udp.getSockets(function callback)

Retrieves the list of currently opened sockets owned by the application.

Parameters

function

callback

Called when the list of sockets is available.

The callback parameter should be a function that looks like this:

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

array of SocketInfo

socketInfos

Array of object containing socket information.

joinGroup


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

Joins the multicast group and starts to receive packets from that group. The socket must be bound to a local port before calling this method.

Parameters

integer

socketId

The socket ID.

string

address

The group address to join. Domain names are not supported.

function

callback

Called when the joinGroup operation completes.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call. A negative value indicates an error.

leaveGroup


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

Leaves the multicast group previously joined using joinGroup. This is only necessary to call if you plan to keep using the socketafterwards, since it will be done automatically by the OS when the socket is closed.

Leaving the group will prevent the router from sending multicast datagrams to the local host, presuming no other process on the host is still joined to the group.

Parameters

integer

socketId

The socket ID.

string

address

The group address to leave. Domain names are not supported.

function

callback

Called when the leaveGroup operation completes.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call. A negative value indicates an error.

setMulticastTimeToLive


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

Sets the time-to-live of multicast packets sent to the multicast group.

Calling this method does not require multicast permissions.

Parameters

integer

socketId

The socket ID.

integer

ttl

The time-to-live value.

function

callback

Called when the configuration operation completes.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call. A negative value indicates an error.

setMulticastLoopbackMode


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

Sets whether multicast packets sent from the host to the multicast group will be looped back to the host.

Note: the behavior of setMulticastLoopbackMode is slightly different between Windows and Unix-like systems. The inconsistency happens only when there is more than one application on the same host joined to the same multicast group while having different settings on multicast loopback mode. On Windows, the applications with loopback off will not RECEIVE the loopback packets; while on Unix-like systems, the applications with loopback off will not SEND the loopback packets to other applications on the same host. See MSDN: http://goo.gl/6vqbj

Calling this method does not require multicast permissions.

Parameters

integer

socketId

The socket ID.

boolean

enabled

Indicate whether to enable loopback mode.

function

callback

Called when the configuration operation completes.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call. A negative value indicates an error.

getJoinedGroups


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

Gets the multicast group addresses the socket is currently joined to.

Parameters

integer

socketId

The socket ID.

function

callback

Called with an array of strings of the result.

The callback parameter should be a function that looks like this:

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

array of string

groups

Array of groups the socket joined.

setBroadcast


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

Since Chrome 44.

Enables or disables broadcast packets on this socket.

Parameters

integer

socketId

The socket ID.

boolean

enabled

true to enable broadcast packets, false to disable them.

function

callback

Callback from the setBroadcast method.

The callback parameter should be a function that looks like this:

function(integer result) {...};

integer

result

The result code returned from the underlying network call.

Events

onReceive

Event raised when a UDP packet has been received for the given socket.

addListener


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

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

integer	socketId	The socket ID.
ArrayBuffer	data	The UDP packet content (truncated to the current buffer size).
string	remoteAddress	The address of the host the packet comes from.
integer	remotePort	The port of the host the packet comes from.

onReceiveError

Event raised when a network error occured while the runtime was waiting for data on the socket address and port. Once this event is raised, the socket is paused and no more onReceive events will be raised for this socket until the socket is resumed.

addListener


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

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

The event data.

integer	socketId	The socket ID.
integer	resultCode	The result code returned from the underlying recvfrom() call.