Extensions Docs Server: First doc conversions

chrome/common/extensions/docs/server2/templates/private/proxy_intro.html

+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+Use the <code>chrome.proxy</code> module to manage Chrome's
+proxy settings. This module relies on the <a href="types.html#ChromeSetting">
+ChromeSetting prototype of the type API</a> for getting and setting the proxy
+configuration.
+</p>
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "proxy" permission
+in the <a href="manifest.html">extension manifest</a>
+to use the proxy settings API.
+For example:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "proxy"
+  ]</b>,
+  ...
+}</pre>
+<h2 id="description">Objects and properties</h2>
+<p>
+Proxy settings are defined in a
+<a href="#type-proxy.ProxyConfig"><code>ProxyConfig</code></a> object. Depending on
+Chrome's proxy settings, the settings may contain
+<a href="#type-proxy.ProxyRules"><code>ProxyRules</code></a> or a <a
+  href="#type-proxy.PacScript"><code>PacScript</code></a>.
+</p>
+<h3 id="proxy_modes">Proxy modes</h3>
+<p>
+A ProxyConfig object's <code>mode</code> attribute determines the overall
+behavior of Chrome with regards to proxy usage. It can take the following
+values:
+<dl>
+  <dt><code>direct</code></dt>
+  <dd>In <code>direct</code> mode all connections are created directly, without
+  any proxy involved. This mode allows no further parameters in the
+  <code>ProxyConfig</code> object.</dd>
+  <dt><code>auto_detect</code></dt>
+  <dd>In <code>auto_detect</code> mode the proxy configuration is determined by
+  a PAC script that can be downloaded at
+  <a href="http://wpad/wpad.dat">http://wpad/wpad.dat</a>.
+  This mode allows no further parameters in the <code>ProxyConfig</code>
+  object.</dd>
+  <dt><code>pac_script</code></dt>
+  <dd>In <code>pac_script</code> mode the proxy configuration is determined by
+  a PAC script that is either retrieved from the URL specified in the
+  <a href="#type-proxy.PacScript"><code>PacScript</code></a> object or
+  taken literally from the <code>data</code> element specified in the
+  <a href="#type-proxy.PacScript"><code>PacScript</code></a> object.
+  Besides this, this mode allows no further parameters in the
+  <code>ProxyConfig</code> object.</dd>
+  <dt><code>fixed_servers</code></dt>
+  <dd>In <code>fixed_servers</code> mode the proxy configuration is codified in
+  a <a href="#type-proxy.ProxyRules><code>ProxyRules"><code>ProxyRules</code></a>
+  object. Its structure is described in <a href="#proxy_rules">Proxy rules</a>.
+  Besides this, the <code>fixed_servers</code> mode allows no further parameters
+  in the <code>ProxyConfig</code> object.</dd>
+  <dt><code>system</code></dt>
+  <dd>In <code>system</code> mode the proxy configuration is taken from the
+  operating system. This mode allows no further parameters in the
+  <code>ProxyConfig</code> object. Note that the <code>system</code> mode is
+  different from setting no proxy configuration. In the latter case, Chrome
+  falls back to the system settings only if no command-line options influence
+  the proxy configuration.</dd>
+</dl>
+</p>
+<h3 id="proxy_rules">Proxy rules</h3>
+<p>
+The <a href="#type-proxy.ProxyRules"><code>ProxyRules</code></a> object can contain
+either a <code>singleProxy</code> attribute or a subset of
+<code>proxyForHttp</code>, <code>proxyForHttps</code>, <code>proxyForFtp</code>,
+and <code>fallbackProxy</code>.
+</p>
+<p>
+In the first case, HTTP, HTTPS and FTP traffic is proxied through the specified
+proxy server. Other traffic is sent directly. In the latter case the behavior is
+slightly more subtle: If a proxy server is configured for the HTTP, HTTPS or FTP
+protocol, the respective traffic is proxied through the specified server. If no
+such proxy server is specified or traffic uses a different protocol than HTTP,
+HTTPS or FTP, the <code>fallbackProxy</code> is used. If no
+<code>fallbackProxy</code> is specified, traffic is sent directly without a
+proxy server.
+</p>
+<h3 id="proxy_server_objects">Proxy server objects</h3>
+<p>
+A proxy server is configured in a
+<a href="#type-proxy.ProxyServer"><code>ProxyServer</code></a> object. The connection
+to the proxy server (defined by the <code>host</code> attribute) uses the
+protocol defined in the <code>scheme</code> attribute. If no <code>scheme</code>
+is specified, the proxy connection defaults to <code>http</code>.
+</p>
+<p>
+If no <code>port</code> is defined in a
+<a href="#type-proxy.ProxyServer"><code>ProxyServer</code></a> object, the port is
+derived from the scheme. The default ports are:
+<table>
+  <tr><th>Scheme</th><th>Port</th></tr>
+  <tr><td>http</td><td>80</td></tr>
+  <tr><td>https</td><td>443</td></tr>
+  <tr><td>socks4</td><td>1080</td></tr>
+  <tr><td>socks5</td><td>1080</td></tr>
+</table>
+</p>
+<h3 id="bypass_list">Bypass list</h3>
+<p>
+Individual servers may be excluded from being proxied with the
+<code>bypassList</code>. This list may contain the following entries:
+<dl>
+  <dt><code>[<em>&lt;scheme&gt;</em>://]<em>&lt;host-pattern&gt;</em>[:<em>&lt;port&gt;</em>]</code></dt>
+  <dd>Match all hostnames that match the pattern <em>&lt;host-pattern&gt;</em>.<br>
+  Examples: <code>"foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99",
+    "https://x.*.y.com:99"</code></dd>
+  <dt><code>[<em>&lt;scheme&gt;</em>://]<em>&lt;ip-literal&gt;</em>[:<em>&lt;port&gt;</em>]</code></dt>
+  <dd>Match URLs that are IP address literals.<br>
+  Conceptually this is the similar to the first case, but with special cases
+  to handle IP literal canonicalization. For example, matching
+  on "[0:0:0::1]" is the same as matching on "[::1]" because
+  the IPv6 canonicalization is done internally.<br>
+  Examples: <code>"127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"</code></dd>
+  <dt><code><em>&lt;ip-literal&gt;</em>/<em>&lt;prefix-length-in-bits&gt;</em></code></dt>
+  <dd>Match any URL containing an IP literal within the given range. The IP
+  range is specified using CIDR notation.<br>
+  Examples: <code>"192.168.1.1/16", "fefe:13::abc/33"</code></dd>
+  <dt><code>&lt;local&gt;</code></dt>
+  <dd>Match local addresses. An address is local if the host is "127.0.0.1",
+  "::1", or "localhost".<br>
+  Example: <code>"&lt;local&gt;"</code></dd>
+</dl>
+<h2 id="overview-examples">Examples</h2>
+<p>
+The following code sets a SOCKS 5 proxy for HTTP connections to all servers but
+foobar.com and uses direct connections for all other protocols. The settings
+apply to regular and incognito windows, as incognito windows inherit settings
+from regular windows. Please also consult the <a
+  href="types.html#ChromeSetting">Types API</a> documentation.
+</p>
+<pre>
+var config = {
+  mode: "fixed_servers",
+  rules: {
+    proxyForHttp: {
+      scheme: "socks5",
+      host: "1.2.3.4"
+    },
+    bypassList: ["foobar.com"]
+  }
+};
+chrome.proxy.settings.set(
+    {value: config, scope: 'regular'},
+    function() {});
+</pre>
+<p>
+The following code sets a custom PAC script.
+</p>
+<pre>
+var config = {
+  mode: "pac_script",
+  pacScript: {
+    data: "function FindProxyForURL(url, host) {\n" +
+          "  if (host == 'foobar.com')\n" +
+          "    return 'PROXY blackhole:80';\n" +
+          "  return 'DIRECT';\n" +
+          "}"
+  }
+};
+chrome.proxy.settings.set(
+    {value: config, scope: 'regular'},
+    function() {});
+</pre>
+<p>
+The next snippet queries the currently effective proxy settings. The effective
+proxy settings can be determined by another extension or by a policy. See the <a
+  href="types.html#ChromeSetting">Types API</a> documentation for details.
+</p>
+<pre>
+chrome.proxy.settings.get(
+    {'incognito': false},
+    function(config) {console.log(JSON.stringify(config));});
+</pre>
+<p>
+Note that the <code>value</code> object passed to <code>set()</code> is not
+identical to the <code>value</code> object passed to callback function of
+<code>get()</code>. The latter will contain a
+<code>rules.proxyForHttp.port</code> element.
+</p>
+<!-- END AUTHORED CONTENT -->