migrate peerstore to new service MQ API

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

diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index 7ecdf1d537e6971408caca64345382c6d61b7ef5..e9c7f309cf4ccab376ceb249617e65b32e66c5d2 100644 (file)
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -194,7 +194,7 @@ Description of file
 
 Messages with a _file method contain a file,
 which is saved to disk upon reception at the following location:
-$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
+$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)>
 
 ### Environment
 
@@ -307,29 +307,39 @@ typedef void
 
 
 /**
- * Entry status of a place.
- *
- * Note: The intermediate status of having entered a place without
- * being subscribed to it may be obsoleted in future unless we find a
- * compelling reason for it to exist. FIXME: See questions.org.
+ * Entry status of a place per application.
  */
-enum GNUNET_SOCIAL_PlaceState
+enum GNUNET_SOCIAL_AppPlaceState
 {
   /**
-   * Place was once entered but left since.
+   * The place was once entered by the ego, but left since.
+   * It's possible to establish a local connection to the place
+   * without re-entering to fetch history from the PSYCstore.
+   * @see enum GNUNET_PSYC_SlaveJoinFlags and GNUNET_SOCIAL_guest_enter()
    */
   GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
+
   /**
-   * Place is entered but not subscribed.
+   * The place is entered by the ego,
+   * but this application is not subscribed to it.
    */
   GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
+
   /**
-   * Place is entered and subscribed.
+   * The place is entered by the ego and
+   * and this application is subscribed to it.
    */
   GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
 };
 
 
+/**
+ * Called after receiving initial list of egos and places.
+ */
+typedef void
+(*GNUNET_SOCIAL_AppConnectedCallback) (void *cls);
+
+
 /**
  * Notification about a home.
  *
@@ -342,14 +352,14 @@ enum GNUNET_SOCIAL_PlaceState
  * @param place_pub_key
  *        Public key of the place.
  * @param place_state
- *        @see enum GNUNET_SOCIAL_PlaceState
+ *        @see enum GNUNET_SOCIAL_AppPlaceState
  */
 typedef void
 (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
                                        struct GNUNET_SOCIAL_HostConnection *hconn,
                                        struct GNUNET_SOCIAL_Ego *ego,
                                        const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
-                                       enum GNUNET_SOCIAL_PlaceState place_state);
+                                       enum GNUNET_SOCIAL_AppPlaceState place_state);
 
 /**
  * Notification about a place.
@@ -363,20 +373,20 @@ typedef void
  * @param place_pub_key
  *        Public key of the place.
  * @param place_state
- *        @see enum GNUNET_SOCIAL_PlaceState
+ *        @see enum GNUNET_SOCIAL_AppPlaceState
  */
 typedef void
 (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
                                         struct GNUNET_SOCIAL_GuestConnection *gconn,
                                         struct GNUNET_SOCIAL_Ego *ego,
                                         const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
-                                        enum GNUNET_SOCIAL_PlaceState place_state);
+                                        enum GNUNET_SOCIAL_AppPlaceState place_state);
 
 
 /**
  * Establish application connection to the social service.
  *
- * The @host_place_cb and @guest_place_cb functions are
+ * The @host_cb and @guest_cb functions are
  * initially called for each entered places,
  * then later each time a new place is entered with the current app ID.
  *
@@ -399,17 +409,24 @@ GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
                            GNUNET_SOCIAL_AppEgoCallback ego_cb,
                            GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
                            GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
+                           GNUNET_SOCIAL_AppConnectedCallback connected_cb,
                            void *cls);
 
 
 /**
  * Disconnect app.
  *
- * @param c
- *        App handle.
+ * @param app
+ *        Application handle.
+ * @param disconnect_cb
+ *        Disconnect callback.
+ * @param disconnect_cls
+ *        Disconnect closure.
  */
 void
-GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app);
+GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app,
+                              GNUNET_ContinuationCallback disconnect_cb,
+                              void *disconnect_cls);
 
 
 /**