Added WHEREIS to external special remote protocol.

1 files changed, 17 insertions, 4 deletions

diff --git a/doc/design/external_special_remote_protocol.mdwn b/doc/design/external_special_remote_protocol.mdwn
index d6aa9904a..524271d10 100644
--- a/doc/design/external_special_remote_protocol.mdwn
+++ b/doc/design/external_special_remote_protocol.mdwn
@@ -133,6 +133,15 @@ replying with `UNSUPPORTED-REQUEST` is acceptable.
   Asks the remote to check if the url's content can currently be downloaded
   (without downloading it). The remote replies with one of `CHECKURL-FAILURE`,
   `CHECKURL-CONTENTS`, or `CHECKURL-MULTI`.
+* `WHEREIS Key`
+  Asks the remote to provide any information it can about ways to access
+  the content of a key stored in it, such as eg, public urls.
+  This will be displayed to the user by eg, `git annex whereis`. The remote
+  replies with `WHEREIS-SUCCESS` or `WHEREIS-FAILURE`.  
+  Note that users expect `git annex whereis` to run fast, without eg,
+  network access.  
+  This is not needed when `SETURIPRESENT` is used, since such uris are
+  automatically displayed by `git annex whereis`.  
 
 More optional requests may be added, without changing the protocol version,
 so if an unknown request is seen, reply with `UNSUPPORTED-REQUEST`.
@@ -193,6 +202,12 @@ while it's handling a request.
   can contain spaces.
 * `CHECKURL-FAILURE`  
   Indicates that the requested url could not be accessed.
+* `WHEREIS-SUCCESS String`  
+  Indicates a location of a key. Typically an url, the string can
+  be anything that it makes sense to display to the user about content
+  stored in the special remote.
+* `WHEREIS-FAILURE`  
+  Indicates that no location is known for a key.
 * `UNSUPPORTED-REQUEST`  
   Indicates that the special remote does not know how to handle a request.
 
@@ -281,11 +296,9 @@ in control.
   Records that the key can no longer be downloaded from the specified
   URL.
 * `SETURIPRESENT Key Uri`  
-  Records a special URI where the Key can be downloaded from.  
+  Records an URI where the Key can be downloaded from.  
   For example, "ipfs:ADDRESS" is used for the ipfs special remote;
-  its CLAIMURL handler checks for such URIS and claims them. Setting
-  it present as an URI makes `git annex whereis` display the URI
-  as belonging to the special remote.
+  its CLAIMURL handler checks for such URIS and claims them.
 * `SETURIMISSING Key Uri`  
   Records that the key can no longer be downloaded from the specified
   URI.