// Copyright (c) 2012 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": "proxy",
    "description": "Use the <code>chrome.proxy</code> API to manage Chrome's proxy settings. This API relies on the <a href='types.html#ChromeSetting'>ChromeSetting prototype of the type API</a> for getting and setting the proxy configuration.",
    "types": [
      {
        "id": "ProxyServer",
        "type": "object",
        "description": "An object encapsulating a single proxy server's specification.",
        "properties": {
          "scheme": {"type": "string", "optional": true, "enum": ["http", "https", "socks4", "socks5"], "description": "The scheme (protocol) of the proxy server itself. Defaults to 'http'."},
          "host": {"type": "string", "description": "The URI of the proxy server. This must be an ASCII hostname (in Punycode format). IDNA is not supported, yet."},
          "port": {"type": "integer", "optional": true, "description": "The port of the proxy server. Defaults to a port that depends on the scheme."}
        }
      },
      {
        "id": "ProxyRules",
        "type": "object",
        "description": "An object encapsulating the set of proxy rules for all protocols. Use either 'singleProxy' or (a subset of) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' and 'fallbackProxy'.",
        "properties": {
          "singleProxy": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for all per-URL requests (that is http, https, and ftp)."},
          "proxyForHttp": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for HTTP requests."},
          "proxyForHttps": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for HTTPS requests."},
          "proxyForFtp": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for FTP requests."},
          "fallbackProxy": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for everthing else or if any of the specific proxyFor... is not specified."},
          "bypassList": {"type": "array", "items": {"type": "string"}, "optional": true, "description": "List of servers to connect to without a proxy server."}
        }
      },
      {
        "id": "PacScript",
        "type": "object",
        "description": "An object holding proxy auto-config information. Exactly one of the fields should be non-empty.",
        "properties": {
          "url": {"type": "string", "optional": true, "description": "URL of the PAC file to be used."},
          "data": {"type": "string", "optional": true, "description": "A PAC script."},
          "mandatory": {"type": "boolean", "optional": true, "description": "If true, an invalid PAC script will prevent the network stack from falling back to direct connections. Defaults to false."}
        }
      },
      {
        "id": "ProxyConfig",
        "type": "object",
        "description": "An object encapsulating a complete proxy configuration.",
        "properties": {
          "rules": {"$ref": "ProxyRules", "optional": true, "description": "The proxy rules describing this configuration. Use this for 'fixed_servers' mode."},
          "pacScript": {"$ref": "PacScript", "optional": true, "description": "The proxy auto-config (PAC) script for this configuration. Use this for 'pac_script' mode."},
          "mode": {
            "type": "string",
            "enum": ["direct", "auto_detect", "pac_script", "fixed_servers", "system"],
            "description": "'direct' = Never use a proxy<br>'auto_detect' = Auto detect proxy settings<br>'pac_script' = Use specified PAC script<br>'fixed_servers' = Manually specify proxy servers<br>'system' = Use system proxy settings"
          }
        }
      }
    ],
    "properties": {
      "settings": {
        "$ref": "types.ChromeSetting",
        "description": "Proxy settings to be used. The value of this setting is a ProxyConfig object.",
        "value": [
          "proxy",
          {"$ref": "ProxyConfig"}
        ]
      }
    },
    "events": [
      {
        "name": "onProxyError",
        "type": "function",
        "description": "Notifies about proxy errors.",
        "parameters": [
          {
            "type": "object",
            "name": "details",
            "properties": {
              "fatal": {
                "type": "boolean",
                "description": "If true, the error was fatal and the network transaction was aborted. Otherwise, a direct connection is used instead."
              },
              "error": {
                "type": "string",
                "description": "The error description."
              },
              "details": {
                "type": "string",
                "description": "Additional details about the error such as a JavaScript runtime error."
              }
            }
          }
        ]
      }
    ]
  }
]