2013-09-09 07:35:57 +00:00
# protocol
2013-09-03 10:22:40 +00:00
2016-04-22 18:42:54 +00:00
> Register a custom protocol and intercept existing protocol requests.
2013-09-03 10:22:40 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main ](../glossary.md#main-process )
2016-11-03 17:26:00 +00:00
2015-08-29 05:03:39 +00:00
An example of implementing a protocol that has the same effect as the
2013-09-03 10:22:40 +00:00
`file://` protocol:
```javascript
2018-09-13 16:10:51 +00:00
const { app, protocol } = require('electron')
2016-07-26 01:39:25 +00:00
const path = require('path')
2016-05-09 01:20:08 +00:00
2016-05-10 17:15:09 +00:00
app.on('ready', () => {
protocol.registerFileProtocol('atom', (request, callback) => {
2016-07-26 01:39:25 +00:00
const url = request.url.substr(7)
2018-09-13 16:10:51 +00:00
callback({ path: path.normalize(`${__dirname}/${url}`) })
2016-05-10 17:15:09 +00:00
}, (error) => {
2016-07-26 01:39:25 +00:00
if (error) console.error('Failed to register protocol')
})
})
2013-09-03 10:22:40 +00:00
```
2016-07-26 01:39:25 +00:00
2016-05-09 01:20:08 +00:00
**Note:** All methods unless specified can only be used after the `ready` event
of the `app` module gets emitted.
2013-09-20 10:36:16 +00:00
2015-08-29 05:03:39 +00:00
## Methods
The `protocol` module has the following methods:
2019-01-30 20:54:18 +00:00
### `protocol.registerSchemesAsPrivileged(customSchemes)`
2015-08-14 05:44:18 +00:00
2019-01-30 20:54:18 +00:00
* `customSchemes` [CustomScheme[]](structures/custom-scheme.md)
2019-01-29 07:11:01 +00:00
**Note:** This method can only be used before the `ready` event of the `app`
module gets emitted and can be called only once.
Registers the `scheme` as standard, secure, bypasses content security policy for resources,
allows registering ServiceWorker and supports fetch API.
2019-01-30 20:54:18 +00:00
Specify a privilege with the value of `true` to enable the capability.
2019-01-29 07:11:01 +00:00
An example of registering a privileged scheme, with bypassing Content Security Policy:
```javascript
const { protocol } = require('electron')
protocol.registerSchemesAsPrivileged([
2019-01-30 20:54:18 +00:00
{ scheme: 'foo', privileges: { bypassCSP: true } }
2019-01-29 07:11:01 +00:00
])
```
2015-08-14 05:44:18 +00:00
2016-05-09 01:20:08 +00:00
A standard scheme adheres to what RFC 3986 calls [generic URI
syntax](https://tools.ietf.org/html/rfc3986#section-3). For example `http` and
`https` are standard schemes, while `file` is not.
Registering a scheme as standard, will allow relative and absolute resources to
be resolved correctly when served. Otherwise the scheme will behave like the
`file` protocol, but without the ability to resolve relative URLs.
For example when you load following page with custom protocol without
registering it as standard scheme, the image will not be loaded because
non-standard schemes can not recognize relative URLs:
```html
< body >
< img src = 'test.png' >
< / body >
```
2016-08-24 16:03:44 +00:00
Registering a scheme as standard will allow access to files through the
[FileSystem API][file-system-api]. Otherwise the renderer will throw a security
2016-09-21 18:50:34 +00:00
error for the scheme.
By default web storage apis (localStorage, sessionStorage, webSQL, indexedDB, cookies)
are disabled for non standard schemes. So in general if you want to register a
2019-01-29 07:11:01 +00:00
custom protocol to replace the `http` protocol, you have to register it as a standard scheme.
2015-12-08 19:21:46 +00:00
2019-02-12 14:31:53 +00:00
`protocol.registerSchemesAsPriviliged` can be used to replicate the functionality of the previous `protocol.registerStandardSchemes` , `webFrame.registerURLSchemeAs*` and `protocol.registerServiceWorkerSchemes` functions that existed prior to Electron 5.0.0, for example:
2019-02-12 18:49:47 +00:00
**before (< = v4.x)**
```javascript
2019-02-12 14:31:53 +00:00
// Main
protocol.registerStandardSchemes(['scheme1', 'scheme2'], { secure: true })
// Renderer
webFrame.registerURLSchemeAsPrivileged('scheme1', { secure: true })
webFrame.registerURLSchemeAsPrivileged('scheme2', { secure: true })
2019-02-12 18:49:47 +00:00
```
2019-02-12 14:31:53 +00:00
2019-02-12 18:49:47 +00:00
**after (>= v5.x)**
```javascript
2019-02-12 14:31:53 +00:00
protocol.registerSchemesAsPriviliged([
{ scheme: 'scheme1', privileges: { standard: true, secure: true } },
2019-02-12 18:49:47 +00:00
{ scheme: 'scheme2', privileges: { standard: true, secure: true } }
2019-02-12 14:31:53 +00:00
])
```
2015-08-29 05:03:39 +00:00
### `protocol.registerFileProtocol(scheme, handler[, completion])`
2013-09-03 10:22:40 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `filePath` String (optional)
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-08-14 05:44:18 +00:00
2015-09-02 02:08:31 +00:00
Registers a protocol of `scheme` that will send the file as a response. The
`handler` will be called with `handler(request, callback)` when a `request` is
going to be created with `scheme` . `completion` will be called with
`completion(null)` when `scheme` is successfully registered or
`completion(error)` when failed.
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
To handle the `request` , the `callback` should be called with either the file's
path or an object that has a `path` property, e.g. `callback(filePath)` or
2018-12-19 06:17:02 +00:00
`callback({ path: filePath })` . The object may also have a `headers` property
which gives a list of strings for the response headers, e.g.
`callback({ path: filePath, headers: ["Content-Security-Policy: default-src 'none'"]})` .
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
When `callback` is called with nothing, a number, or an object that has an
`error` property, the `request` will fail with the `error` number you
2015-09-02 02:08:31 +00:00
specified. For the available error numbers you can use, please see the
2016-01-28 10:59:07 +00:00
[net error list][net-error].
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
By default the `scheme` is treated like `http:` , which is parsed differently
2015-09-02 02:08:31 +00:00
than protocols that follow the "generic URI syntax" like `file:` , so you
probably want to call `protocol.registerStandardSchemes` to have your scheme
treated as a standard scheme.
2015-07-16 13:32:09 +00:00
2015-08-29 05:03:39 +00:00
### `protocol.registerBufferProtocol(scheme, handler[, completion])`
2013-09-03 10:22:40 +00:00
* `scheme` String
2015-08-14 05:44:18 +00:00
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
2016-11-25 12:17:31 +00:00
* `buffer` (Buffer | [MimeTypedBuffer ](structures/mime-typed-buffer.md )) (optional)
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-06-12 07:58:23 +00:00
2016-01-28 10:59:07 +00:00
Registers a protocol of `scheme` that will send a `Buffer` as a response.
The usage is the same with `registerFileProtocol` , except that the `callback`
should be called with either a `Buffer` object or an object that has the `data` ,
`mimeType` , and `charset` properties.
2015-06-12 07:58:23 +00:00
2015-08-14 05:44:18 +00:00
Example:
2015-07-16 13:32:09 +00:00
2015-08-14 05:44:18 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { protocol } = require('electron')
2016-07-26 01:39:25 +00:00
2016-05-04 17:59:02 +00:00
protocol.registerBufferProtocol('atom', (request, callback) => {
2018-09-13 16:10:51 +00:00
callback({ mimeType: 'text/html', data: Buffer.from('< h5 > Response< / h5 > ') })
2016-05-04 17:59:02 +00:00
}, (error) => {
2016-07-26 01:39:25 +00:00
if (error) console.error('Failed to register protocol')
})
2015-08-14 05:44:18 +00:00
```
2015-06-12 07:58:23 +00:00
2015-08-29 05:03:39 +00:00
### `protocol.registerStringProtocol(scheme, handler[, completion])`
2013-09-03 10:22:40 +00:00
* `scheme` String
2015-08-14 05:44:18 +00:00
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `data` String (optional)
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2013-09-03 10:22:40 +00:00
2016-01-28 10:59:07 +00:00
Registers a protocol of `scheme` that will send a `String` as a response.
The usage is the same with `registerFileProtocol` , except that the `callback`
should be called with either a `String` or an object that has the `data` ,
`mimeType` , and `charset` properties.
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
### `protocol.registerHttpProtocol(scheme, handler[, completion])`
2013-09-03 10:22:40 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
2018-10-30 18:37:49 +00:00
* `headers` Object
2016-10-13 06:30:57 +00:00
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `redirectRequest` Object
* `url` String
* `method` String
* `session` Object (optional)
* `uploadData` Object (optional)
* `contentType` String - MIME type of the content.
* `data` String - Content to be sent.
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-08-14 05:44:18 +00:00
2015-08-29 05:03:39 +00:00
Registers a protocol of `scheme` that will send an HTTP request as a response.
2016-01-28 10:59:07 +00:00
The usage is the same with `registerFileProtocol` , except that the `callback`
should be called with a `redirectRequest` object that has the `url` , `method` ,
2015-12-06 20:27:02 +00:00
`referrer` , `uploadData` and `session` properties.
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
By default the HTTP request will reuse the current session. If you want the
request to have a different session you should set `session` to `null` .
2013-09-03 10:22:40 +00:00
2016-01-28 10:59:07 +00:00
For POST requests the `uploadData` object must be provided.
2017-11-10 16:21:09 +00:00
### `protocol.registerStreamProtocol(scheme, handler[, completion])`
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `headers` Object
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `stream` (ReadableStream | [StreamProtocolResponse ](structures/stream-protocol-response.md )) (optional)
* `completion` Function (optional)
* `error` Error
Registers a protocol of `scheme` that will send a `Readable` as a response.
The usage is similar to the other `register{Any}Protocol` , except that the
`callback` should be called with either a `Readable` object or an object that
has the `data` , `statusCode` , and `headers` properties.
Example:
```javascript
2018-09-13 16:10:51 +00:00
const { protocol } = require('electron')
const { PassThrough } = require('stream')
2017-11-10 16:21:09 +00:00
function createStream (text) {
2017-11-29 10:58:24 +00:00
const rv = new PassThrough() // PassThrough is also a Readable stream
2017-11-10 16:21:09 +00:00
rv.push(text)
rv.push(null)
return rv
}
protocol.registerStreamProtocol('atom', (request, callback) => {
callback({
statusCode: 200,
headers: {
'content-type': 'text/html'
},
data: createStream('< h5 > Response< / h5 > ')
})
}, (error) => {
if (error) console.error('Failed to register protocol')
})
```
It is possible to pass any object that implements the readable stream API (emits
`data` /`end`/`error` events). For example, here's how a file could be returned:
```javascript
2018-09-13 16:10:51 +00:00
const { protocol } = require('electron')
2017-11-10 16:21:09 +00:00
const fs = require('fs')
protocol.registerStreamProtocol('atom', (request, callback) => {
callback(fs.createReadStream('index.html'))
}, (error) => {
if (error) console.error('Failed to register protocol')
})
```
2015-08-29 05:03:39 +00:00
### `protocol.unregisterProtocol(scheme[, completion])`
2013-09-03 10:22:40 +00:00
* `scheme` String
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2013-09-03 10:22:40 +00:00
2015-08-14 05:44:18 +00:00
Unregisters the custom protocol of `scheme` .
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
### `protocol.isProtocolHandled(scheme, callback)`
2013-09-03 10:22:40 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
* `callback` Function
2018-10-29 19:23:23 +00:00
* `handled` Boolean
2013-09-03 10:22:40 +00:00
2015-08-14 05:44:18 +00:00
The `callback` will be called with a boolean that indicates whether there is
already a handler for `scheme` .
2013-09-03 10:22:40 +00:00
2019-01-17 17:05:10 +00:00
**[Deprecated Soon](promisification.md)**
### `protocol.isProtocolHandled(scheme)`
* `scheme` String
Returns `Promise<Boolean>` - fulfilled with a boolean that indicates whether there is
already a handler for `scheme` .
2015-08-29 05:03:39 +00:00
### `protocol.interceptFileProtocol(scheme, handler[, completion])`
2013-09-03 10:22:40 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `filePath` String
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2013-09-03 10:22:40 +00:00
2015-08-29 05:03:39 +00:00
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a file as a response.
2015-03-16 12:53:45 +00:00
2015-08-29 05:03:39 +00:00
### `protocol.interceptStringProtocol(scheme, handler[, completion])`
2015-03-16 12:53:45 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `data` String (optional)
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-08-14 05:44:18 +00:00
2015-08-29 05:03:39 +00:00
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `String` as a response.
2015-03-16 12:53:45 +00:00
2015-10-08 03:14:04 +00:00
### `protocol.interceptBufferProtocol(scheme, handler[, completion])`
2015-05-07 07:42:35 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `buffer` Buffer (optional)
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-06-17 03:32:39 +00:00
2015-08-29 05:03:39 +00:00
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `Buffer` as a response.
2015-06-17 03:32:39 +00:00
2015-10-08 03:14:04 +00:00
### `protocol.interceptHttpProtocol(scheme, handler[, completion])`
2015-06-17 03:32:39 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
* `handler` Function
2016-10-13 06:30:57 +00:00
* `request` Object
* `url` String
2018-10-30 18:37:49 +00:00
* `headers` Object
2016-10-13 06:30:57 +00:00
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `redirectRequest` Object
* `url` String
* `method` String
* `session` Object (optional)
* `uploadData` Object (optional)
* `contentType` String - MIME type of the content.
* `data` String - Content to be sent.
2015-08-29 05:03:39 +00:00
* `completion` Function (optional)
2016-10-13 06:30:57 +00:00
* `error` Error
2015-05-07 07:42:35 +00:00
2015-08-29 05:03:39 +00:00
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a new HTTP request as a response.
2015-05-07 07:42:35 +00:00
2017-11-10 16:21:09 +00:00
### `protocol.interceptStreamProtocol(scheme, handler[, completion])`
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `headers` Object
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `stream` (ReadableStream | [StreamProtocolResponse ](structures/stream-protocol-response.md )) (optional)
* `completion` Function (optional)
* `error` Error
Same as `protocol.registerStreamProtocol` , except that it replaces an existing
protocol handler.
2015-10-08 03:14:04 +00:00
### `protocol.uninterceptProtocol(scheme[, completion])`
2015-05-07 07:42:35 +00:00
2015-08-14 05:44:18 +00:00
* `scheme` String
2016-10-13 06:30:57 +00:00
* `completion` Function (optional)
* `error` Error
2015-08-14 05:44:18 +00:00
Remove the interceptor installed for `scheme` and restore its original handler.
2016-01-28 10:59:07 +00:00
[net-error]: https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h
2016-08-24 16:03:44 +00:00
[file-system-api]: https://developer.mozilla.org/en-US/docs/Web/API/LocalFileSystem
