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 ONC documentation for descriptions of properties.
+// TODO(stevenjb/pneubeck): Merge the ONC documentation with this document and
+// use it as the ONC specification.

[asargent_no_longer_on_chrome, 2015/03/26 19:57:09]

Is there a pointer to the ONC documentation you can provide here, to help point
folks in the right direction until you finish this TODO? (Is this the right one?
http://www.chromium.org/chromium-os/chromiumos-design-docs/open-network-confi...)

Also, I don't think that the ONC acronym is well-known, so it might make sense
to spell it out the first time you use the term in the above comment and include
the abbreviation in parentheses, e.g. "Open Networking Configuration (ONC)"

[stevenjb, 2015/03/27 16:59:14]

Done.

+
+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,
+    // representing the public key to be used by verifyAndEncryptCredentials and
+    // 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.
+    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. Use 0 for no
+    // limit.

[asargent_no_longer_on_chrome, 2015/03/26 19:57:08]

it might be worth mentioning if leaving limit undefined means no limit, or means
the default of 1000

[stevenjb, 2015/03/27 16:59:14]

Done.

+    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 GetEnabledNetwrokTypesCallback = void(NetworkType[] result);

[asargent_no_longer_on_chrome, 2015/03/26 19:57:08]

typo: "..Netwrok.."

[stevenjb, 2015/03/27 16:59:14]

Done.

+  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
+    // 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.
+    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.
+    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.
+    // |callback|: Returns the identifier of the created network.
+    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
+    // 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.
+    static void forgetNetwork(DOMString networkGuid,
+                              optional VoidCallback callback);
+
+    // Returns a list of network objects with the same properties provided by
+    // getState. A filter is provided to specify the type of networks returned

[asargent_no_longer_on_chrome, 2015/03/26 19:57:08]

Consider using "$(ref:networkingPrivate.getState)" instead of just "getState"
here

+    // and to limit the number of networks. Networks are ordered by the system
+    // based on their priority, with connected or connecting networks listed
+    // first. static void getNetworks();

[asargent_no_longer_on_chrome, 2015/03/26 19:57:08]

Did you mean to leave "static void getNetworks();" in the comment here? 

[stevenjb, 2015/03/27 16:59:14]

Done.

+    // |filter|: Describes which networks to return.
+    // |callback|: Returns the network state properties.
+    static void getNetworks(NetworkFilter filter,
+                            GetNetworksCallback callback);
+
+    // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
+    // filter.visble = true instead.
+    [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(GetEnabledNetwrokTypesCallback 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
+    // request: the network subsystem can choose to ignore it.  If the list
+    // is updated, then the onNetworkListChanged event will be fired.
+    static void requestNetworkScan();
+
+    // Starts a connection to the network with networkGuid.
+    // |networkGuid|: The identifier of the network to connect to.
+    static void startConnect(DOMString networkGuid,
+                             optional VoidCallback callback);
+    
+    // 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.
+    // |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
+    //     (e.g. MAC address lookup failed). 'Timeout' indicates that the lookup
+    //     timed out. Otherwise a valid status is returned (see
+    //     getWifiTDLSStatus).
+    static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
+                                        boolean enabled,
+                                        StringCallback callback);
+
+    // 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',
+    //     'Nonexistent', or 'Unknown'.
+    static void getWifiTDLSStatus(DOMString ip_or_mac_address,
+                                  StringCallback callback);
+
+    // Returns captive portal status for the network matching 'guid'.
+    // |networkGuid|: The identifier of the network to get the captive portal
+    //     status for.
+    // |calback|: Results of the query for network captive portal status.
+    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);
+  };
+};