From 7d97bb6fe0a6feef886d927ea894bcb2f3521577 Mon Sep 17 00:00:00 2001
From: Cheng Zhao <zcbenz@gmail.com>
Date: Fri, 14 Aug 2015 13:44:18 +0800
Subject: [PATCH] docs: Rewrite docs for new protocol API

---
 docs/api/protocol.md | 175 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 97 insertions(+), 78 deletions(-)

diff --git a/docs/api/protocol.md b/docs/api/protocol.md
index 03e9796..a256bf3 100644
--- a/docs/api/protocol.md
+++ b/docs/api/protocol.md
@@ -1,7 +1,7 @@
 # protocol
 
-The `protocol` module can register a new protocol or intercept an existing
-protocol, so you can customize the response to the requests for various protocols.
+The `protocol` module can register a custom protocol or intercept an existing
+protocol.
 
 An example of implementing a protocol that has the same effect with the
 `file://` protocol:
@@ -12,130 +12,149 @@ var path = require('path');
 
 app.on('ready', function() {
     var protocol = require('protocol');
-    protocol.registerProtocol('atom', function(request) {
-      var url = request.url.substr(7)
-      return new protocol.RequestFileJob(path.normalize(__dirname + '/' + url));
-    }, function (error, scheme) {
-      if (!error)
-        console.log(scheme, ' registered successfully')
+    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')
     });
 });
 ```
 
-**Note:** This module can only be used after the `ready` event
-was emitted.
+**Note:** This module can only be used after the `ready` event was emitted.
 
-## protocol.registerProtocol(scheme, handler, callback)
+## 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])
 
 * `scheme` String
 * `handler` Function
-* `callback` Function
+* `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.
 
-Registers a custom protocol of `scheme`, the `handler` would be called with
-`handler(request)` when the a request with registered `scheme` is made.
+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})`.
 
-You need to return a request job in the `handler` to specify which type of
-response you would like to send.
+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
 
 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.
 
-## protocol.unregisterProtocol(scheme, callback)
+## protocol.registerBufferProtocol(scheme, handler[, completion])
 
 * `scheme` String
-* `callback` Function
-
-Unregisters the custom protocol of `scheme`.
-
-## protocol.registerStandardSchemes(value)
+* `handler` Function
+* `completion` Function
 
-* `value` Array
+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.
 
-`value` is an array of custom schemes to be registered as standard schemes.
+Example:
 
-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:`.
+```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')
+});
+```
 
-## protocol.isHandledProtocol(scheme, callback)
+## protocol.registerStringProtocol(scheme, handler[, completion])
 
 * `scheme` String
-* `callback` Function
+* `handler` Function
+* `completion` Function
 
-`callback` returns a boolean whether the `scheme` can be handled already.
+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.
 
-## protocol.interceptProtocol(scheme, handler, callback)
+## protocol.registerHttpProtocol(scheme, handler[, completion])
 
 * `scheme` String
 * `handler` Function
-* `callback` Function
+* `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.
 
-Intercepts an existing protocol with `scheme`, returning `null` or `undefined`
-in `handler` would use the original protocol handler to handle the request.
+By default the HTTP request will reuse current session, if you want the request
+to have different session you should specify `session` to `null`.
 
-## protocol.uninterceptProtocol(scheme, callback)
+## protocol.unregisterProtocol(scheme[, completion])
 
 * `scheme` String
-* `callback` Function
+* `completion` Function
 
-Unintercepts a protocol.
+Unregisters the custom protocol of `scheme`.
 
-## Class: protocol.RequestFileJob(path)
+## protocol.isProtocolHandled(scheme, callback)
 
-* `path` String
+* `scheme` String
+* `callback` Function
 
-Create a request job which would query a file of `path` and set corresponding
-mime types.
+The `callback` will be called with a boolean that indicates whether there is
+already a handler for `scheme`.
 
-## Class: protocol.RequestStringJob(options)
+## protocol.interceptFileProtocol(scheme, handler[, completion])
 
-* `options` Object
-  * `mimeType` String - Default is `text/plain`
-  * `charset` String - Default is `UTF-8`
-  * `data` String
+* `scheme` String
+* `handler` Function
+* `callback` Function
 
-Create a request job which sends a string as response.
+Intercepts `scheme` protocol and use `handler` as the protocol's new handler
+which sends file as response.
 
-## Class: protocol.RequestBufferJob(options)
+## protocol.interceptStringProtocol(scheme, handler[, completion])
 
-* `options` Object
-  * `mimeType` String - Default is `application/octet-stream`
-  * `encoding` String - Default is `UTF-8`
-  * `data` Buffer
+* `scheme` String
+* `handler` Function
+* `callback` Function
+
+Intercepts `scheme` protocol and use `handler` as the protocol's new handler
+which sends String as response.
 
-Create a request job which sends a buffer as response.
+## protocol.interceptBufferProtocol(scheme, handler[, completion])
 
-## Class: protocol.RequestHttpJob(options)
+* `scheme` String
+* `handler` Function
+* `callback` Function
 
-* `options` Object
-  * `session` [Session](browser-window.md#class-session) - By default it is
-    the app's default session, setting it to `null` will create a new session
-    for the requests
-  * `url` String
-  * `method` String - Default is `GET`
-  * `referrer` String
+Intercepts `scheme` protocol and use `handler` as the protocol's new handler
+which sends `Buffer` as response.
 
-Send a request to `url` and pipe the response back.
+## protocol.interceptHttpProtocol(scheme, handler[, completion])
 
-## Class: protocol.RequestErrorJob(code)
+* `scheme` String
+* `handler` Function
+* `callback` Function
 
-* `code` Integer
+Intercepts `scheme` protocol and use `handler` as the protocol's new handler
+which sends a new HTTP request as response.
 
-Create a request job which sets appropriate network error message to console.
-Default message is `net::ERR_NOT_IMPLEMENTED`. Code should be in the following
-range.
+## protocol.uninterceptProtocol(scheme[, completion])
 
-* Ranges:
-  * 0- 99 System related errors
-  * 100-199 Connection related errors
-  * 200-299 Certificate errors
-  * 300-399 HTTP errors
-  * 400-499 Cache errors
-  * 500-599 ?
-  * 600-699 FTP errors
-  * 700-799 Certificate manager errors
-  * 800-899 DNS resolver errors
+* `scheme` String
+* `callback` Function
 
-Check the [network error list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h) for code and message relations.
+Remove the interceptor installed for `scheme` and restore its original handler.
-- 
2.7.4