chrome/common/extensions/api/gcd_private.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.gcdPrivate</code> API to discover GCD APIs and register
   6 // them.
   7 namespace gcdPrivate {
   8
   9   enum SetupType { mdns, wifi, cloud };
  10
  11   // Represents a GCD device discovered locally or registered to a given user.
  12   dictionary GCDDevice {
  13     // Opaque device identifier to be passed to API.
  14     DOMString deviceId;
  15
  16     // How this device was discovered.
  17     SetupType setupType;
  18
  19     // Cloud identifier string.
  20     DOMString? cloudId;
  21
  22     // Device type (camera, printer, etc)
  23     DOMString deviceType;
  24
  25     // Device human readable name.
  26     DOMString deviceName;
  27
  28     // Device human readable description.
  29     DOMString deviceDescription;
  30   };
  31
  32   enum Status {
  33     // Success.
  34     success,
  35
  36     // populateWifiPassword was true and the password has not been prefetched.
  37     wifiPasswordError,
  38
  39     // populateWifiPassword was true and the message cannot be parsed as a setup
  40     // message.
  41     setupParseError,
  42
  43     // Could not connect to the device.
  44     connectionError,
  45
  46     // Error in establishing session.
  47     sessionError,
  48
  49     // Unknown session.
  50     unknownSessionError,
  51
  52     // Bad pairing code.
  53     badPairingCodeError,
  54
  55     // Device error with details in response object.
  56     deviceError
  57   };
  58
  59   enum PairingType {
  60     pinCode,
  61     embeddedCode
  62   };
  63
  64   callback CloudDeviceListCallback = void(GCDDevice[] devices);
  65
  66   // |commandDefinitions| : Is "commandDefs" value of device described at
  67   // https://developers.google.com/cloud-devices/v1/reference/devices
  68   // TODO(vitalybuka): consider to describe object in IDL.
  69   callback CommandDefinitionsCallback = void(object commandDefinitions);
  70
  71   // |command| : Described at
  72   // https://developers.google.com/cloud-devices/v1/reference/commands
  73   // TODO(vitalybuka): consider to describe object in IDL.
  74   callback CommandCallback = void(object command);
  75
  76   // |commands| : Array of commands described at
  77   // https://developers.google.com/cloud-devices/v1/reference/commands
  78   // TODO(vitalybuka): consider to describe object in IDL.
  79   callback CommandListCallback = void(object[] commands);
  80
  81   // Generic callback for session calls, with status only.
  82   callback SessionCallback = void(Status status);
  83
  84   // Called when device starts to establish a secure session.
  85   // If |status| is |success| app should call |startPairing|.
  86   // |sessionId| : The session ID (identifies the session for future calls).
  87   // |status| : The status of operation (success or type of error).
  88   // |pairingTypes| is the list of supported pairing types.
  89   callback EstablishSessionCallback = void(long sessionId,
  90                                            Status status,
  91                                            PairingType[] pairingTypes);
  92
  93   // Called when the response to the message sent is available or on error.
  94   // |status| : The status of operation (success or type of error).
  95   // |response| : The response object with result or error description. May be
  96   // empty for some errors.
  97   callback SendMessageCallback = void(Status status, object response);
  98
  99   // Called as a response to |prefetchWifiPassword|
 100   // |success| : Denotes whether the password fetch has succeeded or failed.
 101   callback SuccessCallback = void(boolean success);
 102
 103   // Called as a response to |getPrefetchedWifiNameList|
 104   // |networks| : The list of ssids for which wifi passwords were prefetched.
 105   callback SSIDListCallback = void(DOMString[] networks);
 106
 107   interface Functions {
 108     // Returns the list of cloud devices visible locally or available in the
 109     // cloud for user account.
 110     static void getCloudDeviceList(CloudDeviceListCallback callback);
 111
 112     // Queries network for local devices. Triggers an onDeviceStateChanged and
 113     // onDeviceRemoved events. Call this function *only* after registering for
 114     // onDeviceStateChanged and onDeviceRemoved events, or it will do nothing.
 115     static void queryForNewLocalDevices();
 116
 117     // Cache the WiFi password in the browser process for use during
 118     // provisioning. This is done to allow the gathering of the wifi password to
 119     // not be done while connected to the device's network. Callback is called
 120     // with true if wifi password was cached and false if it was unavailable.
 121     // |ssid| : The network to prefetch password for.
 122     static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);
 123
 124     // Get the list of ssids with prefetched callbacks.
 125     static void getPrefetchedWifiNameList(SSIDListCallback callback);
 126
 127     // Establish the session.
 128     // |ipAddress| : The IPv4 or IPv6 address of the device.
 129     // |port| : The port with Privet HTTP server.
 130     static void establishSession(DOMString ipAddress,
 131                                  long port,
 132                                  EstablishSessionCallback callback);
 133
 134     // Start pairing with selected method. Should be called after
 135     // |establishSession|.
 136     // |sessionId| : The ID of the session created with |establishSession|.
 137     // |pairingType| : The value selected from the list provided in
 138     // callback of |establishSession|.
 139     static void startPairing(long sessionId,
 140                              PairingType pairingType,
 141                              SessionCallback callback);
 142
 143     // Confirm pairing code. Should be called after |startPairing|.
 144     // |sessionId| : The ID of the session created with |establishSession|.
 145     // |code| : The string generated by pairing process and availible to the
 146     // user.
 147     static void confirmCode(long sessionId,
 148                             DOMString code,
 149                             SessionCallback callback);
 150
 151     // Send an encrypted message to the device.
 152     // If the message is a setup message with a wifi ssid specified but no
 153     // password, the password cached by |prefetchWifiPassword| will be used and
 154     // the call will fail if it's not available. For open networks use an empty
 155     // string as the password.
 156     // |sessionId| : The ID of the session created with |establishSession|.
 157     // |api| : The Privet API name to call.
 158     // |input| : Input data for |api|.
 159     static void sendMessage(long sessionId,
 160                             DOMString api,
 161                             object input,
 162                             SendMessageCallback callback);
 163
 164     // Terminate the session with the device.
 165     // |sessionId| : The ID of the session created with |establishSession|.
 166     static void terminateSession(long sessionId);
 167
 168     // Returns command definitions.
 169     // |deviceId| : The device to get command definitions for.
 170     // |callback| : The result callback.
 171     static void getCommandDefinitions(DOMString deviceId,
 172                                       CommandDefinitionsCallback callback);
 173
 174     // Creates and sends a new command.
 175     // |deviceId| : The device to send the command to.
 176     // |expireInMs| : The number of milliseconds since now before the command
 177     // expires. Expired command should not be executed by device. Acceptable
 178     // values are 10000 to 2592000000, inclusive. All values outside that range
 179     // will be replaced by 2592000000.
 180     // |command| : Described at
 181     // https://developers.google.com/cloud-devices/v1/reference/commands
 182     // |callback| : The result callback.
 183     static void insertCommand(DOMString deviceId,
 184                               long expireInMs,
 185                               object command,
 186                               CommandCallback callback);
 187
 188     // Returns a particular command.
 189     // |commandId| : Unique command ID.
 190     // |callback| : The result callback.
 191     static void getCommand(DOMString commandId, CommandCallback callback);
 192
 193     // Cancels a command.
 194     // |commandId| : Unique command ID.
 195     // |callback| : The result callback.
 196     static void cancelCommand(DOMString commandId, CommandCallback callback);
 197
 198     // Lists all commands in order of creation.
 199     // |deviceId| : The device to get the commands for.
 200     // |byUser| : List all the commands issued by the user. Special value 'me'
 201     // can be used to list by the current user.
 202     // |state| : Command state.
 203     // |callback| : The result callback.
 204     static void getCommandsList(DOMString deviceId,
 205                                 DOMString byUser,
 206                                 DOMString state,
 207                                 CommandListCallback callback);
 208   };
 209
 210   interface Events {
 211     // Subscribe to this event to start listening new or updated devices. New
 212     // listeners will get called with all known devices on the network, and
 213     // status updates for devices available through the cloud.
 214     static void onDeviceStateChanged(GCDDevice device);
 215
 216     // Notifies that device has disappeared.
 217     // |deviceId| : The device has disappeared.
 218     static void onDeviceRemoved(DOMString deviceId);
 219   };
 220 };