path: root/extensions/common/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",
    "description": "none",
    "compiler_options": {
      "implemented_in": "extensions/browser/api/networking_private/networking_private_api.h"
    },
    "platforms": ["chromeos", "win", "mac", "linux"],
    "types" : [
      {
        "id": "NetworkProperties",
        "type": "object",
        "additionalProperties": { "type": "any" }
      },
      {
        "id": "ManagedNetworkProperties",
        "type": "object",
        "additionalProperties": { "type": "any" }
      },
      {
        "id": "VerificationProperties",
        "type": "object",
        "properties": {
          "certificate": {
            "type": "string",
            "description": "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."
          },
          "intermediateCertificates": {
            "type": "array",
            "items": { "type": "string" },
            "optional": true,
            "description": "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."
          },
          "publicKey": {
            "type": "string",
            "description": "A string containing a Base64-encoded RSAPublicKey ASN.1 structure, representing the public key to be used by verifyAndEncryptCredentials and verifyAndEncryptData methods."
          },
          "nonce": {
            "type": "string",
            "description": "A string containing a base64-encoded random binary data for use in verifying the signed data."
          },
          "signedData": {
            "type": "string",
            "description": "A string containing the identifying data string signed by the device."
          },
          "deviceSerial": {
            "type": "string",
            "description": "A string containing the serial number of the device."
          },
          "deviceSsid": {
            "type": "string",
            "description": "A string containing the SSID of the device.  Only set if the device has already been setup once."
          },
          "deviceBssid": {
            "type": "string",
            "description": "A string containing the BSSID of the device.  Only set if the device has already been setup."
          }
        }
      },
      {
        "id": "NetworkType",
        "type": "string",
        "enum": ["All", "Bluetooth", "Cellular", "Ethernet", "VPN", "Wireless", "WiFi", "Wimax"]
      },
      {
        "id": "CaptivePortalStatus",
        "type": "string",
        "enum": ["Unknown", "Offline", "Online", "Portal", "ProxyAuthRequired"]
      }
    ],
    "functions": [
      {
        "name": "getProperties",
        "description": "Gets all the properties of the network with id networkGuid.  Includes all properties of the network (read-only and read/write values).",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string",
            "description": "The unique identifier of the network to get properties from."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "properties",
                "$ref": "NetworkProperties",
                "description": "Results of the query for network properties."
              }
            ]
          }
        ]
      },
      {
        "name": "getManagedProperties",
        "description": "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.",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string",
            "description": "The unique identifier of the network to get properties from."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "properties",
                "$ref": "ManagedNetworkProperties",
                "description": "Results of the query for managed network properties."
              }
            ]
          }
        ]
      },
      {
        "name": "getState",
        "description": "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.",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string",
            "description": "The unique identifier of the network to set properties on."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "properties",
                "$ref": "NetworkProperties",
                "description": "Results of the query for network state properties."
              }
            ]
          }
        ]
      },
      {
        "name": "setProperties",
        "description": "Sets the properties of the network with id networkGuid.",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string",
            "description": "The unique identifier of the network to set properties on."
          },
          {
            "name": "properties",
            "$ref": "NetworkProperties",
            "description": "The properties to set on the network."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": []
          }
        ]
      },
      {
        "name": "createNetwork",
        "description": "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.",
        "parameters": [
          {
            "name": "shared",
            "type": "boolean",
            "description": "If true, share this network configuration with other users."
          },
          {
            "name": "properties",
            "$ref": "NetworkProperties",
            "description": "The properties to configure the new network with."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "networkGuid",
                "type": "string"
              }
            ]
          }
        ]
      },
      {
        "name": "getNetworks",
        "description": "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.",
        "parameters": [
          {
            "name": "filter",
            "type": "object",
            "properties": {
              "networkType": {
                "$ref": "NetworkType",
                "description": "The type of networks to return."
              },
              "visible": {
                "type": "boolean",
                "optional": true,
                "description": "If true, only include visible (physically connected or in-range) networks. Defaults to 'false'."
              },
              "configured": {
                "type": "boolean",
                "optional": true,
                "description": "If true, only include configured (saved) networks. Defaults to 'false'."
              },
              "limit": {
                "type": "integer",
                "optional": true,
                "description": "Maximum number of networks to return. Defaults to 1000. Use 0 for no limit."
              }
            }
          },
          {
            "name": "callback",
            "type": "function",
            "optional": true,
            "parameters": [
              {
                "name": "networkList",
                "type": "array",
                "items": { "$ref": "NetworkProperties" }
              }
            ]
          }
        ]
      },
      {
        "name": "getVisibleNetworks",
        "deprecated": "Please use $(ref:networkingPrivate.getNetworks) with filter.visble = true.",
        "description": "Returns a list of visible network objects with the same properties provided by getState.",
        "parameters": [
          {
            "name": "networkType",
            "$ref": "NetworkType",
            "description": "The type of networks to return."
          },
          {
            "name": "callback",
            "type": "function",
            "optional": true,
            "parameters": [
              {
                "name": "networkList",
                "type": "array",
                "items": { "$ref": "NetworkProperties" }
              }
            ]
          }
        ]
      },
      {
        "name": "getEnabledNetworkTypes",
        "description": "Returns a list of the enabled network types. Note: this only returns discrete types that can be enabled or disabled: Cellular, Ethernet, WiFi, Wimax.",
        "parameters": [
          {
            "name": "callback",
            "type": "function",
            "optional": true,
            "parameters": [
              {
                "name": "enabledTypes",
                "type": "array",
                "items": { "$ref": "NetworkType" }
              }
            ]
          }
        ]
      },
      {
        "name": "enableNetworkType",
        "description": "Enable the specified network type. Note, the type might represent multiple network types (e.g. 'Wireless').",
        "parameters": [
          {
            "name": "networkType",
            "$ref": "NetworkType"
          }
        ]
      },
      {
        "name": "disableNetworkType",
        "description": "Disable the specified network type. See note for $(ref:networkingPrivate.enableNetworkType).",
        "parameters": [
          {
            "name": "networkType",
            "$ref": "NetworkType"
          }
        ]
      },
      {
        "name": "requestNetworkScan",
        "description": "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.",
        "parameters": []
      },
      {
        "name": "startConnect",
        "description": "Starts a connection 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": "startDisconnect",
        "description": "Starts 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."
          }
        ]
      },
      {
        "name": "verifyDestination",
        "description": "Verifies that the device is a trusted device.",
        "parameters": [
          {
            "name": "properties",
            "$ref": "VerificationProperties",
            "description": "Properties of the destination to use in verifying that it is a trusted device."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "verified",
                "type": "boolean"
              }
            ],
            "description": "A callback function that indicates whether or not the device is a trusted device."
          }
        ]
      },
      {
        "name": "verifyAndEncryptCredentials",
        "description": "Verifies that the device is a trusted device and retrieves encrypted network credentials.",
        "parameters": [
          {
            "name": "properties",
            "$ref": "VerificationProperties",
            "description": "Properties of the destination to use in verifying that it is a trusted device."
          },
          {
            "name": "networkGuid",
            "type": "string",
            "description": "A string containing the unique identifier of the network to get credentials for."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "credentials",
                "type": "string"
              }
            ],
            "description": "A callback function that receives base64-encoded encrypted credential data to send to a trusted device."
          }
        ]
      },
      {
        "name": "verifyAndEncryptData",
        "description": "Verifies that the device is a trusted device and encrypts supplied data with device public key.",
        "parameters": [
          {
            "name": "properties",
            "$ref": "VerificationProperties",
            "description": "Properties of the destination to use in verifying that it is a trusted device."
          },
          {
            "name": "data",
            "type": "string",
            "description": "A string containing the base64-encoded data to encrypt."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "encryptedData",
                "type": "string"
              }
            ],
            "description": "A callback function that receives base64-encoded encrypted data to send to a trusted device."
          }
        ]
      },
      {
        "name": "setWifiTDLSEnabledState",
        "description": "Enables TDLS for wifi traffic with a specified peer if available.",
        "parameters": [
          {
            "name": "ip_or_mac_address",
            "type": "string",
            "description": "The IP or MAC address of the peer with which to enable a TDLS connection."
          },
          {
            "name": "enabled",
            "type": "boolean",
            "description": "If true, enable TDLS, otherwise disable TDLS."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "status",
                "type": "string"
              }
            ],
            "description": "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)."
          }
        ]
      },
      {
        "name": "getWifiTDLSStatus",
        "description": "Returns the current TDLS status for the specified peer.",
        "parameters": [
          {
            "name": "ip_or_mac_address",
            "type": "string",
            "description": "The IP or MAC address of the peer."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "status",
                "type": "string"
              }
            ],
            "description": "A callback function that receives a string with the current TDLS status which can be 'Connected', 'Disabled', 'Disconnected', 'Nonexistent', or 'Unknown'"
          }
        ]
      },
      {
        "name": "getCaptivePortalStatus",
        "description": "Returns captive portal status for the network matching 'guid'.",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string",
            "description": "The guid of the network to get captive portal status."
          },
          {
            "name": "callback",
            "type": "function",
            "parameters": [
              {
                "name": "status",
                "$ref": "CaptivePortalStatus",
                "description": "Results of the query for network captive portal status."
              }
            ]
          }
        ]
      }
    ],
    "events": [
      {
        "name": "onNetworksChanged",
        "type": "function",
        "description": "Fired when the properties change on any of the networks.  Sends a list of identifiers for networks whose properties have changed.",
        "parameters": [
          {
            "name": "changes",
            "type": "array",
            "items": { "type": "string" }
          }
        ]
      },
      {
        "name": "onNetworkListChanged",
        "type": "function",
        "description": "Fired when the list of networks has changed.  Sends a complete list of identifiers for all the current networks.",
        "parameters": [
          {
            "name": "changes",
            "type": "array",
            "items": { "type": "string" }
          }
        ]
      },
      {
        "name": "onPortalDetectionCompleted",
        "type": "function",
        "description": "Fired when a portal detection for a network completes. Sends the guid of the network and the corresponding captive portal status.",
        "parameters": [
          {
            "name": "networkGuid",
            "type": "string"
          },
          {
            "name": "status",
            "$ref": "CaptivePortalStatus"
          }
        ]
      }
    ]
  }
]