This adds a private extension API to use for simple networking

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",
+    "nodoc": "true",
+    "functions": [
+      {
+        "name": "getProperties",
+        "description": "Gets the properties of the network with id networkGuid.",
+        "parameters": [
+          {
+            "name": "networkGuid",
+            "type": "string",
+            "description": "The unique identifier of the network to get properties from."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "parameters": [
+              {
+                "name": "properties",
+                "type": "object",
+                "additionalProperties": { "type": "any" },

[not at google - send to devlin, 2013/01/23 22:37:52]

Why isn't it possible to enumerate the properties?

[Greg Spencer (Chromium), 2013/01/31 16:40:36]

It is possible, but will have to be kept in sync with the ONC spec.  Currently,
this API only supports five properties, but it will very shortly be more like
40, and that seems prohibitive to maintain.

I have a hard time making a "correctness" argument for keeping it unenumerated
however, so if you want I can enumerate the five properties for now, and when it
gets hard to maintain we can switch it back to this...

[not at google - send to devlin, 2013/02/01 19:09:42]

Yeah, I have a strong preference to making this an enum - if it's a matter of
keeping it in sync with an enum elsewhere, making the compiler check it could
look something like

// (declare make NetworkConfig an enum type)
const char* GetNetworkConfigName(api::networking_private::NetworkConfig name) {
  switch (name) {
    case api::networking_private::NETWORK_CONFIG_WIFI:
      return onc::network_constants::kWiFi;
    ...
    // No default case so that compiler picks up problems.
  }
  NOTREACHED();
  return "";
}

At least then you would only need to update a single place (the JSON) and a
comment to that effect in onc_constants.h seems like it would suffice.

If for some reason that isn't practical I'd still like to try making it an enum
then as you suggest switch it to "additionalProperties:" {"type": "string"} if
necessary.

[Greg Spencer (Chromium), 2013/02/01 23:35:55]

No, it's not really practical because we already have constants for these values
in chromeos/network/onc/onc_constants.h, and that can't be dependent upon a
generated header from the schema compiler.

I started to change this to call out the (for now) five properties that can be
present, but quickly realized that it's not that simple: the WiFi value is an
object that can have other nested objects, etc, and there a a lot of other
objects like that which will be present in the future.

It's really too bad that this JSON schema doesn't allow us to have objects with
an empty set of required properties (making all properties optional), so that I
could stop at specifying the top level properties and just specify that WiFi is
an object with no required properties.

The "additional properties" thing is a hack, and makes it hard with nested
values, since I'd have to traverse the result and "explode" all of the
"additional_properties" elements in the results so that they are presented to
the JavaScript as correct ONC dictionaries.

I *could* still make the fields explicit, but I think it's an awful lot of pain
for very little gain.

As an example, a WiFi object looks something like this (and there are several
more optional fields that aren't included in this example):

"WiFi": {
        "AutoConnect": false,
        "EAP": {
          "ClientCertPattern": {
            "EnrollmentURI": [
              "http://fetch-my-certificate.com"
            ],
            "IssuerCARef": [
              "{6ed8dce9-64c8-d568-d225d7e467e37828}"
            ]
          },
          "ClientCertType": "Pattern",
          "Outer": "EAP-TLS",
          "ServerCARef": "{6ed8dce9-64c8-d568-d225d7e467e37828}",
          "UseSystemCAs": true
        },
        "HiddenSSID": false,
        "SSID": "MyTTLSNetwork",
        "Security": "WPA-EAP"
      }

[not at google - send to devlin, 2013/02/02 00:11:32]

Ah, I didn't realise these were rich structures, I thought they were just
strings. My apologies.

+                "description": "Results of the query for network properties."
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "getVisibleNetworks",
+        "description": "Gets the list of visible networks.",
+        "parameters": [
+          {
+            "name": "type",
+            "type": "string",
+            "enum": ["Ethernet", "WiFi", "Bluetooth", "Cellular", "VPN", "All"],
+            "description": "The type of networks to return."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [
+              {
+                "name": "networkList",
+                "type": "array",
+                "items": { "type": "object",
+                           "additionalProperties": { "type": "any"} }

[not at google - send to devlin, 2013/01/23 22:37:52]

Ditto. In fact will this be the same data as returned by getProperties? In which
case it should be defined as a type.

[Greg Spencer (Chromium), 2013/01/31 16:40:36]

Good point. I defined it as a type.

+              }
+            ]
+          }
+        ]
+      },
+      {
+        "name": "requestConnect",

[not at google - send to devlin, 2013/01/23 22:37:52]

"request" seems tautological, since an API call is effectively a request. Just
"connect"?

[Greg Spencer (Chromium), 2013/01/31 16:40:36]

Well, but the reason it's a "request" is because when this call finishes
successfully, it's not connected to a network, it's just successfully requested
a connection to a network from Shill.  If it were just "connect", then one might
expect that the network is connected when this function calls it's closure, and
that's not correct.

[not at google - send to devlin, 2013/02/01 19:09:42]

Ok - so to make sure I understand - there are two events that will happen here.
(1) it requests a connection, (2) the connection is (or isn't) established.

Currently this API call returns when (1), but would it make sense to return when
it's (2)? If not, should there be a way to notify (e.g. an event)?

"requestConnect" still sounds to me like it could be denied, but the only way it
will fail is if there's a hard error, so I'd prefer name like "startConnect" or
"beginConnect" or something (same for disconnect).

[Greg Spencer (Chromium), 2013/02/01 23:35:55]

There is an event coming in a later CL that will propagate network changes,
including connection state.

I've changed the names to startConnect and startDisconnect.

+        "description": "Connects to the network with networkGuid.",
+        "parameters": [
+          {
+            "name": "networkGuid",
+            "type": "string",
+            "description": "The unique identifier of the network to connect to."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [],
+            "description": "A callback function that indicates that a connection has been initiated."
+          }
+        ]
+      },
+      {
+        "name": "requestDisconnect",

[not at google - send to devlin, 2013/01/23 22:37:52]

ditto

+        "description": "Requests a disconnect from the network with networkGuid.",
+        "parameters": [
+          {
+            "name": "networkGuid",
+            "type": "string",
+            "description": "The unique identifier of the network to disconnect from."
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "optional": true,
+            "parameters": [],
+            "description": "A callback function that indicates that a disconnect has been initiated."
+          }
+        ]
+      }
+    ]
+  }
+]