Implement networkingPrivate.getNetworks

chrome/common/extensions/api/networking_private.json

Index: chrome/common/extensions/api/networking_private.json
diff --git a/chrome/common/extensions/api/networking_private.json b/chrome/common/extensions/api/networking_private.json
index db603ccf76241100603be8fa2a5cd8c4010b39b6..de456578e473819852ac6ab75c080beb23338fb1 100644
--- a/chrome/common/extensions/api/networking_private.json
+++ b/chrome/common/extensions/api/networking_private.json
@@ -113,7 +113,7 @@
       },
       {
         "name": "getState",
-        "description": "Gets the cached read-only properties of the network with id networkGuid.  This is meant to be a higher performance function than getProperties, which requires a round trip to query the networking subsystem.  It only returns a subset of the properties returned by getProperties.",
+        "description": "Gets the cached read-only properties of the network with id networkGuid. This is meant to be a higher performance function than getProperties, which requires a round trip to query the networking subsystem.  It only returns the following properties: GUID, Type, Name, ConnectionState, ErrorState, WiFi.Security, WiFi.SignalStrength, Cellular.NetworkTechnology, Cellular.ActivationState, Cellular.RoamingState, Cellular.OutOfCredits",
         "parameters": [
           {
             "name": "networkGuid",
@@ -127,7 +127,7 @@
               {
                 "name": "properties",
                 "$ref": "NetworkProperties",
-                "description": "Results of the query for network properties."
+                "description": "Results of the query for network state properties."
               }
             ]
           }
@@ -156,7 +156,7 @@
       },
       {
         "name": "createNetwork",
-        "description": "Creates a new network configuration from propeties. If a matching configured network already exists, this will fail. Otherwise returns the guid of the new network.",
+        "description": "Creates a new network configuration from properties. If a matching configured network already exists, this will fail. Otherwise returns the guid of the new network.",
         "parameters": [
           {
             "name": "shared",
@@ -181,13 +181,58 @@
         ]
       },
       {
+        "name": "getNetworks",
+        "description": "Returns a list of network objects with the same properties provided by getState.",

[pneubeck (no reviews), 2014/05/15 18:28:37]

could mention the filter argument

since you allow limiting the number of networks, it might be helpful to mention
the ordering.

[stevenjb, 2014/05/15 20:12:41]

Ah, sure, I'll mention the filter at the top level, and the ordering.

+        "parameters": [
+          {
+            "name": "filter",
+            "type": "object",
+            "properties": {
+              "type": {
+		"type": "string",
+		"enum": ["All", "Bluetooth", "Cellular", "Ethernet", "VPN", "Wireless", "WiFi", "Wimax"],

[pneubeck (no reviews), 2014/05/15 18:28:37]

could you move this to the toplevel , and maybe mention that these are types
from ONC?

There is already a toplevel 'NetworkType' used by enabledNetworkType. You could
define another 'NetworkPatternType' consisting of the enum ['All', 'Wireless']
and then use the union/choice of NetworkType and NetworkPatternType for the
filter.type.

[stevenjb, 2014/05/15 20:12:41]

Ah, so there is, even better. I will unify these, I don't think we should need
to distinguish between 'NetworkType' and 'NetworkPatternType' at the API level.
Enable/disable technology can already support patterns in NetworkStateHandler, I
will fix Enable/DisableNetworkType to support patterns also. I will also add a
comment to getEnabledNetworkTypes which is the only place where non-discrete
types don't make sense.

+		"description": "The type of networks to return."
+              },
+	      "visible": {
+		"type": "boolean",
+		"optional": true,
+		"description": "If true, only include visible (physically connected or in-range) networks. Defaults to 'false'."

[pneubeck (no reviews), 2014/05/15 18:28:37]

physically connected or in-range

this doesn't explain what happens for VPN :-/ ; maybe add a 'or connectable'.

Potentially, VPN could be left out if there is no host network to route the VPN
traffic. So, maybe it's fine to leave this unspecified so far.

[stevenjb, 2014/05/15 20:12:41]

I'm not entirely certain what the VPN behavior is. I think I'll leave it
undocumented until/unless it becomes an issue (we may need to add a NonVirtual
type to NetworkType).

+              },
+              "configured": {
+		"type": "boolean",
+		"optional": true,
+		"description": "If true, only include configured (saved) networks. Defaults to 'false'."
+              },
+              "limit": {
+		"type": "integer",
+		"optional": true,
+		"description": "Maximum number of networks to return. Default: 1000"

[pneubeck (no reviews), 2014/05/15 18:28:37]

s/Default: /Defaults to /

[stevenjb, 2014/05/15 20:12:41]

Done.

+              }
+	    }
+	  },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {
+                "name": "networkList",
+                "type": "array",
+                "items": { "$ref": "NetworkProperties" }
+              }
+            ]
+          }
+        ]
+      },
+      {
         "name": "getVisibleNetworks",
-        "description": "Returns a list of visible network objects with the following ONC properties: GUID, Type, Name, ConnectionState, ErrorState, WiFi.Security, WiFi.SignalStrength, Cellular.NetworkTechnology, Cellular.ActivationState, Cellular.RoamingState. Cellular.OutOfCredits",
+	"deprecated": "Please Use $(ref:networkingPrivate.getNetworks).",

[pneubeck (no reviews), 2014/05/15 18:28:37]

Use -> use
or remove 'Please'

could mention what call to getNetworks is equivalent: 'with filter.visible =
true'

[stevenjb, 2014/05/15 20:12:41]

Done.

+        "description": "Returns a list of visible network objects with the same properties provided by getState.",
         "parameters": [
           {
             "name": "type",
             "type": "string",
-            "enum": ["Ethernet", "WiFi", "Bluetooth", "Cellular", "VPN", "All"],
+            "enum": ["All", "Bluetooth", "Cellular", "Ethernet", "VPN", "Wireless", "WiFi", "WiMax"],
             "description": "The type of networks to return."
           },
           {
@@ -206,7 +251,7 @@
       },
       {
         "name": "getEnabledNetworkTypes",
-        "description": "Returns a list of the enabled network type.",
+        "description": "Returns a list of the enabled network types.",
         "parameters": [
           {
             "name": "callback",
@@ -214,7 +259,7 @@
             "optional": true,
             "parameters": [
               {
-                "name": "networkList",
+                "name": "enabledTypes",
                 "type": "array",
                 "items": { "$ref": "NetworkType" }
               }