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
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
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.
+
+#### `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
-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 `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
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
* `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
* `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
* `timestamp` Double
* `requestHeaders` Object
-#### `ses.webRequest.onHeadersReceived([filter,]listener)`
+#### `webRequest.onHeadersReceived([filter,]listener)`
* `filter` Object
* `listener` Function
`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
* `statusCode` Integer
* `statusLine` String
-#### `ses.webRequest.onBeforeRedirect([filter, ]listener)`
+#### `webRequest.onBeforeRedirect([filter, ]listener)`
* `filter` Object
* `listener` Function
* `fromCache` Boolean
* `responseHeaders` Object
-#### `ses.webRequest.onCompleted([filter, ]listener)`
+#### `webRequest.onCompleted([filter, ]listener)`
* `filter` Object
* `listener` Function
* `statusCode` Integer
* `statusLine` String
-#### `ses.webRequest.onErrorOccurred([filter, ]listener)`
+#### `webRequest.onErrorOccurred([filter, ]listener)`
* `filter` Object
* `listener` Function
* `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')
- })
-})
-```
projects / platform / framework / web / crosswalk-tizen.git / commitdiff