mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: Improve the webRequets docs

Browse source
This commit is contained in:
Cheng Zhao 2015-12-11 19:02:56 +08:00
parent 98ba1a24db
commit b7fce578d5
1 changed files with 143 additions and 123 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

194
docs/api/session.md
View file

@ -12,7 +12,7 @@ const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600 }); var win = new BrowserWindow({ width: 800, height: 600 });
win.loadURL("http://github.com"); win.loadURL("http://github.com");
var ses = win.webContents.session var ses = win.webContents.session;
``` ```
## Methods ## Methods
@ -289,88 +289,107 @@ myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, c
#### `ses.webRequest` #### `ses.webRequest`
The `webRequest` api allows to intercept and modify contents of a request at various The `webRequest` API set allows to intercept and modify contents of a request at
stages of its lifetime. various stages of its lifetime.
Each API accepts an optional `filter` and a `listener`, the `listener` will be
called with `listener(details)` when the API's event has happened, the `details`
is an object that describes the request. Passing `null` as `listener` will
unsubscribe from the event.
The `filter` is an object that has an `urls` property, which is an Array of URL
patterns that will be used to filter out the requests that do not match the URL
patterns. If the `filter` is omitted then all requests will be matched.
For certain events the `listener` is required to return an object that describes
how to handle the request, users can specify the `cancel` property to `true` to
cancel the request.
```javascript ```javascript
// Modify the user agent for all requests to the following urls. // Modify the user agent for all requests to the following urls.
var filter = { var filter = {
urls: ["https://*.github.com/*", "*://electron.github.io"] urls: ["https://*.github.com/*", "*://electron.github.io"]
} };
myWindow.webContents.session.webRequest.onBeforeSendHeaders(filter, function(details) { session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details) {
details.requestHeaders['User-Agent'] = "MyAgent"; details.requestHeaders['User-Agent'] = "MyAgent";
return {cancel: false, requestHeaders: details.requestHeaders}; return {cancel: false, requestHeaders: details.requestHeaders};
}) });
``` ```
#### `ses.webRequest.onBeforeRequest([filter,] listener)` #### `ses.webRequest.onBeforeRequest([filter, ]listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when a request is about
to occur.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `blockingResponse` Object
* `cancel` Boolean - Whether to continue or block the request.
* `redirectURL` String **optional** - The original request is prevented from being sent or
completed, and is instead redirected to the given URL.
Fired when a request is about to occur. Should return a `blockingResponse`. The `listener` has to return an `response` object:
#### `ses.webRequest.onBeforeSendHeaders([filter,] listener)` * `response` Object
* `cancel` Boolean
* `redirectURL` String __optional__ - The original request is prevented from
being sent or completed, and is instead redirected to the given URL.
#### `ses.webRequest.onBeforeSendHeaders([filter, ]listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id.
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
* `blockingResponse` Object
* `cancel` Boolean - Whether to continue or block the request.
* `requestHeaders` Object **optional** - When provided, request will be made with these
headers.
Fired before sending an HTTP request, once the request headers are available. This may The `listener` will be called with `listener(details)` before sending an HTTP
occur after a TCP connection is made to the server, but before any http data is sent. request, once the request headers are available. This may occur after a TCP
Should return a `blockingResponse`. connection is made to the server, but before any http data is sent.
#### `ses.webRequest.onSendHeaders([filter,] listener)` * `details` Object
* `id` String - Request ID.
* `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function
* `details` Object
* `id` String - Request id.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `requestHeaders` Object * `requestHeaders` Object
Fired just before a request is going to be sent to the server, modifications of previous The `listener` has to return an `response` object:
`onBeforeSendHeaders` response are visible by the time this listener is fired.
* `response` Object
* `cancel` Boolean
* `requestHeaders` Object __optional__ - When provided, request will be made
with these headers.
#### `ses.webRequest.onSendHeaders([filter, ]listener)`
* `filter` Object
* `listener` Function
The `listener` will be called with `listener(details)` just before a request is
going to be sent to the server, modifications of previous `onBeforeSendHeaders`
response are visible by the time this listener is fired.
* `details` Object
* `id` String - Request ID.
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
#### `ses.webRequest.onHeadersReceived([filter,] listener)` #### `ses.webRequest.onHeadersReceived([filter,] listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when HTTP response
headers of a request have been received.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
@ -378,86 +397,87 @@ Fired just before a request is going to be sent to the server, modifications of
* `statusLine` String * `statusLine` String
* `statusCode` Integer * `statusCode` Integer
* `responseHeaders` Object * `responseHeaders` Object
* `blockingResponse` Object
* `cancel` Boolean - Whether to continue or block the request.
* `responseHeaders` Object **optional** - When provided, the server is assumed to have
responded with these headers.
Fired when HTTP response headers of a request have been received. Should return a The `listener` has to return an `response` object:
`blockingResponse`.
#### `ses.webRequest.onResponseStarted([filter,] listener)` * `response` Object
* `cancel` Boolean
* `responseHeaders` Object __optional__ - When provided, the server is assumed
to have responded with these headers.
#### `ses.webRequest.onResponseStarted([filter, ]listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when first byte of the
response body is received. For HTTP requests, this means that the status line
and response headers are available.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `responseHeaders` Object * `responseHeaders` Object
* `fromCache` Boolean * `fromCache` Boolean - Indicates whether the response was fetched from disk
cache.
* `statusCode` Integer * `statusCode` Integer
* `statusLine` String * `statusLine` String
Fired when first byte of the response body is received. For HTTP requests, this means that the #### `ses.webRequest.onBeforeRedirect([filter, ]listener)`
status line and response headers are available.
#### `ses.webRequest.onBeforeRedirect([filter,] listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when a server initiated
redirect is about to occur.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `redirectURL` String * `redirectURL` String
* `statusCode` Integer * `statusCode` Integer
* `ip` String **optional** - The server IP address that the request was actually sent to. * `ip` String __optional__ - The server IP address that the request was
actually sent to.
* `fromCache` Boolean * `fromCache` Boolean
* `responseHeaders` Object * `responseHeaders` Object
Fired when a server initiated redirect is about to occur. #### `ses.webRequest.onCompleted([filter, ]listener)`
#### `ses.webRequest.onCompleted([filter,] listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when a request is
completed.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `responseHeaders` Object * `responseHeaders` Object
* `fromCache` Boolean - Indicates whether the response was fetched from disk cache. * `fromCache` Boolean
* `statusCode` Integer * `statusCode` Integer
* `statusLine` String * `statusLine` String
Fired when a request is completed. #### `ses.webRequest.onErrorOccurred([filter, ]listener)`
#### `ses.webRequest.onErrorOccurred([filter,] listener)`
* `filter` Object * `filter` Object
* `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs
will be filtered out.
* `listener` Function * `listener` Function
* `details` Object
* `id` String - Request id. The `listener` will be called with `listener(details)` when an error occurs.
* `details` Object
* `id` String - Request ID.
* `url` String * `url` String
* `method` String * `method` String
* `resourceType` String * `resourceType` String
* `timestamp` Double * `timestamp` Double
* `fromCache` Boolean - Indicates whether the response was fetched from disk cache. * `fromCache` Boolean
* `error` String - The error description. * `error` String - The error description.
Fired when an error occurs.