Convert networkingPrivate to use IDL format

extensions/common/api/networking_private.idl

+// Copyright 2015 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.
+
+// The <code>chrome.networkingPrivate</code> API is used for configuring
+// network connections (Cellular, Ethernet, VPN, WiFi or WiMAX). This private
+// API is only valid if called from a browser or app associated with the
+// primary user. See the Open Network Configuration (ONC) documentation for
+// descriptions of properties: 
+// src/components/onc/docs/onc_spec.html, also available at 
+// http://www.chromium.org/chromium-os/chromiumos-design-docs/open-network-configuration
+// TODO(stevenjb/pneubeck): Merge the ONC documentation with this document and
+// use it as the ONC specification.
+
+namespace networkingPrivate {
+  enum CaptivePortalStatus {
+    Unknown, Offline, Online, Portal, ProxyAuthRequired
+  };
+
+  enum NetworkType {
+    All, Bluetooth, Cellular, Ethernet, VPN, Wireless, WiFi, WiMAX
+  };
+
+  dictionary VerificationProperties {
+    // A string containing a PEM-encoded (including the 'BEGIN CERTIFICATE'
+    // header and 'END CERTIFICATE' footer) X.509 certificate for use in
+    // verifying the signed data.
+    DOMString certificate;
+
+    // An array of PEM-encoded X.509 intermediate certificate authority
+    // certificates. Each PEM-encoded certificate is expected to have the
+    // 'BEGIN CERTIFICATE' header and 'END CERTIFICATE' footer.
+    DOMString[]? intermediateCertificates;
+
+    // A string containing a Base64-encoded RSAPublicKey ASN.1 structure,

[pneubeck (no reviews), 2015/03/27 18:08:02]

nit: Base64 -> base64

[stevenjb, 2015/03/27 19:32:55]

Done.

+    // representing the public key to be used by verifyAndEncryptCredentials and

[pneubeck (no reviews), 2015/03/27 18:08:03]

references in comments can be done using $(ref:verifyAndEncryptCredentials)
feel free to do another pass to cleanup the generated documentation in a follow
up CL.

[stevenjb, 2015/03/27 19:32:55]

Done.

+    // verifyAndEncryptData methods.
+    DOMString publicKey;
+
+    // A string containing a base64-encoded random binary data for use in
+    // verifying the signed data.
+    DOMString nonce;
+
+    // A string containing the identifying data string signed by the device.
+    DOMString signedData;
+
+    // A string containing the serial number of the device.
+    DOMString deviceSerial;
+
+    // A string containing the SSID of the device. Should be empty for new
+    // configurations.

[pneubeck (no reviews), 2015/03/27 18:08:03]

neither the old "Only set if the device has already been setup once." nor the
new comment are very clear, since it's not obvious what 'configuration' or
'setup' means in this case.

[stevenjb, 2015/03/27 19:32:54]

Acknowledged.

+    DOMString deviceSsid;
+
+    // A string containing the BSSID of the device. Should be empty for new
+    // configurations.
+    DOMString deviceBssid;
+  };
+
+  dictionary NetworkFilter {
+    // The type of networks to return.
+    NetworkType networkType;
+
+    // If true, only include visible (physically connected or in-range)
+    // networks. Defaults to 'false'.
+    boolean? visible;
+
+    // If true, only include configured (saved) networks. Defaults to 'false'.
+    boolean? configured;
+
+    // Maximum number of networks to return. Defaults to 1000 if unspecified. 
+    // Use 0 for no limit.
+    long? limit;
+  };
+
+  callback VoidCallback = void();
+  callback BooleanCallback = void(boolean result);
+  callback StringCallback = void(DOMString result);
+  // TODO(stevenjb): Use NetworkProperties for |result| once defined.
+  callback GetPropertiesCallback = void(object result);
+  // TODO(stevenjb): Use ManagedNetworkProperties for |result| once defined.
+  callback GetManagedPropertiesCallback = void(object result);
+  callback GetStatePropertiesCallback = void(object result);
+  callback GetNetworksCallback = void(object[] result);
+  callback GetEnabledNetworkTypesCallback = void(NetworkType[] result);
+  callback CaptivePortalStatusCallback = void(CaptivePortalStatus result);
+
+  // These functions all report failures via chrome.runtime.lastError.
+  interface Functions {
+    // Gets all the properties of the network with id networkGuid. Includes all

[pneubeck (no reviews), 2015/03/27 18:08:03]

I'd put references to variables (that you can't refer to with $(ref:..), I
think) between <code>...</code>

again feel free to defer.

[stevenjb, 2015/03/27 19:32:54]

Acknowledged.

+    // properties of the network (read-only and read/write values).
+    // |networkGuid|: The identifier of the network to get properties for.
+    // |callback|: Returns the properties of the network.

[pneubeck (no reviews), 2015/03/27 18:08:02]

technically it's not a return but more of a 'receives' or so.
others seem to document it in the way
  'Called with ... when ... is done.'

[stevenjb, 2015/03/27 19:32:54]

Done.

+    static void getProperties(DOMString networkGuid,
+                              GetPropertiesCallback callback);
+
+    // Gets the merged properties of the network with id networkGuid from the
+    // sources: User settings, shared settings, user policy, device policy and
+    // the currently active settings.
+    // |networkGuid|: The identifier of the network to get properties for.
+    // |callback|: Returns the managed properties of the network.
+    static void getManagedProperties(DOMString networkGuid,
+                                     GetManagedPropertiesCallback callback);
+
+    // 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.  The
+    // following properties are returned for all networks: GUID, Type, Name,
+    // WiFi.Security. Additional properties are provided for visible networks:
+    // ConnectionState, ErrorState, WiFi.SignalStrength,
+    // Cellular.NetworkTechnology, Cellular.ActivationState,
+    // Cellular.RoamingState, Cellular.OutOfCredits.
+    // |networkGuid|: The identifier of the network to get properties for.
+    // |callback|: Returns the managed properties of the network.

[pneubeck (no reviews), 2015/03/27 18:08:03]

'managed' is wrong

[stevenjb, 2015/03/27 19:32:55]

Done.

+    static void getState(DOMString networkGuid,
+                         GetStatePropertiesCallback callback);
+
+    // Sets the properties of the network with id networkGuid.
+    // |networkGuid|: The identifier of the network to set properties for.
+    // |properties|: The ONC properties to set.
+    // |callback|: Called when the operation has completed.
+    static void setProperties(DOMString networkGuid,
+                              object properties,
+                              optional VoidCallback callback);
+
+    // 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.
+    // |shared|: If true, share this network configuration with other users.
+    // |properties|: The ONC properties to configure the new network with.

[pneubeck (no reviews), 2015/03/27 18:08:03]

here and for setProperties, you call it ONC properties. In get*Properties it's
just 'properties' and 'managed properties'

I'd leave ONC out. Once the type descriptions are added, it's anyways defined.

[stevenjb, 2015/03/27 19:32:55]

Done.

+    // |callback|: Returns the identifier of the created network.

[pneubeck (no reviews), 2015/03/27 18:08:02]

here or in a follow up, the use of 'identifier'/GUID/... should be made
consistent, e.g. always be called 'network identifier' or 'network GUID'.

[stevenjb, 2015/03/27 19:32:55]

Done.

+    static void createNetwork(boolean shared,
+                              object properties,
+                              optional StringCallback callback);
+
+    // Forgets a network configuration by clearing any configured properties for
+    // the network with GUID 'networkGuid'. This may also include any other

[pneubeck (no reviews), 2015/03/27 18:08:03]

s/'...'/<code>...</code>

[stevenjb, 2015/03/27 19:32:54]

Acknowledged.

+    // networks with matching identifiers (e.g. WiFi SSID and Security). If no
+    // such configuration exists, an error will be set and the operation will
+    // fail.

[pneubeck (no reviews), 2015/03/27 18:08:03]

other functions have parameter comments.

[stevenjb, 2015/03/27 19:32:54]

Done.

+    static void forgetNetwork(DOMString networkGuid,
+                              optional VoidCallback callback);
+
+    // Returns a list of network objects with the same properties provided by
+    // $(ref:networkingPrivate.getState). A filter is provided to specify the
+    // type of networks returned and to limit the number of networks. Networks
+    // are ordered by the system based on their priority, with connected or
+    // connecting networks listed first.
+    // |filter|: Describes which networks to return.
+    // |callback|: Returns the network state properties.
+    static void getNetworks(NetworkFilter filter,
+                            GetNetworksCallback callback);

[pneubeck (no reviews), 2015/03/27 18:08:03]

was optional but probably didn't make sense

[stevenjb, 2015/03/27 19:32:55]

Correct.

+
+    // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
+    // filter.visble = true instead.

[pneubeck (no reviews), 2015/03/27 18:08:03]

typo: visble -> visible

should be embedded in <code>...</code>

[stevenjb, 2015/03/27 19:32:54]

Done, ack

+    [deprecated="Use getNetworks."] static void getVisibleNetworks(
+        NetworkType networkType,
+        GetNetworksCallback callback);
+
+    // Returns a list of the enabled network types. Note: this only returns
+    // discrete types that can be enabled or disabled: Cellular, Ethernet, WiFi,
+    // Wimax.
+    static void getEnabledNetworkTypes(GetEnabledNetworkTypesCallback callback);
+
+    // Enable the specified network type. Note, the type might represent
+    // multiple network types (e.g. 'Wireless').
+    static void enableNetworkType(NetworkType networkType);
+
+    // Disable the specified network type. See note for
+    // $(ref:networkingPrivate.enableNetworkType).
+    static void disableNetworkType(NetworkType networkType);
+
+    // Requests that the networking subsystem scan for new networks and
+    // update the list returned by getVisibleNetworks.  This is only a

[pneubeck (no reviews), 2015/03/27 18:08:03]

$(ref:getVisibleNetworks)

[stevenjb, 2015/03/27 19:32:54]

Done.

+    // request: the network subsystem can choose to ignore it.  If the list
+    // is updated, then the onNetworkListChanged event will be fired.

[pneubeck (no reviews), 2015/03/27 18:08:03]

$(ref:onNetworkListChanged)

[stevenjb, 2015/03/27 19:32:54]

Done.

+    static void requestNetworkScan();
+
+    // Starts a connection to the network with networkGuid.
+    // |networkGuid|: The identifier of the network to connect to.

[pneubeck (no reviews), 2015/03/27 18:08:03]

probably drop the argument comments in all trivial cases (or use them
everywhere)?

[stevenjb, 2015/03/27 19:32:54]

Using everywhere.

+    static void startConnect(DOMString networkGuid,
+                             optional VoidCallback callback);

[pneubeck (no reviews), 2015/03/27 18:08:03]

actually, for the start* functions, the comment at the |callback| was rather
important to explain that it's called independently of the actual operation
finishing.

[stevenjb, 2015/03/27 19:32:54]

Done.

+    
+    // Starts a disconnect from the network with networkGuid.
+    // |networkGuid|: The identifier of the network to disconnect from.
+    static void startDisconnect(DOMString networkGuid,
+                                optional VoidCallback callback);
+
+    // Starts activation of the Cellular network with networkGuid.
+    // |networkGuid|: The identifier of the Cellular network to activate.
+    // |carrier|: Optional name of carrier to activate.
+    static void startActivate(DOMString networkGuid,
+                              optional DOMString carrier,
+                              optional VoidCallback callback);
+
+    // Verifies that the device is a trusted device.
+    // |properties|: Properties of the destination to use in verifying that it
+    //     is a trusted device.
+    // |callback|: A callback function that indicates whether or not the device
+    //     is a trusted device.
+    static void verifyDestination(VerificationProperties properties,
+                                  BooleanCallback callback);
+
+    // Verifies that the device is a trusted device and retrieves encrypted
+    // network credentials.
+    // |properties|: Properties of the destination to use in verifying that it
+    //     is a trusted device.
+    // |networkGuid|: The identifier of the Cellular network to activate.
+    // |callback|: A callback function that receives base64-encoded encrypted
+    //     credential data to send to a trusted device.
+    static void verifyAndEncryptCredentials(VerificationProperties properties,
+                                            DOMString networkGuid,
+                                            StringCallback callback);
+
+    // Verifies that the device is a trusted device and encrypts supplied
+    // data with device public key.
+    // |properties|: Properties of the destination to use in verifying that it
+    //     is a trusted device.
+    // |data|: A string containing the base64-encoded data to encrypt.
+    // |callback|: A callback function that receives base64-encoded encrypted
+    //     data to send to a trusted device.
+    static void verifyAndEncryptData(VerificationProperties properties,
+                                     DOMString data, 
+                                     StringCallback callback);
+
+    // Enables TDLS for wifi traffic with a specified peer if available.

[pneubeck (no reviews), 2015/03/27 18:08:03]

wifi -> WiFi

[stevenjb, 2015/03/27 19:32:54]

Done.

+    // |ip_or_mac_address|: The IP or MAC address of the peer with which to
+    //     enable a TDLS connection.
+    // |enabled| If true, enable TDLS, otherwise disable TDLS.
+    // |calback|: A callback function that receives a string with an error or
+    //     the current TDLS status. 'Failed' indicates that the request failed

[pneubeck (no reviews), 2015/03/27 18:08:03]

these strings should probably be enums

[stevenjb, 2015/03/27 19:32:54]

Acknowledged.

+    //     (e.g. MAC address lookup failed). 'Timeout' indicates that the lookup
+    //     timed out. Otherwise a valid status is returned (see
+    //     getWifiTDLSStatus).

[pneubeck (no reviews), 2015/03/27 18:08:03]

$(ref:getWifiTDLSStatus)

[stevenjb, 2015/03/27 19:32:54]

Done.

+    static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
+                                        boolean enabled,
+                                        StringCallback callback);

[pneubeck (no reviews), 2015/03/27 18:08:03]

was optional but probably you changed it on purpose (potentially breaking
consumers)

[stevenjb, 2015/03/27 19:32:55]

Actually, setter callbacks should be optional, good catch, thanks.

+
+    // Returns the current TDLS status for the specified peer.
+    // |ip_or_mac_address|: The IP or MAC address of the peer.
+    // |calback|: A callback function that receives a string with the current
+    //     TDLS status which can be 'Connected', 'Disabled', 'Disconnected',

[pneubeck (no reviews), 2015/03/27 18:08:03]

these strings should probably be enums

[stevenjb, 2015/03/27 19:32:55]

Acknowledged.

+    //     'Nonexistent', or 'Unknown'.
+    static void getWifiTDLSStatus(DOMString ip_or_mac_address,
+                                  StringCallback callback);
+
+    // Returns captive portal status for the network matching 'guid'.

[pneubeck (no reviews), 2015/03/27 18:08:03]

'guid' is wrong

[stevenjb, 2015/03/27 19:32:54]

Done.

+    // |networkGuid|: The identifier of the network to get the captive portal
+    //     status for.
+    // |calback|: Results of the query for network captive portal status.

[pneubeck (no reviews), 2015/03/27 18:08:03]

calback -> callback

the comment isn't right for a callback (it was the comment from the callback's
argument)

[stevenjb, 2015/03/27 19:32:55]

Done.

+    static void getCaptivePortalStatus(DOMString networkGuid,
+                                       CaptivePortalStatusCallback callback);
+  };
+
+  interface Events {
+    // Fired when the properties change on any of the networks.  Sends a list of
+    // identifiers for networks whose properties have changed.
+    static void onNetworksChanged(DOMString[] changes);
+
+    // Fired when the list of networks has changed.  Sends a complete list of
+    // identifiers for all the current networks.
+    static void onNetworkListChanged(DOMString[] changes);
+
+    // Fired when a portal detection for a network completes. Sends the guid of
+    // the network and the corresponding captive portal status.
+    static void onPortalDetectionCompleted(DOMString networkGuid,
+                                           CaptivePortalStatus status);
+  };
+};