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     // populateWifiPassword was true and the password has not been prefetched.
  34     wifiPasswordError,
  35
  36     // populateWifiPassword was true and the message cannot be parsed as a setup
  37     // message.
  38     setupParseError,
  39
  40     // Could not connect to the device.
  41     connectionError,
  42
  43     // Error in establishing session.
  44     sessionError,
  45
  46     // Unknown session.
  47     unknownSessionError,
  48
  49     // Bad confirmation code. Ask user to retype.
  50     badConfirmationCodeError,
  51
  52     // Success.
  53     success
  54   };
  55
  56   enum ConfirmationType {
  57     displayCode,
  58     stickerCode
  59   };
  60
  61   // Information regarding the confirmation of a device.
  62   dictionary ConfirmationInfo {
  63     // Type of confirmation.
  64     ConfirmationType type;
  65
  66     // Code if available.
  67     DOMString? code;
  68   };
  69
  70   callback CloudDeviceListCallback = void(GCDDevice[] devices);
  71
  72   // |commandDefinitions| : Is "commandDefs" value of device described at
  73   // https://developers.google.com/cloud-devices/v1/reference/devices
  74   // TODO(vitalybuka): consider to describe object in IDL.
  75   callback CommandDefinitionsCallback = void(object commandDefinitions);
  76
  77   // |command| : Described at
  78   // https://developers.google.com/cloud-devices/v1/reference/commands
  79   // TODO(vitalybuka): consider to describe object in IDL.
  80   callback CommandCallback = void(object command);
  81
  82   // |commands| : Array of commands described at
  83   // https://developers.google.com/cloud-devices/v1/reference/commands
  84   // TODO(vitalybuka): consider to describe object in IDL.
  85   callback CommandListCallback = void(object[] commands);
  86
  87   // Called when the confirmation code is available or on error.
  88   // |sessionId| is the session ID (identifies the session for future calls)
  89   // |status| is the status (success or type of error)
  90   // |confirmation| is the information about the confirmation.
  91   callback ConfirmationCodeCallback = void(long sessionId,
  92                                            Status status,
  93                                            ConfirmationInfo confirmation);
  94
  95   // Called to indicated the session is established.
  96   // |status| is the status (success or type of error)
  97   callback SessionEstablishedCallback = void(Status status);
  98
  99   // Called when the response to the message sent is available or on error.
 100   // |status| is the status (success or type of error)
 101   // |response| is the response object or null on error
 102   callback MessageResponseCallback = void(Status status,
 103                                           object response);
 104
 105   // Called as a response to |prefetchWifiPassword|
 106   // |success| Denotes whether the password fetch has succeeded or failed.
 107   callback SuccessCallback = void(boolean success);
 108
 109   // Called as a response to |getPrefetchedWifiNameList|
 110   // |list| the list of ssids for which wifi passwords were prefetched.
 111   callback SSIDListCallback = void(DOMString[] networks);
 112
 113   interface Functions {
 114     // Returns the list of cloud devices visible locally or available in the
 115     // cloud for user account.
 116     static void getCloudDeviceList(CloudDeviceListCallback callback);
 117
 118     // Queries network for local devices. Triggers an onDeviceStateChanged and
 119     // onDeviceRemoved events. Call this function *only* after registering for
 120     // onDeviceStateChanged and onDeviceRemoved events, or it will do nothing.
 121     static void queryForNewLocalDevices();
 122
 123     // Cache the WiFi password in the browser process for use during
 124     // provisioning. This is done to allow the gathering of the wifi password to
 125     // not be done while connected to the device's network. Callback is called
 126     // with true if wifi password was cached and false if it was unavailable.
 127     static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);
 128
 129     // Get the list of ssids with prefetched callbacks.
 130     static void getPrefetchedWifiNameList(SSIDListCallback callback);
 131
 132     // Establish the session.
 133     static void establishSession(DOMString ipAddress,
 134                                  long port,
 135                                  ConfirmationCodeCallback callback);
 136
 137     // Send confirmation code. Device will still need to confirm. |code| must be
 138     // present and must match the code from the device, even when the code is
 139     // supplied in the |ConfirmationInfo| object.
 140     static void confirmCode(long sessionId,
 141                             DOMString code,
 142                             SessionEstablishedCallback callback);
 143
 144     // Send an encrypted message to the device. |api| is the API path and
 145     // |input| is the input object. If the message is a setup message with a
 146     // wifi ssid specified but no password, the password cached from
 147     // |prefetchWifiPassword| will be used and the call will fail if it's not
 148     // available. For open networks use an empty string as the password.
 149     static void sendMessage(long sessionId,
 150                             DOMString api,
 151                             object input,
 152                             MessageResponseCallback callback);
 153
 154     // Terminate the session with the device.
 155     static void terminateSession(long sessionId);
 156
 157     // Returns command definitions.
 158     // |deviceId| : The device to get command definitions for.
 159     // |callback| : The result callback.
 160     static void getCommandDefinitions(DOMString deviceId,
 161                                       CommandDefinitionsCallback callback);
 162
 163     // Creates and sends a new command.
 164     // |deviceId| : The device to send the command to.
 165     // |expireInMs| : The number of milliseconds since now before the command
 166     // expires. Expired command should not be executed by device. Acceptable
 167     // values are 10000 to 2592000000, inclusive. All values outside that range
 168     // will be replaced by 2592000000.
 169     // |command| : Described at
 170     // https://developers.google.com/cloud-devices/v1/reference/commands
 171     // |callback| : The result callback.
 172     static void insertCommand(DOMString deviceId,
 173                               long expireInMs,
 174                               object command,
 175                               CommandCallback callback);
 176
 177     // Returns a particular command.
 178     // |commandId| : Unique command ID.
 179     // |callback| : The result callback.
 180     static void getCommand(DOMString commandId, CommandCallback callback);
 181
 182     // Cancels a command.
 183     // |commandId| : Unique command ID.
 184     // |callback| : The result callback.
 185     static void cancelCommand(DOMString commandId, CommandCallback callback);
 186
 187     // Lists all commands in order of creation.
 188     // |deviceId| : The device to get the commands for.
 189     // |byUser| : List all the commands issued by the user. Special value 'me'
 190     // can be used to list by the current user.
 191     // |state| : Command state.
 192     // |callback| : The result callback.
 193     static void getCommandsList(DOMString deviceId,
 194                                 DOMString byUser,
 195                                 DOMString state,
 196                                 CommandListCallback callback);
 197   };
 198
 199   interface Events {
 200     // Subscribe to this event to start listening new or updated devices. New
 201     // listeners will get called with all known devices on the network, and
 202     // status updates for devices available through the cloud.
 203     static void onDeviceStateChanged(GCDDevice device);
 204
 205     // Notifies that device has disappeared.
 206     // |deviceId| : The device has disappeared.
 207     static void onDeviceRemoved(DOMString deviceId);
 208   };
 209 };