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: 
+// <a href="https://code.google.com/p/chromium/codesearch#chromium/src/components/onc/docs/onc_spec.html">
+// src/components/onc/docs/onc_spec.html</a>, or the 
+// <a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/open-network-configuration">
+// Open Network Configuration</a> page at chromium.org.
+//
+// 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,
+    // representing the public key to be used by
+    // $(ref:verifyAndEncryptCredentials) and $(ref: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 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
+    // properties of the network (read-only and read/write values).
+    // |networkGuid|: The GUID of the network to get properties for.
+    // |callback|: Called with the network properties when received.
+    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 GUID of the network to get properties for.
+    // |callback|: Called with the managed network properties when received.
+    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
+    // $(ref: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 GUID of the network to get properties for.
+    // |callback|: Called immediately with the network state properties.
+    static void getState(DOMString networkGuid,
+                         GetStatePropertiesCallback callback);
+
+    // Sets the properties of the network with id networkGuid.
+    // |networkGuid|: The GUID of the network to set properties for.
+    // |properties|: The 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 properties to configure the new network with.
+    // |callback|: Called with the GUID for the new network configuration once
+    //     the network has been created.
+    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.
+    // |networkGuid|: The GUID of the network to forget.
+    // |callback|: Called when the operation has completed.
+    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|: Called with a dictionary of networks and their state 
+    //     properties when received.
+    static void getNetworks(NetworkFilter filter,
+                            GetNetworksCallback callback);
+
+    // Deprecated. Please use $(ref:networkingPrivate.getNetworks) with
+    // filter.visible = 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.
+    // |callback|: Called immediately with the enabled network types.
+    static void getEnabledNetworkTypes(GetEnabledNetworkTypesCallback callback);
+
+    // Enable the specified network type. Note, the type might represent
+    // multiple network types (e.g. 'Wireless').
+    // |networkType|: The type of network to enable.
+    static void enableNetworkType(NetworkType networkType);
+
+    // Disable the specified network type. See note for
+    // $(ref:networkingPrivate.enableNetworkType).
+    // |networkType|: The type of network to disable.
+    static void disableNetworkType(NetworkType networkType);
+
+    // Requests that the networking subsystem scan for new networks and
+    // update the list returned by $(ref:getVisibleNetworks). This is only a
+    // request: the network subsystem can choose to ignore it.  If the list
+    // is updated, then the $(ref:onNetworkListChanged) event will be fired.
+    static void requestNetworkScan();
+
+    // Starts a connection to the network with networkGuid.
+    // |networkGuid|: The GUID of the network to connect to.
+    // |callback|: Called when the connect request has been sent. Note: the
+    //     connection may not have completed. Observe $(ref:onNetworksChanged)
+    //     to be notified when a network state changes.
+    static void startConnect(DOMString networkGuid,
+                             optional VoidCallback callback);
+    
+    // Starts a disconnect from the network with networkGuid.
+    // |networkGuid|: The GUID of the network to disconnect from.
+    // |callback|: Called when the disconnect request has been sent. See note
+    //     for $(ref:startConnect).
+    static void startDisconnect(DOMString networkGuid,
+                                optional VoidCallback callback);
+
+    // Starts activation of the Cellular network with networkGuid.
+    // |networkGuid|: The GUID of the Cellular network to activate.
+    // |carrier|: Optional name of carrier to activate.
+    // |callback|: Called when the activation request has been sent. See note
+    //     for $(ref:startConnect).
+    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 GUID 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.
+    // |callback|: 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
+    //     $(ref:getWifiTDLSStatus)).
+    static void setWifiTDLSEnabledState(DOMString ip_or_mac_address,
+                                        boolean enabled,
+                                        optional StringCallback callback);
+
+    // Returns the current TDLS status for the specified peer.
+    // |ip_or_mac_address|: The IP or MAC address of the peer.
+    // |callback|: 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 'networkGuid'.
+    // |networkGuid|: The GUID of the network to get captive portal status for.
+    // |callback|: A callback function that returns the 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
+    // GUIDs for networks whose properties have changed.
+    static void onNetworksChanged(DOMString[] changes);
+
+    // Fired when the list of networks has changed.  Sends a complete list of
+    // GUIDs 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);
+  };
+};