[lsd0004] branch master updated: -API description

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository lsd0004.

The following commit(s) were added to refs/heads/master by this push:
     new 566b586  -API description
566b586 is described below

commit 566b5860a276fa7b5affa13ff2000dbe87299785
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Thu Mar 10 08:26:40 2022 +0100

    -API description
---
 draft-schanzen-r5n.xml | 63 ++++++++++++++++++++++++++------------------------
 1 file changed, 33 insertions(+), 30 deletions(-)

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 542d019..d1de3c7 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -325,26 +325,26 @@ Connectivity | |Underlay|  |Underlay|
           A basic GET procedure may be exposed as:
         </t>
         <t>
-          <tt>GET(Query-Key) -> Results as List</tt>
+          <tt>GET(Query-Key, Block-Type) -> Results as List</tt>
         </t>
         <t>
-          The procedure requires at least a Query-Key to initiate a lookup:
+          The procedure typically takes at least two arguments to initiate a 
lookup:
         </t>
         <dl>
           <dt><tt>QueryKey</tt>:</dt>
           <dd>
             the 512-bit key to look for in the DHT.
           </dd>
+          <dt>Block-Type:</dt>
+          <dd>
+            the type of block to look for, possibly "any".
+          </dd>
         </dl>
         <t>
-          The procedure may allow a set of optional parameters in order to
+          The GET procedure may allow a set of optional parameters in order to
           control or modify the query:
         </t>
         <dl>
-          <dt>Block-Type:</dt>
-          <dd>
-            the type of block to look for, possibly "any".
-          </dd>
           <dt>Replication-Level:</dt>
           <dd>
             An integer which controls how many nearest peers the request
@@ -371,14 +371,16 @@ Connectivity | |Underlay|  |Underlay|
           </dd>
           <dt>Result-Filter:</dt>
           <dd>
-            allows to indicate results which are not relevant anymore to the
+            allows applications to indicate results which are not relevant 
anymore to the
             caller (see <xref target="result_bloomfilter"/>).
           </dd>
         </dl>
         <t>
-         If the procedure is implemented synchronuously, it may return a list
-         of results. If it is implemented asynchronuously, it may return
-         individual results. A single result commonly consists of:</t>
+          The GET procedure should be implemented as an asynchronous
+         operation that returns individual results as they are found
+         in the DHT.  It should terminate only once the application
+         explicitly cancels the operation.  A single result commonly
+         consists of:</t>
         <dl>
           <dt>Block-Type:</dt>
           <dd>
@@ -386,7 +388,7 @@ Connectivity | |Underlay|  |Underlay|
           </dd>
           <dt>Block-Data:</dt>
           <dd>
-            the block payload. Contents are defined by the Block-Type.
+            the block payload. Contents are specific to the 
<tt>Block-Type</tt>.
           </dd>
           <dt>Expiration:</dt>
           <dd>
@@ -394,18 +396,23 @@ Connectivity | |Underlay|  |Underlay|
           </dd>
           <dt>Key:</dt>
           <dd>
-            the key of the result. This may be different from the
-            Query-Key, for example if a flag for approximate matches was
-            set.
+            the key under which the block was stored. This may be different 
from the
+            key that was queried if the flag for approximate matches was set.
           </dd>
           <dt>GET-Path:</dt>
           <dd>
-            is a signed path the query took through the network.
+            is a signed path the query took through the network. Only 
available if
+           the flag for tracking the path was set by the peer calling
+           the PUT procedure.
           </dd>
           <dt>PUT-Path:</dt>
           <dd>
             is a signed path the PUT-Request of this data took through the
-            network.
+            network. Only available if the flag for tracking the path
+           was set for the GET procedure.
+           As the block was cached by the node at the end of this
+           path, this path is more likely to be stale compared to the
+           <tt>GET-Path</tt>.
           </dd>
         </dl>
       </section>
@@ -415,26 +422,26 @@ Connectivity | |Underlay|  |Underlay|
           A PUT procedure may be exposed as:
         </t>
         <t>
-          <tt>PUT(Key, Block)</tt>
+          <tt>PUT(Key, Block-Type, Block-Expiration, Block)</tt>
         </t>
         <t>
-          The procedure takes at least two parameters:
+          The procedure typically takes at least four parameters:
         </t>
         <dl>
           <dt>Key:</dt>
           <dd>the key under which to store the block.</dd>
-          <dt>Block:</dt>
+          <dt>Block-Type:</dt>
+          <dd>the type of the block to store.</dd>
+          <dt>Block-Expiration:</dt>
+          <dd>when should the block expire.</dd>
+          <dt>Block-Data:</dt>
           <dd>the block to store.</dd>
         </dl>
         <t>
-          The procedure may allow a set of optional parameters in order to
+          The PUT procedure may allow a set of optional parameters in order to
           control or modify the query:
         </t>
         <dl>
-          <dt>Block-Type:</dt>
-          <dd>
-            the type of the block to store.
-          </dd>
           <dt>Replication-Level:</dt>
           <dd>
             An integer which controls how many nearest peers the request
@@ -447,13 +454,9 @@ Connectivity | |Underlay|  |Underlay|
             Any combination of flags as defined in <xref target="route_flags"/>
             may be specified.
           </dd>
-          <dt>Block-Expiration</dt>
-          <dd>
-            is the requested expiration date for the block payload.
-          </dd>
         </dl>
         <t>
-          The procedure does not necessarily output any information.
+          The PUT procedure does not necessarily yield any information.
         </t>
       </section>
     </section>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.