psyc/social: request history & state from psycstore; more documentation, tests, cleanup

5 files changed, 325 insertions, 128 deletions

diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index cdbc46f7f..2c73eadd6 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -2222,7 +2222,7 @@ extern "C"
 
 /* 700 */
 
-/** C->S: client requests channel history from PSYCstore. */
+/** C->S: request channel history replay from PSYCstore. */
 #define GNUNET_MESSAGE_TYPE_PSYC_HISTORY_REPLAY 701
 
 /** S->C: result for a channel history request */
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 5239acb16..c7692f074 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -376,6 +376,106 @@ struct GNUNET_PSYC_JoinDecisionMessage
   /* Followed by struct GNUNET_MessageHeader join_response */
 };
 
+
+enum GNUNET_PSYC_HistoryReplayFlags
+{
+  /**
+   * Replay locally available messages.
+   */
+  GNUNET_PSYC_HISTORY_REPLAY_LOCAL  = 0,
+
+  /**
+   * Replay messages from remote peers if not found locally.
+   */
+  GNUNET_PSYC_HISTORY_REPLAY_REMOTE = 1,
+};
+
+
+struct GNUNET_PSYC_HistoryRequestMessage
+{
+  /**
+   * Type: GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_HISTORY_REPLAY
+   */
+  struct GNUNET_MessageHeader header;
+
+  /**
+   * @see enum GNUNET_PSYC_HistoryReplayFlags
+   */
+  uint32_t flags GNUNET_PACKED;
+
+  /**
+   * ID for this operation.
+   */
+  uint64_t op_id GNUNET_PACKED;
+
+  uint64_t start_message_id GNUNET_PACKED;
+
+  uint64_t end_message_id GNUNET_PACKED;
+
+  uint64_t message_limit GNUNET_PACKED;
+
+  /* Followed by NUL-terminated method name prefix. */
+};
+
+
+struct GNUNET_PSYC_StateRequestMessage
+{
+  /**
+   * Types:
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_GET_PREFIX
+   */
+  struct GNUNET_MessageHeader header;
+
+  uint32_t reserved GNUNET_PACKED;
+
+  /**
+   * ID for this operation.
+   */
+  uint64_t op_id GNUNET_PACKED;
+
+  /* Followed by NUL-terminated name. */
+};
+
+
+/**** service -> library ****/
+
+
+/**
+ * Answer from service to client about last operation.
+ */
+struct GNUNET_PSYC_OperationResultMessage
+{
+  /**
+   * Types:
+   * - GNUNET_MESSAGE_TYPE_PSYC_RESULT_CODE
+   * - GNUNET_MESSAGE_TYPE_PSYC_CHANNEL_STATE_RESULT
+   */
+  struct GNUNET_MessageHeader header;
+
+  uint32_t reserved GNUNET_PACKED;
+
+  /**
+   * Operation ID.
+   */
+  uint64_t op_id GNUNET_PACKED;
+
+  /**
+   * Status code for the operation.
+   */
+  uint64_t result_code GNUNET_PACKED;
+
+  /* Followed by:
+   * - on error: NUL-terminated error message
+   * - on success: one of the following message types
+   *
+   *   For a STATE_RESULT, one of:
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MODIFIER
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_MOD_CONT
+   *   - GNUNET_MESSAGE_TYPE_PSYC_MESSAGE_END
+   */
+};
+
 GNUNET_NETWORK_STRUCT_END
 
 
@@ -907,23 +1007,6 @@ 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.
  *
@@ -960,17 +1043,28 @@ GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave);
  * correctly; not doing so correctly will result in either denying other slaves
  * access or offering access to channel data to non-members.
  *
- * @param channel Channel handle.
- * @param slave_key Identity of channel slave to add.
- * @param announced_at ID of the message that announced the membership change.
- * @param effective_since Addition of slave is in effect since this message ID.
+ * @param channel
+ *        Channel handle.
+ * @param slave_key
+ *        Identity of channel slave to add.
+ * @param announced_at
+ *        ID of the message that announced the membership change.
+ * @param effective_since
+ *        Addition of slave is in effect since this message ID.
+ * @param result_cb
+ *        Function to call with the result of the operation.
+ *        The @e result_code argument is #GNUNET_OK on success, or
+ *        #GNUNET_SYSERR on error.  In case of an error, the @e data argument
+ *        can contain an optional error message.
+ * @param cls
+ *        Closure for @a result_cb.
  */
 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,
-                               GNUNET_PSYC_ResultCallback result_cb,
+                               GNUNET_ResultCallback result_cb,
                                void *cls);
 
 
@@ -991,33 +1085,33 @@ GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel,
  * denying members access or offering access to channel data to
  * non-members.
  *
- * @param channel Channel handle.
- * @param slave_key Identity of channel slave to remove.
- * @param announced_at ID of the message that announced the membership change.
+ * @param channel
+ *        Channel handle.
+ * @param slave_key
+ *        Identity of channel slave to remove.
+ * @param announced_at
+ *        ID of the message that announced the membership change.
+ * @param result_cb
+ *        Function to call with the result of the operation.
+ *        The @e result_code argument is #GNUNET_OK on success, or
+ *        #GNUNET_SYSERR on error.  In case of an error, the @e data argument
+ *        can contain an optional error message.
+ * @param cls
+ *        Closure for @a result_cb.
  */
 void
 GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel,
                                   const struct GNUNET_CRYPTO_EcdsaPublicKey
                                   *slave_key,
                                   uint64_t announced_at,
-                                  GNUNET_PSYC_ResultCallback result_cb,
+                                  GNUNET_ResultCallback result_cb,
                                   void *cls);
 
 
 /**
- * Function called to inform a member about stored state values for a channel.
- *
- * @param cls Closure.
- * @param name Name of the state variable.  A NULL value indicates that there
- *        are no more state variables to be returned.
- * @param value Value of the state variable.
- * @param value_size Number of bytes in @a value.
+ * History request handle.
  */
-typedef void
-(*GNUNET_PSYC_StateVarCallback) (void *cls,
-                                 const char *name,
-                                 const void *value,
-                                 size_t value_size);
+struct GNUNET_PSYC_HistoryRequest;
 
 
 /**
@@ -1032,22 +1126,28 @@ typedef void
  *        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 method_prefix
+ *        Retrieve only messages with a matching method prefix.
+ * @param flags
+ *        OR'ed enum GNUNET_PSYC_HistoryReplayFlags
+ * @param result_cb
+ *        Function to call when the requested history has been fully replayed.
+ *        Once this function has been called, the client must not call
+ *        GNUNET_PSYC_channel_history_replay_cancel() anymore.
  * @param cls
  *        Closure for the callbacks.
  *
  * @return Handle to cancel history replay operation.
  */
-void
+struct GNUNET_PSYC_HistoryRequest *
 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,
+                                    const char *method_prefix,
+                                    uint32_t flags,
+                                    GNUNET_PSYC_MessageCallback message_cb,
+                                    GNUNET_PSYC_MessagePartCallback message_part_cb,
+                                    GNUNET_ResultCallback result_cb,
                                     void *cls);
 
 
@@ -1061,6 +1161,8 @@ GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel,
  *        Which channel should be replayed?
  * @param message_limit
  *        Maximum number of messages to replay.
+ * @param flags
+ *        OR'ed enum GNUNET_PSYC_HistoryReplayFlags
  * @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
@@ -1072,13 +1174,44 @@ GNUNET_PSYC_channel_history_replay (struct GNUNET_PSYC_Channel *channel,
  *
  * @return Handle to cancel history replay operation.
  */
-void
+struct GNUNET_PSYC_HistoryRequest *
 GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel,
                                            uint64_t message_limit,
-                                           GNUNET_PSYC_ResultCallback finish_cb,
+                                           const char *method_prefix,
+                                           uint32_t flags,
+                                           GNUNET_PSYC_MessageCallback message_cb,
+                                           GNUNET_PSYC_MessagePartCallback message_part_cb,
+                                           GNUNET_ResultCallback result_cb,
                                            void *cls);
 
 
+void
+GNUNET_PSYC_channel_history_replay_cancel (struct GNUNET_PSYC_Channel *channel,
+                                           struct GNUNET_PSYC_HistoryRequest *hr);
+
+
+/**
+ * Function called to inform a member about stored state values for a channel.
+ *
+ * @param cls Closure.
+ * @param name Name of the state variable.  A NULL value indicates that there
+ *        are no more state variables to be returned.
+ * @param value Value of the state variable.
+ * @param value_size Number of bytes in @a value.
+ */
+typedef void
+(*GNUNET_PSYC_StateVarCallback) (void *cls,
+                                 const char *name,
+                                 const void *value,
+                                 size_t value_size);
+
+
+/**
+ * State request handle.
+ */
+struct GNUNET_PSYC_StateRequest;
+
+
 /**
  * Retrieve the best matching channel state variable.
  *
@@ -1100,11 +1233,11 @@ GNUNET_PSYC_channel_history_replay_latest (struct GNUNET_PSYC_Channel *channel,
  * @param cls
  *        Closure for the callbacks.
  */
-void
+struct GNUNET_PSYC_StateRequest *
 GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel,
                                const char *full_name,
                                GNUNET_PSYC_StateVarCallback var_cb,
-                               GNUNET_PSYC_ResultCallback result_cb,
+                               GNUNET_ResultCallback result_cb,
                                void *cls);
 
 
@@ -1131,13 +1264,23 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel,
  * @param cls
  *        Closure for the callbacks.
  */
-void
+struct GNUNET_PSYC_StateRequest *
 GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel,
                                       const char *name_prefix,
                                       GNUNET_PSYC_StateVarCallback var_cb,
-                                      GNUNET_PSYC_ResultCallback result_cb,
+                                      GNUNET_ResultCallback result_cb,
                                       void *cls);
 
+/**
+ * Cancel a state request operation.
+ *
+ * @param sr
+ *        Handle for the operation to cancel.
+ */
+void
+GNUNET_PSYC_channel_state_get_cancel (struct GNUNET_PSYC_StateRequest *sr);
+
+
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_psyc_util_lib.h b/src/include/gnunet_psyc_util_lib.h
index 488edc03b..3ec9fe1bf 100644
--- a/src/include/gnunet_psyc_util_lib.h
+++ b/src/include/gnunet_psyc_util_lib.h
@@ -115,16 +115,24 @@ GNUNET_PSYC_transmit_destroy (struct GNUNET_PSYC_TransmitHandle *tmit);
 /**
  * Transmit a message.
  *
- * @param tmit         Transmission handle.
- * @param method_name  Which method should be invoked.
- * @param env          Environment for the message.
- *   Should stay available until the first call to notify_data.
- *   Can be NULL if there are no modifiers or @a notify_mod is provided instead.
- * @param notify_mod   Function to call to obtain modifiers.
- *   Can be NULL if there are no modifiers or @a env is provided instead.
- * @param notify_data  Function to call to obtain fragments of the data.
- * @param notify_cls   Closure for @a notify_mod and @a notify_data.
- * @param flags        Flags for the message being transmitted.
+ * @param tmit
+ *        Transmission handle.
+ * @param method_name
+ *        Which method should be invoked.
+ * @param env
+ *        Environment for the message.
+ *        Should stay available until the first call to notify_data.
+ *        Can be NULL if there are no modifiers or @a notify_mod is
+ *        provided instead.
+ * @param notify_mod
+ *        Function to call to obtain modifiers.
+ *        Can be NULL if there are no modifiers or @a env is provided instead.
+ * @param notify_data
+ *        Function to call to obtain fragments of the data.
+ * @param notify_cls
+ *        Closure for @a notify_mod and @a notify_data.
+ * @param flags
+ *        Flags for the message being transmitted.
  *
  * @return #GNUNET_OK if the transmission was started.
  *         #GNUNET_SYSERR if another transmission is already going on.
diff --git a/src/include/gnunet_psycstore_service.h b/src/include/gnunet_psycstore_service.h
index 2cb155f69..40acdae61 100644
--- a/src/include/gnunet_psycstore_service.h
+++ b/src/include/gnunet_psycstore_service.h
@@ -107,15 +107,20 @@ struct GNUNET_PSYCSTORE_OperationHandle;
 /**
  * Function called with the result of an asynchronous operation.
  *
+ * @param cls
+ *        Closure.
  * @param result
- *        #GNUNET_YES on success or if the peer was a member,
- *        #GNUNET_NO if the peer was not a member,
- *        #GNUNET_SYSERR on error,
+ *        Result of the operation.
+ * @param err_msg
+ *        Error message, or NULL if there's no error.
+ * @param err_msg_size
+ *        Size of @a err_msg
  */
 typedef void
 (*GNUNET_PSYCSTORE_ResultCallback) (void *cls,
                                     int64_t result,
-                                    const char *err_msg);
+                                    const char *err_msg,
+                                    uint16_t err_msg_size);
 
 
 /**
@@ -318,15 +323,15 @@ GNUNET_PSYCSTORE_fragment_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
  * @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.
+ *        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 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 method_prefix
+ *        Retrieve only messages with a matching method prefix.
  * @param fragment_cb
  *        Callback to call with the retrieved fragments.
  * @param result_cb
@@ -342,6 +347,7 @@ GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               const struct GNUNET_CRYPTO_EcdsaPublicKey *slave_key,
                               uint64_t first_message_id,
                               uint64_t last_message_id,
+                              const char *method_prefix,
                               GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
                               GNUNET_PSYCSTORE_ResultCallback result_cb,
                               void *cls);
@@ -355,14 +361,16 @@ GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
  * @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.
+ *        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 method_prefix
+ *        Retrieve only messages with a matching method prefix.
  * @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.
@@ -374,6 +382,7 @@ 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,
+                                     const char *method_prefix,
                                      GNUNET_PSYCSTORE_FragmentCallback fragment_cb,
                                      GNUNET_PSYCSTORE_ResultCallback rcb,
                                      void *cls);
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index fcfc8a359..a17446cf5 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -749,9 +749,45 @@ GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
 
 
 /**
- * A history lesson.
+ * A history request.
  */
-struct GNUNET_SOCIAL_HistoryLesson;
+struct GNUNET_SOCIAL_HistoryRequest;
+
+
+/**
+ * Learn about the history of a place.
+ *
+ * Messages are returned through the @a slicer function
+ * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
+ *
+ * @param place
+ *        Place we want to learn more about.
+ * @param start_message_id
+ *        First historic message we are interested in.
+ * @param end_message_id
+ *        Last historic message we are interested in (inclusive).
+ * @param method_prefix
+ *        Only retrieve messages with this method prefix.
+ * @param flags
+ *        OR'ed GNUNET_PSYC_HistoryReplayFlags
+ * @param slicer
+ *        Slicer to use for retrieved messages.
+ *        Can be the same as the slicer of the place.
+ * @param result_cb
+ *        Function called after all messages retrieved.
+ *        NULL if not needed.
+ * @param cls Closure for @a result_cb.
+ */
+struct GNUNET_SOCIAL_HistoryRequest *
+GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
+                                    uint64_t start_message_id,
+                                    uint64_t end_message_id,
+                                    const char *method_prefix,
+                                    uint32_t flags,
+                                    struct GNUNET_SOCIAL_Slicer *slicer,
+                                    GNUNET_ResultCallback result_cb,
+                                    void *cls);
+
 
 /**
  * Learn about the history of a place.
@@ -762,36 +798,32 @@ struct GNUNET_SOCIAL_HistoryLesson;
  *
  * To get the latest message, use 0 for both the start and end message ID.
  *
- * @param place Place we want to learn more about.
- * @param start_message_id First historic message we are interested in.
- * @param end_message_id Last historic message we are interested in (inclusive).
- * @param slicer Slicer to use to process history.  Can be the same as the
- *               slicer of the place, as the HISTORIC flag allows distinguishing
- *               old messages from fresh ones.
- * @param finish_cb Function called after the last message in the history lesson
- *              is passed through the @a slicer. NULL if not needed.
- * @param finish_cb_cls Closure for @a finish_cb.
- * @return Handle to abort history lesson, never NULL (multiple lessons
- *         at the same time are allowed).
+ * @param place
+ *        Place we want to learn more about.
+ * @param message_limit
+ *        Maximum number of historic messages we are interested in.
+ * @param result_cb
+ *        Function called after all messages retrieved.
+ *        NULL if not needed.
+ * @param cls Closure for @a result_cb.
  */
-struct GNUNET_SOCIAL_HistoryLesson *
-GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
-                                 uint64_t start_message_id,
-                                 uint64_t end_message_id,
-                                 const struct GNUNET_SOCIAL_Slicer *slicer,
-                                 void (*finish_cb)(void *),
-                                 void *finish_cb_cls);
-
+struct GNUNET_SOCIAL_HistoryRequest *
+GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
+                                           uint64_t message_limit,
+                                           const char *method_prefix,
+                                           uint32_t flags,
+                                           struct GNUNET_SOCIAL_Slicer *slicer,
+                                           GNUNET_ResultCallback result_cb,
+                                           void *cls);
 
 /**
- * Stop processing messages from the history lesson.
- *
- * Must not be called after the finish callback of the history lesson is called.
+ * Cancel learning about the history of a place.
  *
- * @param hist History lesson to cancel.
+ * @param hist
+ *        History lesson to cancel.
  */
 void
-GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
+GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
 
 
 struct GNUNET_SOCIAL_WatchHandle;
@@ -803,7 +835,7 @@ struct GNUNET_SOCIAL_WatchHandle;
  *        Place to watch.
  * @param object_filter
  *        Object prefix to match.
- * @param state_var_cb
+ * @param var_cb
  *        Function to call when an object/state var changes.
  * @param cls
  *        Closure for callback.
@@ -813,7 +845,7 @@ struct GNUNET_SOCIAL_WatchHandle;
 struct GNUNET_SOCIAL_WatchHandle *
 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
                            const char *object_filter,
-                           GNUNET_PSYC_StateVarCallback state_var_cb,
+                           GNUNET_PSYC_StateVarCallback var_cb,
                            void *cls);
 
 
@@ -830,13 +862,35 @@ struct GNUNET_SOCIAL_LookHandle;
 
 
 /**
- * Look at objects in the place with a matching name prefix.
+ * Look at a particular object in the place.
+ *
+ * The best matching object is returned (its name might be less specific than
+ * what was requested).
+ *
+ * @param place
+ *        The place to look the object at.
+ * @param full_name
+ *        Full name of the object.
+ * @param value_size
+ *        Set to the size of the returned value.
+ *
+ * @return NULL if there is no such object at this place.
+ */
+struct GNUNET_SOCIAL_LookHandle *
+GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
+                             const char *full_name,
+                             GNUNET_PSYC_StateVarCallback var_cb,
+                             GNUNET_ResultCallback result_cb,
+                             void *cls);
+
+/**
+ * Look for 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_var_cb
+ * @param var_cb
  *        Function to call for each object found.
  * @param cls
  *        Closure for callback function.
@@ -844,10 +898,11 @@ struct GNUNET_SOCIAL_LookHandle;
  * @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_StateVarCallback state_var_cb,
-                          void *cls);
+GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
+                              const char *name_prefix,
+                              GNUNET_PSYC_StateVarCallback var_cb,
+                              GNUNET_ResultCallback result_cb,
+                              void *cls);
 
 
 /**
@@ -859,24 +914,6 @@ void
 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 
 
-
-/**
- * Look at a particular object in the place.
- *
- * The best matching object is returned (its name might be less specific than
- * what was requested).
- *
- * @param place The place to look the object at.
- * @param full_name Full name of the object.
- * @param value_size Set to the size of the returned value.
- * @return NULL if there is no such object at this place.
- */
-const void *
-GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
-                             const char *full_name,
-                             size_t *value_size);
-
-
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif