move each API doc into its own file
This commit is contained in:
Zeke Sikelianos
parent
436775b1e4
commit
b084dc29ea
10 changed files with 711 additions and 718 deletions
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue