Rename chrome.experimental.webRequest to chrome.webRequest and chrome.webRequestBlocking

chrome/common/extensions/docs/static/experimental.webRequest.html

Index: chrome/common/extensions/docs/static/experimental.webRequest.html
diff --git a/chrome/common/extensions/docs/static/experimental.webRequest.html b/chrome/common/extensions/docs/static/experimental.webRequest.html
deleted file mode 100644
index fe0c82ded9c89c33f7322d7ba45d6f200cb5367c..0000000000000000000000000000000000000000
--- a/chrome/common/extensions/docs/static/experimental.webRequest.html
+++ /dev/null
@@ -1,319 +0,0 @@
-<div id="pageData-name" class="pageData">WebRequest API</div>
-
-<!-- BEGIN AUTHORED CONTENT -->
-<p id="classSummary">
-Use the <code>chrome.experimental.webRequest</code> module to intercept, block,
-or modify requests in-flight. This module is still experimental. For
-information on how to use experimental APIs, see the
-<a href="experimental.html">chrome.experimental.* APIs</a> page.
-</p>
-
-<h2 id="manifest">Manifest</h2>
-<p>You must declare the "experimental" permission in the <a
-  href="manifest.html">extension manifest</a> to use the webRequest settings
-API, along with <a href="manifest.html#permissions">host permissions</a>
-for any hosts whose network requests you want to access.
-For example:</p>
-<pre>{
-  "name": "My extension",
-  ...
-  <b>"permissions": [
-    "experimental",
-    "*://*.google.com"
-  ]</b>,
-  ...
-}</pre>
-
-<h2 id="life_cycle">Life-cycle of requests</h2>
-
-<p>
-The webRequest API defines the following events:
-<dl>
-  <dt><code>onBeforeRequest (optionally synchronous)</code></dt>
-  <dd>Fires when a request is about to occur. This is sent before any TCP
-  connection is made and can be used to cancel or redirect requests.</dd>
-  <dt><code>onBeforeSendHeaders (optionally synchronous)</code></dt>
-  <dd>Fires when a request is about to occur and the initial headers are
-  prepared. The event is intended to allow extensions to add, modify and delete
-  request headers <a href="#life_cycle_footnote">(*)</a>. The
-  <code>onBeforeSendHeaders</code> event is passed to all subscribers, so
-  different subscribers may attempt to modify the request, see section <a
-    href="#conflict_resolution">conflict resolution</a> for details how this is
-  handled. This event can still be used to cancel the request.</dd>
-  <dt><code>onSendHeaders</code></dt>
-  <dd>Fires after all extensions had a chance of modifying the request headers
-  and presents the final <a href="#life_cycle_footnote">(*)</a> version. The
-  event is triggered, before the headers are sent to the network. This event is
-  informational and handled asynchronously. It does not allow to modify or
-  cancel the request.</dd>
-  <dt><code>onHeadersReceived (optionally synchronous)</code></dt>
-  <dd>Fires each time when a HTTP(S) response header has been received. Due
-  to redirects and authentication requests this can happen multiple times per
-  request. This event is intended to allow extensions to add, modify and delete
-  response headers, like incoming Set-Cookie headers for example.</dd>
-  <dt><code>onAuthRequired (optionally synchronous)</code></dt>
-  <dd>Fires when a request requires authentication of the user. This signal can
-  be handled synchronously to provide authentication credentials. Note that
-  extensions may provide invalid credentials. Take care not to enter an infinite
-  loop by repeatedly providing invalid credentials.</dd>
-  <dt><code>onBeforeRedirect</code></dt>
-  <dd>Fires before a redirect is about to be executed. A redirection can be
-  triggered by a HTTP response code or by an extension. This event is
-  informational and handled asynchronously. It does not allow you to modify or
-  cancel the request. </dd>
-  <dt><code>onResponseStarted</code></dt>
-  <dd>Fires when the first byte of the response body is received. For HTTP
-  requests, this means that the status line and response headers are
-  available. This event is informational and handled asynchronously. It does not
-  allow to modify or cancel the request.</dd>
-  <dt><code>onCompleted</code></dt>
-  <dd>Fires when a request has been processed successfully.</dd>
-  <dt><code>onErrorOccurred</code></dt>
-  <dd>Fires when a request could not be processed successfully.</dd>
-</dl>
-The webRequest API gurantees that for each request either
-<code>onComplete</code> or <code>onErrorOccurred</code> is fired as the final
-event.
-</p>
-
-<p>
-The life-cycle of successful requests can be illustrated as follows:
-<pre>
-  |
-  v
-onBeforeRequest --------------------------------
-  |          ^             |                    | [data and file URLs]
-  |          |             | [redirection       |
-  |           ----------   |  from extension]   |
-  v                     |  |                    |
-onBeforeSendHeaders     |  |                    |
-  |               ^     |  |                    |
-  v               |     |  |                    |
-onSendHeaders     |     |  |                    |
-  |               |     |  |                    |
-  v               |     |  |                    |
-onHeadersReceived |     |  |                    |
-  |  |  |         |     |  |                    |
-  |  |  v         |     |  |                    |
-  |  |  onAuthRequired /   |                    |
-  |  v                /    |                    |
-  |  onBeforeRedirect <----                     |
-  v                                             |
-onResponseStarted <-----------------------------
-  |
-  v
-onCompleted
-</pre>
-<em>Note that this diagram does not capture a bug that will be fixed soon: If
-extensions redirect a URL request via the webRequest API, this redirection does
-not trigger <code>onBeforeRedirect</code>. Instead the request is cancelled
-and a new request is started at <code>onBeforeRedirect</code>. See <a
-  href="http://crbug.com/79520">http://crbug.com/79520</a>.</em>
-</p>
-
-<p id="life_cycle_footnote">(*) Note that the webRequest API presents an
-abstraction of the network stack to the extension. Internally, one URL request
-can be split into several HTTP requests (for example to fetch individual byte
-ranges from a large file) or can be handled by the network stack without
-communicating with the network. For this reason, the API does not provide the
-final HTTP headers that are sent to the network. For example all headers that
-are related to caching are invisible to the extension.</p>
-
-<p>This is a list of headers that are currently not provided to the
-onBeforeSendHeaders signal. The list is not guaranteed to be complete nor
-stable:
-<ul>
-  <li>Authorization</li>
-  <li>Cache-Control</li>
-  <li>Connection</li>
-  <li>Content-Length</li>
-  <li>Host</li>
-  <li>If-Modified-Since</li>
-  <li>If-None-Match</li>
-  <li>If-Range</li>
-  <li>Partial-Data</li>
-  <li>Pragma</li>
-  <li>Proxy-Authorization</li>
-  <li>Proxy-Connection</li>
-  <li>Transfer-Encoding</li>
-</ul>
-</p>
-
-<h2 id="concepts">Concepts of the webRequest API</h2>
-
-<p>The signals of the webRequest API follow certain concepts and patterns that
-shall be described in the following.</p>
-
-<h3 id="Request IDs">Request IDs</h3>
-
-<p>Each request is identified by a request ID. This ID is unique within a
-browser session and the context of an extension. It remains constant during the
-the life-cycle of a request and can be used to match signals for the same
-request. Note that several HTTP requests are mapped to one webRequest in case of
-HTTP redirection or HTTP authentication.</p>
-
-<h3 id="subscription">Subscription</h3>
-
-<p>For each signal XXX of the webRequest API, the API provides a function
-<code>chrome.experimental.webRequest.XXX.addListener()</code> with the following
-signature.</p>
-
-<pre>
-var callback = function(details) {...};
-var opt_filter = {...};
-var opt_extraInfoSpec = [...];
-
-chrome.experimental.webRequest.XXX.addListener(
-  callback, opt_filter, opt_extraInfoSpec);
-</pre>
-
-<p>Each <code>addListener()</code> call takes a mandatory callback function as
-the first parameter. This callback function is passed a dictionary containing
-information about the current URL request. The information in this dictionary
-depends on the specific event type as well as the content of
-<code>opt_extraInfoSpec</code>.</p>
-
-<p>If the optional <code>opt_extraInfoSpec</code> array contains the string
-<code>'blocking'</code> (only allowed for specific signals), the callback
-function is handled synchronously. That means that the request is blocked until
-the callback function returns. In this case, the callback can return a <a
-  href="#type-BlockingResponse">BlockingResponse</a> that determines the further
-life-cycle of the request. Depending on the context, this response allows
-cancelling or redirecting a request (onBeforeRequest), cancelling or
-modifying headers (onBeforeSendHeaders, onHeadersReceived), or providing
-authentication credentials (onAuthRequired).</p>
-
-<p>Depending on the specific signal, <code>opt_extraInfoSpec</code> may contain
-further strings that indicate that specific information shall be passed to the
-extension. This is used to provide detailed information on requests data only if
-explicitly requested.</p>
-
-<p>The optional <a href="#type-RequestFilter">RequestFilter</a>
-<code>opt_filter</code> allows to limit the requests for which events are
-triggered in various dimensions:
-<dl>
-  <dt>URLs</dt>
-  <dd>URL patterns like <code>*://www.google.com/foo*bar</code>.</dd>
-  <dt>Types</dt>
-  <dd>Request types like <code>main_frame</code> (a document that is loaded for
-  a top-level frame), <code>sub_frame</code> (a document that is loaded for an
-  embedded frame), <code>image</code> (an image on a web site) and others. See
-  <a href="#type-RequestFilter">RequestFilter</a>.</dd>
-  <dt>Tab IDs</dt>
-  <dd>The ID that identifies a specific tab in a window.</dd>
-  <dt>Window IDs</dt>
-  <dd>The ID that identifies a specific window.</dd>
-</p>
-
-<h2 id="conflict_resolution">Conflict resolution</h2>
-
-<p>In the current implementation of the webRequest API, a request is considered
-as canceled if at least one extension instructs to cancel the request. If
-an extension cancels a request, all extensions are notified by an
-onErrorOccurred event. Only one extension is allowed to redirect a request or
-modify a header at a time. If more than one extension attempts to modify the
-request, the most recently installed extension wins while all others are
-ignored. An extension is currently not notified, if its instruction to modify or
-redirect has been ignored.</p>
-
-<h2>A note about caching</h2>
-<p>
-Chrome employs two caches, an on-disk cache and a very fast in-memory cache.
-The life-time of an in-memory cache is attached to the life-time of a render
-process which roughly corresponds to a tab. Requests that are answered from the
-in-memory cache are invisible to the webRequest API. If a request handler
-changes its behavior (for example the behavior according to which requests are
-blocked), a simple page refresh might not respect this changed behavior.
-<code>chrome.experimental.webRequest.handlerBehaviorChanged()</code> needs to be
-called to flush the in-memory cache. This is a very expensive operation and
-should not be done often.
-</p>
-
-<h2>A note about timestamps</h2>
-<p>
-It's important to note that some technical oddities in the OS's handling
-of distinct Chrome processes can cause the clock to be skewed between the
-browser itself and extension processes. That means that WebRequest's events'
-<code>timeStamp</code> property is only guaranteed to be <i>internally</i>
-consistent. Comparing one event to another event will give you the correct
-offset between them, but comparing them to the current time inside the
-extension (via <code>(new Date()).getTime()</code>, for instance) might give
-unexpected results.
-</p>
-
-<h2 id="examples">Examples</h2>
-
-<p>The following example illustrates how to block all requests to
-<code>www.evil.com</code>:</p>
-<pre>
-chrome.experimental.webRequest.onBeforeRequest.addListener(
-  function(details) {
-    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
-  },
-  {},
-  ["blocking"]);
-</pre>
-
-<p>The following example achives the same goal in a more efficient way because
-requests that are not targeted to <code>www.evil.com</code> do not need to be
-passed to the extension:</p>
-<pre>
-chrome.experimental.webRequest.onBeforeRequest.addListener(
-  function(details) { return {cancel: true}; },
-  {urls: ["*://www.evil.com/*"]},
-  ["blocking"]);
-</pre>
-
-<p>The following example illustrates how the User-Agent header can be deleted
-from all requests:</p>
-<pre>
-chrome.experimental.webRequest.onBeforeSendHeaders.addListener(
-  function(details) {
-    delete details.requestHeaders['User-Agent'];
-    return {requestHeaders: details.requestHeaders};
-  },
-  {},
-  ["blocking"]);
-</pre>
-
-<!--
-TODO(mkwst): update this section. We do not pass windowIds any more.
-http://crbug.com/98937
-
-<h3 id="tracking_frames">Tracking frames</h3>
-<p>For efficiency reason, the webRequest API does not pass the URL of the frame
-that issued a request to each request. If this information is required, for
-example to distinguish between first and third party requests, this example
-shows how to track the URLs of frames.</p>
-<pre>
-// dictionary "windowId" -> "tabId"-"frameId" -> "frameUrl"
-var frameUrl = {};
-
-function recordFrameUrl(windowId, tabId, frameId, frameUrl) {
-  if (!frameUrl[windowId]) {
-    frameUrl[windowId] = {};
-  }
-  frameUrl[windowId][tabId + "-" + frameId] = frameUrl;
-}
-
-function getFrameUrl(windowId, tabId, frameId, frameUrl) {
-  return (frameUrl[windowId] || {})[tabId + "-" + frameId];
-}
-
-chrome.experimental.webRequest.onBeforeRequest.addListener(
-  function(d) {
-    if (d.type == 'main_frame' || d.type == 'sub_frame') {
-      recordFrameUrl(d.windowId, d.tabId, d.frameId, d.frameUrl);
-    }
-    var frameUrl = getFrameUrl(d.windowId, d.tabId, d.frameId);
-    // Use the frameUrl e.g. to selectively cancel requests.
-    // Attention: The frameUrl can be undefined in some cases. Requests may not
-    // originate from a frame (e.g. requests from extensions or shared workers).
-  });
-
-chrome.windows.onRemoved.addListener(
-  function(windowId) {delete frameUrl[windowId];}
-  );
-</pre>
--->
-<!-- END AUTHORED CONTENT -->