X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_social_service.h;h=7faa336d6a5a7109cd1d3d15a139a21c4583ae74;hb=634aea297cc983c3d70f65a004f698f215abe590;hp=26b335facd8c64327844ed143c479bfc0f1ff67e;hpb=9a12525940373bd2616357e066fe59cb2ea08d8d;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index 26b335fac..7faa336d6 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -2,20 +2,20 @@
      This file is part of GNUnet.
      Copyright (C) 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
-     by the Free Software Foundation; either version 3, or (at your
-     option) any later version.
+     GNUnet is free software: you can redistribute it and/or modify it
+     under the terms of the GNU Affero General Public License as published
+     by the Free Software Foundation, either version 3 of the License,
+     or (at your option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-     General Public License for more details.
+     Affero General Public License for more details.
+    
+     You should have received a copy of the GNU Affero General Public License
+     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-     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., 51 Franklin Street, Fifth Floor,
-     Boston, MA 02110-1301, USA.
+     SPDX-License-Identifier: AGPL3.0-or-later
 */
 
 /**
@@ -86,7 +86,7 @@ or process it using a message handler function.
 
 A client first establishes an _application connection_ to the service using
 GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
-public keys of subscribed places and available egos and in response.
+public keys of subscribed places and available egos in response.
 
 ## Reconnecting to places
 
@@ -112,13 +112,13 @@ When leaving a place its network connections are closed and all applications are
 
 # Message methods
 
-## _message
+## _converse
 
-A message sent to the place.
+Human conversation in a private or public place.
 
 ### Environment
 
-#### _id_reply_to
+#### _id_reply
 Message ID this message is in reply to.
 
 #### _id_thread
@@ -127,10 +127,14 @@ Thread ID, the first message ID in the thread.
 #### _nym_author
 Nym of the author.
 
+FIXME: Are nyms a different data type from egos and person entities?
+Do they have a different format than any other entity address?
+Questions and thoughts on how to fix this in "questions.org"
+
 #### _sig_author
 Signature of the message body and its variables by the author.
 
-## Data
+### Data
 
 Message body.
 
@@ -148,11 +152,18 @@ e.g. files under a given size.
 ##### _gns_place
 GNS name of the place in a globally unique .zkey zone
 
+FIXME: A custom _gns PSYC data type should be avoidable by parsing
+and interpreting PSYC uniforms appropriately.
+Thoughts on this in "questions.org"
+
 #### Without GNS
 
 ##### _key_pub_place
 Public key of place
 
+FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic
+addressing. Questions and thoughts on how to fix this in "questions.org"
+
 ##### _peer_origin
 Peer ID of origin
 
@@ -170,7 +181,7 @@ The environment of _notice_place above, plus the following:
 #### _size_file
 Size of file
 
-#### _mime_file
+#### _type_file
 MIME type of file
 
 #### _name_file
@@ -182,15 +193,15 @@ Description of file
 ## _file
 
 Messages with a _file method contain a file,
-which is saved to disk upon receipt at the following location:
-$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
+which is saved to disk upon reception at the following location:
+$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)>
 
 ### Environment
 
 #### _size_file
 Size of file
 
-#### _mime_file
+#### _type_file
 MIME type of file
 
 #### _name_file
@@ -296,25 +307,39 @@ typedef void
 
 
 /**
- * Entry status of a place.
+ * 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.
  *
@@ -327,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.
@@ -348,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.
  *
@@ -384,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);
 
 
 /**
@@ -457,21 +489,28 @@ GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
  * for it.
  *
- * @param cls Closure.
- * @param nym Handle for the user who wants to enter.
- * @param method_name Method name in the entry request.
- * @param variable_count Number of elements in the @a variables array.
- * @param variables Variables present in the message.
- * @param data_size Number of bytes in @a data.
- * @param data Payload given on enter (e.g. a password).
+ * @param cls
+ *        Closure.
+ * @param nym
+ *        Handle for the user who wants to enter.
+ * @param method_name
+ *        Method name in the entry request.
+ * @param variable_count
+ *        Number of elements in the @a variables array.
+ * @param variables
+ *        Variables present in the message.
+ * @param data
+ *        Payload given on enter (e.g. a password).
+ * @param data_size
+ *        Number of bytes in @a data.
  */
 typedef void
 (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
                                      struct GNUNET_SOCIAL_Nym *nym,
                                      const char *method_name,
                                      struct GNUNET_PSYC_Environment *env,
-                                     size_t data_size,
-                                     const void *data);
+                                     const void *data,
+                                     size_t data_size);
 
 
 /**
@@ -589,14 +628,8 @@ GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn,
  *        #GNUNET_YES    if @a nym is admitted,
  *        #GNUNET_NO     if @a nym is refused entry,
  *        #GNUNET_SYSERR if we cannot answer the request.
- * @param method_name
- *        Method name for the rejection message.
- * @param env
- *        Environment containing variables for the message, or NULL.
- * @param data
- *        Data for the rejection message to send back.
- * @param data_size
- *        Number of bytes in @a data for method.
+ * @param entry_resp
+ *        Entry response message, or NULL.
  * @return #GNUNET_OK on success,
  *         #GNUNET_SYSERR if the message is too large.
  */
@@ -782,7 +815,7 @@ GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst,
 /**
  * Stop hosting a home.
  *
- * Sends a _notice_place_closed announcement to the home.
+ * Sends a _notice_place_closing announcement to the home.
  * Invalidates host handle.
  *
  * @param hst
@@ -814,12 +847,15 @@ GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst,
  *        #GNUNET_OK on success, or
  *        #GNUNET_SYSERR on error, e.g. could not connect to the service, or
  *        could not resolve GNS name.
+ * @param place_pub_key
+ *        Public key of place.
  * @param max_message_id
  *        Last message ID sent to the place.
  *        Or 0 if no messages have been sent to the place yet.
  */
 typedef void
 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
+                                     const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
                                      uint64_t max_message_id);
 
 
@@ -857,14 +893,8 @@ typedef void
  *        Number of elements in the @a relays array.
  * @param relays
  *        Relays for the underlying multicast group.
- * @param method_name
- *        Method name for the message.
- * @param env
- *        Environment containing variables for the message, or NULL.
- * @param data
- *        Payload for the message to give to the enter callback.
- * @param data_size
- *        Number of bytes in @a data.
+ * @param entry_msg
+ *        Entry message.
  * @param slicer
  *        Slicer to use for processing incoming requests from guests.
  *
@@ -1068,6 +1098,18 @@ GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
 struct GNUNET_SOCIAL_HistoryRequest;
 
 
+/**
+ * Get the public key of a place.
+ *
+ * @param plc
+ *        Place.
+ *
+ * @return Public key of the place.
+ */
+const struct GNUNET_CRYPTO_EddsaPublicKey *
+GNUNET_SOCIAL_place_get_pub_key (const struct GNUNET_SOCIAL_Place *plc);
+
+
 /**
  * Set message processing @a flags for a @a method_prefix.
  *
@@ -1175,8 +1217,6 @@ struct GNUNET_SOCIAL_LookHandle;
  *        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.
  */