From 1a74177e2d0bb1d86d2d2ac2b2399f88b638445c Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Wed, 22 Jun 2016 16:34:25 +0900 Subject: [PATCH] docs: Separate Cookies and WebRequest classes in session.md --- docs/api/session.md | 283 ++++++++++++++++++++++++-------------------- 1 file changed, 154 insertions(+), 129 deletions(-) diff --git a/docs/api/session.md b/docs/api/session.md index 1b23ff5865d9..b6026c32ddda 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -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') - }) -}) -```