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

Formatting net documentation.

Browse source
This commit is contained in:
ali.ibrahim 2016-10-20 12:30:03 +02:00
parent 69790bd7ed
commit 9f15191280
1 changed files with 99 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

174
docs/api/net.md
View file

@ -2,52 +2,52 @@
> Issue HTTP/HTTPS requests. > Issue HTTP/HTTPS requests.
The `net` module is a client-side API for issuing HTTP(S) requests. It is similar to the The `net` module is a client-side API for issuing HTTP(S) requests. It is
[HTTP](https://nodejs.org/api/http.html) and [HTTPS](https://nodejs.org/api/https.html) modules of Node.js similar to the [HTTP](https://nodejs.org/api/http.html) and
but it uses Chromium native networking library instead of the Node.js implementation offering [HTTPS](https://nodejs.org/api/https.html) modules of Node.js but it uses
therefore a much greater support regarding web proxies. Chromium native networking library instead of the Node.js implementation
offering therefore a much greater support regarding web proxies.
Following is a non-exhaustive list of why you may consider using the `net` module instead of the native Node.js modules: Following is a non-exhaustive list of why you may consider using the `net`
* Automatic management of system proxy configuration, support of the wpad protocol and proxy pac configuration files. module instead of the native Node.js modules:
* Automatic management of system proxy configuration, support of the wpad
protocol and proxy pac configuration files.
* Automatic tunneling of HTTPS requests. * Automatic tunneling of HTTPS requests.
* Support for authenticating proxies using basic, digest, NTLM, Kerberos or negotiate authentication schemes. * Support for authenticating proxies using basic, digest, NTLM, Kerberos or
* Support for traffic monitoring proxies: Fiddler-like proxies used for access control and monitoring. negotiate authentication schemes.
* Support for traffic monitoring proxies: Fiddler-like proxies used for access
control and monitoring.
The `net` module API has been specifically designed to mimic, as much closely as possible, the familiar Node.js API. The `net` module API has been specifically designed to mimic, as much closely as
The API components including classes, methods, properties and event names are similar to those commonly used in Node.js. possible, the familiar Node.js API. The API components including classes,
methods, properties and event names are similar to those commonly used in
Node.js.
For instance, the following example quickly shows how the `net` API might be used: For instance, the following example quickly shows how the `net` API might be
used:
```javascript ```javascript
const {app} = require('electron') const {app} = require('electron')
app.on('ready', () => { app.on('ready', () => {
const {net} = require('electron') const {net} = require('electron')
const request = net.request('https://github.com') const request = net.request('https://github.com')
request.on('response', (response) => { request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`); console.log(`STATUS: ${response.statusCode}`);
console.log(`HEADERS: ${JSON.stringify(response.headers)}`); console.log(`HEADERS: ${JSON.stringify(response.headers)}`);
response.on('data', (chunk) => { response.on('data', (chunk) => {
console.log(`BODY: ${chunk}`) console.log(`BODY: ${chunk}`)
}) })
response.on('end', () => { response.on('end', () => {
console.log('No more data in response.'); console.log('No more data in response.');
}) })
}) })
request.end() request.end()
}) })
``` ```
By the way, it is almost identical to the way you would normally use the By the way, it is almost identical to how you would normally use the
[HTTP](https://nodejs.org/api/http.html)/[HTTPS](https://nodejs.org/api/https.html) modules of Node.js [HTTP](https://nodejs.org/api/http.html)/[HTTPS](https://nodejs.org/api/https.html)
modules of Node.js
## Methods ## Methods
@ -59,29 +59,37 @@ The `net` module has the following methods:
Returns `ClientRequest` Returns `ClientRequest`
Create a `ClientRequest` instance using the provided `options` object which is directly Creates a `ClientRequest` instance using the provided `options` which are
passed to the `ClientRequest` constructor. The `net.request` method would be used to issue directly forwarded to the `ClientRequest` constructor. The `net.request` method
both secure and insecure HTTP requests according to the specified protocol scheme in the `options` object. would be used to issue both secure and insecure HTTP requests according to the
specified protocol scheme in the `options` object.
## Class: ClientRequest ## Class: ClientRequest
`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams) interface `ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams)
and it is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). interface and it is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
### `new ClientRequest(options)` ### `new ClientRequest(options)`
* `options` Object or String - If `options` is a String, it is interpreted as the request URL. * `options` Object or String - If `options` is a String, it is interpreted as
If it is an object, it is expected to fully specify an HTTP request via the following properties: the request URL.
* `method` String (optional) - The HTTP request method. Defaults to the GET method. If it is an object, it is expected to fully specify an HTTP request via the
* `url` String (required) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https. following properties:
* `protocol` String (optional) - The protocol scheme in the form 'scheme:'. Current supported values are 'http:' or 'https:'. Defaults to 'http:'. * `method` String (optional) - The HTTP request method. Defaults to the GET
* `host` String (optional) - The server host provided as a concatenation of a hostname and a port number 'hostname:port' method.
* `url` String (optional) - The request URL. Must be provided in the absolute
form with the protocol scheme specified as http or https.
* `protocol` String (optional) - The protocol scheme in the form 'scheme:'.
Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
* `host` String (optional) - The server host provided as a concatenation of
the hostname and the port number 'hostname:port'
* `hostname` String (optional) - The server host name. * `hostname` String (optional) - The server host name.
* `port` Integer (optional) - The server's listening port number. * `port` Integer (optional) - The server's listening port number.
* `path` String (optional) - The path part of the request URL. * `path` String (optional) - The path part of the request URL.
`options` properties `protocol`, `host`, `hostname`, `port` and `path` strictly `options` properties such as `protocol`, `host`, `hostname`, `port` and `path`
follow the Node.js model as described in the [URL](https://nodejs.org/api/url.html) module. strictly follow the Node.js model as described in the
[URL](https://nodejs.org/api/url.html) module.
For instance, we could have created the same request to 'github.com' as follows: For instance, we could have created the same request to 'github.com' as follows:
@ -101,7 +109,7 @@ const request = net.request({
Returns: Returns:
* `response` IncomingMessage - An object representing an HTTP response message. * `response` IncomingMessage - An object representing the HTTP response message.
#### Event: 'login' #### Event: 'login'
@ -127,7 +135,8 @@ request.on('login', (authInfo, callback) => {
callback('username', 'password') callback('username', 'password')
}) })
``` ```
Providing empty credentials will cancel the request and report an authentication error on the response object: Providing empty credentials will cancel the request and report an authentication
error on the response object:
```JavaScript ```JavaScript
request.on('response', (response) => { request.on('response', (response) => {
@ -143,11 +152,13 @@ request.on('login', (authInfo, callback) => {
#### Event: 'finish' #### Event: 'finish'
Emitted just after the last chunk of the `request`'s data has been written into the `request` object. Emitted just after the last chunk of the `request`'s data has been written into
the `request` object.
#### Event: 'abort' #### Event: 'abort'
Emitted when the `request` is aborted. The abort event will not be fired if the `request` is already closed. Emitted when the `request` is aborted. The `abort` event will not be fired if
the `request` is already closed.
#### Event: 'error' #### Event: 'error'
@ -155,36 +166,40 @@ Returns:
* `error` Error - an error object providing some information about the failure. * `error` Error - an error object providing some information about the failure.
Emitted when the `net` module fails to issue a network request. Typically when the `request` Emitted when the `net` module fails to issue a network request. Typically when
object emits an error event, a close event will subsequently follow and no response object will be provided. the `request` object emits an `error` event, a `close` event will subsequently
follow and no response object will be provided.
#### Event: 'close' #### Event: 'close'
Emitted as the last event in the HTTP request-response transaction. The close event indicates Emitted as the last event in the HTTP request-response transaction. The `close`
that no more events will be emitted on either the `request` or `response` objects. event indicates that no more events will be emitted on either the `request` or
`response` objects.
### Instance Properties ### Instance Properties
#### `request.chunkedEncoding` #### `request.chunkedEncoding`
A Boolean specifying whether the request will use HTTP chunked transfer encoding or A Boolean specifying whether the request will use HTTP chunked transfer encoding
not. Defaults to false. The property is readable and writable, or not. Defaults to false. The property is readable and writable, however it can
however it can be set only before the first write operation as the HTTP headers are be set only before the first write operation as the HTTP headers are not yet put
not yet put on the wire. Trying to set the `chunkedEncoding` property on the wire. Trying to set the `chunkedEncoding` property after the first write
after a write will throw an error. will throw an error.
Using chunked encoding is strongly recommended if you need to send a large request body as Using chunked encoding is strongly recommended if you need to send a large
data will be streamed as small chunks instead of being internally buffered request body as data will be streamed in small chunks instead of being
in Electron memory. internally buffered inside Electron process memory.
### Instance Methods ### Instance Methods
#### `request.setHeader(name, value)` #### `request.setHeader(name, value)`
* `name` String - An extra header name. * `name` String - An extra HTTP header name.
* `value` String - An extra header value. * `value` String - An extra HTTP header value.
Adds an extra HTTP header. The header name will issued as it is without lowercasing. Adds an extra HTTP header. The header name will issued as it is without
lowercasing. It can be called only before first write. Calling this method after
the first write will throw an error.
#### `request.getHeader(name)` #### `request.getHeader(name)`
@ -196,17 +211,20 @@ Returns String - The value of a previously set extra header name.
* `name` String - Specify an extra header name. * `name` String - Specify an extra header name.
Removes a previously set extra header name. Removes a previously set extra header name. This method can be called only
before first write. Trying to call it after the first write will throw an error.
#### `request.write(chunk[, encoding][, callback])` #### `request.write(chunk[, encoding][, callback])`
* `chunk` String or Buffer - A chunk of the request body' data. If it is a string, * `chunk` String or Buffer - A chunk of the request body's data. If it is a
it is converted into a Buffer object using the specified encoding. string, it is converted into a Buffer using the specified encoding.
* `encoding` String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'. * `encoding` String (optional) - Used to convert string chunks into Buffer
objects. Defaults to 'utf-8'.
* `callback` Function (optional) - Called after the write operation ends. * `callback` Function (optional) - Called after the write operation ends.
Adds a chunk of data to the request body. Generally, the first write operation causes the request headers to be issued on the wire. Adds a chunk of data to the request body. The first write operation may cause
After the first write operation, it is not allowed to add or remove a custom header. the request headers to be issued on the wire. After the first write operation,
it is not allowed to add or remove a custom header.
#### `request.end([chunk][, encoding][, callback])` #### `request.end([chunk][, encoding][, callback])`
@ -214,21 +232,22 @@ After the first write operation, it is not allowed to add or remove a custom hea
* `encoding` String (optional) * `encoding` String (optional)
* `callback` Function (optional) * `callback` Function (optional)
Sends the last chunk of the request data. Subsequent write or end operations will not Sends the last chunk of the request data. Subsequent write or end operations
be allowed. The finish event is emitted just after the end operation. will not be allowed. The `finish` event is emitted just after the end operation.
#### `request.abort()` #### `request.abort()`
Cancels an ongoing HTTP transaction. If the request has already closed, the abort operation will have no effect. Cancels an ongoing HTTP transaction. If the request has already emitted the
Otherwise an ongoing event will emit abort and close events. Additionally, if there is an ongoing response object, `close` event, the abort operation will have no effect. Otherwise an ongoing
it will emit the aborted event. event will emit `abort` and `close` events. Additionally, if there is an ongoing
response object,it will emit the `aborted` event.
## Class: IncomingMessage ## Class: IncomingMessage
`IncomingMessage` represents an HTTP response message. `IncomingMessage` represents an HTTP response message.
It is a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) and therefore It is a [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams)
an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). and consequently an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter).
### Instance Events ### Instance Events
@ -238,7 +257,8 @@ Returns:
* `chunk`: Buffer - A chunk of response body's data. * `chunk`: Buffer - A chunk of response body's data.
The data event is the usual method of transferring response data into applicative code. The `data` event is the usual method of transferring response data into
applicative code.
#### Event 'end' #### Event 'end'
@ -250,13 +270,14 @@ Emitted when a request has been canceled during an ongoing HTTP transaction.
#### Event 'error' #### Event 'error'
Returns Returns:
`error` Error - Typically holds an error string identifying failure root cause. `error` Error - Typically holds an error string identifying failure root cause.
Emitted if an error is encountered while streaming response data events. For instance, Emitted when an error was encountered while streaming response data events. For
if the server closes the underlying socket while streaming the response, an error event instance, if the server closes the underlying while the response is still
will be emitted on the response object and a close event will subsequently follow in the request object. streaming, an `error` event will be emitted on the response object and a `close`
event will subsequently follow on the request object.
### Instance properties ### Instance properties
@ -272,7 +293,8 @@ A String representing the HTTP status message.
#### `response.headers` #### `response.headers`
An Object representing the response HTTP headers. The `headers` object is formatted as follows: An Object representing the response HTTP headers. The `headers` object is
formatted as follows:
* All header names are lowercased. * All header names are lowercased.
* Each header name produces an array-valued property on the headers object. * Each header name produces an array-valued property on the headers object.
@ -280,8 +302,10 @@ An Object representing the response HTTP headers. The `headers` object is format
#### `response.httpVersion` #### `response.httpVersion`
A String indicating the HTTP protocol version number. Typical values are '1.0' or '1.1'. Additionally `httpVersionMajor` and A String indicating the HTTP protocol version number. Typical values are '1.0'
`httpVersionMinor` are two Integer-valued readable properties that return respectively the HTTP major and minor version numbers. or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two
Integer-valued readable properties that return respectively the HTTP major and
minor version numbers.