webRequest
==========

为发出的 HTTP 请求在不同阶段添加事件监听器。事件监听器可以接收到请求的详细信息，也可以修改或取消请求。概况
--

每个事件都会在请求的特定阶段触发。事件的顺序大概是这样的：

在请求过程中的任意时间，`onErrorOccurred` (en-US) 可以被触发。虽然有时候触发的事件顺序不同，举个例子，在火狐浏览器中的 HSTS 过程，在 onBeforeRequest 事件执行后，onBeforeRedirect 事件会被立即触发。

所有的事件，接受 `onErrorOccurred` 事件，`addListener()` 有三个参数：

* 监听本身
* 一个 `filter` 对象，所以你仅可以被特定请求或特定的资源类型提醒
* 一个可选的`extraInfoSpec`对象。你可以使用这个对象添加特定的事件命令

这个监听函数接收一个`details`对象，这个对象包含这个请求的信息。他包含一个请求 ID, 在插件中这个 ID 可以关联唯一个请求事件。这个 ID 是浏览器会话和插件上下文中唯一的。他始终在同一个请求中，贯穿着转发和授权等事件中。

在一个给定的主机上使用 webRequest API, 你必须有这个主机的相关权限，包括"webRequest" API permission 和 host permission. 为了使用 "blocking" 特性，你必须有 "webRequestBlocking" API 权限。

这个 webRequest API 不能让你进入一些安全敏感的请求，比如update checks and OCSP checks.

### Modifying requests

在下边这些事件中，你可以修改请求。比如一些特别的操作：

* 取消请求：
    + `onBeforeRequest` (en-US)
    + `onBeforeSendHeaders` (en-US)
    + `onAuthRequired` (en-US)
* 重定向请求：
    + `onBeforeRequest` (en-US)
    + `onHeadersReceived` (en-US)
* 修改请求头：
    + `onBeforeSendHeaders` (en-US)
* 修改响应头：
    + `onHeadersReceived` (en-US)
* 加入认证功能：
    + `onAuthRequired` (en-US)

为了完成这些操作，你需要在`extraInfoSpec`参数中添加"blocking"的值到事件的`addListener()`。这将使得监听器变成同步执行。在监听器中，你可以返回一个表明需要作修改的`BlockingResponse` (en-US)对象：比如说，你想要发送的修改后的请求头。

从 Firefox 52 开始，监听器会返回一个`resolve(BlockingResponse)` 的 `Promise`，而不是直接返回一个`BlockingResponse`。这使得监听器可以异步地处理请求。

Types
-----

`webRequest.ResourceType` (en-US)

Represents a particular kind of resource fetched in a web request.

`webRequest.RequestFilter`

An object describing filters to apply to webRequest events.

`webRequest.HttpHeaders` (en-US)

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

`webRequest.BlockingResponse` (en-US)

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument. By setting particular properties in `BlockingResponse`, the listener can modify network requests.

`webRequest.UploadData` (en-US)

Contains data uploaded in a URL request.

Properties
----------

`webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES` (en-US)

The maximum number of times that `handlerBehaviorChanged()` (en-US) can be called in a 10 minute period.

Functions
---------

`webRequest.handlerBehaviorChanged()` (en-US)

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

Events
------

`webRequest.onBeforeRequest` (en-US)

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

`webRequest.onBeforeSendHeaders` (en-US)

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

`webRequest.onSendHeaders` (en-US)

Fired just before sending headers. If your add-on or some other add-on modified headers in ``onBeforeSendHeaders` (en-US)`, you'll see the modified version here.

`webRequest.onHeadersReceived` (en-US)

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

`webRequest.onAuthRequired` (en-US)

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

`webRequest.onResponseStarted` (en-US)

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect` (en-US)

Fired when a server-initiated redirect is about to occur.

`webRequest.onCompleted` (en-US)

Fired when a request is completed.

`webRequest.onErrorOccurred` (en-US)

Fired when an error occurs.

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.