src/chrome/common/extensions/api/proxy.json

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "proxy",
   8     "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.",
   9     "types": [
  10       {
  11         "id": "ProxyServer",
  12         "type": "object",
  13         "description": "An object encapsulating a single proxy server's specification.",
  14         "properties": {
  15           "scheme": {"type": "string", "optional": true, "enum": ["http", "https", "quic", "socks4", "socks5"], "description": "The scheme (protocol) of the proxy server itself. Defaults to 'http'."},
  16           "host": {"type": "string", "description": "The URI of the proxy server. This must be an ASCII hostname (in Punycode format). IDNA is not supported, yet."},
  17           "port": {"type": "integer", "optional": true, "description": "The port of the proxy server. Defaults to a port that depends on the scheme."}
  18         }
  19       },
  20       {
  21         "id": "ProxyRules",
  22         "type": "object",
  23         "description": "An object encapsulating the set of proxy rules for all protocols. Use either 'singleProxy' or (a subset of) 'proxyForHttp', 'proxyForHttps', 'proxyForFtp' and 'fallbackProxy'.",
  24         "properties": {
  25           "singleProxy": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for all per-URL requests (that is http, https, and ftp)."},
  26           "proxyForHttp": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for HTTP requests."},
  27           "proxyForHttps": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for HTTPS requests."},
  28           "proxyForFtp": {"$ref": "ProxyServer", "optional": true, "description": "The proxy server to be used for FTP requests."},
  29           "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."},
  30           "bypassList": {"type": "array", "items": {"type": "string"}, "optional": true, "description": "List of servers to connect to without a proxy server."}
  31         }
  32       },
  33       {
  34         "id": "PacScript",
  35         "type": "object",
  36         "description": "An object holding proxy auto-config information. Exactly one of the fields should be non-empty.",
  37         "properties": {
  38           "url": {"type": "string", "optional": true, "description": "URL of the PAC file to be used."},
  39           "data": {"type": "string", "optional": true, "description": "A PAC script."},
  40           "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."}
  41         }
  42       },
  43       {
  44         "id": "ProxyConfig",
  45         "type": "object",
  46         "description": "An object encapsulating a complete proxy configuration.",
  47         "properties": {
  48           "rules": {"$ref": "ProxyRules", "optional": true, "description": "The proxy rules describing this configuration. Use this for 'fixed_servers' mode."},
  49           "pacScript": {"$ref": "PacScript", "optional": true, "description": "The proxy auto-config (PAC) script for this configuration. Use this for 'pac_script' mode."},
  50           "mode": {
  51             "type": "string",
  52             "enum": ["direct", "auto_detect", "pac_script", "fixed_servers", "system"],
  53             "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"
  54           }
  55         }
  56       }
  57     ],
  58     "properties": {
  59       "settings": {
  60         "$ref": "types.ChromeSetting",
  61         "description": "Proxy settings to be used. The value of this setting is a ProxyConfig object.",
  62         "value": [
  63           "proxy",
  64           {"$ref": "ProxyConfig"}
  65         ]
  66       }
  67     },
  68     "events": [
  69       {
  70         "name": "onProxyError",
  71         "type": "function",
  72         "description": "Notifies about proxy errors.",
  73         "parameters": [
  74           {
  75             "type": "object",
  76             "name": "details",
  77             "properties": {
  78               "fatal": {
  79                 "type": "boolean",
  80                 "description": "If true, the error was fatal and the network transaction was aborted. Otherwise, a direct connection is used instead."
  81               },
  82               "error": {
  83                 "type": "string",
  84                 "description": "The error description."
  85               },
  86               "details": {
  87                 "type": "string",
  88                 "description": "Additional details about the error such as a JavaScript runtime error."
  89               }
  90             }
  91           }
  92         ]
  93       }
  94     ]
  95   }
  96 ]