electron/docs/api/net.md

65 lines
2.2 KiB
Markdown
Raw Normal View History

2016-10-18 19:14:43 +02:00
# net
2016-10-31 15:48:06 -07:00
> Issue HTTP/HTTPS requests using Chromium's native networking library
2016-10-18 19:14:43 +02:00
2016-11-23 11:20:56 -08:00
Process: [Main](../glossary.md#main-process)
2016-11-03 10:26:00 -07:00
2016-10-20 12:30:03 +02:00
The `net` module is a client-side API for issuing HTTP(S) requests. It is
2016-11-01 03:05:23 +00:00
similar to the [HTTP](https://nodejs.org/api/http.html) and
2016-10-20 13:57:08 +02:00
[HTTPS](https://nodejs.org/api/https.html) modules of Node.js but uses
2016-10-31 15:48:06 -07:00
Chromium's native networking library instead of the Node.js implementation,
offering better support for web proxies.
2016-10-20 12:30:03 +02:00
2016-10-31 15:48:06 -07:00
The following is a non-exhaustive list of why you may consider using the `net`
2016-10-20 12:30:03 +02:00
module instead of the native Node.js modules:
2016-10-31 15:48:06 -07:00
2016-10-20 12:30:03 +02:00
* Automatic management of system proxy configuration, support of the wpad
2016-11-01 03:05:23 +00:00
protocol and proxy pac configuration files.
2016-10-18 19:14:43 +02:00
* Automatic tunneling of HTTPS requests.
2016-10-20 12:30:03 +02:00
* Support for authenticating proxies using basic, digest, NTLM, Kerberos or
2016-11-01 03:05:23 +00:00
negotiate authentication schemes.
2016-10-20 12:30:03 +02:00
* Support for traffic monitoring proxies: Fiddler-like proxies used for access
2016-11-01 03:05:23 +00:00
control and monitoring.
2016-10-18 19:14:43 +02:00
The API components (including classes, methods, properties and event names) are similar to those used in
2016-10-20 12:30:03 +02:00
Node.js.
2016-10-19 18:19:28 +02:00
Example usage:
2016-10-19 18:05:38 +02:00
2016-10-18 19:14:43 +02:00
```javascript
2018-09-14 02:10:51 +10:00
const { app } = require('electron')
app.whenReady().then(() => {
2018-09-14 02:10:51 +10:00
const { net } = require('electron')
2016-10-19 18:05:38 +02:00
const request = net.request('https://github.com')
request.on('response', (response) => {
console.log(`STATUS: ${response.statusCode}`)
console.log(`HEADERS: ${JSON.stringify(response.headers)}`)
2016-10-19 18:05:38 +02:00
response.on('data', (chunk) => {
console.log(`BODY: ${chunk}`)
})
response.on('end', () => {
console.log('No more data in response.')
2016-10-19 18:05:38 +02:00
})
2016-10-19 15:34:21 +02:00
})
2016-10-19 18:05:38 +02:00
request.end()
2016-10-18 19:14:43 +02:00
})
```
2016-10-20 13:57:08 +02:00
The `net` API can be used only after the application emits the `ready` event.
Trying to use the module before the `ready` event will throw an error.
2016-10-18 19:14:43 +02:00
## Methods
2016-10-19 15:34:21 +02:00
The `net` module has the following methods:
### `net.request(options)`
* `options` (ClientRequestConstructorOptions | String) - The `ClientRequest` constructor options.
2016-10-19 15:34:21 +02:00
2016-12-19 09:40:07 -08:00
Returns [`ClientRequest`](./client-request.md)
2016-10-18 19:14:43 +02:00
2016-11-10 12:25:26 -08:00
Creates a [`ClientRequest`](./client-request.md) instance using the provided
`options` which are directly forwarded to the `ClientRequest` constructor.
The `net.request` method would be used to issue both secure and insecure HTTP
requests according to the specified protocol scheme in the `options` object.