configuration serialization

[oweals/gnunet.git] / src / include / gnunet_namestore_service.h

diff --git a/src/include/gnunet_namestore_service.h b/src/include/gnunet_namestore_service.h
index 05e4fbf062dfbdfc5fffd218a82addab116e41df..00c8ba26be7d683d5a579afe10dd7dcab9dbe475 100644 (file)
--- a/src/include/gnunet_namestore_service.h
+++ b/src/include/gnunet_namestore_service.h
@@ -25,8 +25,6 @@
  *
  * Other functions we might want:
  * - enumerate all known zones
- * - convenience function to gather record and the full affilliated stree
- *   in one shot
  */
 
 #ifndef GNUNET_NAMESTORE_SERVICE_H
@@ -110,10 +108,9 @@ GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  * resources).
  *
  * @param h handle to the namestore
- * @param drop set to GNUNET_YES to delete all data in namestore (!)
  */
 void
-GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
+GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);
 
 
 /**
@@ -159,7 +156,13 @@ enum GNUNET_NAMESTORE_RecordFlags
    * This record was added by the system
    * and is pending user confimation
    */
-  GNUNET_NAMESTORE_RF_PENDING = 4
+  GNUNET_NAMESTORE_RF_PENDING = 4,
+
+  /**
+   * This expiration time of the record is a relative
+   * time (not an absolute time).
+   */
+  GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION = 8
 
 };
 
@@ -176,9 +179,10 @@ struct GNUNET_NAMESTORE_RecordData
   const void *data;
 
   /**
-   * Expiration time for the DNS record.
+   * Expiration time for the DNS record.  Can be relative
+   * or absolute, depending on 'flags'.
    */
-  struct GNUNET_TIME_Absolute expiration;
+  uint64_t expiration_time;
 
   /**
    * Number of bytes in 'data'.
@@ -232,7 +236,7 @@ GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
  * to validate signatures received from the network.
  *
  * @param public_key public key of the zone
- * @param expire block expiration
+ * @param freshness time set for block expiration
  * @param name name that is being mapped (at most 255 characters long)
  * @param rd_count number of entries in 'rd' array
  * @param rd array of records with data to store
@@ -299,7 +303,7 @@ GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
  *
  * @param cls closure
  * @param zone_key public key of the zone
- * @param expire when does the corresponding block in the DHT expire (until
+ * @param freshness when does the corresponding block in the DHT expire (until
  *               when should we never do a DHT lookup for the same name again)?; 
  *               GNUNET_TIME_UNIT_ZERO_ABS if there are no records of any type in the namestore,
  *               or the expiration time of the block in the namestore (even if there are zero
@@ -364,9 +368,23 @@ GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
 
 /**
  * Starts a new zone iteration (used to periodically PUT all of our
- * records into our DHT). "proc" will be called once
- * immediately, and then again after
- * "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
+ * records into our DHT). "proc" will be called once immediately, and
+ * then again after "GNUNET_NAMESTORE_zone_iterator_next" is invoked.
+ *
+ * By specifying a 'zone' of NULL and setting 'GNUNET_NAMESTORE_RF_AUTHORITY'
+ * in 'must_have_flags', we can iterate over all records for which we are
+ * the authority.  In this case, the 'GNUNET_NAMESTORE_RF_RELATIVE_EXPIRATION'
+ * bit in 'must_have_flags' has a special meaning:
+ *
+ * 0) If the bit is clear, all relative expriation times are converted to
+ *    absolute expiration times.  This is useful for performing DHT PUT
+ *    operations (and zone transfers) of our zone.
+ * 1) if it is set, it means that relative expiration times should be
+ *    preserved when returned (this is useful for the zone editor user 
+ *    interface).
+ *
+ * Note that not all queries against this interface are equally performant
+ * as for some combinations no efficient index may exist.
  *
  * @param h handle to the namestore
  * @param zone zone to access, NULL for all zones