Add queryForNewLocalDevices to gcdPrivate

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 15 matching lines @@
     DOMString deviceName;
 
     // Device human readable description
     DOMString deviceDescription;
   };
 
   callback CloudDeviceListCallback = void(GCDDevice[] devices);
 
   interface Functions {
     static void getCloudDeviceList(CloudDeviceListCallback callback);
+
+    // Call this function *only* after registering for onLocalDeviceStateChanged
+    // events, or it will do nothing. This will trigger an
+    // onLocalDeviceStateChanged event per device.

[asargent_no_longer_on_chrome, 2014/06/24 22:31:48]

Did you consider having this method take a callback function that will get
called with the results, rather than making consumers of this API register for
the onLocalDeviceStateChanged event? I can imagine one advantage of using a
callback here would be that consumers would then know when the query had
finished; with the event only approach they don't ever know when it's done. (Not
sure if this is a useful concern or not though)

Also, a question - I would have assumed that onLocalDeviceStateChanged would
just fire automatically as new devices are discovered, and
queryForNewLocalDevices isn't needed. Is the point that queryForNewLocalDevices
just causes the system to immediately check for new devices sooner than we would
have based on some timer or something?

[Noam Samuel, 2014/06/24 23:07:05]

So registering for onLocalDeviceStateChanged causes the system to listen for
devices without generating network traffic. This means whenever a device
announces itself (either through an mDNS announce packet or by creating a new
WiFi network and sending a beacon frame), the event will be called immediately.

queryForNewLocalDevices generates a query on the network. This means sending an
mDNS query packets and (on platforms that support WiFi device discovery)
triggering a scan for new WiFi networks. The devices themselves will then reply
by announcing themselves, which will trigger onLocalDeviceStateChanged.

We could also send the query whenever the API user registers for
onLocalDeviceStateChanged, but we want to support the ability to have a refresh
button for re-querying the network.

+    static void queryForNewLocalDevices();
   };
 
   interface Events {
     // Subscribe to this event to start listening to cloud devices. New
     // listeners will get called with all known devices on the network.
-    static void onCloudDeviceStateChanged(boolean available, GCDDevice device);
+    static void onLocalDeviceStateChanged(boolean available, GCDDevice device);
   };
 };