2013-09-09 07:35:57 +00:00
|
|
|
# protocol
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
The `protocol` module can register a custom protocol or intercept an existing
|
|
|
|
protocol.
|
2013-09-03 10:22:40 +00:00
|
|
|
|
|
|
|
An example of implementing a protocol that has the same effect with the
|
|
|
|
`file://` protocol:
|
|
|
|
|
|
|
|
```javascript
|
2015-06-09 16:10:02 +00:00
|
|
|
var app = require('app');
|
|
|
|
var path = require('path');
|
2014-05-18 10:33:10 +00:00
|
|
|
|
2015-03-24 11:56:12 +00:00
|
|
|
app.on('ready', function() {
|
2014-05-18 10:33:10 +00:00
|
|
|
var protocol = require('protocol');
|
2015-08-14 05:44:18 +00:00
|
|
|
protocol.registerFileProtocol('atom', function(request, callback) {
|
|
|
|
var url = request.url.substr(7);
|
|
|
|
callback({path: path.normalize(__dirname + '/' + url)});
|
|
|
|
}, function (error) {
|
|
|
|
if (error)
|
|
|
|
console.error('Failed to register protocol')
|
2014-05-18 10:33:10 +00:00
|
|
|
});
|
2013-09-03 10:22:40 +00:00
|
|
|
});
|
|
|
|
```
|
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
**Note:** This module can only be used after the `ready` event was emitted.
|
2013-09-20 10:36:16 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
## protocol.registerStandardSchemes(schemes)
|
|
|
|
|
|
|
|
* `schemes` Array - Custom schemes to be registered as standard schemes.
|
|
|
|
|
|
|
|
A standard scheme adheres to what RFC 3986 calls
|
|
|
|
[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3). This
|
|
|
|
includes `file:` and `filesystem:`.
|
|
|
|
|
|
|
|
## protocol.registerFileProtocol(scheme, handler[, completion])
|
2013-09-03 10:22:40 +00:00
|
|
|
|
|
|
|
* `scheme` String
|
|
|
|
* `handler` Function
|
2015-08-14 05:44:18 +00:00
|
|
|
* `completion` Function
|
|
|
|
|
|
|
|
Registers a protocol of `scheme` that will send file as response, the `handler`
|
|
|
|
will be called with `handler(request, callback)` when a `request` is going to be
|
|
|
|
created with `scheme`, and `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-14 05:44:18 +00:00
|
|
|
To handle the `request`, the `callback` should be called with either file's path
|
|
|
|
or an object that has `path` property, e.g. `callback(filePath)` or
|
|
|
|
`callback({path: filePath})`.
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
When `callback` is called with nothing, or a number, or an object that has
|
|
|
|
`error` property, the `request` will be failed with the `error` number you
|
|
|
|
specified. For the available error numbers you can use, please check:
|
|
|
|
https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-07-16 13:32:09 +00:00
|
|
|
By default the scheme is treated like `http:`, which is parsed differently
|
|
|
|
from protocols that follows "generic URI syntax" like `file:`, so you probably
|
|
|
|
want to call `protocol.registerStandardSchemes` to make your scheme treated as
|
|
|
|
standard scheme.
|
|
|
|
|
2015-08-14 05:44:18 +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
|
|
|
|
* `completion` Function
|
2015-06-12 07:58:23 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
Registers a protocol of `scheme` that will send `Buffer` as response, the
|
|
|
|
`callback` should be called with either an `Buffer` object, or an object that
|
|
|
|
has `data`, `mimeType`, `chart` 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
|
|
|
|
protocol.registerBufferProtocol('atom', function(request, callback) {
|
|
|
|
callback({mimeType: 'text/html', data: new Buffer('<h5>Response</h5>')});
|
|
|
|
}, function (error) {
|
|
|
|
if (error)
|
|
|
|
console.error('Failed to register protocol')
|
|
|
|
});
|
|
|
|
```
|
2015-06-12 07:58:23 +00:00
|
|
|
|
2015-08-14 05:44:18 +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
|
|
|
|
* `completion` Function
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
Registers a protocol of `scheme` that will send `String` as response, the
|
|
|
|
`callback` should be called with either a `String`, or an object that
|
|
|
|
has `data`, `mimeType`, `chart` properties.
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
## protocol.registerHttpProtocol(scheme, handler[, completion])
|
2013-09-03 10:22:40 +00:00
|
|
|
|
|
|
|
* `scheme` String
|
|
|
|
* `handler` Function
|
2015-08-14 05:44:18 +00:00
|
|
|
* `completion` Function
|
|
|
|
|
|
|
|
Registers a protocol of `scheme` that will send a HTTP request as response, the
|
|
|
|
`callback` should be called with an object that has `url`, `method`, `referer`,
|
|
|
|
`session` properties.
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
By default the HTTP request will reuse current session, if you want the request
|
|
|
|
to have different session you should specify `session` to `null`.
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
## protocol.unregisterProtocol(scheme[, completion])
|
2013-09-03 10:22:40 +00:00
|
|
|
|
|
|
|
* `scheme` String
|
2015-08-14 05:44:18 +00:00
|
|
|
* `completion` Function
|
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-14 05:44:18 +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-14 05:44:18 +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-21 12:16:56 +00:00
|
|
|
* `completion` Function
|
2013-09-03 10:22:40 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
|
|
|
which sends file as response.
|
2015-03-16 12:53:45 +00:00
|
|
|
|
2015-08-14 05:44:18 +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-21 12:16:56 +00:00
|
|
|
* `completion` Function
|
2015-08-14 05:44:18 +00:00
|
|
|
|
|
|
|
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
|
|
|
which sends String as response.
|
2015-03-16 12:53:45 +00:00
|
|
|
|
2015-08-14 05:44:18 +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-21 12:16:56 +00:00
|
|
|
* `completion` Function
|
2015-06-17 03:32:39 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
|
|
|
which sends `Buffer` as response.
|
2015-06-17 03:32:39 +00:00
|
|
|
|
2015-08-14 05:44:18 +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-21 12:16:56 +00:00
|
|
|
* `completion` Function
|
2015-05-07 07:42:35 +00:00
|
|
|
|
2015-08-14 05:44:18 +00:00
|
|
|
Intercepts `scheme` protocol and use `handler` as the protocol's new handler
|
|
|
|
which sends a new HTTP request as response.
|
2015-05-07 07:42:35 +00:00
|
|
|
|
2015-08-14 05:44:18 +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.
|