Use GNU printf format

[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 e7da0d3f297ab5a4de15b6ea3a6339bfc109d20e..0add8852a942bf348cbe0fe3d05cc711f5752e39 100644 (file)
--- a/src/include/gnunet_namestore_service.h
+++ b/src/include/gnunet_namestore_service.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet
 /*
      This file is part of GNUnet

-     (C) 2012 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2012, 2013 GNUnet e.V.

 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published

-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -14,26 +14,33 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the

-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.

 */
 
 /**
 */
 
 /**

- * @file include/gnunet_namestore_service.h
- * @brief API that can be used to store naming information on a GNUnet node;

  * @author Christian Grothoff
  *
  * @author Christian Grothoff
  *

- * Other functions we might want:
- * - enumerate all known zones
- * - convenience function to gather record and the full affilliated stree
- *   in one shot
+ * @file
+ * API that can be used to store naming information on a GNUnet node;
+ *
+ * @defgroup namestore  Name Store service
+ * Store naming information on a GNUnet node.
+ *
+ * Naming information can either be records for which this peer/user is
+ * authoritative, or blocks which are cached, encrypted naming data from other
+ * peers.
+ *
+ * @see [Documentation](https://gnunet.org/namestore-subsystem)
+ *
+ * @{

  */
  */

-

 #ifndef GNUNET_NAMESTORE_SERVICE_H
 #define GNUNET_NAMESTORE_SERVICE_H
 
 #include "gnunet_util_lib.h"
 #include "gnunet_block_lib.h"
 #ifndef GNUNET_NAMESTORE_SERVICE_H
 #define GNUNET_NAMESTORE_SERVICE_H
 
 #include "gnunet_util_lib.h"
 #include "gnunet_block_lib.h"

+#include "gnunet_gnsrecord_lib.h"

 
 #ifdef __cplusplus
 extern "C"
 
 #ifdef __cplusplus
 extern "C"


@@ -43,6 +50,7 @@ extern "C"
 #endif
 #endif
 
 #endif
 #endif
 

+

 /**
  * Entry in the queue.
  */
 /**
  * Entry in the queue.
  */


@@ -54,9 +62,10 @@ struct GNUNET_NAMESTORE_QueueEntry;
 struct GNUNET_NAMESTORE_Handle;
 
 /**
 struct GNUNET_NAMESTORE_Handle;
 
 /**

- * Maximum size of a value that can be stored in the namestore.
+ * Handle to the namestore zone iterator.

  */
  */

-#define GNUNET_NAMESTORE_MAX_VALUE_SIZE (63 * 1024)
+struct GNUNET_NAMESTORE_ZoneIterator;
+

 
 /**
  * Connect to the namestore service.
 
 /**
  * Connect to the namestore service.


@@ -69,14 +78,14 @@ GNUNET_NAMESTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
 /**
 
 
 /**

- * Disconnect from the namestore service (and free
- * associated resources).
+ * Disconnect from the namestore service (and free associated
+ * resources).  Must not be called from within operation callbacks of
+ * the API.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param drop set to GNUNET_YES to delete all data in namestore (!)

  */
 void
  */
 void

-GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
+GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h);

 
 
 /**
 
 
 /**


@@ -84,391 +93,249 @@ GNUNET_NAMESTORE_disconnect (struct GNUNET_NAMESTORE_Handle *h, int drop);
  * operation.
  *
  * @param cls closure
  * operation.
  *
  * @param cls closure

- * @param success GNUNET_SYSERR on failure (including timeout/queue drop)
- *                GNUNET_NO if content was already there
- *                GNUNET_YES (or other positive value) on success
+ * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
+ *                #GNUNET_NO if content was already there or not found
+ *                #GNUNET_YES (or other positive value) on success

  * @param emsg NULL on success, otherwise an error message
  */
  * @param emsg NULL on success, otherwise an error message
  */

-typedef void (*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
-                                                         int32_t success,
-                                                         const char *emsg);
-
-
-/**
- * Flags that can be set for a record.
- */
-enum GNUNET_NAMESTORE_RecordFlags
-{
-  
-  /**
-   * No special options.
-   */
-  GNUNET_NAMESTORE_RF_NONE = 0,
-
-  /**
-   * This peer is the authority for this record; it must thus
-   * not be deleted (other records can be deleted if we run
-   * out of space).
-   */
-  GNUNET_NAMESTORE_RF_AUTHORITY = 1,
-
-  /**
-   * This is a private record of this peer and it should
-   * thus not be handed out to other peers.
-   */
-  GNUNET_NAMESTORE_RF_PRIVATE = 2
-
-};
-
-
-/**
- * We formally store records in a B-tree for signing.  This struct
- * identifies the location of a record in the B-tree.
- */
-struct GNUNET_NAMESTORE_SignatureLocation
-{
-  /**
-   * Offset in the B-tree.
-   */
-  uint64_t offset;
-
-  /**
-   * Depth in the B-tree.
-   */
-  uint32_t depth;
-
-  /**
-   * Revision of the B-tree.
-   */
-  uint32_t revision;
-};
+typedef void
+(*GNUNET_NAMESTORE_ContinuationWithStatus) (void *cls,
+                                            int32_t success,
+                                            const char *emsg);

 
 
 /**
 
 
 /**

- * Continuation called to notify client about result of the
- * signing operation.
- *
- * @param cls closure
- * @param sig where the signature is now located in the S-tree
- */
-typedef void (*GNUNET_NAMESTORE_ContinuationWithSignature) (void *cls,
-                                                           const struct GNUNET_NAMESTORE_SignatureLocation *sig);
-
-
-
-
-
-/**
- * Get the hash of a record (what will be signed in the Stree for
- * the record).
- *
- * @param zone hash of the public key of the zone
- * @param name name that is being mapped (at most 255 characters long)
- * @param record_type type of the record (A, AAAA, PKEY, etc.)
- * @param expiration expiration time for the content
- * @param flags flags for the content
- * @param data_size number of bytes in data
- * @param data value, semantics depend on 'record_type' (see RFCs for DNS and 
- *             GNS specification for GNS extensions)
- * @param record_hash hash of the record (set)
- */
-void
-GNUNET_NAMESTORE_record_hash (struct GNUNET_NAMESTORE_Handle *h,
-                             const GNUNET_HashCode *zone,
-                             const char *name,
-                             uint32_t record_type,
-                             struct GNUNET_TIME_Absolute expiration,
-                             enum GNUNET_NAMESTORE_RecordFlags flags,
-                             size_t data_size,
-                             const void *data, 
-                             GNUNET_HashCode *record_hash);
-
-
-/**
- * Sign a record.  This function is used by the authority of the zone
- * to add a record.
+ * Store an item in the namestore.  If the item is already present,
+ * it is replaced with the new record.  Use an empty array to
+ * remove all records under the given name.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param zone_privkey private key of the zone
- * @param record_hash hash of the record to be signed
+ * @param pkey private key of the zone
+ * @param label name that is being mapped
+ * @param rd_count number of records in the 'rd' array
+ * @param rd array of records with data to store

  * @param cont continuation to call when done
  * @param cont continuation to call when done

- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *

-GNUNET_NAMESTORE_stree_extend (struct GNUNET_NAMESTORE_Handle *h,
-                              const struct GNUNET_CRYPTO_RsaPrivateKey *zone_privkey,
-                              const GNUNET_HashCode *record_hash,
-                              GNUNET_NAMESTORE_ContinuationWithSignature cont,
-                              void *cont_cls);
+GNUNET_NAMESTORE_records_store (struct GNUNET_NAMESTORE_Handle *h,
+                               const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                               const char *label,
+                               unsigned int rd_count,
+                               const struct GNUNET_GNSRECORD_Data *rd,
+                               GNUNET_NAMESTORE_ContinuationWithStatus cont,
+                               void *cont_cls);

 
 
 
 

-/**
- * Rebalance the signature tree of our zone.  This function should
- * be called "rarely" to rebalance the tree.
- *
- * @param h handle to the namestore
- * @param zone_privkey private key for the zone to rebalance
- * @param cont continuation to call when done
- * @param cont_cls closure for cont
- * @return handle to abort the request
- */
-struct GNUNET_NAMESTORE_QueueEntry *
-GNUNET_NAMESTORE_stree_rebalance (struct GNUNET_NAMESTORE_Handle *h,
-                                 const struct GNUNET_CRYPTO_RsaPrivateKey *zone_privkey,
-                                 GNUNET_NAMESTORE_ContinuationWithStatus cont,
-                                 void *cont_cls);
-

 
 /**
 
 /**

- * Provide the root of a signature tree.  This function is 
- * used by non-authorities as the first operation when 
- * adding a foreign zone.
+ * Process a record that was stored in the namestore.

  *
  *

- * @param h handle to the namestore
- * @param zone_key public key of the zone
- * @param signature signature of the top-level entry of the zone
- * @param revision revision number of the zone
- * @param top_hash top-level hash of the zone
- * @param cont continuation to call when done
- * @param cont_cls closure for cont
- * @return handle to abort the request
+ * @param cls closure
+ * @param zone private key of the zone
+ * @param label label of the records
+ * @param rd_count number of entries in @a rd array, 0 if label was deleted
+ * @param rd array of records with data to store

  */
  */

-struct GNUNET_NAMESTORE_QueueEntry *
-GNUNET_NAMESTORE_stree_start (struct GNUNET_NAMESTORE_Handle *h,
-                             const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
-                             const struct GNUNET_CRYPTO_RsaSignature *signature,
-                             uint32_t revision,
-                             const GNUNET_HashCode *top_hash,
-                             GNUNET_NAMESTORE_ContinuationWithSignature cont,
-                             void *cont_cls);
+typedef void
+(*GNUNET_NAMESTORE_RecordMonitor) (void *cls,
+                                   const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                   const char *label,
+                                   unsigned int rd_count,
+                                   const struct GNUNET_GNSRECORD_Data *rd);

 
 
 /**
 
 
 /**

- * Store part of a signature B-tree in the namestore.  This function
- * is used by non-authorities to cache parts of a zone's signature tree.
- * Note that the tree must be build top-down.  This function must check
- * that the nodes being added are valid, and if not refuse the operation.
+ * Set the desired nick name for a zone

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param zone_key public key of the zone
- * @param loc location in the B-tree
- * @param ploc parent's location in the B-tree (must have depth = loc.depth - 1), NULL for root
- * @param top_sig signature at the top, NULL if 'loc.depth > 0'
- * @param num_entries number of entries at this node in the B-tree
- * @param entries the 'num_entries' entries to store (hashes over the
- *                records)
+ * @param pkey private key of the zone
+ * @param nick the nick name to set

  * @param cont continuation to call when done
  * @param cont continuation to call when done

- * @param cont_cls closure for cont
+ * @param cont_cls closure for 'cont'

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *

-GNUNET_NAMESTORE_stree_put (struct GNUNET_NAMESTORE_Handle *h,
-                           const struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *zone_key,
-                           const struct GNUNET_NAMESTORE_SignatureLocation *loc,
-                           const struct GNUNET_NAMESTORE_SignatureLocation *ploc,
-                           const struct GNUNET_CRYPTO_RsaSignature *sig,
-                           unsigned int num_entries,
-                           const GNUNET_HashCode *entries,
-                           GNUNET_NAMESTORE_ContinuationWithStatus cont,
-                           void *cont_cls);
+GNUNET_NAMESTORE_set_nick (struct GNUNET_NAMESTORE_Handle *h,
+                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                           const char *nick,
+                           GNUNET_NAMESTORE_ContinuationWithStatus cont,
+                           void *cont_cls);

 
 
 /**
 
 
 /**

- * Store an item in the namestore.  If the item is already present,
- * the expiration time is updated to the max of the existing time and
- * the new time.  The operation must fail if there is no matching
- * entry in the signature tree.
+ * Lookup an item in the namestore.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param zone hash of the public key of the zone
- * @param name name that is being mapped (at most 255 characters long)
- * @param record_type type of the record (A, AAAA, PKEY, etc.)
- * @param expiration expiration time for the content
- * @param flags flags for the content
- * @param sig_loc where is the information about the signature for this record stored?
- * @param data_size number of bytes in data
- * @param data value, semantics depend on 'record_type' (see RFCs for DNS and 
- *             GNS specification for GNS extensions)
- * @param cont continuation to call when done
- * @param cont_cls closure for cont
+ * @param pkey private key of the zone
+ * @param label name that is being mapped
+ * @param error_cb function to call on error (i.e. disconnect)
+ *        the handle is afterwards invalid
+ * @param error_cb_cls closure for @a error_cb
+ * @param rm function to call with the result (with 0 records if we don't have that label);
+ *        the handle is afterwards invalid
+ * @param rm_cls closure for @a rm

  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *
  * @return handle to abort the request
  */
 struct GNUNET_NAMESTORE_QueueEntry *

-GNUNET_NAMESTORE_record_put (struct GNUNET_NAMESTORE_Handle *h,
-                            const GNUNET_HashCode *zone,
-                            const char *name,
-                            uint32_t record_type,
-                            struct GNUNET_TIME_Absolute expiration,
-                            enum GNUNET_NAMESTORE_RecordFlags flags,
-                            const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc,
-                            size_t data_size,
-                            const void *data, 
-                            GNUNET_NAMESTORE_ContinuationWithStatus cont,
-                            void *cont_cls);
+GNUNET_NAMESTORE_records_lookup (struct GNUNET_NAMESTORE_Handle *h,
+                                 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
+                                 const char *label,
+                                 GNUNET_SCHEDULER_TaskCallback error_cb,
+                                 void *error_cb_cls,
+                                 GNUNET_NAMESTORE_RecordMonitor rm,
+                                 void *rm_cls);

 
 
 /**
 
 
 /**

- * Explicitly remove some content from the database.  The
- * "cont"inuation will be called with status "GNUNET_OK" if content
- * was removed, "GNUNET_NO" if no matching entry was found and
- * "GNUNET_SYSERR" on all other types of errors.
+ * Look for an existing PKEY delegation record for a given public key.
+ * Returns at most one result to the processor.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param zone hash of the public key of the zone
- * @param name name that is being mapped (at most 255 characters long)
- * @param record_type type of the record (A, AAAA, PKEY, etc.)
- * @param size number of bytes in data
- * @param data content stored
- * @param cont continuation to call when done
- * @param cont_cls closure for cont
- * @return handle to abort the request
+ * @param zone public key of the zone to look up in, never NULL
+ * @param value_zone public key of the target zone (value), never NULL
+ * @param error_cb function to call on error (i.e. disconnect)
+ *        the handle is afterwards invalid
+ * @param error_cb_cls closure for @a error_cb
+ * @param proc function to call on the matching records, or with
+ *        NULL (rd_count == 0) if there are no matching records;
+ *        the handle is afterwards invalid
+ * @param proc_cls closure for @a proc
+ * @return a handle that can be used to
+ *         cancel

  */
 struct GNUNET_NAMESTORE_QueueEntry *
  */
 struct GNUNET_NAMESTORE_QueueEntry *

-GNUNET_NAMESTORE_record_remove (struct GNUNET_NAMESTORE_Handle *h,
-                               const GNUNET_HashCode *zone, 
-                               const char *name,
-                               uint32_t record_type,
-                               size_t size,
-                               const void *data, 
-                               GNUNET_NAMESTORE_ContinuationWithStatus cont,
-                               void *cont_cls);
+GNUNET_NAMESTORE_zone_to_name (struct GNUNET_NAMESTORE_Handle *h,
+                              const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                              const struct GNUNET_CRYPTO_EcdsaPublicKey *value_zone,
+                               GNUNET_SCHEDULER_TaskCallback error_cb,
+                               void *error_cb_cls,
+                              GNUNET_NAMESTORE_RecordMonitor proc,
+                               void *proc_cls);

 
 
 /**
 
 
 /**

- * Process a record that was stored in the namestore.
+ * Cancel a namestore operation.  The final callback from the
+ * operation must not have been done yet.  Must be called on any
+ * namestore operation that has not yet completed prior to calling
+ * #GNUNET_NAMESTORE_disconnect.

  *
  *

- * @param cls closure
- * @param zone hash of the public key of the zone
- * @param name name that is being mapped (at most 255 characters long)
- * @param record_type type of the record (A, AAAA, PKEY, etc.)
- * @param expiration expiration time for the content
- * @param flags flags for the content
- * @param sig_loc where is the information about the signature for this record stored?
- * @param size number of bytes in data
- * @param data content stored
+ * @param qe operation to cancel

  */
  */

-typedef void (*GNUNET_NAMESTORE_RecordProcessor) (void *cls,
-                                                 const GNUNET_HashCode *zone,
-                                                const char *name,
-                                                uint32_t record_type,
-                                                struct GNUNET_TIME_Absolute expiration,
-                                                enum GNUNET_NAMESTORE_RecordFlags flags,
-                                                const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc,
-                                                size_t size, const void *data);
+void
+GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);

 
 
 /**
 
 
 /**

- * Get a result for a particular key from the namestore.  The processor
- * will only be called once.
+ * Starts a new zone iteration (used to periodically PUT all of our
+ * records into our DHT). This MUST lock the `struct GNUNET_NAMESTORE_Handle`
+ * for any other calls than #GNUNET_NAMESTORE_zone_iterator_next() and
+ * #GNUNET_NAMESTORE_zone_iteration_stop. @a proc will be called once
+ * immediately, and then again after
+ * #GNUNET_NAMESTORE_zone_iterator_next() is invoked.
+ *
+ * On error (disconnect), @a error_cb will be invoked.
+ * On normal completion, @a finish_cb proc will be
+ * invoked.

  *
  * @param h handle to the namestore
  *
  * @param h handle to the namestore

- * @param zone zone to look up a record from
- * @param name name to look up
- * @param record_type desired record type
- * @param proc function to call on each matching value;
- *        will be called once with a NULL value at the end
- * @param proc_cls closure for proc
- * @return a handle that can be used to
- *         cancel
+ * @param zone zone to access, NULL for all zones
+ * @param error_cb function to call on error (i.e. disconnect),
+ *        the handle is afterwards invalid
+ * @param error_cb_cls closure for @a error_cb
+ * @param proc function to call on each name from the zone; it
+ *        will be called repeatedly with a value (if available)
+ * @param proc_cls closure for @a proc
+ * @param finish_cb function to call on completion
+ *        the handle is afterwards invalid
+ * @param finish_cb_cls closure for @a finish_cb
+ * @return an iterator handle to use for iteration

  */
  */

-struct GNUNET_NAMESTORE_QueueEntry *
-GNUNET_NAMESTORE_lookup_name (struct GNUNET_NAMESTORE_Handle *h, 
-                             const GNUNET_HashCode *zone,
-                             const char *name,
-                             uint32_t record_type,
-                             GNUNET_NAMESTORE_RecordProcessor proc, void *proc_cls);
-
+struct GNUNET_NAMESTORE_ZoneIterator *
+GNUNET_NAMESTORE_zone_iteration_start (struct GNUNET_NAMESTORE_Handle *h,
+                                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                       GNUNET_SCHEDULER_TaskCallback error_cb,
+                                       void *error_cb_cls,
+                                      GNUNET_NAMESTORE_RecordMonitor proc,
+                                      void *proc_cls,
+                                       GNUNET_SCHEDULER_TaskCallback finish_cb,
+                                       void *finish_cb_cls);

 
 
 /**
 
 
 /**

- * Get the hash of a subtree in the STree (what will be signed in the parent
- * location). FIXME naming conflict!
+ * Calls the record processor specified in #GNUNET_NAMESTORE_zone_iteration_start
+ * for the next record.

  *
  *

- * @param zone hash of the public key of the zone
- * @param loc where we are in the signature tree
- * @param num_entries number of entries being stored here
- * @param entries the entries themselves
- * @param st_hash hash of the stree node (set)
+ * @param it the iterator

  */
 void
  */
 void

-GNUNET_NAMESTORE_record_hash_dup (struct GNUNET_NAMESTORE_Handle *h,
-                             const GNUNET_HashCode *zone,
-                             const struct GNUNET_NAMESTORE_SignatureLocation *loc,
-                             unsigned int num_entries,
-                             const GNUNET_HashCode *entries,
-                             GNUNET_HashCode *st_hash);
+GNUNET_NAMESTORE_zone_iterator_next (struct GNUNET_NAMESTORE_ZoneIterator *it);

 
 
 /**
 
 
 /**

- * Process a Stree node that was stored in the namestore.
+ * Stops iteration and releases the namestore handle for further calls.  Must
+ * be called on any iteration that has not yet completed prior to calling
+ * #GNUNET_NAMESTORE_disconnect.

  *
  *

- * @param cls closure
- * @param zone hash of the public key of the zone
- * @param loc where we are in the signature tree
- * @param ploc location of our parent in the signature tree (NULL if 'loc.depth == 0')
- * @param top_sig signature at the root (NULL if 'loc.depth > 0')
- * @param num_entries number of entries being stored here
- * @param entries the entries themselves
+ * @param it the iterator

  */
  */

-typedef void (*GNUNET_NAMESTORE_StreeProcessor) (void *cls,
-                                                 const GNUNET_HashCode *zone,
-                                                const struct GNUNET_NAMESTORE_SignatureLocation *loc,
-                                                const struct GNUNET_NAMESTORE_SignatureLocation *ploc,
-                                                const struct GNUNET_CRYPTO_RsaSignature *top_sig,
-                                                unsigned int num_entries,
-                                                const GNUNET_HashCode *entries);
+void
+GNUNET_NAMESTORE_zone_iteration_stop (struct GNUNET_NAMESTORE_ZoneIterator *it);

 
 
 /**
 
 
 /**

- * Obtain part of a signature B-tree.  The processor
- * will only be called once.
- *
- * @param h handle to the namestore
- * @param zone zone to look up a record from
- * @param sig_loc location to look up
- * @param proc function to call on each matching value;
- *        will be called once with a NULL value at the end
- * @param proc_cls closure for proc
- * @return a handle that can be used to
- *         cancel
+ * Handle for a monitoring activity.

  */
  */

-struct GNUNET_NAMESTORE_QueueEntry *
-GNUNET_NAMESTORE_lookup_stree (struct GNUNET_NAMESTORE_Handle *h, 
-                              const GNUNET_HashCode *zone,
-                              const struct GNUNET_NAMESTORE_SignatureLocation *sig_loc,
-                              GNUNET_NAMESTORE_StreeProcessor proc, void *proc_cls);
+struct GNUNET_NAMESTORE_ZoneMonitor;

 
 
 /**
 
 
 /**

- * Get all records of a zone.
+ * Begin monitoring a zone for changes.  Will first call the @a
+ * monitor function on all existing records in the selected zone(s) if
+ * @a iterate_first is #GNUNET_YES.  In any case, we will then call @a
+ * sync_cb, and then afterwards call the @a monitor whenever a record
+ * changes.  If the namestore disconnects, the @a error_cb function is
+ * called with a disconnect event. Once the connection is
+ * re-established, the process begins from the start (depending on @a
+ * iterate_first, we will again first do all existing records, then @a
+ * sync, then updates).

  *
  *

- * @param h handle to the namestore
- * @param zone zone to access
- * @param proc function to call on a random value; it
- *        will be called repeatedly with a value (if available)
- *        and always once at the end with a zone and name of NULL.
- * @param proc_cls closure for proc
- * @return a handle that can be used to
- *         cancel
+ * @param cfg configuration to use to connect to namestore
+ * @param zone zone to monitor, NULL for all zones
+ * @param iterate_first #GNUNET_YES to first iterate over all existing records,
+ *                      #GNUNET_NO to only return changes that happen from now on
+ * @param error_cb function to call on error (i.e. disconnect); note that
+ *         unlike the other error callbacks in this API, a call to this
+ *         function does NOT destroy the monitor handle, it merely signals
+ *         that monitoring is down. You need to still explicitly call
+ *         #GNUNET_NAMESTORE_zone_monitor_stop().
+ * @param error_cb_cls closure for @a error_cb
+ * @param monitor function to call on zone changes
+ * @param monitor_cls closure for @a monitor
+ * @param sync_cb function called when we're in sync with the namestore
+ * @param sync_cb_cls closure for @a sync_cb
+ * @return handle to stop monitoring

  */
  */

-struct GNUNET_NAMESTORE_QueueEntry *
-GNUNET_NAMESTORE_zone_transfer (struct GNUNET_NAMESTORE_Handle *h,
-                               const GNUNET_HashCode *zone,
-                               GNUNET_NAMESTORE_RecordProcessor proc,
-                               void *proc_cls);
-
-
+struct GNUNET_NAMESTORE_ZoneMonitor *
+GNUNET_NAMESTORE_zone_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                    const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone,
+                                     int iterate_first,
+                                     GNUNET_SCHEDULER_TaskCallback error_cb,
+                                     void *error_cb_cls,
+                                    GNUNET_NAMESTORE_RecordMonitor monitor,
+                                     void *monitor_cls,
+                                    GNUNET_SCHEDULER_TaskCallback sync_cb,
+                                    void *sync_cb_cls);

 
 
 /**
 
 
 /**

- * Cancel a namestore operation.  The final callback from the
- * operation must not have been done yet.
+ * Stop monitoring a zone for changes.

  *
  *

- * @param qe operation to cancel
+ * @param zm handle to the monitor activity to stop

  */
 void
  */
 void

-GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
+GNUNET_NAMESTORE_zone_monitor_stop (struct GNUNET_NAMESTORE_ZoneMonitor *zm);

 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */


@@ -478,5 +345,6 @@ GNUNET_NAMESTORE_cancel (struct GNUNET_NAMESTORE_QueueEntry *qe);
 }
 #endif
 
 }
 #endif
 

-/* end of gnunet_namestore_service.h */

 #endif
 #endif

+
+/** @} */  /* end of group */