// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.sockets.udp</code> API to send and receive data over the
// network using UDP connections. This API supersedes the UDP functionality
// previously found in the "socket" API.
namespace sockets.udp {
  // The socket properties specified in the <code>create</code> or
  // <code>update</code> function. Each property is optional. If a property
  // value is not specified, a default value is used when calling
  // <code>create</code>, or the existing value if preserved when calling
  // <code>update</code>.
  dictionary SocketProperties {
    // Flag indicating if the socket is left open when the event page of the
    // application is unloaded (see
    // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
    // Lifecycle</a>). The default value is "false." When the application is
    // loaded, any sockets previously opened with persistent=true can be fetched
    // with <code>getSockets</code>.
    boolean? persistent;

    // An application-defined string associated with the socket.
    DOMString? name;

    // 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.
    long? bufferSize;
  };

  // Result of <code>create</code> call.
  dictionary CreateInfo {
    // 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 <code>$(ref:socket)</code> API.
    long socketId;
  };

  // Callback from the <code>create</code> method.
  // |createInfo| : The result of the socket creation.
  callback CreateCallback = void (CreateInfo createInfo);

  // Callback from the <code>bind</code> method.
  // |result| : The result code returned from the underlying network call.
  // A negative value indicates an error.
  callback BindCallback = void (long result);

  // DNS resolution preferences. The default is <code>any</code> and uses the
  // current OS config which may return IPv4 or IPv6. <code>ipv4</code> forces
  // IPv4, and <code>ipv6</code> forces IPv6.
  enum DnsQueryType { any, ipv4, ipv6 };

  // Result of the <code>send</code> method.
  dictionary SendInfo {
    // The result code returned from the underlying network call.
    // A negative value indicates an error.
    long resultCode;

    // The number of bytes sent (if result == 0)
    long? bytesSent;
  };

  // Callback from the <code>send</code> method.
  // |sendInfo| : Result of the <code>send</code> method.
  callback SendCallback = void (SendInfo sendInfo);

  // Callback from the <code>close</code> method.
  callback CloseCallback = void ();

  // Callback from the <code>update</code> method.
  callback UpdateCallback = void ();

  // Callback from the <code>setPaused</code> method.
  callback SetPausedCallback = void ();

  // Result of the <code>getInfo</code> method.
  dictionary SocketInfo {
    // The socket identifier.
    long socketId;

    // Flag indicating whether the socket is left open when the application is
    // suspended (see <code>SocketProperties.persistent</code>).
    boolean persistent;

    // Application-defined string associated with the socket.
    DOMString? name;

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

    // Flag indicating whether the socket is blocked from firing onReceive
    // events.
    boolean paused;

    // If the underlying socket is bound, contains its local
    // IPv4/6 address.
    DOMString? localAddress;

    // If the underlying socket is bound, contains its local port.
    long? localPort;
  };

  // Callback from the <code>getInfo</code> method.
  // |socketInfo| : Object containing the socket information.
  callback GetInfoCallback = void (SocketInfo socketInfo);

  // Callback from the <code>getSockets</code> method.
  // |socketInfos| : Array of object containing socket information.
  callback GetSocketsCallback = void (SocketInfo[] socketInfos);

  // Callback from the <code>joinGroup</code> method.
  // |result| : The result code returned from the underlying network call.
  // A negative value indicates an error.
  callback JoinGroupCallback = void (long result);

  // Callback from the <code>leaveGroup</code> method.
  // |result| : The result code returned from the underlying network call.
  // A negative value indicates an error.
  callback LeaveGroupCallback = void (long result);

  // Callback from the <code>setMulticastTimeToLive</code> method.
  // |result| : The result code returned from the underlying network call.
  // A negative value indicates an error.
  callback SetMulticastTimeToLiveCallback = void (long result);

  // Callback from the <code>setMulticastLoopbackMode</code> method.
  // |result| : The result code returned from the underlying network call.
  // A negative value indicates an error.
  callback SetMulticastLoopbackModeCallback = void (long result);

  // Callback from the <code>getJoinedGroupsCallback</code> method.
  // |groups| : Array of groups the socket joined.
  callback GetJoinedGroupsCallback = void (DOMString[] groups);

  // Callback from the <code>setBroadcast</code> method.
  // |result| : The result code returned from the underlying network call.
  callback SetBroadcastCallback = void (long result);

  // Data from an <code>onReceive</code> event.
  dictionary ReceiveInfo {
    // The socket ID.
    long socketId;

    // The UDP packet content (truncated to the current buffer size).
    ArrayBuffer data;

    // The address of the host the packet comes from.
    DOMString remoteAddress;

     // The port of the host the packet comes from.
    long remotePort;
  };

  // Data from an <code>onReceiveError</code> event.
  dictionary ReceiveErrorInfo {
    // The socket ID.
    long socketId;

     // The result code returned from the underlying recvfrom() call.
    long resultCode;
  };

  interface Functions {
    // Creates a UDP socket with the given properties.
    // |properties| : The socket properties (optional).
    // |callback| : Called when the socket has been created.
    static void create(optional SocketProperties properties,
                       CreateCallback callback);

    // Updates the socket properties.
    // |socketId| : The socket ID.
    // |properties| : The properties to update.
    // |callback| : Called when the properties are updated.
    static void update(long socketId,
                       SocketProperties properties,
                       optional UpdateCallback callback);

    // Pauses or unpauses a socket. A paused socket is blocked from firing
    // <code>onReceive</code> events.
    // |connectionId| : The socket ID.
    // |paused| : Flag to indicate whether to pause or unpause.
    // |callback| : Called when the socket has been successfully paused or
    // unpaused.
    static void setPaused(long socketId,
                          boolean paused,
                          optional SetPausedCallback 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 <code>bind</code> operation completes successfully,
    // <code>onReceive</code> events are raised when UDP packets arrive on the
    // address/port specified -- unless the socket is paused.
    //
    // |socketId| : The socket ID.
    // |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.
    // |port| : The port of the local machine. Use "0" to bind to a free port.
    // |callback| : Called when the <code>bind</code> operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void bind(long socketId,
                     DOMString address,
                     long port,
                     BindCallback 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.
    // |socketId| : The socket ID.
    // |data| : The data to send.
    // |address| : The address of the remote machine.
    // |port| : The port of the remote machine.
    // |dnsQueryType| : The address resolution preference.
    // |callback| : Called when the <code>send</code> operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void send(long socketId,
                     ArrayBuffer data,
                     DOMString address,
                     long port,
                     optional DnsQueryType dnsQueryType,
                     SendCallback 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.
    // |socketId| : The socket ID.
    // |callback| : Called when the <code>close</code> operation completes.
    static void close(long socketId,
                      optional CloseCallback callback);

    // Retrieves the state of the given socket.
    // |socketId| : The socket ID.
    // |callback| : Called when the socket state is available.
    static void getInfo(long socketId,
                        GetInfoCallback callback);

    // Retrieves the list of currently opened sockets owned by the application.
    // |callback| : Called when the list of sockets is available.
    static void getSockets(GetSocketsCallback 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.
    // |socketId| : The socket ID.
    // |address| : The group address to join. Domain names are not supported.
    // |callback| : Called when the <code>joinGroup</code> operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void joinGroup(long socketId,
                          DOMString address,
                          JoinGroupCallback callback);

    // Leaves the multicast group previously joined using
    // <code>joinGroup</code>. 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.
    //
    // |socketId| : The socket ID.
    // |address| : The group address to leave. Domain names are not supported.
    // |callback| : Called when the <code>leaveGroup</code> operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void leaveGroup(long socketId,
                           DOMString address,
                           LeaveGroupCallback callback);

    // Sets the time-to-live of multicast packets sent to the multicast group.
    //
    // Calling this method does not require multicast permissions.
    //
    // |socketId| : The socket ID.
    // |ttl| : The time-to-live value.
    // |callback| : Called when the configuration operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void setMulticastTimeToLive(
        long socketId,
        long ttl,
        SetMulticastTimeToLiveCallback callback);

    // Sets whether multicast packets sent from the host to the multicast group
    // will be looped back to the host.
    //
    // Note: the behavior of <code>setMulticastLoopbackMode</code> 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:
    // https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2
    //
    // Calling this method does not require multicast permissions.
    //
    // |socketId| : The socket ID.
    // |enabled| : Indicate whether to enable loopback mode.
    // |callback| : Called when the configuration operation completes.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void setMulticastLoopbackMode(
        long socketId,
        boolean enabled,
        SetMulticastLoopbackModeCallback callback);

    // Gets the multicast group addresses the socket is currently joined to.
    // |socketId| : The socket ID.
    // |callback| : Called with an array of strings of the result.
    static void getJoinedGroups(long socketId,
                                GetJoinedGroupsCallback callback);

    // Enables or disables broadcast packets on this socket.
    //
    // |socketId| : The socket ID.
    // |enabled| : <code>true</code> to enable broadcast packets,
    // <code>false</code> to disable them.
    [doesNotSupportPromises=
        "Sets error along with callback arguments crbug.com/1504372"]
    static void setBroadcast(long socketId,
                             boolean enabled,
                             SetBroadcastCallback callback);
  };

  interface Events {
    // Event raised when a UDP packet has been received for the given socket.
    // |info| : The event data.
    static void onReceive(ReceiveInfo info);

    // 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 <code>onReceive</code> events will be raised
    // for this socket until the socket is resumed.
    // |info| : The event data.
    static void onReceiveError(ReceiveErrorInfo info);
  };
};