Add API stubs for GCD device commands.

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 };
 
@@ skipping 11 matching lines @@
     // Device type (camera, printer, etc)
     DOMString deviceType;
 
     // Device human readable name
     DOMString deviceName;
 
     // Device human readable description
     DOMString deviceDescription;
   };
 
-  // Represents wifi network credentials.
-  dictionary WiFiCredentials {
-    DOMString ssid;
-    DOMString password;
-  };
-
   callback CloudDeviceListCallback = void(GCDDevice[] devices);
+  callback CommandDefinitionsCallback = void(object commandDefinitions);

[Noam Samuel, 2014/07/08 18:26:32]

Is the object schema in this case a CDD?  I think it's worth it to add comments
to each of these methods explaining what the unschema'd objects are.

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:06]

Done.

+  callback CommandCallback = void(object command);
+  callback CommandListCallback = void(object[] commands);
 
   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 onCloudDeviceStateChanged
+    // event per device. Call this function *only* after registering for
+    // onCloudDeviceStateChanged events, or it will do nothing.
+    static void queryForNewLocalDevices();
+
     // Starts device setup process. Returns id of setup process. Id should be
     // used as |setupId| in all subsequent setup related calls, and for
     // filtering setup events.
     static long startSetup(GCDDevice device);
 
-    // Sets WiFi network list as reply to |onGetWifiNetworks| event.
+    // Sets WiFi network as reply to |onGetWifiNetworks| event.
     // |setupId| : The value returned by |startSetup|.
-    // |networks| : The list of network device should be registered on.
-    static void setWiFiNetworks(long setupId, DOMString[] networks);
+    // |network| : The wifi network for device setup.
+    static void setWiFiNetwork(long setupId, DOMString network);
 
-    // Sets WiFi network credentials as reply to |onGetWifiCredentials|
-    // event.
+    // Sets WiFi network password as reply to |onGetWifiCredentials| event.
     // |setupId| : The value returned by |startSetup|.
-    // |credentials| : The list of ssid with passwoors. The list is not required
-    // to match |networks| provided with |setWiFiNetworks| or
-    // |onGetWifiCredentials|.
-    static void setWiFiCredentials(long setupId, WiFiCredentials[] credentials);
+    // |password| : The passwords for network selected with |setWiFiNetwork|.
+    static void setWiFiPassword(long setupId, DOMString password);
 
     // Confirms that security code known to application match to the code known
     // to device.
     // |setupId| : The value returned by |startSetup|.
     static void confirmCode(long setupId);
 
     // Stops registration process.
     // This call triggers |onSetupError| event. App should wait this even before
     // starting new registration.
     // |setupId| : The value returned by |startSetup|.
     static void stopSetup(long setupId);
+
+    // Returns command definitions.
+    // |device| : The device to get command definitions for.
+    // |callback| : The result callback.
+    static void getCommandDefinitions(GCDDevice device,
+                                      CommandDefinitionsCallback callback);
+
+    // Creates and sends a new command.
+    // |device| : 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.
+    // |callback| : The result callback.
+    static void insertCommand(GCDDevice device,

[Noam Samuel, 2014/07/08 18:26:32]

Does this transparently switch between local and cloud as we discussed?

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:05]

yes
On 2014/07/08 18:26:32, Noam Samuel wrote:

+                              long expireInMs,
+                              object command,

[Noam Samuel, 2014/07/08 18:26:32]

Is the schema for the command the GCD command schema?

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:06]

Done.

+                              CommandCallback callback);
+
+    // Returns a particular command.
+    // |commandId| : Unique command ID.
+    // |callback| : The result callback.
+    static void getCommand(DOMString commandId,

[Noam Samuel, 2014/07/08 18:26:32]

Does this transparently handle local and cloud? If so, should the command ID be
opaquely "munged" by the API layer to signify that a command is a local or cloud
command?

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:06]

implementation should take care about this.

On 2014/07/08 18:26:32, Noam Samuel wrote:

+                           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.
+    // |device| : 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(GCDDevice device,

[Noam Samuel, 2014/07/08 18:26:32]

Is this function cloud-only?

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:06]

No. It going to be local queue for local devices.
Cloud devices would have global queue.
But on API level is irrelevant.

On 2014/07/08 18:26:32, Noam Samuel wrote:

+                                DOMString byUser,
+                                DOMString state,
+                                CommandListCallback callback);
   };
 
   interface Events {
     // Subscribe to this event to start listening to cloud devices. New
-    // listeners will get called with all known devices on the network.
+    // listeners will get called with all known devices on the network, and
+    // devices available using cloud.

[Noam Samuel, 2014/07/08 18:26:32]

Does this mean we want to start a cloud request when users subscribe to this
event?

[Vitaly Buka (NO REVIEWS), 2014/07/08 18:49:05]

Maybe we would need subscribeForDeviceChanges(GCDevice device) method to avoid
updating all devices. Let's assume for now that we get updates for all devices
here.

On 2014/07/08 18:26:32, Noam Samuel wrote:

[Noam Samuel, 2014/07/08 19:04:30]

Maybe "and status updates for devices available through the cloud"?

     static void onCloudDeviceStateChanged(boolean available, GCDDevice device);
 
-    // Notifies app that setup is waiting for network list. App should reply
-    // with |setWiFiNetworks|.
+    // Notifies app that setup is waiting for a wifi network. App should reply
+    // with |setWiFiNetwork|.
     // |setupId| : The value returned by |startSetup|.
-    static void onGetWifiNetworks(long setupId);
+    static void onGetWifiNetwork(long setupId);
 
-    // Notifies app that setup is waiting for credentions for |networks| list.
-    // App should reply with |setWiFiCredentials|.
+    // Notifies app that setup is waiting for password for the network provided
+    // with |setWiFiNetwork|. Even will be called if setup flow would unable to
+    // get password from the system.
+    // App should reply with |setWiFiPassword|.
     // |setupId| : The value returned by |startSetup|.
-    // |networks| : A subset of the list provided in |setWiFiNetworks| for which
-    // setup flow is unable to find credentials
-    static void onGetWifiCredentials(long setupId, DOMString[] networks);
+    static void onGetWifiPassword(long setupId);
 
     // Notifies app that setup is waiting for confirmation that code is the same
     // as code known to device. App should reply with |confirmCode|, or
     // |stopSetup| if code does not match.
     // |confirmationCode| : The code to confirm.
     // |setupId| : The value returned by |startSetup|.
     static void onConfirmCode(long setupId, DOMString confirmationCode);
 
     // Notifies app that setup is completed successfully.
     // |setupId| : The value returned by |startSetup|.
     static void onSetupSuccess(long setupId);
 
-    // Notifies app that setup is failed or stoped.
+    // Notifies app that setup is failed or stopped.
     // |setupId| : The value returned by |startSetup|.
     static void onSetupError(long setupId);
   };
 };