psyc, psycstore: retrieve state and history

5 files changed, 325 insertions, 138 deletions

diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 5626e1e5e..ea295197c 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -2187,10 +2187,10 @@ extern "C"
 /* 700 */
 
 /** C->S: client requests channel history from PSYCstore. */
-#define GNUNET_MESSAGE_TYPE_PSYC_STORY_REQUEST 701
+#define GNUNET_MESSAGE_TYPE_PSYC_HISTORY_REPLAY 701
 
 /** S->C: result for a channel history request */
-#define GNUNET_MESSAGE_TYPE_PSYC_STORY_RESULT 702
+#define GNUNET_MESSAGE_TYPE_PSYC_HISTORY_RESULT 702
 
 
 /** C->S: request best matching state variable from PSYCstore. */
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 7097c46a8..25b405dad 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -160,6 +160,11 @@ enum GNUNET_PSYC_Policy
 enum GNUNET_PSYC_MessageFlags
 {
   /**
+   * Default / no flags.
+   */
+  GNUNET_PSYC_MESSAGE_DEFAULT = 0,
+
+  /**
    * Historic message, retrieved from PSYCstore.
    */
   GNUNET_PSYC_MESSAGE_HISTORIC = 1 << 0,
@@ -314,12 +319,12 @@ struct GNUNET_PSYC_CountersResultMessage
   /**
    * Status code for the operation.
    */
-  int32_t result_code GNUNET_PACKED;
+  uint32_t result_code GNUNET_PACKED;
 
   /**
    * Last message ID sent to the channel.
    */
-  uint64_t max_message_id;
+  uint64_t max_message_id GNUNET_PACKED;
 };
 
 
@@ -503,13 +508,24 @@ struct GNUNET_PSYC_Master;
 
 
 /**
- * Function called after the channel master started.
+ * Function called after connected to the PSYC service
+ * and the channel master started.
  *
- * @param cls Closure.
- * @param max_message_id Last message ID sent to the channel.
+ * Also called when reconnected to the service
+ * after the connection closed unexpectedly.
+ *
+ * @param cls
+ *        Closure.
+ * @param result
+ *        #GNUNET_YES if there were already messages sent to the channel,
+ *        #GNUNET_NO  if the message history is empty,
+ *        #GNUNET_SYSERR on error.
+ * @param max_message_id
+ *        Last message ID sent to the channel.
  */
 typedef void
-(*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id);
+(*GNUNET_PSYC_MasterStartCallback) (void *cls, int result,
+                                    uint64_t max_message_id);
 
 
 /**
@@ -720,11 +736,21 @@ struct GNUNET_PSYC_Slave;
 /**
  * Function called after the slave connected to the PSYC service.
  *
- * @param cls Closure.
- * @param max_message_id Last message ID sent to the channel.
+ * Also called when reconnected to the service
+ * after the connection closed unexpectedly.
+ *
+ * @param cls
+ *        Closure.
+ * @param result
+ *        #GNUNET_YES if there were already messages sent to the channel,
+ *        #GNUNET_NO  if the message history is empty,
+ *        #GNUNET_SYSERR on error.
+ * @param max_message_id
+ *        Last message ID sent to the channel.
  */
 typedef void
-(*GNUNET_PSYC_SlaveConnectCallback) (void *cls, uint64_t max_message_id);
+(*GNUNET_PSYC_SlaveConnectCallback) (void *cls, int result,
+                                     uint64_t max_message_id);
 
 
 /**
@@ -876,6 +902,23 @@ struct GNUNET_PSYC_Channel;
 
 
 /**
+ * Function called with the result of an asynchronous operation.
+ *
+ * @param cls
+ *        Closure.
+ * @param result
+ *        Result of the operation.
+ *        Usually one of #GNUNET_OK, #GNUNET_YES, #GNUNET_NO, or #GNUNET_SYSERR.
+ * @param err_msg
+ *        Error message.
+ */
+typedef void
+(*GNUNET_PSYC_ResultCallback) (void *cls,
+                               int64_t result,
+                               const char *err_msg);
+
+
+/**
  * Convert a channel @a master to a @e channel handle to access the @e channel
  * APIs.
  *
@@ -921,7 +964,9 @@ void
 GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel,
                                const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
                                uint64_t announced_at,
-                               uint64_t effective_since);
+                               uint64_t effective_since,
+                               GNUNET_PSYC_ResultCallback result_cb,
+                               void *cls);
 
 
 /**
@@ -949,7 +994,9 @@ void
 GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel,
                                   const struct GNUNET_CRYPTO_EcdsaPublicKey
                                   *slave_key,
-                                  uint64_t announced_at);
+                                  uint64_t announced_at,
+                                  GNUNET_PSYC_ResultCallback result_cb,
+                                  void *cls);
 
 
 /**
@@ -962,74 +1009,69 @@ GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel,
  * @param value_size Number of bytes in @a value.
  */
 typedef void
-(*GNUNET_PSYC_StateCallback) (void *cls,
-                              const char *name,
-                              const void *value,
-                              size_t value_size);
+(*GNUNET_PSYC_StateVarCallback) (void *cls,
+                                 const char *name,
+                                 const void *value,
+                                 size_t value_size);
 
 
 /**
- * Function called when a requested operation has finished.
- *
- * @param cls Closure.
- */
-typedef void
-(*GNUNET_PSYC_FinishCallback) (void *cls);
-
-
-/**
- * Handle to a story telling operation.
- */
-struct GNUNET_PSYC_Story;
-
-
-/**
- * Request to be told the message history of the channel.
+ * Request to replay a part of the message history of the channel.
  *
  * Historic messages (but NOT the state at the time) will be replayed (given to
  * the normal method handlers) if available and if access is permitted.
  *
- * To get the latest message, use 0 for both the start and end message ID.
+ * @param channel
+ *        Which channel should be replayed?
+ * @param start_message_id
+ *        Earliest interesting point in history.
+ * @param end_message_id
+ *        Last (inclusive) interesting point in history.
+ * @param finish_cb
+ *        Function to call when the requested history has been fully replayed
+ *        (counting message IDs might not suffice, as some messages might be
+ *        secret and thus the listener would not know the story is finished
+ *        without being told explicitly)o once this function has been called, the
+ *        client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore.
+ * @param cls
+ *        Closure for the callbacks.
  *
- * @param channel Which channel should be replayed?
- * @param start_message_id Earliest interesting point in history.
- * @param end_message_id Last (exclusive) interesting point in history.
- * @param message_cb Function to invoke on message parts received from the story.
- * @param finish_cb Function to call when the requested story has been fully
- *        told (counting message IDs might not suffice, as some messages
- *        might be secret and thus the listener would not know the story is
- *        finished without being told explicitly); once this function
- *        has been called, the client must not call
- *        GNUNET_PSYC_channel_story_tell_cancel() anymore.
- * @param cls Closure for the callbacks.
- * @return Handle to cancel story telling operation.
+ * @return Handle to cancel history replay operation.
  */
-struct GNUNET_PSYC_Story *
-GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel,
-                                uint64_t start_message_id,
-                                uint64_t end_message_id,
-                                GNUNET_PSYC_MessageCallback message_cb,
-                                GNUNET_PSYC_MessagePartCallback message_part_cb,
-                                GNUNET_PSYC_FinishCallback finish_cb,
-                                void *cls);
+void
+GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel,
+                                    uint64_t start_message_id,
+                                    uint64_t end_message_id,
+                                    GNUNET_PSYC_ResultCallback finish_cb,
+                                    void *cls);
 
 
 /**
- * Abort story telling.
+ * Request to replay the latest messages from the message history of the channel.
+ *
+ * Historic messages (but NOT the state at the time) will be replayed (given to
+ * the normal method handlers) if available and if access is permitted.
  *
- * This function must not be called from within method handlers (as given to
- * GNUNET_PSYC_slave_join()) of the slave.
+ * @param channel
+ *        Which channel should be replayed?
+ * @param message_limit
+ *        Maximum number of messages to replay.
+ * @param finish_cb
+ *        Function to call when the requested history has been fully replayed
+ *        (counting message IDs might not suffice, as some messages might be
+ *        secret and thus the listener would not know the story is finished
+ *        without being told explicitly)o once this function has been called, the
+ *        client must not call GNUNET_PSYC_channel_history_replay_cancel() anymore.
+ * @param cls
+ *        Closure for the callbacks.
  *
- * @param story Story telling operation to stop.
+ * @return Handle to cancel history replay operation.
  */
 void
-GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story);
-
-
-/**
- * Handle for a state query operation.
- */
-struct GNUNET_PSYC_StateQuery;
+GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel,
+                                           uint64_t message_limit,
+                                           GNUNET_PSYC_ResultCallback finish_cb,
+                                           void *cls);
 
 
 /**
@@ -1039,19 +1081,26 @@ struct GNUNET_PSYC_StateQuery;
  * less-specific name is matched; for example, requesting "_a_b" will match "_a"
  * if "_a_b" does not exist.
  *
- * @param channel Channel handle.
- * @param full_name Full name of the requested variable, the actual variable
- *        returned might have a shorter name..
- * @param cb Function called once when a matching state variable is found.
+ * @param channel
+ *        Channel handle.
+ * @param full_name
+ *        Full name of the requested variable.
+ *        The actual variable returned might have a shorter name.
+ * @param var_cb
+ *        Function called once when a matching state variable is found.
  *        Not called if there's no matching state variable.
- * @param cb_cls Closure for the callbacks.
- * @return Handle that can be used to cancel the query operation.
+ * @param result_cb
+ *        Function called after the operation finished.
+ *        (i.e. all state variables have been returned via @a state_cb)
+ * @param cls
+ *        Closure for the callbacks.
  */
-struct GNUNET_PSYC_StateQuery *
+void
 GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel,
                                const char *full_name,
-                               GNUNET_PSYC_StateCallback cb,
-                               void *cb_cls);
+                               GNUNET_PSYC_StateVarCallback var_cb,
+                               GNUNET_PSYC_ResultCallback result_cb,
+                               void *cls);
 
 
 /**
@@ -1064,26 +1113,25 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel,
  * The @a state_cb is invoked on all matching state variables asynchronously, as
  * the state is stored in and retrieved from the PSYCstore,
  *
- * @param channel Channel handle.
- * @param name_prefix Prefix of the state variable name to match.
- * @param cb Function to call with the matching state variables.
- * @param cb_cls Closure for the callbacks.
- * @return Handle that can be used to cancel the query operation.
+ * @param channel
+ *        Channel handle.
+ * @param name_prefix
+ *        Prefix of the state variable name to match.
+ * @param var_cb
+ *        Function called once when a matching state variable is found.
+ *        Not called if there's no matching state variable.
+ * @param result_cb
+ *        Function called after the operation finished.
+ *        (i.e. all state variables have been returned via @a state_cb)
+ * @param cls
+ *        Closure for the callbacks.
  */
-struct GNUNET_PSYC_StateQuery *
+void
 GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel,
                                       const char *name_prefix,
-                                      GNUNET_PSYC_StateCallback cb,
-                                      void *cb_cls);
-
-
-/**
- * Cancel a state query operation.
- *
- * @param query Handle for the operation to cancel.
- */
-void
-GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateQuery *query);
+                                      GNUNET_PSYC_StateVarCallback var_cb,
+                                      GNUNET_PSYC_ResultCallback result_cb,
+                                      void *cls);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
diff --git a/src/include/gnunet_psycstore_plugin.h b/src/include/gnunet_psycstore_plugin.h
index 1945b400e..3f02759f6 100644
--- a/src/include/gnunet_psycstore_plugin.h
+++ b/src/include/gnunet_psycstore_plugin.h
@@ -112,7 +112,7 @@ struct GNUNET_PSYCSTORE_PluginFunctions
                         uint64_t psycstore_flags);
 
   /**
-   * Retrieve a message fragment by fragment ID.
+   * Retrieve a message fragment range by fragment ID.
    *
    * @see GNUNET_PSYCSTORE_fragment_get()
    *
@@ -121,12 +121,29 @@ struct GNUNET_PSYCSTORE_PluginFunctions
   int
   (*fragment_get) (void *cls,
                    const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
-                   uint64_t fragment_id,
+                   uint64_t first_fragment_id,
+                   uint64_t last_fragment_id,
+                   uint64_t *returned_fragments,
                    GNUNET_PSYCSTORE_FragmentCallback cb,
                    void *cb_cls);
 
   /**
-   * Retrieve all fragments of a message.
+   * Retrieve latest message fragments.
+   *
+   * @see GNUNET_PSYCSTORE_fragment_get()
+   *
+   * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+   */
+  int
+  (*fragment_get_latest) (void *cls,
+                          const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+                          uint64_t fragment_limit,
+                          uint64_t *returned_fragments,
+                          GNUNET_PSYCSTORE_FragmentCallback cb,
+                          void *cb_cls);
+
+  /**
+   * Retrieve all fragments of a message ID range.
    *
    * @see GNUNET_PSYCSTORE_message_get()
    *
@@ -135,12 +152,28 @@ struct GNUNET_PSYCSTORE_PluginFunctions
   int
   (*message_get) (void *cls,
                   const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
-                  uint64_t message_id,
+                  uint64_t first_fragment_id,
+                  uint64_t last_fragment_id,
                   uint64_t *returned_fragments,
                   GNUNET_PSYCSTORE_FragmentCallback cb,
                   void *cb_cls);
 
   /**
+   * Retrieve all fragments of the latest messages.
+   *
+   * @see GNUNET_PSYCSTORE_message_get()
+   *
+   * @return #GNUNET_OK on success, else #GNUNET_SYSERR
+   */
+  int
+  (*message_get_latest) (void *cls,
+                         const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+                         uint64_t fragment_limit,
+                         uint64_t *returned_fragments,
+                         GNUNET_PSYCSTORE_FragmentCallback cb,
+                         void *cb_cls);
+
+  /**
    * Retrieve a fragment of message specified by its message ID and fragment
    * offset.
    *
diff --git a/src/include/gnunet_psycstore_service.h b/src/include/gnunet_psycstore_service.h
index 84d69c24d..78d016bb3 100644
--- a/src/include/gnunet_psycstore_service.h
+++ b/src/include/gnunet_psycstore_service.h
@@ -107,9 +107,10 @@ struct GNUNET_PSYCSTORE_OperationHandle;
 /**
  * Function called with the result of an asynchronous operation.
  *
- * @param result #GNUNET_SYSERR on error,
+ * @param result
  *        #GNUNET_YES on success or if the peer was a member,
- *        #GNUNET_NO if the peer was not a member
+ *        #GNUNET_NO if the peer was not a member,
+ *        #GNUNET_SYSERR on error,
  */
 typedef void
 (*GNUNET_PSYCSTORE_ResultCallback) (void *cls,
@@ -235,7 +236,7 @@ typedef int
 
 
 /**
- * Retrieve a message fragment by fragment ID.
+ * Retrieve message fragments by fragment ID range.
  *
  * @param h
  *        Handle for the PSYCstore.
@@ -245,11 +246,15 @@ typedef int
  *        The slave requesting the fragment.  If not NULL, a membership test is
  *        performed first and the fragment is only returned if the slave has
  *        access to it.
- * @param fragment_id
- *        Fragment ID to retrieve.  Use 0 to get the latest message fragment.
- * @param fcb
+ * @param first_fragment_id
+ *        First fragment ID to retrieve.
+ *        Use 0 to get the latest message fragment.
+ * @param last_fragment_id
+ *        Last consecutive fragment ID to retrieve.
+ *        Use 0 to get the latest message fragment.
+ * @param fragment_cb
  *        Callback to call with the retrieved fragments.
- * @param rcb
+ * @param result_cb
  *        Callback to call with the result of the operation.
  * @param cls
  *        Closure for the callbacks.
@@ -260,14 +265,53 @@ struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_fragment_get (struct GNUNET_PSYCSTORE_Handle *h,
                                const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
                                const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
-                               uint64_t fragment_id,
-                               GNUNET_PSYCSTORE_FragmentCallback fcb,
-                               GNUNET_PSYCSTORE_ResultCallback rcb,
+                               uint64_t first_message_id,
+                               uint64_t last_message_id,
+                               GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
+                               GNUNET_PSYCSTORE_ResultCallback result_cb,
                                void *cls);
 
 
 /**
- * Retrieve all fragments of a message.
+ * Retrieve latest message fragments.
+ *
+ * @param h
+ *        Handle for the PSYCstore.
+ * @param channel_key
+ *        The channel we are interested in.
+ * @param slave_key
+ *        The slave requesting the fragment.  If not NULL, a membership test is
+ *        performed first and the fragment is only returned if the slave has
+ *        access to it.
+ * @param first_fragment_id
+ *        First fragment ID to retrieve.
+ *        Use 0 to get the latest message fragment.
+ * @param last_fragment_id
+ *        Last consecutive fragment ID to retrieve.
+ *        Use 0 to get the latest message fragment.
+ * @param fragment_limit
+ *        Maximum number of fragments to retrieve.
+ * @param fragment_cb
+ *        Callback to call with the retrieved fragments.
+ * @param rcb
+ *        Callback to call with the result of the operation.
+ * @param cls
+ *        Closure for the callbacks.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
+struct GNUNET_PSYCSTORE_OperationHandle *
+GNUNET_PSYCSTORE_fragment_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
+                                      const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+                                      const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
+                                      uint64_t fragment_limit,
+                                      GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
+                                      GNUNET_PSYCSTORE_ResultCallback rcb,
+                                      void *cls);
+
+
+/**
+ * Retrieve all fragments of messages in a message ID range.
  *
  * @param h
  *        Handle for the PSYCstore.
@@ -277,11 +321,15 @@ GNUNET_PSYCSTORE_fragment_get (struct GNUNET_PSYCSTORE_Handle *h,
  *        The slave requesting the message.  If not NULL, a membership test is
  *        performed first and the message is only returned if the slave has
  *        access to it.
- * @param message_id
- *        Message ID to retrieve.  Use 0 to get the latest message.
- * @param fcb
+ * @param first_message_id
+ *        First message ID to retrieve.
+ *        Use 0 to get the latest message.
+ * @param last_message_id
+ *        Last consecutive message ID to retrieve.
+ *        Use 0 to get the latest message.
+ * @param fragment_cb
  *        Callback to call with the retrieved fragments.
- * @param rcb
+ * @param result_cb
  *        Callback to call with the result of the operation.
  * @param cls
  *        Closure for the callbacks.
@@ -292,23 +340,67 @@ struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
                               const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
-                              uint64_t message_id,
-                              GNUNET_PSYCSTORE_FragmentCallback fcb,
-                              GNUNET_PSYCSTORE_ResultCallback rcb,
+                              uint64_t first_message_id,
+                              uint64_t last_message_id,
+                              GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
+                              GNUNET_PSYCSTORE_ResultCallback result_cb,
                               void *cls);
 
 
 /**
+ * Retrieve all fragments of the latest messages.
+ *
+ * @param h
+ *        Handle for the PSYCstore.
+ * @param channel_key
+ *        The channel we are interested in.
+ * @param slave_key
+ *        The slave requesting the message.  If not NULL, a membership test is
+ *        performed first and the message is only returned if the slave has
+ *        access to it.
+ * @param message_limit
+ *        Maximum number of messages to retrieve.
+ * @param fragment_cb
+ *        Callback to call with the retrieved fragments.
+ * @param rcb
+ *        Callback to call with the result of the operation.
+ * @param cls
+ *        Closure for the callbacks.
+ *
+ * @return Handle that can be used to cancel the operation.
+ */
+struct GNUNET_PSYCSTORE_OperationHandle *
+GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
+                                     const struct GNUNET_CRYPTO_EddsaPublicKey *channel_key,
+                                     const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
+                                     uint64_t message_limit,
+                                     GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
+                                     GNUNET_PSYCSTORE_ResultCallback rcb,
+                                     void *cls);
+
+
+/**
  * Retrieve a fragment of message specified by its message ID and fragment
  * offset.
  *
- * @param h Handle for the PSYCstore.
- * @param channel_key The channel we are interested in.
- * @param message_id Message ID to check.  Use 0 to get the latest message.
- * @param fragment_offset Offset of the fragment to retrieve.
- * @param fcb Callback to call with the retrieved fragments.
- * @param rcb Callback to call with the result of the operation.
- * @param cls Closure for the callbacks.
+ * @param h
+ *        Handle for the PSYCstore.
+ * @param channel_key
+ *        The channel we are interested in.
+ * @param slave_key
+ *        The slave requesting the message fragment.  If not NULL, a membership
+ *        test is performed first and the message fragment is only returned
+ *        if the slave has access to it.
+ * @param message_id
+ *        Message ID to retrieve.  Use 0 to get the latest message.
+ * @param fragment_offset
+ *        Offset of the fragment to retrieve.
+ * @param fragment_cb
+ *        Callback to call with the retrieved fragments.
+ * @param result_cb
+ *        Callback to call with the result of the operation.
+ * @param cls
+ *        Closure for the callbacks.
  *
  * @return Handle that can be used to cancel the operation.
  */
@@ -318,8 +410,8 @@ GNUNET_PSYCSTORE_message_get_fragment (struct GNUNET_PSYCSTORE_Handle *h,
                                        const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
                                        uint64_t message_id,
                                        uint64_t fragment_offset,
-                                       GNUNET_PSYCSTORE_FragmentCallback fcb,
-                                       GNUNET_PSYCSTORE_ResultCallback rcb,
+                                       GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
+                                       GNUNET_PSYCSTORE_ResultCallback result_cb,
                                        void *cls);
 
 
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index ca1578820..66427a072 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -287,12 +287,18 @@ typedef void
 /**
  * Function called after the host entered the place.
  *
- * @param cls             Closure.
- * @param max_message_id  Last message ID sent to the channel.
- *   Or 0 if no messages have been sent to the place yet.
+ * @param cls
+ *        Closure.
+ * @param result
+ *        #GNUNET_OK on success, or
+ *        #GNUNET_SYSERR on error.
+ * @param max_message_id
+ *        Last message ID sent to the channel.
+ *        Or 0 if no messages have been sent to the place yet.
  */
 typedef void
-(*GNUNET_SOCIAL_HostEnterCallback) (void *cls, uint64_t max_message_id);
+(*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result,
+                                    uint64_t max_message_id);
 
 
 /**
@@ -793,18 +799,22 @@ struct GNUNET_SOCIAL_WatchHandle;
 /**
  * Watch a place for changed objects.
  *
- * @param place Place to watch.
- * @param object_filter Object prefix to match.
- * @param state_cb Function to call when an object/state changes.
- * @param state_cb_cls Closure for callback.
+ * @param place
+ *        Place to watch.
+ * @param object_filter
+ *        Object prefix to match.
+ * @param state_var_cb
+ *        Function to call when an object/state var changes.
+ * @param cls
+ *        Closure for callback.
  *
  * @return Handle that can be used to cancel watching.
  */
 struct GNUNET_SOCIAL_WatchHandle *
 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
                            const char *object_filter,
-                           GNUNET_PSYC_StateCallback state_cb,
-                           void *state_cb_cls);
+                           GNUNET_PSYC_StateVarCallback state_var_cb,
+                           void *cls);
 
 
 /**
@@ -822,18 +832,22 @@ struct GNUNET_SOCIAL_LookHandle;
 /**
  * Look at objects in the place with a matching name prefix.
  *
- * @param place The place to look its objects at.
- * @param name_prefix Look at objects with names beginning with this value.
- * @param state_cb Function to call for each object found.
- * @param state_cb_cls Closure for callback function.
+ * @param place
+ *        The place to look its objects at.
+ * @param name_prefix
+ *        Look at objects with names beginning with this value.
+ * @param state_var_cb
+ *        Function to call for each object found.
+ * @param cls
+ *        Closure for callback function.
  *
  * @return Handle that can be used to stop looking at objects.
  */
 struct GNUNET_SOCIAL_LookHandle *
 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
                           const char *name_prefix,
-                          GNUNET_PSYC_StateCallback state_cb,
-                          void *state_cb_cls);
+                          GNUNET_PSYC_StateVarCallback state_var_cb,
+                          void *cls);
 
 
 /**