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