Welcome Getting started API Reference Samples
Welcome Getting started API Reference Samples

chrome.sockets.udp

Warning
This API is part of the deprecated Chrome Apps platform. Learn more about migrating your app.
  • 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

  • socketId
    number

    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.

ReceiveErrorInfo

Properties

  • resultCode
    number

    The result code returned from the underlying recvfrom() call.

  • socketId
    number

    The socket ID.

ReceiveInfo

Properties

  • data
    ArrayBuffer

    The UDP packet content (truncated to the current buffer size).

  • remoteAddress
    string

    The address of the host the packet comes from.

  • remotePort
    number

    The port of the host the packet comes from.

  • socketId
    number

    The socket ID.

SendInfo

Properties

  • bytesSent
    number optional

    The number of bytes sent (if result == 0)

  • resultCode
    number

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

SocketInfo

Properties

  • bufferSize
    number optional

    The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.

  • localAddress
    string optional

    If the underlying socket is bound, contains its local IPv4/6 address.

  • localPort
    number optional

    If the underlying socket is bound, contains its local port.

  • name
    string optional

    Application-defined string associated with the socket.

  • paused
    boolean

    Flag indicating whether the socket is blocked from firing onReceive events.

  • persistent
    boolean

    Flag indicating whether the socket is left open when the application is suspended (see SocketProperties.persistent).

  • socketId
    number

    The socket identifier.

SocketProperties

Properties

  • bufferSize
    number 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.

  • name
    string optional

    An application-defined string associated with the socket.

  • persistent
    boolean 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

  • socketId
    number

    The socket ID.

  • address
    string

    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.

  • port
    number

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

  • callback
    function

    Called when the bind operation completes.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number

    The socket ID.

  • callback
    function

    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

  • properties

    The socket properties (optional).

  • callback
    function

    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

  • socketId
    number

    The socket ID.

  • callback
    function

    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

  • socketId
    number

    The socket ID.

  • callback
    function

    Called with an array of strings of the result.

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

    (groups: string[]) => {...}
    • groups
      string[]

      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

  • callback
    function

    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

  • socketId
    number

    The socket ID.

  • address
    string

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

  • callback
    function

    Called when the joinGroup operation completes.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number

    The socket ID.

  • address
    string

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

  • callback
    function

    Called when the leaveGroup operation completes.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number

    The socket ID.

  • data
    ArrayBuffer

    The data to send.

  • address
    string

    The address of the remote machine.

  • port
    number

    The port of the remote machine.

  • callback
    function

    Called when the send operation completes.

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

    (sendInfo: SendInfo) => {...}
    • sendInfo

      Result of the send method.

setBroadcast

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

Enables or disables broadcast packets on this socket.

Parameters

  • socketId
    number

    The socket ID.

  • enabled
    boolean

    true to enable broadcast packets, false to disable them.

  • callback
    function

    Callback from the setBroadcast method.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number

    The socket ID.

  • enabled
    boolean

    Indicate whether to enable loopback mode.

  • callback
    function

    Called when the configuration operation completes.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number

    The socket ID.

  • ttl
    number

    The time-to-live value.

  • callback
    function

    Called when the configuration operation completes.

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

    (result: number) => {...}
    • result
      number

      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

  • socketId
    number
  • paused
    boolean

    Flag to indicate whether to pause or unpause.

  • callback
    function

    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

  • socketId
    number

    The socket ID.

  • The properties to update.

  • callback
    function

    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

  • listener
    function

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

    (info: ReceiveInfo) => {...}

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

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.