move each API doc into its own file

This commit is contained in:
Zeke Sikelianos 2016-11-10 12:25:26 -08:00
parent 436775b1e4
commit b084dc29ea
10 changed files with 711 additions and 718 deletions

View file

@ -374,316 +374,3 @@ app.on('ready', function () {
})
})
```
## Class: Cookies
> Query and modify a session's cookies.
Process: [Main](../tutorial/quick-start.md#main-process)
Instances of the `Cookies` class are accessed by using `cookies` property of
a `Session`.
For example:
```javascript
const {session} = require('electron')
// Query all cookies.
session.defaultSession.cookies.get({}, (error, cookies) => {
console.log(error, cookies)
})
// Query all cookies associated with a specific url.
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
console.log(error, 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 Events
The following events are available on instances of `Cookies`:
#### Event: 'changed'
* `event` Event
* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed
* `cause` String - The cause of the change with one of the following values:
* `explicit` - The cookie was changed directly by a consumer's action.
* `overwrite` - The cookie was automatically removed due to an insert
operation that overwrote it.
* `expired` - The cookie was automatically removed as it expired.
* `evicted` - The cookie was automatically evicted during garbage collection.
* `expired-overwrite` - The cookie was overwritten with an already-expired
expiration date.
* `removed` Boolean - `true` if the cookie was removed, `false` otherwise.
Emitted when a cookie is changed because it was added, edited, removed, or
expired.
### 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
* `error` Error
* `cookies` Cookies[]
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`](structures/cookie.md) objects.
#### `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.
* `httpOnly` 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
* `error` Error
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
> Intercept and modify the contents of a request at various stages of its lifetime.
Process: [Main](../tutorial/quick-start.md#main-process)
Instances of the `WebRequest` class are accessed by using the `webRequest`
property of a `Session`.
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` object describes the request. Passing `null`
as `listener` will unsubscribe from the event.
The `filter` object has a `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. 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 a `response` object when `listener` has done its work.
An example of adding `User-Agent` header for requests:
```javascript
const {session} = require('electron')
// 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})
})
```
### Instance Methods
The following methods are available on instances of `WebRequest`:
#### `webRequest.onBeforeRequest([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `response` Object
* `cancel` Boolean (optional)
* `redirectURL` String (optional) - The original request is prevented from
being sent or completed and is instead redirected to the given URL.
The `listener` will be called with `listener(details, callback)` when a request
is about to occur.
The `uploadData` is an array of `UploadData` objects.
The `callback` has to be called with an `response` object.
#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
* `filter` Object
* `listener` Function
The `listener` will be called with `listener(details, callback)` before sending
an HTTP request, once the request headers are available. This may occur after a
TCP connection is made to the server, but before any http data is sent.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
* `callback` Function
* `response` Object
* `cancel` Boolean (optional)
* `requestHeaders` Object (optional) - When provided, request will be made
with these headers.
The `callback` has to be called with an `response` object.
#### `webRequest.onSendHeaders([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
The `listener` will be called with `listener(details)` just before a request is
going to be sent to the server, modifications of previous `onBeforeSendHeaders`
response are visible by the time this listener is fired.
#### `webRequest.onHeadersReceived([filter, ]listener)`
* `filter` Object
* `listener` Function
The `listener` will be called with `listener(details, callback)` when HTTP
response headers of a request have been received.
* `details` Object
* `id` String
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `statusLine` String
* `statusCode` Integer
* `responseHeaders` Object
* `callback` Function
* `response` Object
* `cancel` Boolean
* `responseHeaders` Object (optional) - When provided, the server is assumed
to have responded with these headers.
* `statusLine` String (optional) - Should be provided when overriding
`responseHeaders` to change header status otherwise original response
header's status will be used.
The `callback` has to be called with an `response` object.
#### `webRequest.onResponseStarted([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean - Indicates whether the response was fetched from disk
cache.
* `statusCode` Integer
* `statusLine` String
The `listener` will be called with `listener(details)` when first byte of the
response body is received. For HTTP requests, this means that the status line
and response headers are available.
#### `webRequest.onBeforeRedirect([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` String
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `redirectURL` String
* `statusCode` Integer
* `ip` String (optional) - The server IP address that the request was
actually sent to.
* `fromCache` Boolean
* `responseHeaders` Object
The `listener` will be called with `listener(details)` when a server initiated
redirect is about to occur.
#### `webRequest.onCompleted([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean
* `statusCode` Integer
* `statusLine` String
The `listener` will be called with `listener(details)` when a request is
completed.
#### `webRequest.onErrorOccurred([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `fromCache` Boolean
* `error` String - The error description.
The `listener` will be called with `listener(details)` when an error occurs.