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

Merge pull request #6174 from electron/session-docs-cleanup

Browse source 
docs: Separate Cookies and WebRequest classes in session.md
This commit is contained in:
Cheng Zhao 2016-06-23 04:05:18 +00:00 committed by GitHub
commit 6cfd078d19
1 changed files with 154 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

283
docs/api/session.md
View file

@ -5,16 +5,15 @@
The `session` module can be used to create new `Session` objects. The `session` module can be used to create new `Session` objects.
You can also access the `session` of existing pages by using the `session` You can also access the `session` of existing pages by using the `session`
property of [`webContents`](web-contents.md) which is a property of property of [`WebContents`](web-contents.md), or from the `session` module.
[`BrowserWindow`](browser-window.md).
```javascript ```javascript
const {BrowserWindow} = require('electron'); const {session, BrowserWindow} = require('electron')
let win = new BrowserWindow({width: 800, height: 600}); let win = new BrowserWindow({width: 800, height: 600})
win.loadURL('http://github.com'); win.loadURL('http://github.com')
const ses = win.webContents.session; const ses = win.webContents.session
``` ```
## Methods ## Methods
@ -78,91 +77,6 @@ session.defaultSession.on('will-download', (event, item, webContents) => {
The following methods are available on instances of `Session`: 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)` #### `ses.getCacheSize(callback)`
* `callback` Function * `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. 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` #### `ses.webRequest`
The `webRequest` API set allows to intercept and modify contents of a request at Returns an instance of `WebRequest` class for this session.
various stages of its lifetime.
Each API accepts an optional `filter` and a `listener`, the `listener` will be #### `ses.protocol`
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 Returns an instance of [protocol](protocol.md) module for this session.
unsubscribe from the event.
```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 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 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 For certain events the `listener` is passed with a `callback`, which should be
called with an `response` object when `listener` has done its work. called with an `response` object when `listener` has done its work.
An example of adding `User-Agent` header for requests:
```javascript ```javascript
// Modify the user agent for all requests to the following urls. // Modify the user agent for all requests to the following urls.
const filter = { const filter = {
urls: ['https://*.github.com/*', '*://electron.github.io'] urls: ['https://*.github.com/*', '*://electron.github.io']
}; }
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => { session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
details.requestHeaders['User-Agent'] = "MyAgent"; details.requestHeaders['User-Agent'] = "MyAgent"
callback({cancel: false, requestHeaders: details.requestHeaders}); 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 * `filter` Object
* `listener` Function * `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 * `redirectURL` String (optional) - The original request is prevented from
being sent or completed, and is instead redirected to the given URL. being sent or completed, and is instead redirected to the given URL.
#### `ses.webRequest.onBeforeSendHeaders([filter, ]listener)` #### `webRequest.onBeforeSendHeaders([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `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 * `requestHeaders` Object (optional) - When provided, request will be made
with these headers. with these headers.
#### `ses.webRequest.onSendHeaders([filter, ]listener)` #### `webRequest.onSendHeaders([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -459,7 +504,7 @@ response are visible by the time this listener is fired.
* `timestamp` Double * `timestamp` Double
* `requestHeaders` Object * `requestHeaders` Object
#### `ses.webRequest.onHeadersReceived([filter,]listener)` #### `webRequest.onHeadersReceived([filter,]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -488,7 +533,7 @@ The `callback` has to be called with an `response` object:
`responseHeaders` to change header status otherwise original response `responseHeaders` to change header status otherwise original response
header's status will be used. header's status will be used.
#### `ses.webRequest.onResponseStarted([filter, ]listener)` #### `webRequest.onResponseStarted([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -509,7 +554,7 @@ and response headers are available.
* `statusCode` Integer * `statusCode` Integer
* `statusLine` String * `statusLine` String
#### `ses.webRequest.onBeforeRedirect([filter, ]listener)` #### `webRequest.onBeforeRedirect([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -530,7 +575,7 @@ redirect is about to occur.
* `fromCache` Boolean * `fromCache` Boolean
* `responseHeaders` Object * `responseHeaders` Object
#### `ses.webRequest.onCompleted([filter, ]listener)` #### `webRequest.onCompleted([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -549,7 +594,7 @@ completed.
* `statusCode` Integer * `statusCode` Integer
* `statusLine` String * `statusLine` String
#### `ses.webRequest.onErrorOccurred([filter, ]listener)` #### `webRequest.onErrorOccurred([filter, ]listener)`
* `filter` Object * `filter` Object
* `listener` Function * `listener` Function
@ -564,23 +609,3 @@ The `listener` will be called with `listener(details)` when an error occurs.
* `timestamp` Double * `timestamp` Double
* `fromCache` Boolean * `fromCache` Boolean
* `error` String - The error description. * `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')
})
})
```