1 files changed, 160 insertions, 40 deletions

diff --git a/src/include/gnunet_peerstore_service.h b/src/include/gnunet_peerstore_service.h
index 91a8f2e66..3fb9df82a 100644
--- a/src/include/gnunet_peerstore_service.h
+++ b/src/include/gnunet_peerstore_service.h
@@ -19,6 +19,9 @@
  */
 
 /**
+ * @addtogroup Backbone
+ * @{
+ *
  * @author Omar Tarabai
  *
  * @file
@@ -33,6 +36,7 @@
 #ifndef GNUNET_PEERSTORE_SERVICE_H
 #define GNUNET_PEERSTORE_SERVICE_H
 
+
 #include "gnunet_util_lib.h"
 
 #ifdef __cplusplus
@@ -42,6 +46,10 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * Key used for storing HELLO in the peerstore
+ */
+#define GNUNET_PEERSTORE_HELLO_KEY "peerstore-peer-hello-uri"
 
 /**
  * Key used for storing addresses in URL format in the peerstore
@@ -58,32 +66,32 @@ extern "C" {
  * messages.
  */
 #define GNUNET_PEERSTORE_TRANSPORT_BACKCHANNEL_MONOTIME \
-  "transport-backchannel-monotonic-time"
+        "transport-backchannel-monotonic-time"
 
 /**
  * Key used to store sender's monotonic time from DV learn
  * messages.
  */
 #define GNUNET_PEERSTORE_TRANSPORT_DVLEARN_MONOTIME \
-  "transport-dv-learn-monotonic-time"
+        "transport-dv-learn-monotonic-time"
 
 /**
  * Key used to store sender's monotonic time from handshake message.
  */
 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE \
-  "transport-tcp-communicator-handshake"
+        "transport-tcp-communicator-handshake"
 
 /**
  * Key used to store sender's monotonic time from handshake ack message.
  */
 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_HANDSHAKE_ACK \
-  "transport-tcp-communicator-handshake-ack"
+        "transport-tcp-communicator-handshake-ack"
 
 /**
  * Key used to store sender's monotonic time from rekey message.
  */
 #define GNUNET_PEERSTORE_TRANSPORT_TCP_COMMUNICATOR_REKEY \
-  "transport-tcp-communicator-rekey"
+        "transport-tcp-communicator-rekey"
 
 
 /**
@@ -100,7 +108,8 @@ enum GNUNET_PEERSTORE_StoreOption
    * Delete any previous values for the given key before
    * storing the given value.
    */
-  GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1
+  GNUNET_PEERSTORE_STOREOPTION_REPLACE = 1,
+
 };
 
 /**
@@ -114,6 +123,11 @@ struct GNUNET_PEERSTORE_Handle;
 struct GNUNET_PEERSTORE_StoreContext;
 
 /**
+ * Context for the info handler.
+ */
+struct GNUNET_PEERSTORE_NotifyContext;
+
+/**
  * Single PEERSTORE record
  */
 struct GNUNET_PEERSTORE_Record
@@ -148,11 +162,6 @@ struct GNUNET_PEERSTORE_Record
    */
   struct GNUNET_TIME_Absolute expiry;
 
-  /**
-   * Client from which this record originated.
-   * NOTE: This is internal to the service.
-   */
-  struct GNUNET_SERVICE_Client *client;
 };
 
 
@@ -166,9 +175,16 @@ typedef void (*GNUNET_PEERSTORE_Continuation) (void *cls, int success);
 
 
 /**
+ * Context for a add hello uri request.
+ */
+struct GNUNET_PEERSTORE_StoreHelloContext;
+
+
+/**
  * Function called by PEERSTORE for each matching record.
  *
  * @param cls closure
+ * @param seq sequence in interation
  * @param record peerstore record information
  * @param emsg error message, or NULL if no errors
  */
@@ -177,6 +193,43 @@ typedef void (*GNUNET_PEERSTORE_Processor) (
   const struct GNUNET_PEERSTORE_Record *record,
   const char *emsg);
 
+/**
+ * Function called by PEERSTORE when notifying a client about a changed hello.
+ *
+ * @param cls closure
+ * @param hello_uri Hello uri.
+ */
+typedef void (*GNUNET_PEERSTORE_hello_notify_cb) (
+  void *cls,
+  const struct GNUNET_PeerIdentity *peer,
+  const struct GNUNET_MessageHeader *hello,
+  const char *err_msg);
+
+/**
+ * Add hello to peerstore.
+ *
+ * @param h handle for peerstore.
+ * @param msg The hello to add.
+ * @param cont The continuation function to execute after storing.
+ * @param cont_cls The continuation function closure.
+ * @return The context for storing.
+ */
+struct GNUNET_PEERSTORE_StoreHelloContext *
+GNUNET_PEERSTORE_hello_add (struct GNUNET_PEERSTORE_Handle *h,
+                            const struct GNUNET_MessageHeader *msg,
+                            GNUNET_PEERSTORE_Continuation cont,
+                            void *cont_cls);
+
+
+/**
+ * Cancel the request to add a hello.
+ *
+ * @param huc The context for storing a hello.
+ */
+void
+GNUNET_PEERSTORE_hello_add_cancel (struct
+                                   GNUNET_PEERSTORE_StoreHelloContext *huc);
+
 
 /**
  * Connect to the PEERSTORE service.
@@ -188,15 +241,13 @@ GNUNET_PEERSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
 /**
- * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH requests
- * will be canceled.
- * Any pending STORE requests will depend on @e snyc_first flag.
+ * Disconnect from the PEERSTORE service. Any pending ITERATE and WATCH and
+ * STORE requests will be canceled.
  *
  * @param h handle to disconnect
- * @param sync_first send any pending STORE requests before disconnecting
  */
 void
-GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first);
+GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h);
 
 
 /**
@@ -238,63 +289,130 @@ GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
 
 
 /**
- * Iterate over records matching supplied key information
+ * Iterate over peerstore entries.
+ * The iteration can be filtered to contain only records
+ * matching @a peer and/or @a key.
+ * The @a sub_system to match must be provided.
+ * @a callback will be called with (each) matching record.
+ * #GNUNET_PEERSTORE_iteration_next() must be invoked
+ * to continue processing until the end of the iteration is
+ * reached.
  *
  * @param h handle to the PEERSTORE service
  * @param sub_system name of sub system
  * @param peer Peer identity (can be NULL)
  * @param key entry key string (can be NULL)
- * @param callback function called with each matching record, all NULL's on end
+ * @param callback function called with each matching record. The record will be NULL to indicate end.
  * @param callback_cls closure for @a callback
+ * @return Handle to iteration request
  */
 struct GNUNET_PEERSTORE_IterateContext *
-GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h,
-                          const char *sub_system,
-                          const struct GNUNET_PeerIdentity *peer,
-                          const char *key,
-                          GNUNET_PEERSTORE_Processor callback,
-                          void *callback_cls);
+GNUNET_PEERSTORE_iteration_start (struct GNUNET_PEERSTORE_Handle *h,
+                                  const char *sub_system,
+                                  const struct GNUNET_PeerIdentity *peer,
+                                  const char *key,
+                                  GNUNET_PEERSTORE_Processor callback,
+                                  void *callback_cls);
 
 
 /**
- * Cancel an iterate request
- * Please do not call after the iterate request is done
+ * Continue an iteration.
+ * Do NOT call after the iterate request is done.
  *
- * @param ic Iterate request context as returned by GNUNET_PEERSTORE_iterate()
+ * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start()
+ * @param limit how many records to return max until #GNUNET_PEERSTORE_iterate_next() needs to be called again.
  */
 void
-GNUNET_PEERSTORE_iterate_cancel (struct GNUNET_PEERSTORE_IterateContext *ic);
+GNUNET_PEERSTORE_iteration_next (struct GNUNET_PEERSTORE_IterateContext *ic,
+                                 uint64_t limit);
 
 
 /**
+ * Cancel an iteration.
+ * Do NOT call after the iterate request is done
+ *
+ * @param ic Iterate request context as returned by #GNUNET_PEERSTORE_iteration_start()
+ */
+void
+GNUNET_PEERSTORE_iteration_stop (struct GNUNET_PEERSTORE_IterateContext *ic);
+
+/**
  * Request watching a given key
- * User will be notified with any new values added to key.
+ * The monitoring can be filtered to contain only records
+ * matching @a peer and/or @a key.
+ * The @a sub_system to match must be provided.
+ * @a callback will be called with (each) matching new record.
+ * #GNUNET_PEERSTORE_monitor_next() must be invoked
+ * to continue processing until @a sync_cb is
+ * called, indicating that the caller should be up-to-date.
+ * The caller will be notified with any new values added to key
+ * through @a callback.
+ * If @a iterate_first is set to GNUNET_YES, the monitor will first
+ * iterate over all existing, matching records. In any case,
+ * after @a sync_cb is called the first time monitoring starts.
  *
  * @param h handle to the PEERSTORE service
+ * @param iterate_first first iterated of all results if GNUNET_YES
  * @param sub_system name of sub system
  * @param peer Peer identity
  * @param key entry key string
+ * @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_PEERSTORE_monitor_stop().
+ * @param error_cb_cls closure for @a error_cb
+ * @param sync_cb function called when we're in sync with the peerstore
+ * @param sync_cb_cls closure for @a sync_cb
  * @param callback function called with each new value
  * @param callback_cls closure for @a callback
  * @return Handle to watch request
  */
-struct GNUNET_PEERSTORE_WatchContext *
-GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h,
-                        const char *sub_system,
-                        const struct GNUNET_PeerIdentity *peer,
-                        const char *key,
-                        GNUNET_PEERSTORE_Processor callback,
-                        void *callback_cls);
-
+struct GNUNET_PEERSTORE_Monitor *
+GNUNET_PEERSTORE_monitor_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                int iterate_first,
+                                const char *sub_system,
+                                const struct GNUNET_PeerIdentity *peer,
+                                const char *key,
+                                GNUNET_SCHEDULER_TaskCallback error_cb,
+                                void *error_cb_cls,
+                                GNUNET_SCHEDULER_TaskCallback sync_cb,
+                                void *sync_cb_cls,
+                                GNUNET_PEERSTORE_Processor callback,
+                                void *callback_cls);
 
 /**
- * Cancel a watch request
+ * Calls the monitor processor specified in #GNUNET_PEERSTORE_monitor_start
+ * for the next record(s).  This function is used to allow clients that merely
+ * monitor the NAMESTORE to still throttle namestore operations, so we can be
+ * sure that the monitors can keep up.
+ *
+ * Note that #GNUNET_PEERSTORE_store() only waits for this
+ * call if the previous limit set by the client was already reached.
+ * Thus, by using a @a limit greater than 1, monitors basically enable
+ * a queue of notifications to be processed asynchronously with some
+ * delay.  Note that even with a limit of 1 the
+ * #GNUNET_PEERSTORE_store() function will run asynchronously
+ * and the continuation may be invoked before the monitors completed
+ * (or even started) processing the notification.  Thus, monitors will
+ * only closely track the current state of the peerstore, but not
+ * be involved in the transactions.
  *
- * @param wc handle to the watch request
+ * @param zm the monitor
+ * @param limit number of records to return to the iterator in one shot
+ *        (before #GNUNET_PEERSTORE_monitor_next is to be called again)
  */
 void
-GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc);
+GNUNET_PEERSTORE_monitor_next (struct GNUNET_PEERSTORE_Monitor *zm,
+                               uint64_t limit);
 
+/**
+ * Stop monitoring.
+ *
+ * @param zm handle to the monitor activity to stop
+ */
+void
+GNUNET_PEERSTORE_monitor_stop (struct GNUNET_PEERSTORE_Monitor *zm);
 
 #if 0 /* keep Emacsens' auto-indent happy */
 {
@@ -306,3 +424,5 @@ GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc);
 #endif
 
 /** @} */ /* end of group */
+
+/** @} */ /* end of group addition */