X Tutup
Skip to content

Commit b084dc2

Browse files
zekezeke
committed
move each API doc into its own file
1 parent 436775b commit b084dc2

File tree

10 files changed

+711
-718
lines changed

10 files changed

+711
-718
lines changed

‎docs/api/browser-window-proxy.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Class: BrowserWindowProxy
2+
3+
> Manipulate the child browser window
4+
5+
Process: [Renderer](../tutorial/quick-start.md#renderer-process)
6+
7+
The `BrowserWindowProxy` object is returned from `window.open` and provides
8+
limited functionality with the child window.
9+
10+
### Instance Methods
11+
12+
The `BrowserWindowProxy` object has the following instance methods:
13+
14+
#### `win.blur()`
15+
16+
Removes focus from the child window.
17+
18+
#### `win.close()`
19+
20+
Forcefully closes the child window without calling its unload event.
21+
22+
#### `win.eval(code)`
23+
24+
* `code` String
25+
26+
Evaluates the code in the child window.
27+
28+
#### `win.focus()`
29+
30+
Focuses the child window (brings the window to front).
31+
32+
#### `win.print()`
33+
34+
Invokes the print dialog on the child window.
35+
36+
#### `win.postMessage(message, targetOrigin)`
37+
38+
* `message` String
39+
* `targetOrigin` String
40+
41+
Sends a message to the child window with the specified origin or `*` for no
42+
origin preference.
43+
44+
In addition to these methods, the child window implements `window.opener` object
45+
with no properties and a single method.
46+
47+
### Instance Properties
48+
49+
The `BrowserWindowProxy` object has the following instance properties:
50+
51+
#### `win.closed`
52+
53+
A Boolean that is set to true after the child window gets closed.

‎docs/api/client-request.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
## Class: ClientRequest
2+
3+
> Make HTTP/HTTPS requests.
4+
5+
Process: [Main](../tutorial/quick-start.md#main-process)
6+
7+
`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
8+
interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
9+
10+
### `new ClientRequest(options)`
11+
12+
* `options` (Object | String) - If `options` is a String, it is interpreted as
13+
the request URL. If it is an object, it is expected to fully specify an HTTP request via the
14+
following properties:
15+
* `method` String (optional) - The HTTP request method. Defaults to the GET
16+
method.
17+
* `url` String (optional) - The request URL. Must be provided in the absolute
18+
form with the protocol scheme specified as http or https.
19+
* `session` Object (optional) - The [`Session`](session.md) instance with
20+
which the request is associated.
21+
* `partition` String (optional) - The name of the [`partition`](session.md)
22+
with which the request is associated. Defaults to the empty string. The
23+
`session` option prevails on `partition`. Thus if a `session` is explicitly
24+
specified, `partition` is ignored.
25+
* `protocol` String (optional) - The protocol scheme in the form 'scheme:'.
26+
Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
27+
* `host` String (optional) - The server host provided as a concatenation of
28+
the hostname and the port number 'hostname:port'
29+
* `hostname` String (optional) - The server host name.
30+
* `port` Integer (optional) - The server's listening port number.
31+
* `path` String (optional) - The path part of the request URL.
32+
33+
`options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
34+
strictly follow the Node.js model as described in the
35+
[URL](https://nodejs.org/api/url.html) module.
36+
37+
For instance, we could have created the same request to 'github.com' as follows:
38+
39+
```JavaScript
40+
const request = net.request({
41+
method: 'GET',
42+
protocol: 'https:',
43+
hostname: 'github.com',
44+
port: 443,
45+
path: '/'
46+
})
47+
```
48+
49+
### Instance Events
50+
51+
#### Event: 'response'
52+
53+
Returns:
54+
55+
* `response` IncomingMessage - An object representing the HTTP response message.
56+
57+
#### Event: 'login'
58+
59+
Returns:
60+
61+
* `authInfo` Object
62+
* `isProxy` Boolean
63+
* `scheme` String
64+
* `host` String
65+
* `port` Integer
66+
* `realm` String
67+
* `callback` Function
68+
69+
Emitted when an authenticating proxy is asking for user credentials.
70+
71+
The `callback` function is expected to be called back with user credentials:
72+
73+
* `username` String
74+
* `password` String
75+
76+
```JavaScript
77+
request.on('login', (authInfo, callback) => {
78+
callback('username', 'password')
79+
})
80+
```
81+
Providing empty credentials will cancel the request and report an authentication
82+
error on the response object:
83+
84+
```JavaScript
85+
request.on('response', (response) => {
86+
console.log(`STATUS: ${response.statusCode}`);
87+
response.on('error', (error) => {
88+
console.log(`ERROR: ${JSON.stringify(error)}`)
89+
})
90+
})
91+
request.on('login', (authInfo, callback) => {
92+
callback()
93+
})
94+
```
95+
96+
#### Event: 'finish'
97+
98+
Emitted just after the last chunk of the `request`'s data has been written into
99+
the `request` object.
100+
101+
#### Event: 'abort'
102+
103+
Emitted when the `request` is aborted. The `abort` event will not be fired if
104+
the `request` is already closed.
105+
106+
#### Event: 'error'
107+
108+
Returns:
109+
110+
* `error` Error - an error object providing some information about the failure.
111+
112+
Emitted when the `net` module fails to issue a network request. Typically when
113+
the `request` object emits an `error` event, a `close` event will subsequently
114+
follow and no response object will be provided.
115+
116+
#### Event: 'close'
117+
118+
Emitted as the last event in the HTTP request-response transaction. The `close`
119+
event indicates that no more events will be emitted on either the `request` or
120+
`response` objects.
121+
122+
### Instance Properties
123+
124+
#### `request.chunkedEncoding`
125+
126+
A Boolean specifying whether the request will use HTTP chunked transfer encoding
127+
or not. Defaults to false. The property is readable and writable, however it can
128+
be set only before the first write operation as the HTTP headers are not yet put
129+
on the wire. Trying to set the `chunkedEncoding` property after the first write
130+
will throw an error.
131+
132+
Using chunked encoding is strongly recommended if you need to send a large
133+
request body as data will be streamed in small chunks instead of being
134+
internally buffered inside Electron process memory.
135+
136+
### Instance Methods
137+
138+
#### `request.setHeader(name, value)`
139+
140+
* `name` String - An extra HTTP header name.
141+
* `value` String - An extra HTTP header value.
142+
143+
Adds an extra HTTP header. The header name will issued as it is without
144+
lowercasing. It can be called only before first write. Calling this method after
145+
the first write will throw an error.
146+
147+
#### `request.getHeader(name)`
148+
149+
* `name` String - Specify an extra header name.
150+
151+
Returns String - The value of a previously set extra header name.
152+
153+
#### `request.removeHeader(name)`
154+
155+
* `name` String - Specify an extra header name.
156+
157+
Removes a previously set extra header name. This method can be called only
158+
before first write. Trying to call it after the first write will throw an error.
159+
160+
#### `request.write(chunk[, encoding][, callback])`
161+
162+
* `chunk` (String | Buffer) - A chunk of the request body's data. If it is a
163+
string, it is converted into a Buffer using the specified encoding.
164+
* `encoding` String (optional) - Used to convert string chunks into Buffer
165+
objects. Defaults to 'utf-8'.
166+
* `callback` Function (optional) - Called after the write operation ends.
167+
168+
`callback` is essentially a dummy function introduced in the purpose of keeping
169+
similarity with the Node.js API. It is called asynchronously in the next tick
170+
after `chunk` content have been delivered to the Chromium networking layer.
171+
Contrary to the Node.js implementation, it is not guaranteed that `chunk`
172+
content have been flushed on the wire before `callback` is called.
173+
174+
Adds a chunk of data to the request body. The first write operation may cause
175+
the request headers to be issued on the wire. After the first write operation,
176+
it is not allowed to add or remove a custom header.
177+
178+
#### `request.end([chunk][, encoding][, callback])`
179+
180+
* `chunk` (String | Buffer) (optional)
181+
* `encoding` String (optional)
182+
* `callback` Function (optional)
183+
184+
Sends the last chunk of the request data. Subsequent write or end operations
185+
will not be allowed. The `finish` event is emitted just after the end operation.
186+
187+
#### `request.abort()`
188+
189+
Cancels an ongoing HTTP transaction. If the request has already emitted the
190+
`close` event, the abort operation will have no effect. Otherwise an ongoing
191+
event will emit `abort` and `close` events. Additionally, if there is an ongoing
192+
response object,it will emit the `aborted` event.

‎docs/api/cookies.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
## Class: Cookies
2+
3+
> Query and modify a session's cookies.
4+
5+
Process: [Main](../tutorial/quick-start.md#main-process)
6+
7+
Instances of the `Cookies` class are accessed by using `cookies` property of
8+
a `Session`.
9+
10+
For example:
11+
12+
```javascript
13+
const {session} = require('electron')
14+
15+
// Query all cookies.
16+
session.defaultSession.cookies.get({}, (error, cookies) => {
17+
console.log(error, cookies)
18+
})
19+
20+
// Query all cookies associated with a specific url.
21+
session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
22+
console.log(error, cookies)
23+
})
24+
25+
// Set a cookie with the given cookie data;
26+
// may overwrite equivalent cookies if they exist.
27+
const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
28+
session.defaultSession.cookies.set(cookie, (error) => {
29+
if (error) console.error(error)
30+
})
31+
```
32+
33+
### Instance Events
34+
35+
The following events are available on instances of `Cookies`:
36+
37+
#### Event: 'changed'
38+
39+
* `event` Event
40+
* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed
41+
* `cause` String - The cause of the change with one of the following values:
42+
* `explicit` - The cookie was changed directly by a consumer's action.
43+
* `overwrite` - The cookie was automatically removed due to an insert
44+
operation that overwrote it.
45+
* `expired` - The cookie was automatically removed as it expired.
46+
* `evicted` - The cookie was automatically evicted during garbage collection.
47+
* `expired-overwrite` - The cookie was overwritten with an already-expired
48+
expiration date.
49+
* `removed` Boolean - `true` if the cookie was removed, `false` otherwise.
50+
51+
Emitted when a cookie is changed because it was added, edited, removed, or
52+
expired.
53+
54+
### Instance Methods
55+
56+
The following methods are available on instances of `Cookies`:
57+
58+
#### `cookies.get(filter, callback)`
59+
60+
* `filter` Object
61+
* `url` String (optional) - Retrieves cookies which are associated with
62+
`url`. Empty implies retrieving cookies of all urls.
63+
* `name` String (optional) - Filters cookies by name.
64+
* `domain` String (optional) - Retrieves cookies whose domains match or are
65+
subdomains of `domains`
66+
* `path` String (optional) - Retrieves cookies whose path matches `path`.
67+
* `secure` Boolean (optional) - Filters cookies by their Secure property.
68+
* `session` Boolean (optional) - Filters out session or persistent cookies.
69+
* `callback` Function
70+
* `error` Error
71+
* `cookies` Cookies[]
72+
73+
Sends a request to get all cookies matching `details`, `callback` will be called
74+
with `callback(error, cookies)` on complete.
75+
76+
`cookies` is an Array of [`cookie`](structures/cookie.md) objects.
77+
78+
#### `cookies.set(details, callback)`
79+
80+
* `details` Object
81+
* `url` String - The url to associate the cookie with.
82+
* `name` String - The name of the cookie. Empty by default if omitted.
83+
* `value` String - The value of the cookie. Empty by default if omitted.
84+
* `domain` String - The domain of the cookie. Empty by default if omitted.
85+
* `path` String - The path of the cookie. Empty by default if omitted.
86+
* `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to
87+
false.
88+
* `httpOnly` Boolean - Whether the cookie should be marked as HTTP only.
89+
Defaults to false.
90+
* `expirationDate` Double - The expiration date of the cookie as the number of
91+
seconds since the UNIX epoch. If omitted then the cookie becomes a session
92+
cookie and will not be retained between sessions.
93+
* `callback` Function
94+
* `error` Error
95+
96+
Sets a cookie with `details`, `callback` will be called with `callback(error)`
97+
on complete.
98+
99+
#### `cookies.remove(url, name, callback)`
100+
101+
* `url` String - The URL associated with the cookie.
102+
* `name` String - The name of cookie to remove.
103+
* `callback` Function
104+
105+
Removes the cookies matching `url` and `name`, `callback` will called with
106+
`callback()` on complete.

0 commit comments

Comments
 (0)
X Tutup