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

// Use the <code>chrome.gcdPrivate</code> API to discover GCD APIs and register
// them.
namespace gcdPrivate {

  enum SetupType { mdns, wifi, cloud };

  // Represents a GCD device discovered locally or registered to a given user.
  dictionary GCDDevice {
    // Opaque device identifier to be passed to API.
    DOMString deviceId;

    // How this device was discovered.
    SetupType setupType;

    // Cloud identifier string.
    DOMString? cloudId;

    // Device type (camera, printer, etc)
    DOMString deviceType;

    // Device human readable name.
    DOMString deviceName;

    // Device human readable description.
    DOMString deviceDescription;
  };

  callback CloudDeviceListCallback = void(GCDDevice[] devices);

  // |commandDefinitions| : Is "commandDefs" value of device described at
  // https://developers.google.com/cloud-devices/v1/reference/devices
  // TODO(vitalybuka): consider to describe object in IDL.
  callback CommandDefinitionsCallback = void(object commandDefinitions);

  // |command| : Described at
  // https://developers.google.com/cloud-devices/v1/reference/commands
  // TODO(vitalybuka): consider to describe object in IDL.
  callback CommandCallback = void(object command);

  // |commands| : Array of commands described at
  // https://developers.google.com/cloud-devices/v1/reference/commands
  // TODO(vitalybuka): consider to describe object in IDL.
  callback CommandListCallback = void(object[] commands);

  interface Functions {
    // Returns the list of cloud devices visible locally or available in the
    // cloud for user account.
    static void getCloudDeviceList(CloudDeviceListCallback callback);

    // Queries network for local devices. Triggers an onDeviceStateChanged and
    // onDeviceRemoved events. Call this function *only* after registering for
    // onDeviceStateChanged and onDeviceRemoved events, or it will do nothing.
    static void queryForNewLocalDevices();

    // Starts device setup process. Returns id of setup process. Id should be
    // used as |setupId| in all subsequent setup related calls, and for
    // filtering setup events.
    static long startSetup(DOMString deviceId);

    // Sets WiFi network as reply to |onGetWifiNetworks| event.
    // |setupId| : The value returned by |startSetup|.
    // |network| : The wifi network for device setup.
    static void setWiFiNetwork(long setupId, DOMString network);

    // Sets WiFi network password as reply to |onGetWifiPassword| event.
    // |setupId| : The value returned by |startSetup|.
    // |password| : The password for network selected with |setWiFiNetwork|.
    static void setWiFiPassword(long setupId, DOMString password);

    // Confirms that security code known to application match to the code known
    // to device.
    // |setupId| : The value returned by |startSetup|.
    static void confirmCode(long setupId);

    // Stops registration process.
    // This call triggers |onSetupError| event. App should wait this even before
    // starting new registration.
    // |setupId| : The value returned by |startSetup|.
    static void stopSetup(long setupId);

    // Returns command definitions.
    // |deviceId| : The device to get command definitions for.
    // |callback| : The result callback.
    static void getCommandDefinitions(DOMString deviceId,
                                      CommandDefinitionsCallback callback);

    // Creates and sends a new command.
    // |deviceId| : The device to send the command to.
    // |expireInMs| : The number of milliseconds since now before the command
    // expires. Expired command should not be executed by device. Acceptable
    // values are 10000 to 2592000000, inclusive. All values outside that range
    // will be replaced by 2592000000.
    // |command| : Described at
    // https://developers.google.com/cloud-devices/v1/reference/commands
    // |callback| : The result callback.
    static void insertCommand(DOMString deviceId,
                              long expireInMs,
                              object command,
                              CommandCallback callback);

    // Returns a particular command.
    // |commandId| : Unique command ID.
    // |callback| : The result callback.
    static void getCommand(DOMString commandId, CommandCallback callback);

    // Cancels a command.
    // |commandId| : Unique command ID.
    // |callback| : The result callback.
    static void cancelCommand(DOMString commandId, CommandCallback callback);

    // Lists all commands in order of creation.
    // |deviceId| : The device to get the commands for.
    // |byUser| : List all the commands issued by the user. Special value 'me'
    // can be used to list by the current user.
    // |state| : Command state.
    // |callback| : The result callback.
    static void getCommandsList(DOMString deviceId,
                                DOMString byUser,
                                DOMString state,
                                CommandListCallback callback);
  };

  interface Events {
    // Subscribe to this event to start listening new or updated devices. New
    // listeners will get called with all known devices on the network, and
    // status updates for devices available through the cloud.
    static void onDeviceStateChanged(GCDDevice device);

    // Notifies that device has disappeared.
    // |deviceId| : The device has disappeared.
    static void onDeviceRemoved(DOMString deviceId);

    // Notifies app that setup is waiting for a wifi network. App should reply
    // with |setWiFiNetwork|.
    // |setupId| : The value returned by |startSetup|.
    static void onGetWifiNetwork(long setupId);

    // Notifies app that setup is waiting for password for the network provided
    // with |setWiFiNetwork|. Even will be called if setup flow would unable to
    // get password from the system.
    // App should reply with |setWiFiPassword|.
    // |setupId| : The value returned by |startSetup|.
    static void onGetWifiPassword(long setupId);

    // Notifies app that setup is waiting for confirmation that code is the same
    // as code known to device. App should reply with |confirmCode|, or
    // |stopSetup| if code does not match.
    // |confirmationCode| : The code to confirm.
    // |setupId| : The value returned by |startSetup|.
    static void onConfirmCode(long setupId, DOMString confirmationCode);

    // Notifies app that setup is completed successfully.
    // |setupId| : The value returned by |startSetup|.
    static void onSetupSuccess(long setupId);

    // Notifies app that setup is failed or stopped.
    // |setupId| : The value returned by |startSetup|.
    static void onSetupError(long setupId);
  };
};