[gnunet-scheme] branch master updated (a71bdc2 -> 8814f16)

[gnunet]

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

maxime-devos pushed a change to branch master
in repository gnunet-scheme.

    from a71bdc2  reuse: Fix remaining REUSE problems.
     new f55e0a7  doc: Set the ‘message-symbol’ property for DHT network 
structures.
     new 8814f16  doc: Set the new ‘c-type’ property for many network 
structures.

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 NEWS                           |  7 +++++++
 doc/scheme-gnunet.tm           | 33 ++++++++++++++++++++++++++++++++-
 gnu/gnunet/crypto/struct.scm   | 15 ++++++++++++++-
 gnu/gnunet/dht/struct.scm      | 22 +++++++++++++++++++++-
 gnu/gnunet/hashcode/struct.scm |  4 +++-
 gnu/gnunet/nse/struct.scm      |  6 ++++--
 gnu/gnunet/util/struct.scm     |  6 +++++-
 7 files changed, 86 insertions(+), 7 deletions(-)

diff --git a/NEWS b/NEWS
index fc71214..ced0881 100644
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,13 @@
 # without any warranty.
 
 -*- mode: org; coding: utf-8 -*-
+* Changes since 0.2
+** Documentation
+   - The ‘message-symbol’ network structure property is now defined for DHT
+     messages and documented in the manual.  The aim is to make the code
+     a little more self-documenting and understandable.
+   - Likewise, a new ‘c-type’ property has been defined, making
+     cross-referencing between Scheme and C sources simpler.
 * Changes since 0.1
 ** Features
    - A DHT client! (gnu gnunet dht client), documented in the manual
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index f14e836..f017a84 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -614,6 +614,36 @@
   with <scm|structure/packed> and individual fields and can be accessed with
   the procedures <scm|documentation>, <scm|synopsis> and <scm|properties>.
 
+  The following properties are defined in Scheme-GNUnet:
+
+  <\description>
+    <\item*>
+      <\code>
+        message-symbol
+      </code>
+    </item*>
+
+    <index|message-symbol>For <with|font-shape|italic|message structures>,
+    this is a list of the names of the <with|font-shape|italic|message types>
+    (see <reference|sec:message type> Message type database) this structure
+    can be used for \U most of the time, there's only a single such message
+    type, but sometimes a single structure can be used for multiple message
+    types.
+
+    <item*|c-type>
+
+    <label|c-type>The value is the name of the equivalent type in the C
+    implementation, if any, as a symbol. This can be useful if you know the
+    name of the C type but not the name of the Scheme type: in that case, you
+    can do <shell|git grep -F GNUNET_MessageHeader> in a git checkout of the
+    source code of Scheme-GNUnet to discover that Scheme-GNUnet's name for
+    <cpp|GNUNET_MessageHeader> is <scm|/:message-header>.
+  </description>
+
+  <todo|TODO: it would be nice to use the properties and documentation to
+  automatically create a form of documentation, with some cross-references to
+  the C code>
+
   <section|Reading and writing>
 
   The procedures <scm|read%><index|read%>, <scm|set%!><index|set%!>,
@@ -838,7 +868,8 @@
 
   <todo|document the message type database, various procedures>
 
-  <section|Message type database><subindex|message type|database>
+  <section|Message type database><label|sec:message type><subindex|message
+  type|database>
 
   The module <scm|(gnu gnunet message protocols)><index|(gnu gnunet message
   protocols)> has a mapping of symbolic names of every message type known to
diff --git a/gnu/gnunet/crypto/struct.scm b/gnu/gnunet/crypto/struct.scm
index b485333..ea1d2f8 100644
--- a/gnu/gnunet/crypto/struct.scm
+++ b/gnu/gnunet/crypto/struct.scm
@@ -58,12 +58,13 @@
                define-type structure/packed)
          (only (gnu gnunet netstruct procedural)
                u8vector u32/big)
-         (only (rnrs base) begin))
+         (only (rnrs base) begin quote))
   (begin
     (define-type /eddsa-signature
       (structure/packed
        (synopsis "An ECC signature using EdDSA.")
        (documentation "See cr.yp.to/papers.html#ed25519")
+       (properties '((c-type . GNUNET_CRYPTO_EddsaSignature)))
        (field (r (u8vector 64))
              (synopsis "R value"))
        (field (s (u8vector 64))
@@ -72,6 +73,7 @@
     (define-type /ecdsa-signature
       (structure/packed
        (synopsis "An ECC signature using ECDSA.")
+       (properties '((c-type . GNUNET_CRYPTO_EcdsaSignature)))
        (field (r (u8vector 64))
              (synopsis "R value"))
        (field (s (u8vector 64))
@@ -83,6 +85,7 @@
 a format suitable for network transmission and EdDSA signatures.
 Refer to section 5.1.3 of rfc8032, for a thorough explanation of how this
 value maps to the x- and y-coordinates.")
+       (properties '((c-type . GNUNET_CRYPTO_EddsaPublicKey)))
        (field (q (u8vector 64))
              (documentation "Point Q consists of a y-value mod p (256 bits);
 the x-value is always positive. The point is stored in Ed25519 standard
@@ -93,6 +96,7 @@ compact format."))))
        (documentation
        "Public ECC key (always for Curve25519) encoded in a format suitable
 for network transmission and ECDSA signatures.")
+       (properties '((c-type . GNUNET_CRYPTO_EcdsaPublicKey)))
        (field (q-y (u8vector 64))
              (documentation
               "Q consists of an x- and a y-value, each mod p (256 bits), given
@@ -102,6 +106,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
       (structure/packed
        (synopsis
        "The identity of the host (wraps the signing key of the peer).")
+       (properties '((c-type . GNUNET_PeerIdentity)))
        (field (public-key /eddsa-public-key))))
 
     (define-type /ecdhe-public-key
@@ -110,6 +115,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
        "Public ECC key (always for Curve25519) encoded in a format suitable
 for network transmission and encryption (ECDH),
 See http://cr.yp.to/ecdh.html";)
+       (properties '((c-type . GNUNET_CRYPTO_EcdhePublicKey)))
        (field (q-y (u8vector 6))
              (documentation
               "Q consists of an x- and a y-value, each mod p (256 bits), given
@@ -118,6 +124,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
     (define-type /ecdhe-private-key
       (structure/packed
        (synopsis "Private ECC key encoded for transmission")
+       (properties '((c-type . GNUNET_CRYPTO_EcdhePrivateKey)))
        (documentation
        "To be used only for ECDH key exchange (ECDHE to be precise)")
        (field (d (u8vector 64))
@@ -129,6 +136,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
        (synopsis "Private ECC key encoded for transmission")
        (documentation
        "To be used only for ECDSA signatures.")
+       (properties '((c-type . GNUNET_CRYPTO_EcdsaPrivatecKey)))
        (field (d (u8vector 64))
              (documentation
               "d is a value mod n, where n has at most 256 bits"))))
@@ -137,6 +145,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
       (structure/packed
        (synopsis "Private ECC key encoded for transmission")
        (documentation "To be used only for EdDSA signatures.")
+       (properties '((c-type . GNUNET_CRYPTO_EddsaPrivateKey)))
        (field (d (u8vector 64))
              (documentation
               "d is a value mod n, where n has at most 256 bits."))))
@@ -144,6 +153,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
     (define-type /symmetric-session-key
       (structure/packed
        (synopsis "Type for session keys")
+       (properties '((c-type . GNUNET_CRYPTO_SymmetricSessionKey)))
        (field (aes-key (u8vector 64))
              (synopsis "Actual key for AES"))
        (field (twofish-key (u8vector 64))
@@ -152,6 +162,8 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
     (define-type /challenge-nonce-p
       (structure/packed
        (synopsis "Type of a nonce used for challenges")
+       ;; TODO: https://bugs.gnunet.org/view.php?id=7173
+       (properties '((c-type . ChallengeNonceP)))
        (field (value /hashcode:256)
              (synopsis
               "The value of the nonce.  Note that this is NOT a hash."))))
@@ -159,6 +171,7 @@ here in affine coordinates and Ed25519 standard compact 
format."))))
     (define-type /ecc-signature-purpose
       (structure/packed
        (synopsis "Header indicating what an ECC signature signs")
+       (properties '((c-type . GNUNET_CRYPTO_EccSignaturePurpose)))
        (field (size u32/big)
              (synopsis "The number of bytes the signature signs"))
        (field (purpose u32/big)
diff --git a/gnu/gnunet/dht/struct.scm b/gnu/gnunet/dht/struct.scm
index 644d4dd..98788f7 100644
--- a/gnu/gnunet/dht/struct.scm
+++ b/gnu/gnunet/dht/struct.scm
@@ -30,7 +30,7 @@
          /:msg:dht:monitor:get
          /:msg:dht:monitor:get-response)
   (import (only (rnrs base)
-               define begin)
+               define begin quote)
          (only (gnu gnunet util struct)
                /:message-header /time-absolute)
          (only (gnu gnunet hashcode struct)
@@ -52,6 +52,7 @@
        (synopsis "A (signed) path tracking a block's flow through the DHT is
 represented by an array of path elements, each consisting of a peer on the path
 and a signature by which the peer affirms its routing decision.")
+       (properties '((c-type . GNUNET_DHT_PathElement)))
        (field (previous /peer-identity)
              (synopsis "The previous peer on the path.
 
@@ -66,6 +67,8 @@ path element.")) ;; C GNUnet says somethin about a 
non-existent ‘succ’ field
       (structure/packed
        (synopsis "Message indicating the DHT should cancel outstanding requests
 and discard any state.")
+       (properties '((message-symbol msg:dht:client:get:stop)
+                    (c-type . GNUNET_DHT_ClientGetStopMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get:stop"))
        (field (reserved u32/big)
@@ -80,6 +83,8 @@ and discard any state.")
       (structure/packed
        (synopsis "DHT GET message sent from clients to service, indicating a 
GET
 request should be issued.")
+       (properties '((message-symbol msg:dht:client:get)
+                    (c-type . GNUNET_DHT_ClientGetMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get"))
        (field (options u32/big)
@@ -99,6 +104,8 @@ will not expect a response"))))
       (structure/packed
        (synopsis "Message sent from clients to service, indicating a GET 
request
 should exclude certain results which are already known.")
+       (properties '((message-symbol msg:dht:client:get-result-known)
+                    (c-type . GNUNET_DHT_ClientGetResultSeenMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:get-results-known"))
        (field (reserved u32/big)
@@ -113,6 +120,8 @@ corresponding GET inside the service)."))
     (define-type /:msg:dht:client:result
       (structure/packed
        (synopsis "Reply to a GET sent from the service to a client")
+       (properties '((message-symbol msg:dht:client:result)
+                    (c-type . GNUNET_DHT_ClientResultMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:client:result"))
        (field (type u32/big)
@@ -135,6 +144,8 @@ location to this peer."))
       (structure/packed
        (synopsis "Message to insert data into the DHT, sent from clients to DHT
 service")
+       (properties '((message-symbol msg:dht:client:put)
+                    (c-type . GNUNET_DHT_ClientPutMessage)))
        (field (header /:message-header)
              (synopsis "Type msg:dht:client:put"))
        (field (type u32/big)
@@ -153,6 +164,8 @@ service")
       (structure/packed
        (synopsis "Message to monitor put requests going through peer
 (DHT service -> clients)")
+       (properties '((message-symbol msg:dht:monitor:put)
+                    (c-type . GNUNET_DHT_MonitorPutMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:put"))
        (field (options u32/big)
@@ -175,6 +188,9 @@ source to the target location of this message."))
       (structure/packed
        ;; TODO: also to stop monitoring messages?
        (synopsis "Message to request monitoring messages, client -> DHT 
service")
+       (properties '((message-symbol msg:dht:monitor:start
+                                    msg:dht:monitor:stop)
+                    (c-type . GNUNET_DHT_MonitorStartStopMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:start or msg:dht:monitor:stop"))
        (field (type u32/big)
@@ -200,6 +216,8 @@ source to the target location of this message."))
       (structure/packed
        (synopsis "Message to monitor get requests going through peer,
 DHT service -> clients.")
+       (properties '((message-symbol msg:dht:monitor:get)
+                    (c-type . GNUNET_DHT_MonitorGetMessage)))
        (field (header /:message-header)
              (synopsis "Type: msg:dht:monitor:get"))
        (field (options u32/big)
@@ -221,6 +239,8 @@ source to the storage location of this message"))
       (structure/packed
        (synopsis "Message to monitor get requests going through peer,
 DHT service -> clients")
+       (properties '((message-symbol msg:dht:p2p:result)
+                    (c-type . GNUNET_DHT_MonitorGetRespMessage)))
        (field (header /:message-header)
              ;; XXX correct?
              (synopsis "Type: msg:dht:p2p:result"))
diff --git a/gnu/gnunet/hashcode/struct.scm b/gnu/gnunet/hashcode/struct.scm
index 549648d..d742161 100644
--- a/gnu/gnunet/hashcode/struct.scm
+++ b/gnu/gnunet/hashcode/struct.scm
@@ -19,7 +19,7 @@
 ;; Extracted from src/include/gnunet_common.h
 (define-library (gnu gnunet hashcode struct)
   (export /hashcode:512 /hashcode:256)
-  (import (only (rnrs base) begin)
+  (import (only (rnrs base) begin quote)
          (only (gnu gnunet netstruct syntactic)
                define-type structure/packed)
          (only (gnu gnunet netstruct procedural) u8vector))
@@ -29,6 +29,7 @@
        (synopsis "A 512-bit hashcode.")
        (documentation
        "These are the default length for GNUnet, using SHA-512.")
+       (properties '((c-type . GNUNET_HashCode)))
        (field (bits/u8 (u8vector 64)))))
 
     (define-type /hashcode:256
@@ -37,4 +38,5 @@
        (documentation
        "Used under special conditions, like when space
 is critical and security is not impacted by it.")
+       (properties '((c-type . GNUNET_ShortHashCode)))
        (field (bits/u8 (u8vector 32)))))))
diff --git a/gnu/gnunet/nse/struct.scm b/gnu/gnunet/nse/struct.scm
index 22f3607..d07b1eb 100644
--- a/gnu/gnunet/nse/struct.scm
+++ b/gnu/gnunet/nse/struct.scm
@@ -44,7 +44,8 @@
        "Contains the current size estimate
 (or 0 if none has been calculated) and the
 standard deviation of known estimates.")
-       (properties '((message-symbol msg:nse:estimate)))
+       (properties '((message-symbol msg:nse:estimate)
+                    (c-type . GNUNET_NSE_ClientMessage)))
        (field (header /:message-header))
        (field (reserved u32/big))
        (field (timestamp /time-absolute)
@@ -58,7 +59,8 @@ standard deviation of known estimates.")
        (documentation
        "Sent when \"this\" peer's timer has run out before receiving a
 valid reply from another peer.")
-       (properties '((message-symbol msg:nse:flood)))
+       (properties '((message-symbol msg:nse:flood)
+                    (c-type . GNUNET_NSE_FloodMessage)))
        (field (header /:message-header))
        (field (hop-count u32/big)
              (synopsis
diff --git a/gnu/gnunet/util/struct.scm b/gnu/gnunet/util/struct.scm
index 910f1e1..c4618b2 100644
--- a/gnu/gnunet/util/struct.scm
+++ b/gnu/gnunet/util/struct.scm
@@ -25,7 +25,7 @@
                define-type structure/packed)
          (only (gnu gnunet netstruct procedural)
                u8vector u16/big u32/big u64/big)
-         (only (rnrs base) begin))
+         (only (rnrs base) begin quote))
   (begin
     ;; Absolute time (in GNUnet), in microseconds
     (define-type /time-absolute u64/big)
@@ -33,6 +33,7 @@
     (define-type /uuid
       (structure/packed
        (synopsis "A UUID, a 128 bit random value")
+       (properties '((c-type . GNUNET_Uuid)))
        (field (value/u8 (u8vector 16))
              (synopsis "128 random bits")
              (documentation
@@ -45,6 +46,7 @@
     (define-type /:message-header
       (structure/packed
        (synopsis "Header for all communications")
+       (properties '((c-type . GNUNET_MessageHeader)))
        (field (size u16/big)
              (documentation
               "The length of the struct (in bytes, including the length
@@ -60,6 +62,7 @@ in big-endian format."))))
       (structure/packed
        (synopsis "Answer from service to client about last operation")
        (documentation "Possibly followed by data")
+       (properties '((c-type . GNUNET_OperationResultMessage)))
        (field (header /:message-header))
        (field (reserved u32/big))
        (field (operation-id u64/big)
@@ -72,4 +75,5 @@ in big-endian format."))))
        (synopsis "Identifier for an asynchronous execution context")
        (documentation
        "This is represented as an array of uint32_t in GNUnet.")
+       (properties '((c-type . GNUNET_AsyncScopeId)))
        (field (bits/u8 (u8vector 16)))))))

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