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.
Summary
- Types
- Methods
chrome.sockets.udp.bind(socketId: number, address: string, port: number, callback: function)
chrome.sockets.udp.close(socketId: number, callback: function)
chrome.sockets.udp.create(properties?: SocketProperties, callback: function)
chrome.sockets.udp.getInfo(socketId: number, callback: function)
chrome.sockets.udp.getJoinedGroups(socketId: number, callback: function)
chrome.sockets.udp.getSockets(callback: function)
chrome.sockets.udp.joinGroup(socketId: number, address: string, callback: function)
chrome.sockets.udp.leaveGroup(socketId: number, address: string, callback: function)
chrome.sockets.udp.send(socketId: number, data: ArrayBuffer, address: string, port: number, callback: function)
chrome.sockets.udp.setBroadcast(socketId: number, enabled: boolean, callback: function)
chrome.sockets.udp.setMulticastLoopbackMode(socketId: number, enabled: boolean, callback: function)
chrome.sockets.udp.setMulticastTimeToLive(socketId: number, ttl: number, callback: function)
chrome.sockets.udp.setPaused(socketId: number, paused: boolean, callback: function)
chrome.sockets.udp.update(socketId: number, properties: SocketProperties, callback: function)
- Events
Types
CreateInfo
Properties
- socketIdnumber
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
API.socket
ReceiveErrorInfo
Properties
- resultCodenumber
The result code returned from the underlying recvfrom() call.
- socketIdnumber
The socket ID.
ReceiveInfo
Properties
- dataArrayBuffer
The UDP packet content (truncated to the current buffer size).
- remoteAddressstring
The address of the host the packet comes from.
- remotePortnumber
The port of the host the packet comes from.
- socketIdnumber
The socket ID.
SendInfo
Properties
- bytesSentnumber optional
The number of bytes sent (if result == 0)
- resultCodenumber
The result code returned from the underlying network call. A negative value indicates an error.
SocketInfo
Properties
- bufferSizenumber optional
The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
- localAddressstring optional
If the underlying socket is bound, contains its local IPv4/6 address.
- localPortnumber optional
If the underlying socket is bound, contains its local port.
- namestring optional
Application-defined string associated with the socket.
- pausedboolean
Flag indicating whether the socket is blocked from firing onReceive events.
- persistentboolean
Flag indicating whether the socket is left open when the application is suspended (see
SocketProperties.persistent
). - socketIdnumber
The socket identifier.
SocketProperties
Properties
- bufferSizenumber optional
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.
- namestring optional
An application-defined string associated with the socket.
- persistentboolean optional
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
.
Methods
bind
chrome.sockets.udp.bind(socketId: number, address: string, port: number, callback: function)
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
- socketIdnumber
The socket ID.
- addressstring
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.
- portnumber
The port of the local machine. Use "0" to bind to a free port.
- callbackfunction
Called when the
bind
operation completes.The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
close
chrome.sockets.udp.close(socketId: number, callback: function)
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
- socketIdnumber
The socket ID.
- callbackfunction
Called when the
close
operation completes.The callback parameter should be a function that looks like this:
() => {...}
create
chrome.sockets.udp.create(properties?: SocketProperties, callback: function)
Creates a UDP socket with the given properties.
Parameters
- propertiesSocketProperties optional
The socket properties (optional).
- callbackfunction
Called when the socket has been created.
The callback parameter should be a function that looks like this:
(createInfo: CreateInfo) => {...}
- createInfo
The result of the socket creation.
getInfo
chrome.sockets.udp.getInfo(socketId: number, callback: function)
Retrieves the state of the given socket.
Parameters
- socketIdnumber
The socket ID.
- callbackfunction
Called when the socket state is available.
The callback parameter should be a function that looks like this:
(socketInfo: SocketInfo) => {...}
- socketInfo
Object containing the socket information.
getJoinedGroups
chrome.sockets.udp.getJoinedGroups(socketId: number, callback: function)
Gets the multicast group addresses the socket is currently joined to.
Parameters
- socketIdnumber
The socket ID.
- callbackfunction
Called with an array of strings of the result.
The callback parameter should be a function that looks like this:
(groups: string[]) => {...}
- groupsstring[]
Array of groups the socket joined.
getSockets
chrome.sockets.udp.getSockets(callback: function)
Retrieves the list of currently opened sockets owned by the application.
Parameters
- callbackfunction
Called when the list of sockets is available.
The callback parameter should be a function that looks like this:
(socketInfos: SocketInfo[]) => {...}
- socketInfos
Array of object containing socket information.
joinGroup
chrome.sockets.udp.joinGroup(socketId: number, address: string, callback: function)
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
- socketIdnumber
The socket ID.
- addressstring
The group address to join. Domain names are not supported.
- callbackfunction
Called when the
joinGroup
operation completes.The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
leaveGroup
chrome.sockets.udp.leaveGroup(socketId: number, address: string, callback: function)
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
- socketIdnumber
The socket ID.
- addressstring
The group address to leave. Domain names are not supported.
- callbackfunction
Called when the
leaveGroup
operation completes.The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
send
chrome.sockets.udp.send(socketId: number, data: ArrayBuffer, address: string, port: number, callback: function)
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
- socketIdnumber
The socket ID.
- dataArrayBuffer
The data to send.
- addressstring
The address of the remote machine.
- portnumber
The port of the remote machine.
- callbackfunction
setBroadcast
chrome.sockets.udp.setBroadcast(socketId: number, enabled: boolean, callback: function)
Enables or disables broadcast packets on this socket.
Parameters
- socketIdnumber
The socket ID.
- enabledboolean
true
to enable broadcast packets,false
to disable them. - callbackfunction
Callback from the
setBroadcast
method.The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call.
setMulticastLoopbackMode
chrome.sockets.udp.setMulticastLoopbackMode(socketId: number, enabled: boolean, callback: function)
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
- socketIdnumber
The socket ID.
- enabledboolean
Indicate whether to enable loopback mode.
- callbackfunction
Called when the configuration operation completes.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
setMulticastTimeToLive
chrome.sockets.udp.setMulticastTimeToLive(socketId: number, ttl: number, callback: function)
Sets the time-to-live of multicast packets sent to the multicast group.
Calling this method does not require multicast permissions.
Parameters
- socketIdnumber
The socket ID.
- ttlnumber
The time-to-live value.
- callbackfunction
Called when the configuration operation completes.
The callback parameter should be a function that looks like this:
(result: number) => {...}
- resultnumber
The result code returned from the underlying network call. A negative value indicates an error.
setPaused
chrome.sockets.udp.setPaused(socketId: number, paused: boolean, callback: function)
Pauses or unpauses a socket. A paused socket is blocked from firing onReceive
events.
Parameters
- socketIdnumber
- pausedboolean
Flag to indicate whether to pause or unpause.
- callbackfunction
Called when the socket has been successfully paused or unpaused.
The callback parameter should be a function that looks like this:
() => {...}
update
chrome.sockets.udp.update(socketId: number, properties: SocketProperties, callback: function)
Updates the socket properties.
Parameters
- socketIdnumber
The socket ID.
- properties
The properties to update.
- callbackfunction
Called when the properties are updated.
The callback parameter should be a function that looks like this:
() => {...}
Events
onReceive
chrome.sockets.udp.onReceive.addListener(listener: function)
Event raised when a UDP packet has been received for the given socket.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: ReceiveInfo) => {...}
- info
The event data.
onReceiveError
chrome.sockets.udp.onReceiveError.addListener(listener: function)
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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(info: ReceiveErrorInfo) => {...}
- info
The event data.