Use networkingPrivate types in JS

extensions/common/api/networking_private.idl

+// Copyright 2015 The Chromium Authors. All rights reserved.

[pneubeck (no reviews), 2015/03/26 16:56:47]

you should run chrome/common/extensions/docs/server2/preview.py
to see whether the generated documentation page is acceptable.
Probably you have to tweak it using [noinline] attributes.

+// 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

[pneubeck (no reviews), 2015/03/26 16:56:47]

nit: remove orphaned "

+// 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.
+
+namespace networkingPrivate {
+  enum ActivationStateType {
+    Activated, Activating, NotActivated, PartiallyActivated
+  };
+
+  enum CaptivePortalStatus {
+    Unknown, Offline, Online, Portal, ProxyAuthRequired
+  };
+
+  enum ConnectionStateType {
+    Connected, Connecting, NotConnected
+  };
+
+  enum IPConfigType {
+    DHCP, Static
+  };
+
+  enum NetworkType {
+    All, Bluetooth, Cellular, Ethernet, VPN, Wireless, WiFi, WiMAX
+  };
+
+  dictionary APNProperties {

[pneubeck (no reviews), 2015/03/26 16:56:47]

if you don't need for any of these the generated C++ wrappers, you should add
[nocompile] attributes.

+    DOMString? AccessPointName;
+    DOMString? Name;
+    DOMString? Username;
+    DOMString? Password;
+  };
+
+  dictionary CellularConfigProperties {
+    boolean? AutoConnect;
+    APNProperties? APN;
+  };
+
+  dictionary CellularStateProperties {
+    long? SignalStrength;
+    boolean? OutOfCredits;
+    DOMString? RoamingState;
+    ActivationStateType? ActivationState;
+    DOMString? NetworkTechnology;
+  };
+
+  dictionary EthernetStateProperties {
+    DOMString? Authentication;
+  };
+
+  dictionary IPConfigProperties {
+    DOMString? Gateway;
+    DOMString? IPAddress;
+    DOMString[]? NameServers;
+    DOMString? Type;
+    long? RoutingPrefix;
+  };
+
+  dictionary IPSecProperties {
+    DOMString? AuthenticationType;
+  };
+
+  dictionary VPNConfigProperties {
+    boolean? AutoConnect;
+    DOMString? Type;
+    DOMString? Host;
+  };
+
+  dictionary VPNStateProperties {
+    DOMString? Type;
+    IPSecProperties? IPsec;
+  };
+
+  dictionary WiFiConfigProperties {
+    boolean? AutoConnect;
+  };
+
+  dictionary WiFiStateProperties {
+    DOMString? Security;
+    long? SignalStrength;
+  };
+
+  dictionary WiMaxConfigProperties {
+    boolean? AutoConnect;
+  };
+
+  dictionary WiMAXStateProperties {
+    long? SignalStrength;
+  };
+
+  dictionary NetworkConfigProperties {
+    CellularConfigProperties? Cellular;
+    DOMString? GUID;
+    IPConfigType? IPAddressConfigType;
+    DOMString? Name;
+    IPConfigType? NameServersConfigType;
+    long? Priority;
+    IPConfigProperties? StaticIPConfig;
+    NetworkType? Type;
+    VPNConfigProperties? VPN;
+    WiFiConfigProperties? WiFi;
+    WiMaxConfigProperties? WiMAX;
+  };
+
+  dictionary NetworkStateProperties {
+    CellularStateProperties? Cellular;
+    boolean? Connectable;
+    ConnectionStateType? ConnectionState;
+    EthernetStateProperties? Ethernet;
+    DOMString? ErrorState;
+    DOMString GUID;
+    DOMString? Name;
+    long? Priority;
+    DOMString? Source;
+    NetworkType Type;
+    VPNStateProperties? VPN;
+    WiFiStateProperties? WiFi;
+    WiMAXStateProperties? 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.
+    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(NetworkStateProperties result);
+  callback GetNetworksCallback = void(NetworkStateProperties[] result);
+  callback GetEnabledNetwrokTypesCallback = 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 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,
+                              NetworkConfigProperties 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,
+                              NetworkConfigProperties properties,
+                              optional StringCallback 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
+    // 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();
+    // |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);
+  };
+};