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

docs: Improve the cookies docs

Browse source
This commit is contained in:
Cheng Zhao 2015-12-12 15:41:04 +08:00
parent 4d1e223044
commit ab14a4466d
1 changed files with 60 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

123
docs/api/session.md
View file

@ -63,7 +63,7 @@ Emitted when Electron is about to download `item` in `webContents`.
Calling `event.preventDefault()` will cancel the download. Calling `event.preventDefault()` will cancel the download.
```javascript ```javascript
session.on('will-download', function(event, item, webContents) { session.defaultSession.on('will-download', function(event, item, webContents) {
event.preventDefault(); event.preventDefault();
require('request')(item.getURL(), function(data) { require('request')(item.getURL(), function(data) {
require('fs').writeFileSync('/somewhere', data); require('fs').writeFileSync('/somewhere', data);
@ -80,91 +80,84 @@ The following methods are available on instances of `Session`:
The `cookies` gives you ability to query and modify cookies. For example: The `cookies` gives you ability to query and modify cookies. For example:
```javascript ```javascript
const BrowserWindow = require('electron').BrowserWindow; // Query all cookies.
session.defaultSession.cookies.get({}, function(error, cookies) {
var win = new BrowserWindow({ width: 800, height: 600 });
win.loadURL('https://github.com');
win.webContents.on('did-finish-load', function() {
// Query all cookies.
win.webContents.session.cookies.get({}, function(error, cookies) {
if (error) throw error;
console.log(cookies); console.log(cookies);
}); });
// Query all cookies associated with a specific url. // Query all cookies associated with a specific url.
win.webContents.session.cookies.get({ url : "http://www.github.com" }, session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
function(error, cookies) {
if (error) throw error;
console.log(cookies); console.log(cookies);
}); });
// Set a cookie with the given cookie data; // Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist. // may overwrite equivalent cookies if they exist.
win.webContents.session.cookies.set( var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
{ url : "http://www.github.com", name : "dummy_name", value : "dummy"}, session.defaultSession.cookies.set(cookie, function(error) {
function(error, cookies) { if (error)
if (error) throw error; console.error(error);
console.log(cookies);
});
}); });
``` ```
#### `ses.cookies.get(details, callback)` #### `ses.cookies.get(filter, callback)`
`details` Object, properties: * `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
* `url` String - Retrieves cookies which are associated with `url`. Sends a request to get all cookies matching `details`, `callback` will be called
Empty implies retrieving cookies of all urls. with `callback(error, cookies)` on complete.
* `name` String - Filters cookies by name
* `domain` String - Retrieves cookies whose domains match or are subdomains of `cookies` is an Array of `cookie` objects.
`domains`
* `path` String - Retrieves cookies whose path matches `path` * `cookie` Object
* `secure` Boolean - Filters cookies by their Secure property
* `session` Boolean - Filters out session or persistent cookies.
* `callback` Function - function(error, cookies)
* `error` Error
* `cookies` Array - array of `cookie` objects, properties:
* `name` String - The name of the cookie. * `name` String - The name of the cookie.
* `value` String - The value of the cookie. * `value` String - The value of the cookie.
* `domain` String - The domain of the cookie. * `domain` String - The domain of the cookie.
* `host_only` String - Whether the cookie is a host-only cookie. * `hostOnly` String - Whether the cookie is a host-only cookie.
* `path` String - The path of the cookie. * `path` String - The path of the cookie.
* `secure` Boolean - Whether the cookie is marked as Secure (typically HTTPS). * `secure` Boolean - Whether the cookie is marked as secure.
* `http_only` Boolean - Whether the cookie is marked as HttpOnly. * `httpOnly` Boolean - Whether the cookie is marked as HTTP only.
* `session` Boolean - Whether the cookie is a session cookie or a persistent * `session` Boolean - Whether the cookie is a session cookie or a persistent
cookie with an expiration date. cookie with an expiration date.
* `expirationDate` Double - (Option) The expiration date of the cookie as * `expirationDate` Double __optional__ - The expiration date of the cookie as
the number of seconds since the UNIX epoch. Not provided for session the number of seconds since the UNIX epoch. Not provided for session
cookies. cookies.
#### `ses.cookies.set(details, callback)` #### `ses.cookies.set(details, callback)`
`details` Object, properties:
* `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 - function(error)
* `error` Error
#### `ses.cookies.remove(details, callback)`
* `details` Object * `details` Object
* `url` String - The URL associated with the cookie * `url` String - Retrieves cookies which are associated with `url`
* `name` String - The name of cookie to remove * `name` String - The name of the cookie. Empty by default if omitted.
* `callback` Function - function(error) * `value` String - The value of the cookie. Empty by default if omitted.
* `error` Error * `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.
#### `ses.clearCache(callback)` #### `ses.clearCache(callback)`