2015-08-20 13:17:53 +00:00
|
|
|
|
# session
|
|
|
|
|
|
2016-04-21 22:35:29 +00:00
|
|
|
|
Manage browser cookies, cache, and other session data.
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
The `session` module can be used to create new `Session` objects.
|
|
|
|
|
|
|
|
|
|
You can also access the `session` of existing pages by using the `session`
|
|
|
|
|
property of [`webContents`](web-contents.md) which is a property of
|
|
|
|
|
[`BrowserWindow`](browser-window.md).
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
|
|
|
|
```javascript
|
2015-11-12 13:20:09 +00:00
|
|
|
|
const BrowserWindow = require('electron').BrowserWindow;
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-08-20 17:03:53 +00:00
|
|
|
|
var win = new BrowserWindow({ width: 800, height: 600 });
|
2015-11-13 08:03:40 +00:00
|
|
|
|
win.loadURL("http://github.com");
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
var ses = win.webContents.session;
|
2015-11-19 13:31:39 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Methods
|
|
|
|
|
|
|
|
|
|
The `session` module has the following methods:
|
|
|
|
|
|
|
|
|
|
### session.fromPartition(partition)
|
|
|
|
|
|
|
|
|
|
* `partition` String
|
|
|
|
|
|
|
|
|
|
Returns a new `Session` instance from `partition` string.
|
|
|
|
|
|
|
|
|
|
If `partition` starts with `persist:`, the page will use a persistent session
|
|
|
|
|
available to all pages in the app with the same `partition`. if there is no
|
|
|
|
|
`persist:` prefix, the page will use an in-memory session. If the `partition` is
|
|
|
|
|
empty then default session of the app will be returned.
|
|
|
|
|
|
|
|
|
|
## Properties
|
|
|
|
|
|
|
|
|
|
The `session` module has the following properties:
|
|
|
|
|
|
|
|
|
|
### session.defaultSession
|
|
|
|
|
|
|
|
|
|
Returns the default session object of the app.
|
|
|
|
|
|
|
|
|
|
## Class: Session
|
|
|
|
|
|
|
|
|
|
You can create a `Session` object in the `session` module:
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
const session = require('electron').session;
|
|
|
|
|
|
|
|
|
|
var ses = session.fromPartition('persist:name');
|
2015-08-20 13:17:53 +00:00
|
|
|
|
```
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
### Instance Events
|
2015-09-01 10:02:14 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
The following events are available on instances of `Session`:
|
|
|
|
|
|
|
|
|
|
#### Event: 'will-download'
|
2015-09-01 10:02:14 +00:00
|
|
|
|
|
|
|
|
|
* `event` Event
|
2015-09-20 11:08:31 +00:00
|
|
|
|
* `item` [DownloadItem](download-item.md)
|
2015-09-01 12:16:28 +00:00
|
|
|
|
* `webContents` [WebContents](web-contents.md)
|
2015-09-01 10:02:14 +00:00
|
|
|
|
|
2015-11-17 13:36:36 +00:00
|
|
|
|
Emitted when Electron is about to download `item` in `webContents`.
|
2015-09-01 12:16:28 +00:00
|
|
|
|
|
2016-02-02 10:24:51 +00:00
|
|
|
|
Calling `event.preventDefault()` will cancel the download and `item` will not be
|
|
|
|
|
available from next tick of the process.
|
2015-09-01 10:02:14 +00:00
|
|
|
|
|
|
|
|
|
```javascript
|
2015-12-12 07:41:04 +00:00
|
|
|
|
session.defaultSession.on('will-download', function(event, item, webContents) {
|
2015-09-01 12:16:28 +00:00
|
|
|
|
event.preventDefault();
|
2015-11-13 08:03:40 +00:00
|
|
|
|
require('request')(item.getURL(), function(data) {
|
2015-09-01 10:02:14 +00:00
|
|
|
|
require('fs').writeFileSync('/somewhere', data);
|
|
|
|
|
});
|
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
### Instance Methods
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
The following methods are available on instances of `Session`:
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.cookies`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-08-20 17:03:53 +00:00
|
|
|
|
The `cookies` gives you ability to query and modify cookies. For example:
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
|
|
|
|
```javascript
|
2015-12-12 07:41:04 +00:00
|
|
|
|
// Query all cookies.
|
|
|
|
|
session.defaultSession.cookies.get({}, function(error, cookies) {
|
|
|
|
|
console.log(cookies);
|
|
|
|
|
});
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
// Query all cookies associated with a specific url.
|
|
|
|
|
session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
|
|
|
|
|
console.log(cookies);
|
|
|
|
|
});
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
// Set a cookie with the given cookie data;
|
|
|
|
|
// may overwrite equivalent cookies if they exist.
|
|
|
|
|
var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
|
|
|
|
|
session.defaultSession.cookies.set(cookie, function(error) {
|
|
|
|
|
if (error)
|
|
|
|
|
console.error(error);
|
|
|
|
|
});
|
|
|
|
|
```
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
#### `ses.cookies.get(filter, callback)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `filter` Object
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `url` String (optional) - Retrieves cookies which are associated with
|
2015-12-12 07:41:04 +00:00
|
|
|
|
`url`. Empty implies retrieving cookies of all urls.
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `name` String (optional) - Filters cookies by name.
|
|
|
|
|
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
2015-12-12 07:41:04 +00:00
|
|
|
|
subdomains of `domains`
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `path` String (optional) - Retrieves cookies whose path matches `path`.
|
|
|
|
|
* `secure` Boolean (optional) - Filters cookies by their Secure property.
|
|
|
|
|
* `session` Boolean (optional) - Filters out session or persistent cookies.
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `callback` Function
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
Sends a request to get all cookies matching `details`, `callback` will be called
|
|
|
|
|
with `callback(error, cookies)` on complete.
|
|
|
|
|
|
|
|
|
|
`cookies` is an Array of `cookie` objects.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `cookie` Object
|
2015-08-20 13:17:53 +00:00
|
|
|
|
* `name` String - The name of the cookie.
|
|
|
|
|
* `value` String - The value of the cookie.
|
|
|
|
|
* `domain` String - The domain of the cookie.
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `hostOnly` String - Whether the cookie is a host-only cookie.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
* `path` String - The path of the cookie.
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `secure` Boolean - Whether the cookie is marked as secure.
|
|
|
|
|
* `httpOnly` Boolean - Whether the cookie is marked as HTTP only.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
* `session` Boolean - Whether the cookie is a session cookie or a persistent
|
|
|
|
|
cookie with an expiration date.
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `expirationDate` Double (optional) - The expiration date of the cookie as
|
2015-08-24 22:41:02 +00:00
|
|
|
|
the number of seconds since the UNIX epoch. Not provided for session
|
|
|
|
|
cookies.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.cookies.set(details, callback)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
* `details` Object
|
2015-12-12 07:41:04 +00:00
|
|
|
|
* `url` String - Retrieves cookies which are associated with `url`
|
|
|
|
|
* `name` String - The name of the cookie. Empty by default if omitted.
|
|
|
|
|
* `value` String - The value of the cookie. Empty by default if omitted.
|
|
|
|
|
* `domain` String - The domain of the cookie. Empty by default if omitted.
|
|
|
|
|
* `path` String - The path of the cookie. Empty by default if omitted.
|
|
|
|
|
* `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
|
|
|
|
|
false.
|
|
|
|
|
* `session` Boolean - Whether the cookie should be marked as HttpOnly. Defaults
|
|
|
|
|
to false.
|
|
|
|
|
* `expirationDate` Double - The expiration date of the cookie as the number of
|
|
|
|
|
seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie.
|
|
|
|
|
* `callback` Function
|
|
|
|
|
|
|
|
|
|
Sets the cookie with `details`, `callback` will be called with `callback(error)`
|
|
|
|
|
on complete.
|
|
|
|
|
|
|
|
|
|
#### `ses.cookies.remove(url, name, callback)`
|
|
|
|
|
|
|
|
|
|
* `url` String - The URL associated with the cookie.
|
|
|
|
|
* `name` String - The name of cookie to remove.
|
|
|
|
|
* `callback` Function
|
|
|
|
|
|
|
|
|
|
Removes the cookies matching `url` and `name`, `callback` will called with
|
|
|
|
|
`callback()` on complete.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2016-01-14 09:31:54 +00:00
|
|
|
|
#### `ses.getCacheSize(callback)`
|
|
|
|
|
|
|
|
|
|
* `callback` Function
|
|
|
|
|
* `size` Integer - Cache size used in bytes.
|
|
|
|
|
|
|
|
|
|
Returns the session's current cache size.
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.clearCache(callback)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
|
|
|
|
* `callback` Function - Called when operation is done
|
|
|
|
|
|
|
|
|
|
Clears the session’s HTTP cache.
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.clearStorageData([options, ]callback)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
* `options` Object (optional)
|
2015-08-20 13:17:53 +00:00
|
|
|
|
* `origin` String - Should follow `window.location.origin`’s representation
|
2015-08-26 20:57:42 +00:00
|
|
|
|
`scheme://host:port`.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
* `storages` Array - The types of storages to clear, can contain:
|
|
|
|
|
`appcache`, `cookies`, `filesystem`, `indexdb`, `local storage`,
|
|
|
|
|
`shadercache`, `websql`, `serviceworkers`
|
|
|
|
|
* `quotas` Array - The types of quotas to clear, can contain:
|
2015-08-26 20:57:42 +00:00
|
|
|
|
`temporary`, `persistent`, `syncable`.
|
|
|
|
|
* `callback` Function - Called when operation is done.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
|
|
|
|
Clears the data of web storages.
|
|
|
|
|
|
2016-01-12 15:28:12 +00:00
|
|
|
|
#### `ses.flushStorageData()`
|
|
|
|
|
|
|
|
|
|
Writes any unwritten DOMStorage data to disk.
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.setProxy(config, callback)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2016-01-10 22:25:56 +00:00
|
|
|
|
* `config` Object
|
|
|
|
|
* `pacScript` String - The URL associated with the PAC file.
|
|
|
|
|
* `proxyRules` String - Rules indicating which proxies to use.
|
2015-08-26 20:57:42 +00:00
|
|
|
|
* `callback` Function - Called when operation is done.
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
2016-01-11 14:45:34 +00:00
|
|
|
|
Sets the proxy settings.
|
|
|
|
|
|
2016-01-11 06:54:01 +00:00
|
|
|
|
When `pacScript` and `proxyRules` are provided together, the `proxyRules`
|
|
|
|
|
option is ignored and `pacScript` configuration is applied.
|
|
|
|
|
|
2016-01-11 14:45:34 +00:00
|
|
|
|
The `proxyRules` has to follow the rules bellow:
|
|
|
|
|
|
2015-08-20 13:17:53 +00:00
|
|
|
|
```
|
2016-01-11 14:45:34 +00:00
|
|
|
|
proxyRules = schemeProxies[";"<schemeProxies>]
|
|
|
|
|
schemeProxies = [<urlScheme>"="]<proxyURIList>
|
|
|
|
|
urlScheme = "http" | "https" | "ftp" | "socks"
|
|
|
|
|
proxyURIList = <proxyURL>[","<proxyURIList>]
|
|
|
|
|
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]
|
2015-08-20 13:17:53 +00:00
|
|
|
|
```
|
|
|
|
|
|
2016-01-11 14:45:34 +00:00
|
|
|
|
For example:
|
2016-01-29 19:10:18 +00:00
|
|
|
|
|
2016-01-11 14:45:34 +00:00
|
|
|
|
* `http=foopy:80;ftp=foopy2` - Use HTTP proxy `foopy:80` for `http://` URLs, and
|
|
|
|
|
HTTP proxy `foopy2:80` for `ftp://` URLs.
|
|
|
|
|
* `foopy:80` - Use HTTP proxy `foopy:80` for all URLs.
|
|
|
|
|
* `foopy:80,bar,direct://` - Use HTTP proxy `foopy:80` for all URLs, failing
|
|
|
|
|
over to `bar` if `foopy:80` is unavailable, and after that using no proxy.
|
|
|
|
|
* `socks4://foopy` - Use SOCKS v4 proxy `foopy:1080` for all URLs.
|
|
|
|
|
* `http=foopy,socks5://bar.com` - Use HTTP proxy `foopy` for http URLs, and fail
|
|
|
|
|
over to the SOCKS5 proxy `bar.com` if `foopy` is unavailable.
|
|
|
|
|
* `http=foopy,direct://` - Use HTTP proxy `foopy` for http URLs, and use no
|
|
|
|
|
proxy if `foopy` is unavailable.
|
|
|
|
|
* `http=foopy;socks=foopy2` - Use HTTP proxy `foopy` for http URLs, and use
|
|
|
|
|
`socks4://foopy2` for all other URLs.
|
|
|
|
|
|
2015-11-19 13:32:46 +00:00
|
|
|
|
### `ses.resolveProxy(url, callback)`
|
|
|
|
|
|
|
|
|
|
* `url` URL
|
|
|
|
|
* `callback` Function
|
|
|
|
|
|
|
|
|
|
Resolves the proxy information for `url`. The `callback` will be called with
|
|
|
|
|
`callback(proxy)` when the request is performed.
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.setDownloadPath(path)`
|
2015-08-20 13:17:53 +00:00
|
|
|
|
|
|
|
|
|
* `path` String - The download location
|
|
|
|
|
|
|
|
|
|
Sets download saving directory. By default, the download directory will be the
|
|
|
|
|
`Downloads` under the respective app folder.
|
2015-09-27 13:19:52 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.enableNetworkEmulation(options)`
|
2015-09-27 13:19:52 +00:00
|
|
|
|
|
|
|
|
|
* `options` Object
|
|
|
|
|
* `offline` Boolean - Whether to emulate network outage.
|
|
|
|
|
* `latency` Double - RTT in ms
|
|
|
|
|
* `downloadThroughput` Double - Download rate in Bps
|
|
|
|
|
* `uploadThroughput` Double - Upload rate in Bps
|
|
|
|
|
|
|
|
|
|
Emulates network with the given configuration for the `session`.
|
|
|
|
|
|
2015-09-28 07:22:50 +00:00
|
|
|
|
```javascript
|
|
|
|
|
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
|
|
|
|
|
window.webContents.session.enableNetworkEmulation({
|
|
|
|
|
latency: 500,
|
|
|
|
|
downloadThroughput: 6400,
|
|
|
|
|
uploadThroughput: 6400
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// To emulate a network outage.
|
|
|
|
|
window.webContents.session.enableNetworkEmulation({offline: true});
|
|
|
|
|
```
|
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.disableNetworkEmulation()`
|
2015-09-27 13:19:52 +00:00
|
|
|
|
|
|
|
|
|
Disables any network emulation already active for the `session`. Resets to
|
|
|
|
|
the original network configuration.
|
2015-11-18 03:35:26 +00:00
|
|
|
|
|
2015-11-19 13:31:39 +00:00
|
|
|
|
#### `ses.setCertificateVerifyProc(proc)`
|
2015-11-18 03:35:26 +00:00
|
|
|
|
|
|
|
|
|
* `proc` Function
|
|
|
|
|
|
|
|
|
|
Sets the certificate verify proc for `session`, the `proc` will be called with
|
|
|
|
|
`proc(hostname, certificate, callback)` whenever a server certificate
|
|
|
|
|
verification is requested. Calling `callback(true)` accepts the certificate,
|
|
|
|
|
calling `callback(false)` rejects it.
|
|
|
|
|
|
|
|
|
|
Calling `setCertificateVerifyProc(null)` will revert back to default certificate
|
|
|
|
|
verify proc.
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) {
|
|
|
|
|
if (hostname == 'github.com')
|
|
|
|
|
callback(true);
|
|
|
|
|
else
|
|
|
|
|
callback(false);
|
|
|
|
|
});
|
|
|
|
|
```
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
2016-01-31 21:35:34 +00:00
|
|
|
|
#### `ses.setPermissionRequestHandler(handler)`
|
|
|
|
|
|
|
|
|
|
* `handler` Function
|
|
|
|
|
* `webContents` Object - [WebContents](web-contents.md) requesting the permission.
|
2016-04-22 14:23:15 +00:00
|
|
|
|
* `permission` String - Enum of 'media', 'geolocation', 'notifications', 'midiSysex',
|
2016-04-20 16:55:15 +00:00
|
|
|
|
'pointerLock', 'fullscreen', 'openExternal'.
|
2016-04-22 14:23:15 +00:00
|
|
|
|
* `callback` Function - Allow or deny the permission.
|
2016-01-31 21:35:34 +00:00
|
|
|
|
|
|
|
|
|
Sets the handler which can be used to respond to permission requests for the `session`.
|
2016-02-01 10:03:38 +00:00
|
|
|
|
Calling `callback(true)` will allow the permission and `callback(false)` will reject it.
|
2016-01-31 21:35:34 +00:00
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
session.fromPartition(partition).setPermissionRequestHandler(function(webContents, permission, callback) {
|
|
|
|
|
if (webContents.getURL() === host) {
|
|
|
|
|
if (permission == "notifications") {
|
2016-02-01 10:03:38 +00:00
|
|
|
|
callback(false); // denied.
|
2016-01-31 21:35:34 +00:00
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2016-02-01 10:03:38 +00:00
|
|
|
|
callback(true);
|
2016-01-31 21:35:34 +00:00
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
2016-02-01 13:33:23 +00:00
|
|
|
|
#### `ses.clearHostResolverCache([callback])`
|
|
|
|
|
|
|
|
|
|
* `callback` Function (optional) - Called when operation is done.
|
|
|
|
|
|
|
|
|
|
Clears the host resolver cache.
|
|
|
|
|
|
2015-12-04 00:03:56 +00:00
|
|
|
|
#### `ses.webRequest`
|
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
The `webRequest` API set allows to intercept and modify contents of a request at
|
|
|
|
|
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.
|
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
For certain events the `listener` is passed with a `callback`, which should be
|
|
|
|
|
called with an `response` object when `listener` has done its work.
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
// Modify the user agent for all requests to the following urls.
|
|
|
|
|
var filter = {
|
|
|
|
|
urls: ["https://*.github.com/*", "*://electron.github.io"]
|
2015-12-11 11:02:56 +00:00
|
|
|
|
};
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) {
|
2015-12-04 00:03:56 +00:00
|
|
|
|
details.requestHeaders['User-Agent'] = "MyAgent";
|
2015-12-12 07:45:02 +00:00
|
|
|
|
callback({cancel: false, requestHeaders: details.requestHeaders});
|
2015-12-11 11:02:56 +00:00
|
|
|
|
});
|
2015-12-04 00:03:56 +00:00
|
|
|
|
```
|
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
#### `ses.webRequest.onBeforeRequest([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `listener` will be called with `listener(details, callback)` when a request
|
|
|
|
|
is about to occur.
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
2016-01-26 08:28:21 +00:00
|
|
|
|
* `uploadData` Array (optional)
|
2016-01-28 10:59:07 +00:00
|
|
|
|
* `callback` Function
|
|
|
|
|
|
|
|
|
|
The `uploadData` is an array of `data` objects:
|
|
|
|
|
|
|
|
|
|
* `data` Object
|
|
|
|
|
* `bytes` Buffer - Content being sent.
|
|
|
|
|
* `file` String - Path of file being uploaded.
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `callback` has to be called with an `response` object:
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `response` Object
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `cancel` Boolean (optional)
|
|
|
|
|
* `redirectURL` String (optional) - The original request is prevented from
|
2015-12-11 11:02:56 +00:00
|
|
|
|
being sent or completed, and is instead redirected to the given URL.
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
#### `ses.webRequest.onBeforeSendHeaders([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `listener` will be called with `listener(details, callback)` before sending
|
|
|
|
|
an HTTP request, once the request headers are available. This may occur after a
|
|
|
|
|
TCP connection is made to the server, but before any http data is sent.
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `requestHeaders` Object
|
2016-01-28 10:59:07 +00:00
|
|
|
|
* `callback` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `callback` has to be called with an `response` object:
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `response` Object
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `cancel` Boolean (optional)
|
|
|
|
|
* `requestHeaders` Object (optional) - When provided, request will be made
|
2015-12-11 11:02:56 +00:00
|
|
|
|
with these headers.
|
|
|
|
|
|
|
|
|
|
#### `ses.webRequest.onSendHeaders([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
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
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `requestHeaders` Object
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
2016-04-22 14:26:19 +00:00
|
|
|
|
#### `ses.webRequest.onHeadersReceived([filter,]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `listener` will be called with `listener(details, callback)` when HTTP
|
|
|
|
|
response headers of a request have been received.
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` String
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `statusLine` String
|
|
|
|
|
* `statusCode` Integer
|
|
|
|
|
* `responseHeaders` Object
|
2016-01-28 10:59:07 +00:00
|
|
|
|
* `callback` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
2015-12-12 07:45:02 +00:00
|
|
|
|
The `callback` has to be called with an `response` object:
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
* `response` Object
|
|
|
|
|
* `cancel` Boolean
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `responseHeaders` Object (optional) - When provided, the server is assumed
|
2015-12-11 11:02:56 +00:00
|
|
|
|
to have responded with these headers.
|
2016-04-22 13:53:26 +00:00
|
|
|
|
* `statusLine` String (optional) - Should be provided when overriding
|
|
|
|
|
`responseHeaders` to change header status otherwise original response
|
|
|
|
|
header's status will be used.
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
#### `ses.webRequest.onResponseStarted([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
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
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `responseHeaders` Object
|
2016-04-22 14:30:16 +00:00
|
|
|
|
* `fromCache` Boolean - Indicates whether the response was fetched from disk
|
2015-12-11 11:02:56 +00:00
|
|
|
|
cache.
|
|
|
|
|
* `statusCode` Integer
|
|
|
|
|
* `statusLine` String
|
|
|
|
|
|
|
|
|
|
#### `ses.webRequest.onBeforeRedirect([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
The `listener` will be called with `listener(details)` when a server initiated
|
|
|
|
|
redirect is about to occur.
|
|
|
|
|
|
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` String
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `redirectURL` String
|
|
|
|
|
* `statusCode` Integer
|
2015-12-18 03:07:32 +00:00
|
|
|
|
* `ip` String (optional) - The server IP address that the request was
|
2015-12-11 11:02:56 +00:00
|
|
|
|
actually sent to.
|
|
|
|
|
* `fromCache` Boolean
|
|
|
|
|
* `responseHeaders` Object
|
|
|
|
|
|
|
|
|
|
#### `ses.webRequest.onCompleted([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
The `listener` will be called with `listener(details)` when a request is
|
|
|
|
|
completed.
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `responseHeaders` Object
|
|
|
|
|
* `fromCache` Boolean
|
|
|
|
|
* `statusCode` Integer
|
|
|
|
|
* `statusLine` String
|
|
|
|
|
|
|
|
|
|
#### `ses.webRequest.onErrorOccurred([filter, ]listener)`
|
2015-12-04 00:03:56 +00:00
|
|
|
|
|
|
|
|
|
* `filter` Object
|
|
|
|
|
* `listener` Function
|
2015-12-11 11:02:56 +00:00
|
|
|
|
|
|
|
|
|
The `listener` will be called with `listener(details)` when an error occurs.
|
|
|
|
|
|
|
|
|
|
* `details` Object
|
2015-12-12 03:31:19 +00:00
|
|
|
|
* `id` Integer
|
2015-12-11 11:02:56 +00:00
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `resourceType` String
|
|
|
|
|
* `timestamp` Double
|
|
|
|
|
* `fromCache` Boolean
|
|
|
|
|
* `error` String - The error description.
|