chrome/common/extensions/api/gcd_private.idl

// 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;
  };

  enum Status {
    // Success.
    success,

    // populateWifiPassword was true and the password has not been prefetched.
    wifiPasswordError,

    // populateWifiPassword was true and the message cannot be parsed as a setup
    // message.
    setupParseError,

    // Could not connect to the device.
    connectionError,

    // Error in establishing session.
    sessionError,

    // Unknown session.
    unknownSessionError,

    // Bad pairing code.
    badPairingCodeError,

    // Device error with details in response object.
    deviceError
  };

  enum PairingType {
    pinCode,
    embeddedCode
  };

  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);

  // Generic callback for session calls, with status only.
  callback SessionCallback = void(Status status);

  // Called when device starts to establish a secure session.
  // If |status| is |success| app should call |startPairing|.
  // |sessionId| : The session ID (identifies the session for future calls).
  // |status| : The status of operation (success or type of error).
  // |pairingTypes| is the list of supported pairing types.
  callback EstablishSessionCallback = void(long sessionId,
                                           Status status,
                                           PairingType[] pairingTypes);

  // Called when the response to the message sent is available or on error.
  // |status| : The status of operation (success or type of error).
  // |response| : The response object with result or error description. May be
  // empty for some errors.
  callback SendMessageCallback = void(Status status, object response);

  // Called as a response to |prefetchWifiPassword|
  // |success| : Denotes whether the password fetch has succeeded or failed.
  callback SuccessCallback = void(boolean success);

  // Called as a response to |getPrefetchedWifiNameList|
  // |networks| : The list of ssids for which wifi passwords were prefetched.
  callback SSIDListCallback = void(DOMString[] networks);

  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();

    // Cache the WiFi password in the browser process for use during
    // provisioning. This is done to allow the gathering of the wifi password to
    // not be done while connected to the device's network. Callback is called
    // with true if wifi password was cached and false if it was unavailable.
    // |ssid| : The network to prefetch password for.
    static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);

    // Get the list of ssids with prefetched callbacks.
    static void getPrefetchedWifiNameList(SSIDListCallback callback);

    // Establish the session.
    // |ipAddress| : The IPv4 or IPv6 address of the device.
    // |port| : The port with Privet HTTP server.
    static void establishSession(DOMString ipAddress,
                                 long port,
                                 EstablishSessionCallback callback);

    // Start pairing with selected method. Should be called after
    // |establishSession|.
    // |sessionId| : The ID of the session created with |establishSession|.
    // |pairingType| : The value selected from the list provided in
    // callback of |establishSession|.
    static void startPairing(long sessionId,
                             PairingType pairingType,
                             SessionCallback callback);

    // Confirm pairing code. Should be called after |startPairing|.
    // |sessionId| : The ID of the session created with |establishSession|.
    // |code| : The string generated by pairing process and availible to the
    // user.
    static void confirmCode(long sessionId,
                            DOMString code,
                            SessionCallback callback);

    // Send an encrypted message to the device.
    // If the message is a setup message with a wifi ssid specified but no
    // password, the password cached by |prefetchWifiPassword| will be used and
    // the call will fail if it's not available. For open networks use an empty
    // string as the password.
    // |sessionId| : The ID of the session created with |establishSession|.
    // |api| : The Privet API name to call.
    // |input| : Input data for |api|.
    static void sendMessage(long sessionId,
                            DOMString api,
                            object input,
                            SendMessageCallback callback);

    // Terminate the session with the device.
    // |sessionId| : The ID of the session created with |establishSession|.
    static void terminateSession(long sessionId);

    // 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);
  };
};