chrome.gcdPrivate allows app to choose pairing method.

chrome/common/extensions/api/gcd_private.idl

 // Copyright 2014 The Chromium Authors. All rights reserved.

[mednik, 2014/11/04 02:47:46]

The changes in this file seem pretty big, and I would've loved to understand
them first before the CL lands. We need to make various changes as a result of
this and need to understand how this works, and I wasn't aware there would be a
CL so quickly (I thought first we would discuss it and get on the same page,
like in a doc).

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Sorry, I didn't thins we had open questions.
We discussed this on the last sync and later on chat with Zen.
So I started to feel bad that I promised this almost two weeks ago :-)

In short, App needs a way to fallback to different pairing types.

Let me know if you'd like to revert API change for now.

 // 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 };
 
   // Represents a GCD device discovered locally or registered to a given user.
@@ skipping 11 matching lines @@
     DOMString deviceType;
 
     // Device human readable name.
     DOMString deviceName;
 
     // Device human readable description.
     DOMString deviceDescription;
   };
 
   enum Status {
+    // Success.
+    success,
+
     // populateWifiPassword was true and the password has not been prefetched.
     wifiPasswordError,
 
     // populateWifiPassword was true and the message cannot be parsed as a setup
     // message.
     setupParseError,
 
     // Could not connect to the device.
     connectionError,
 
     // Error in establishing session.
     sessionError,
 
     // Unknown session.
     unknownSessionError,
 
-    // Bad confirmation code. Ask user to retype.
-    badConfirmationCodeError,
+    // Bad pairing code. Ask user to retype.
+    badPairingCodeError,
 
-    // Success.
-    success
+    // Setup error.
+    setupError
   };
 
-  enum ConfirmationType {
-    displayCode,
-    stickerCode
-  };
-
-  // Information regarding the confirmation of a device.
-  dictionary ConfirmationInfo {

[mednik, 2014/11/04 02:47:46]

Why did this go away? How will the app know which confirmation type to show?

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Now app choose which one to use.

-    // Type of confirmation.
-    ConfirmationType type;
-
-    // Code if available.
-    DOMString? code;
+  enum PairingType {
+    pinCode,
+    embeddedCode
   };
 
   callback CloudDeviceListCallback = void(GCDDevice[] devices);
 
   // |commandDefinitions| : Is "commandDefs" value of device described at
   // https://developers.google.com/cloud-devices/v1/reference/devices
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandDefinitionsCallback = void(object commandDefinitions);
 
   // |command| : Described at
   // https://developers.google.com/cloud-devices/v1/reference/commands
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandCallback = void(object command);
 
   // |commands| : Array of commands described at
   // https://developers.google.com/cloud-devices/v1/reference/commands
   // TODO(vitalybuka): consider to describe object in IDL.
   callback CommandListCallback = void(object[] commands);
 
-  // Called when the confirmation code is available or on error.
-  // |sessionId| is the session ID (identifies the session for future calls)
-  // |status| is the status (success or type of error)
-  // |confirmation| is the information about the confirmation.
-  callback ConfirmationCodeCallback = void(long sessionId,
+  // Generic callback for session calls, with status only.
+  callback SessionCallback = void(Status status);
+
+  // Called when device starts to establish a secure session.
+  // If |status| is |success| app should vall |startPairing|.

[mednik, 2014/11/04 02:47:46]

Nit: typo "vall" -> "call".

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Done.

+  // |sessionId| is the session ID (identifies the session for future calls).
+  // |status| is the status (success or type of error).
+  // |pairingTypes| is the list of supported pairing types.
+  callback EstablishSessionCallback = void(long sessionId,
                                            Status status,
-                                           ConfirmationInfo confirmation);
-
-  // Called to indicated the session is established.
-  // |status| is the status (success or type of error)
-  callback SessionEstablishedCallback = void(Status status);
+                                           PairingType[] pairingTypes);

[mednik, 2014/11/04 02:47:46]

Why do we need a list of pairing types? Can something support more than 1? Which
should the app use?

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Yes, if device support several types, we would try to use some user-friendly
first and fallback to something reliable like pinCode.

On 2014/11/04 02:47:46, mednik wrote:

 
   // Called when the response to the message sent is available or on error.
   // |status| is the status (success or type of error)
   // |response| is the response object or null on error
-  callback MessageResponseCallback = void(Status status,
-                                          object response);
+  callback SendMessageCallback = void(Status status,
+                                      object response);
 
   // Called as a response to |prefetchWifiPassword|
   // |success| Denotes whether the password fetch has succeeded or failed.
   callback SuccessCallback = void(boolean success);
 
   // Called as a response to |getPrefetchedWifiNameList|
   // |list| the list of ssids for which wifi passwords were prefetched.
   callback SSIDListCallback = void(DOMString[] networks);
 
   interface Functions {
@@ skipping 11 matching lines @@
     // not be done while connected to the device's network. Callback is called
     // with true if wifi password was cached and false if it was unavailable.
     static void prefetchWifiPassword(DOMString ssid, SuccessCallback callback);
 
     // Get the list of ssids with prefetched callbacks.
     static void getPrefetchedWifiNameList(SSIDListCallback callback);
 
     // Establish the session.
     static void establishSession(DOMString ipAddress,
                                  long port,
-                                 ConfirmationCodeCallback callback);
+                                 EstablishSessionCallback callback);
 
-    // Send confirmation code. Device will still need to confirm. |code| must be
-    // present and must match the code from the device, even when the code is
-    // supplied in the |ConfirmationInfo| object.
+    // Start pairing with selected method.
+    // |pairingType| is the any value provided 

[mednik, 2014/11/04 02:47:46]

Nit: Missing ending period. Also typo "is the any".

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Done.

+    static void startPairing(long sessionId,

[mednik, 2014/11/04 02:47:46]

When should this get called? How does this relate to calling confirmCode?

[Vitaly Buka (NO REVIEWS), 2014/11/04 20:19:05]

Done.

+                             PairingType pairingType,
+                             SessionCallback callback);
+
+    // Confirm pairing code.
+    // |code| is the string generated by pairing process and availible to the
+    // user.
     static void confirmCode(long sessionId,
                             DOMString code,
-                            SessionEstablishedCallback callback);
+                            SessionCallback callback);
 
     // Send an encrypted message to the device. |api| is the API path and
     // |input| is the input object. If the message is a setup message with a
     // wifi ssid specified but no password, the password cached from
     // |prefetchWifiPassword| will be used and the call will fail if it's not
     // available. For open networks use an empty string as the password.
     static void sendMessage(long sessionId,
                             DOMString api,
                             object input,
-                            MessageResponseCallback callback);
+                            SendMessageCallback callback);
 
     // Terminate the session with the device.
     static void terminateSession(long sessionId);
 
     // Returns command definitions.
     // |deviceId| : The device to get command definitions for.
     // |callback| : The result callback.
     static void getCommandDefinitions(DOMString deviceId,
                                       CommandDefinitionsCallback callback);
 
@@ skipping 37 matching lines @@
     // Subscribe to this event to start listening new or updated devices. New
     // listeners will get called with all known devices on the network, and
     // status updates for devices available through the cloud.
     static void onDeviceStateChanged(GCDDevice device);
 
     // Notifies that device has disappeared.
     // |deviceId| : The device has disappeared.
     static void onDeviceRemoved(DOMString deviceId);
   };
 };