Implement networkingPrivate.getNetworks

chrome/common/extensions/api/networking_private.json

 // Copyright (c) 2013 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.
 
 [
   {
     "namespace":"networkingPrivate",
     "description": "none",
     "compiler_options": {
       "implemented_in": "chrome/browser/extensions/api/networking_private/networking_private_api.h"
@@ skipping 95 matching lines @@
                 "name": "properties",
                 "$ref": "ManagedNetworkProperties",
                 "description": "Results of the query for managed network properties."
               }
             ]
           }
         ]
       },
       {
         "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",
             "type": "string",
             "description": "The unique identifier of the network to set properties on."
           },
           {
             "name": "callback",
             "type": "function",
             "parameters": [
               {
                 "name": "properties",
                 "$ref": "NetworkProperties",
-                "description": "Results of the query for network properties."
+                "description": "Results of the query for network state properties."
               }
             ]
           }
         ]
       },
       {
         "name": "setProperties",
         "description": "Sets the properties of the network with id networkGuid.",
         "parameters": [
           {
             "name": "networkGuid",
             "type": "string",
             "description": "The unique identifier of the network to set properties on."
           },
           {
             "name": "properties",
             "$ref": "NetworkProperties",
             "description": "The properties to set on the network."
           },
           {
             "name": "callback",
             "type": "function",
             "parameters": []
           }
         ]
       },
       {
         "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",
             "type": "boolean",
             "description": "If true, share this network configuration with other users."
           },
           {
             "name": "properties",
             "$ref": "NetworkProperties",
             "description": "The properties to configure the new network with."
           },
           {
             "name": "callback",
             "type": "function",
             "parameters": [
               {
                 "name": "networkGuid",
                 "type": "string"
               }
             ]
           }
         ]
       },
       {
+        "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."
           },
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [
               {
                 "name": "networkList",
                 "type": "array",
                 "items": { "$ref": "NetworkProperties" }
               }
             ]
           }
         ]
       },
       {
         "name": "getEnabledNetworkTypes",
-        "description": "Returns a list of the enabled network type.",
+        "description": "Returns a list of the enabled network types.",
         "parameters": [
           {
             "name": "callback",
             "type": "function",
             "optional": true,
             "parameters": [
               {
-                "name": "networkList",
+                "name": "enabledTypes",
                 "type": "array",
                 "items": { "$ref": "NetworkType" }
               }
             ]
           }
         ]
       },
       {
         "name": "enableNetworkType",
         "description": "Enable the specified network type.",
@@ skipping 239 matching lines @@
           },
           {
             "name": "status",
             "$ref": "CaptivePortalStatus"
           }
         ]
       }
     ]
   }
 ]