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
|
|
|
|
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
|
2016-05-10 16:57:55 +00:00
|
|
|
const {app, protocol} = require('electron');
|
|
|
|
|
const path = require('path');
|
2016-05-09 01:20:08 +00:00
|
|
|
|
|
|
|
|
app.on('ready', function () {
|
|
|
|
|
protocol.registerFileProtocol('atom', function (request, callback) {
|
2016-05-10 16:57:55 +00:00
|
|
|
const url = request.url.substr(7);
|
|
|
|
|
callback({path: path.normalize(__dirname + '/' + url)});
|
2016-05-09 01:20:08 +00:00
|
|
|
}, function (error) {
|
|
|
|
|
if (error)
|
2016-05-10 16:57:55 +00:00
|
|
|
console.error('Failed to register protocol');
|
|
|
|
|
});
|
|
|
|
|
});
|
2013-09-03 10:22:40 +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:
|
|
|
|
|
|
|
|
|
|
### `protocol.registerStandardSchemes(schemes)`
|
2015-08-14 05:44:18 +00:00
|
|
|
|
|
|
|
|
* `schemes` Array - Custom schemes to be registered as standard schemes.
|
|
|
|
|
|
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>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
So if you want to register a custom protocol to replace the `http` protocol, you
|
|
|
|
|
have to register it as standard scheme:
|
|
|
|
|
|
|
|
|
|
```javascript
|
2016-05-10 16:57:55 +00:00
|
|
|
protocol.registerStandardSchemes(['atom']);
|
2016-05-09 01:20:08 +00:00
|
|
|
app.on('ready', function () {
|
2016-05-10 16:57:55 +00:00
|
|
|
protocol.registerHttpProtocol('atom', ...);
|
|
|
|
|
});
|
2016-05-09 01:20:08 +00:00
|
|
|
```
|
2016-05-07 20:01:04 +00:00
|
|
|
|
2016-05-09 01:20:08 +00:00
|
|
|
**Note:** This method can only be used before the `ready` event of the `app`
|
|
|
|
|
module gets emitted.
|
2015-08-14 05:44:18 +00:00
|
|
|
|
2015-12-08 19:21:46 +00:00
|
|
|
### `protocol.registerServiceWorkerSchemes(schemes)`
|
|
|
|
|
|
|
|
|
|
* `schemes` Array - Custom schemes to be registered to handle service workers.
|
|
|
|
|
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
|
|
|
2016-01-28 10:59:07 +00:00
|
|
|
* `request` Object
|
|
|
|
|
* `url` String
|
|
|
|
|
* `referrer` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `uploadData` Array (optional)
|
|
|
|
|
* `callback` Function
|
|
|
|
|
|
|
|
|
|
The `uploadData` is an array of `data` objects:
|
|
|
|
|
|
|
|
|
|
* `data` Object
|
|
|
|
|
* `bytes` Buffer - Content being sent.
|
|
|
|
|
* `file` String - Path of file being uploaded.
|
|
|
|
|
|
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
|
2015-08-14 05:44:18 +00:00
|
|
|
`callback({path: filePath})`.
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
2016-05-04 17:59:02 +00:00
|
|
|
protocol.registerBufferProtocol('atom', (request, callback) => {
|
2015-08-14 05:44:18 +00:00
|
|
|
callback({mimeType: 'text/html', data: new Buffer('<h5>Response</h5>')});
|
2016-05-04 17:59:02 +00:00
|
|
|
}, (error) => {
|
2015-08-14 05:44:18 +00:00
|
|
|
if (error)
|
2016-05-10 16:57:55 +00:00
|
|
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
|
|
|
2016-01-28 10:59:07 +00:00
|
|
|
* `redirectRequest` Object
|
|
|
|
|
* `url` String
|
|
|
|
|
* `method` String
|
|
|
|
|
* `session` Object (optional)
|
2016-01-28 10:59:58 +00:00
|
|
|
* `uploadData` Object (optional)
|
2016-01-28 10:59:07 +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.
|
|
|
|
|
|
2015-12-06 20:27:02 +00:00
|
|
|
* `uploadData` object
|
|
|
|
|
* `contentType` String - MIME type of the content.
|
2016-01-28 10:59:07 +00:00
|
|
|
* `data` String - Content to be sent.
|
2015-12-06 20:27:02 +00:00
|
|
|
|
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)
|
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
|
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
|
|
|
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
2015-08-29 05:03:39 +00:00
|
|
|
* `completion` Function (optional)
|
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
|
|
|
|
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
|
2015-08-21 12:16:56 +00:00
|
|
|
* `completion` Function
|
2015-05-07 07:42:35 +00:00
|
|
|
|
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
|
