Merge pull request #6174 from electron/session-docs-cleanup
docs: Separate Cookies and WebRequest classes in session.md
This commit is contained in:
Cheng Zhao
GitHub
commit
6cfd078d19
1 changed files with 154 additions and 129 deletions
|
|
@ -5,16 +5,15 @@
|
|||
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).
|
||||
property of [`WebContents`](web-contents.md), or from the `session` module.
|
||||
|
||||
```javascript
|
||||
const {BrowserWindow} = require('electron');
|
||||
const {session, BrowserWindow} = require('electron')
|
||||
|
||||
let win = new BrowserWindow({width: 800, height: 600});
|
||||
win.loadURL('http://github.com');
|
||||
let win = new BrowserWindow({width: 800, height: 600})
|
||||
win.loadURL('http://github.com')
|
||||
|
||||
const ses = win.webContents.session;
|
||||
const ses = win.webContents.session
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
|
@ -78,91 +77,6 @@ session.defaultSession.on('will-download', (event, item, webContents) => {
|
|||
|
||||
The following methods are available on instances of `Session`:
|
||||
|
||||
#### `ses.cookies`
|
||||
|
||||
The `cookies` gives you ability to query and modify cookies. For example:
|
||||
|
||||
```javascript
|
||||
// Query all cookies.
|
||||
session.defaultSession.cookies.get({}, (error, cookies) => {
|
||||
console.log(cookies);
|
||||
});
|
||||
|
||||
// Query all cookies associated with a specific url.
|
||||
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
|
||||
console.log(cookies);
|
||||
});
|
||||
|
||||
// Set a cookie with the given cookie data;
|
||||
// may overwrite equivalent cookies if they exist.
|
||||
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'};
|
||||
session.defaultSession.cookies.set(cookie, (error) => {
|
||||
if (error)
|
||||
console.error(error);
|
||||
});
|
||||
```
|
||||
|
||||
#### `ses.cookies.get(filter, callback)`
|
||||
|
||||
* `filter` Object
|
||||
* `url` String (optional) - Retrieves cookies which are associated with
|
||||
`url`. Empty implies retrieving cookies of all urls.
|
||||
* `name` String (optional) - Filters cookies by name.
|
||||
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
||||
subdomains of `domains`
|
||||
* `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.
|
||||
* `callback` Function
|
||||
|
||||
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.
|
||||
|
||||
* `cookie` Object
|
||||
* `name` String - The name of the cookie.
|
||||
* `value` String - The value of the cookie.
|
||||
* `domain` String - The domain of the cookie.
|
||||
* `hostOnly` String - Whether the cookie is a host-only cookie.
|
||||
* `path` String - The path of the cookie.
|
||||
* `secure` Boolean - Whether the cookie is marked as secure.
|
||||
* `httpOnly` Boolean - Whether the cookie is marked as HTTP only.
|
||||
* `session` Boolean - Whether the cookie is a session cookie or a persistent
|
||||
cookie with an expiration date.
|
||||
* `expirationDate` Double (optional) - The expiration date of the cookie as
|
||||
the number of seconds since the UNIX epoch. Not provided for session
|
||||
cookies.
|
||||
|
||||
#### `ses.cookies.set(details, callback)`
|
||||
|
||||
* `details` Object
|
||||
* `url` String - The url to associate the cookie with.
|
||||
* `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 HTTP only. Defaults
|
||||
to false.
|
||||
* `expirationDate` Double - The expiration date of the cookie as the number of
|
||||
seconds since the UNIX epoch. If omitted then the cookie becomes a session
|
||||
cookie and will not be retained between sessions.
|
||||
* `callback` Function
|
||||
|
||||
Sets a 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.
|
||||
|
||||
#### `ses.getCacheSize(callback)`
|
||||
|
||||
* `callback` Function
|
||||
|
|
@ -358,15 +272,140 @@ This doesn't affect existing `WebContents`, and each `WebContents` can use
|
|||
|
||||
Returns a `String` representing the user agent for this session.
|
||||
|
||||
### Instance Properties
|
||||
|
||||
The following properties are available on instances of `Session`:
|
||||
|
||||
#### `ses.cookies`
|
||||
|
||||
Returns an instance of `Cookies` class for this session.
|
||||
|
||||
#### `ses.webRequest`
|
||||
|
||||
The `webRequest` API set allows to intercept and modify contents of a request at
|
||||
various stages of its lifetime.
|
||||
Returns an instance of `WebRequest` class for this session.
|
||||
|
||||
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.
|
||||
#### `ses.protocol`
|
||||
|
||||
Returns an instance of [protocol](protocol.md) module for this session.
|
||||
|
||||
```javascript
|
||||
const {app, session} = require('electron')
|
||||
const path = require('path')
|
||||
|
||||
app.on('ready', function () {
|
||||
const protocol = session.fromPartition(partitionName).protocol
|
||||
protocol.registerFileProtocol('atom', function (request, callback) {
|
||||
var url = request.url.substr(7)
|
||||
callback({path: path.normalize(__dirname + '/' + url)})
|
||||
}, function (error) {
|
||||
if (error)
|
||||
console.error('Failed to register protocol')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
## Class: Cookies
|
||||
|
||||
The `Cookies` class gives you ability to query and modify cookies. Instances of
|
||||
`Cookies` class must be received by using `cookies` property of `Session` class.
|
||||
|
||||
For example:
|
||||
|
||||
```javascript
|
||||
// Query all cookies.
|
||||
session.defaultSession.cookies.get({}, (error, cookies) => {
|
||||
console.log(cookies)
|
||||
})
|
||||
|
||||
// Query all cookies associated with a specific url.
|
||||
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
|
||||
console.log(cookies)
|
||||
})
|
||||
|
||||
// Set a cookie with the given cookie data;
|
||||
// may overwrite equivalent cookies if they exist.
|
||||
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
|
||||
session.defaultSession.cookies.set(cookie, (error) => {
|
||||
if (error)
|
||||
console.error(error)
|
||||
})
|
||||
```
|
||||
|
||||
### Instance Methods
|
||||
|
||||
The following methods are available on instances of `Cookies`:
|
||||
|
||||
#### `cookies.get(filter, callback)`
|
||||
|
||||
* `filter` Object
|
||||
* `url` String (optional) - Retrieves cookies which are associated with
|
||||
`url`. Empty implies retrieving cookies of all urls.
|
||||
* `name` String (optional) - Filters cookies by name.
|
||||
* `domain` String (optional) - Retrieves cookies whose domains match or are
|
||||
subdomains of `domains`
|
||||
* `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.
|
||||
* `callback` Function
|
||||
|
||||
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.
|
||||
|
||||
* `cookie` Object
|
||||
* `name` String - The name of the cookie.
|
||||
* `value` String - The value of the cookie.
|
||||
* `domain` String - The domain of the cookie.
|
||||
* `hostOnly` String - Whether the cookie is a host-only cookie.
|
||||
* `path` String - The path of the cookie.
|
||||
* `secure` Boolean - Whether the cookie is marked as secure.
|
||||
* `httpOnly` Boolean - Whether the cookie is marked as HTTP only.
|
||||
* `session` Boolean - Whether the cookie is a session cookie or a persistent
|
||||
cookie with an expiration date.
|
||||
* `expirationDate` Double (optional) - The expiration date of the cookie as
|
||||
the number of seconds since the UNIX epoch. Not provided for session
|
||||
cookies.
|
||||
|
||||
#### `cookies.set(details, callback)`
|
||||
|
||||
* `details` Object
|
||||
* `url` String - The url to associate the cookie with.
|
||||
* `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 HTTP only. Defaults
|
||||
to false.
|
||||
* `expirationDate` Double - The expiration date of the cookie as the number of
|
||||
seconds since the UNIX epoch. If omitted then the cookie becomes a session
|
||||
cookie and will not be retained between sessions.
|
||||
* `callback` Function
|
||||
|
||||
Sets a cookie with `details`, `callback` will be called with `callback(error)`
|
||||
on complete.
|
||||
|
||||
#### `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.
|
||||
|
||||
## Class: WebRequest
|
||||
|
||||
The `WebRequest` class allows to intercept and modify contents of a request at
|
||||
various stages of its lifetime. Instances of `WebRequest` class must be received
|
||||
by using `webRequest` property of `Session` class.
|
||||
|
||||
The methods of `WebRequest` accept 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
|
||||
|
|
@ -375,19 +414,25 @@ patterns. If the `filter` is omitted then all requests will be matched.
|
|||
For certain events the `listener` is passed with a `callback`, which should be
|
||||
called with an `response` object when `listener` has done its work.
|
||||
|
||||
An example of adding `User-Agent` header for requests:
|
||||
|
||||
```javascript
|
||||
// Modify the user agent for all requests to the following urls.
|
||||
const filter = {
|
||||
urls: ['https://*.github.com/*', '*://electron.github.io']
|
||||
};
|
||||
}
|
||||
|
||||
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
|
||||
details.requestHeaders['User-Agent'] = "MyAgent";
|
||||
callback({cancel: false, requestHeaders: details.requestHeaders});
|
||||
});
|
||||
details.requestHeaders['User-Agent'] = "MyAgent"
|
||||
callback({cancel: false, requestHeaders: details.requestHeaders})
|
||||
})
|
||||
```
|
||||
|
||||
#### `ses.webRequest.onBeforeRequest([filter, ]listener)`
|
||||
### Instance Methods
|
||||
|
||||
The following methods are available on instances of `WebRequest`:
|
||||
|
||||
#### `webRequest.onBeforeRequest([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -417,7 +462,7 @@ The `callback` has to be called with an `response` object:
|
|||
* `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)`
|
||||
#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -442,7 +487,7 @@ The `callback` has to be called with an `response` object:
|
|||
* `requestHeaders` Object (optional) - When provided, request will be made
|
||||
with these headers.
|
||||
|
||||
#### `ses.webRequest.onSendHeaders([filter, ]listener)`
|
||||
#### `webRequest.onSendHeaders([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -459,7 +504,7 @@ response are visible by the time this listener is fired.
|
|||
* `timestamp` Double
|
||||
* `requestHeaders` Object
|
||||
|
||||
#### `ses.webRequest.onHeadersReceived([filter,]listener)`
|
||||
#### `webRequest.onHeadersReceived([filter,]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -488,7 +533,7 @@ The `callback` has to be called with an `response` object:
|
|||
`responseHeaders` to change header status otherwise original response
|
||||
header's status will be used.
|
||||
|
||||
#### `ses.webRequest.onResponseStarted([filter, ]listener)`
|
||||
#### `webRequest.onResponseStarted([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -509,7 +554,7 @@ and response headers are available.
|
|||
* `statusCode` Integer
|
||||
* `statusLine` String
|
||||
|
||||
#### `ses.webRequest.onBeforeRedirect([filter, ]listener)`
|
||||
#### `webRequest.onBeforeRedirect([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -530,7 +575,7 @@ redirect is about to occur.
|
|||
* `fromCache` Boolean
|
||||
* `responseHeaders` Object
|
||||
|
||||
#### `ses.webRequest.onCompleted([filter, ]listener)`
|
||||
#### `webRequest.onCompleted([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -549,7 +594,7 @@ completed.
|
|||
* `statusCode` Integer
|
||||
* `statusLine` String
|
||||
|
||||
#### `ses.webRequest.onErrorOccurred([filter, ]listener)`
|
||||
#### `webRequest.onErrorOccurred([filter, ]listener)`
|
||||
|
||||
* `filter` Object
|
||||
* `listener` Function
|
||||
|
|
@ -564,23 +609,3 @@ The `listener` will be called with `listener(details)` when an error occurs.
|
|||
* `timestamp` Double
|
||||
* `fromCache` Boolean
|
||||
* `error` String - The error description.
|
||||
|
||||
#### `ses.protocol`
|
||||
|
||||
Returns an instance of [protocol](protocol.md) module for this session.
|
||||
|
||||
```javascript
|
||||
const {app, session} = require('electron')
|
||||
const path = require('path')
|
||||
|
||||
app.on('ready', function () {
|
||||
const protocol = session.fromPartition(partitionName).protocol
|
||||
protocol.registerFileProtocol('atom', function (request, callback) {
|
||||
var url = request.url.substr(7)
|
||||
callback({path: path.normalize(__dirname + '/' + url)})
|
||||
}, function (error) {
|
||||
if (error)
|
||||
console.error('Failed to register protocol')
|
||||
})
|
||||
})
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue