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     ultrasound32,
  63     audible32
  64   };
  65
  66   callback CloudDeviceListCallback = void(GCDDevice[] devices);
  67
  68   // |commandDefinitions| : Is "commandDefs" value of device described at
  69   // https://developers.google.com/cloud-devices/v1/reference/devices
  70   // TODO(vitalybuka): consider to describe object in IDL.
  71   callback CommandDefinitionsCallback = void(object commandDefinitions);
  72
  73   // |command| : Described at
  74   // https://developers.google.com/cloud-devices/v1/reference/commands
  75   // TODO(vitalybuka): consider to describe object in IDL.
  76   callback CommandCallback = void(object command);
  77
  78   // |commands| : Array of commands described at
  79   // https://developers.google.com/cloud-devices/v1/reference/commands
  80   // TODO(vitalybuka): consider to describe object in IDL.
  81   callback CommandListCallback = void(object[] commands);
  82
  83   // Generic callback for session calls, with status only.
  84   callback SessionCallback = void(Status status);
  85
  86   // Called when device starts to establish a secure session.
  87   // If |status| is |success| app should call |startPairing|.
  88   // |sessionId| : The session ID (identifies the session for future calls).
  89   // |status| : The status of operation (success or type of error).
  90   // |pairingTypes| is the list of supported pairing types.
  91   callback EstablishSessionCallback = void(long sessionId,
  92                                            Status status,
  93                                            PairingType[] pairingTypes);
  94
  95   // Called when the response to the message sent is available or on error.
  96   // |status| : The status of operation (success or type of error).
  97   // |response| : The response object with result or error description. May be
  98   // empty for some errors.
  99   callback SendMessageCallback = void(Status status, object response);
 100
 101   // Called as a response to |prefetchWifiPassword|
 102   // |success| : Denotes whether the password fetch has succeeded or failed.
 103   callback SuccessCallback = void(boolean success);
 104
 105   // Called as a response to |getPrefetchedWifiNameList|
 106   // |networks| : The list of ssids for which wifi passwords were prefetched.
 107   callback SSIDListCallback = void(DOMString[] networks);
 108
 109   interface Functions {
 110     // Returns the list of cloud devices visible locally or available in the
 111     // cloud for user account.
 112     static void getCloudDeviceList(CloudDeviceListCallback callback);
 113
 114     // Queries network for local devices. Triggers an onDeviceStateChanged and
 115     // onDeviceRemoved events. Call this function *only* after registering for
 116     // onDeviceStateChanged and onDeviceRemoved events, or it will do nothing.
 117     static void queryForNewLocalDevices();
 118
 119     // Cache the WiFi password in the browser process for use during
 120     // provisioning. This is done to allow the gathering of the wifi password to
 121     // not be done while connected to the device's network. Callback is called
 122     // with true if wifi password was cached and false if it was unavailable.
 123     // |ssid| : The network to prefetch password for.
 124     static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);
 125
 126     // Get the list of ssids with prefetched callbacks.
 127     static void getPrefetchedWifiNameList(SSIDListCallback callback);
 128
 129     // Establish the session.
 130     // |ipAddress| : The IPv4 or IPv6 address of the device.
 131     // |port| : The port with Privet HTTP server.
 132     static void establishSession(DOMString ipAddress,
 133                                  long port,
 134                                  EstablishSessionCallback callback);
 135
 136     // Start pairing with selected method. Should be called after
 137     // |establishSession|.
 138     // |sessionId| : The ID of the session created with |establishSession|.
 139     // |pairingType| : The value selected from the list provided in
 140     // callback of |establishSession|.
 141     static void startPairing(long sessionId,
 142                              PairingType pairingType,
 143                              SessionCallback callback);
 144
 145     // Confirm pairing code. Should be called after |startPairing|.
 146     // |sessionId| : The ID of the session created with |establishSession|.
 147     // |code| : The string generated by pairing process and availible to the
 148     // user.
 149     static void confirmCode(long sessionId,
 150                             DOMString code,
 151                             SessionCallback callback);
 152
 153     // Send an encrypted message to the device.
 154     // If the message is a setup message with a wifi ssid specified but no
 155     // password, the password cached by |prefetchWifiPassword| will be used and
 156     // the call will fail if it's not available. For open networks use an empty
 157     // string as the password.
 158     // |sessionId| : The ID of the session created with |establishSession|.
 159     // |api| : The Privet API name to call.
 160     // |input| : Input data for |api|.
 161     static void sendMessage(long sessionId,
 162                             DOMString api,
 163                             object input,
 164                             SendMessageCallback callback);
 165
 166     // Terminate the session with the device.
 167     // |sessionId| : The ID of the session created with |establishSession|.
 168     static void terminateSession(long sessionId);
 169
 170     // Returns command definitions.
 171     // |deviceId| : The device to get command definitions for.
 172     // |callback| : The result callback.
 173     static void getCommandDefinitions(DOMString deviceId,
 174                                       CommandDefinitionsCallback callback);
 175
 176     // Creates and sends a new command.
 177     // |deviceId| : The device to send the command to.
 178     // |expireInMs| : The number of milliseconds since now before the command
 179     // expires. Expired command should not be executed by device. Acceptable
 180     // values are 10000 to 2592000000, inclusive. All values outside that range
 181     // will be replaced by 2592000000.
 182     // |command| : Described at
 183     // https://developers.google.com/cloud-devices/v1/reference/commands
 184     // |callback| : The result callback.
 185     static void insertCommand(DOMString deviceId,
 186                               long expireInMs,
 187                               object command,
 188                               CommandCallback callback);
 189
 190     // Returns a particular command.
 191     // |commandId| : Unique command ID.
 192     // |callback| : The result callback.
 193     static void getCommand(DOMString commandId, CommandCallback callback);
 194
 195     // Cancels a command.
 196     // |commandId| : Unique command ID.
 197     // |callback| : The result callback.
 198     static void cancelCommand(DOMString commandId, CommandCallback callback);
 199
 200     // Lists all commands in order of creation.
 201     // |deviceId| : The device to get the commands for.
 202     // |byUser| : List all the commands issued by the user. Special value 'me'
 203     // can be used to list by the current user.
 204     // |state| : Command state.
 205     // |callback| : The result callback.
 206     static void getCommandsList(DOMString deviceId,
 207                                 DOMString byUser,
 208                                 DOMString state,
 209                                 CommandListCallback callback);
 210   };
 211
 212   interface Events {
 213     // Subscribe to this event to start listening new or updated devices. New
 214     // listeners will get called with all known devices on the network, and
 215     // status updates for devices available through the cloud.
 216     static void onDeviceStateChanged(GCDDevice device);
 217
 218     // Notifies that device has disappeared.
 219     // |deviceId| : The device has disappeared.
 220     static void onDeviceRemoved(DOMString deviceId);
 221   };
 222 };