2 This file is part of GNUnet.
3 Copyright (C) 2013 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Gabor X Toth
23 * @author Christian Grothoff
26 * Social service; implements social interactions through the PSYC service.
29 /** @defgroup social Social service
30 Social interactions through the PSYC service.
34 The social service provides an API for social interactions based on a one-to-many messaging model.
35 It manages subscriptions of applications to places, provides messaging functionality in places,
36 allows access to the local message history and manages the GNS zone of _egos_ (user identities).
38 The service stores private and public keys of subscribed places, as well as files received in subscribed places.
40 # Concepts and terminology
44 An _ego_ is an identity of a user, a private-public key pair.
45 A _nym_ is an identity of another user in the network, identified by its public key.
46 Each user can have multiple identities.
48 struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities.
52 A _place_ is where social interactions happen. It is owned and created by an _ego_.
53 Creating a new place happens by an _ego_ entering a new place as a _host_,
54 where _guests_ can enter later to receive messages sent to the place.
56 A place is identified by its public key.
58 - struct GNUNET_SOCIAL_Host represents a place entered as host,
59 - struct GNUNET_SOCIAL_Guest is used for a place entered as guest.
60 - A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place
61 using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place()
62 and can be used with API functions common to hosts and guests.
66 Messages sent to places are stored locally by the PSYCstore service, and can be queried any time.
67 GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place,
68 while GNUNET_SOCIAL_history_replay() is used to query a given message ID range.
72 The GNU Name System is used for assigning human-readable names to nyms and places.
73 There's a _GNS zone_ corresponding to each _nym_.
74 An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively.
76 ## Announcement, talk request
78 The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce().
79 Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk().
80 The host receives talk requests of guests and can _relay_ them to the place,
81 or process it using a message handler function.
85 ## Connecting to the service
87 A client first establishes an _application connection_ to the service using
88 GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
89 public keys of subscribed places and available egos and in response.
91 ## Reconnecting to places
93 Then the application can reconnect to its subscribed places by establishing
94 _place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and
95 GNUNET_SOCIAL_guest_enter_reconnect().
97 ## Subscribing to a place
99 Entering and subscribing a new host or guest place is done using
100 GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter().
102 ## Disconnecting from a place
104 An application can disconnect from a place while the social service keeps its
105 network connection active, using GNUNET_SOCIAL_host_disconnect() and
106 GNUNET_SOCIAL_guest_disconnect().
110 To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave().
111 When leaving a place its network connections are closed and all applications are unsubscribed from the place.
117 A message sent to the place.
122 message ID this message is in reply to.
126 thread ID, the first message ID in the thread.
132 signature of the message body and its variables by the author.
140 Notification about a place.
142 TODO: Applications can decide to auto-subscribe to certain places,
143 e.g. files under a given size.
150 GNS name of the place in a globally unique .zkey zone
160 ##### _list_peer_relays
161 list of peer IDs of relays
163 ## _notice_place_file
165 Notification about a place hosting a file.
169 The environment of _notice_place above, plus the following:
180 #### _description_file
185 Messages with a _file method contain a file,
186 which is saved to disk upon receipt at the following location:
187 $GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
200 #### _description_file
207 #ifndef GNUNET_SOCIAL_SERVICE_H
208 #define GNUNET_SOCIAL_SERVICE_H
213 #if 0 /* keep Emacsens' auto-indent happy */
219 #include "gnunet_util_lib.h"
220 #include "gnunet_env_lib.h"
221 #include "gnunet_identity_service.h"
222 #include "gnunet_namestore_service.h"
223 #include "gnunet_psyc_service.h"
227 * Version number of GNUnet Social API.
229 #define GNUNET_SOCIAL_VERSION 0x00000000
232 * Maximum size of client ID including '\0' terminator.
234 #define GNUNET_SOCIAL_APP_MAX_ID_SIZE 256
237 * Handle for an application.
239 struct GNUNET_SOCIAL_App;
242 * Handle for an ego (own identity)
244 struct GNUNET_SOCIAL_Ego;
247 * Handle for a pseudonym of another user in the network.
249 struct GNUNET_SOCIAL_Nym;
252 * Handle for a place where social interactions happen.
254 struct GNUNET_SOCIAL_Place;
257 * Host handle for a place that we entered.
259 struct GNUNET_SOCIAL_Host;
262 * Guest handle for place that we entered.
264 struct GNUNET_SOCIAL_Guest;
267 * Handle to an implementation of try-and-slice.
269 struct GNUNET_SOCIAL_Slicer;
275 * Handle that can be used to reconnect to a place as host.
277 struct GNUNET_SOCIAL_HostConnection;
280 * Handle that can be used to reconnect to a place as guest.
282 struct GNUNET_SOCIAL_GuestConnection;
285 * Notification about an available identity.
295 (*GNUNET_SOCIAL_AppEgoCallback) (void *cls,
296 struct GNUNET_SOCIAL_Ego *ego,
297 const struct GNUNET_CRYPTO_EcdsaPublicKey *ego_pub_key,
302 * Entry status of a place.
304 enum GNUNET_SOCIAL_PlaceState
307 * Place was once entered but left since.
309 GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
311 * Place is entered but not subscribed.
313 GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
315 * Place is entered and subscribed.
317 GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
322 * Notification about a home.
327 * Host connection, to be used with GNUNET_SOCIAL_host_enter_reconnect()
329 * Ego used to enter the place.
330 * @param place_pub_key
331 * Public key of the place.
333 * @see enum GNUNET_SOCIAL_PlaceState
336 (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
337 struct GNUNET_SOCIAL_HostConnection *hconn,
338 struct GNUNET_SOCIAL_Ego *ego,
339 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
340 enum GNUNET_SOCIAL_PlaceState place_state);
343 * Notification about a place.
348 * Guest connection, to be used with GNUNET_SOCIAL_guest_enter_reconnect()
350 * Ego used to enter the place.
351 * @param place_pub_key
352 * Public key of the place.
354 * @see enum GNUNET_SOCIAL_PlaceState
357 (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
358 struct GNUNET_SOCIAL_GuestConnection *gconn,
359 struct GNUNET_SOCIAL_Ego *ego,
360 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
361 enum GNUNET_SOCIAL_PlaceState place_state);
365 * Establish application connection to the social service.
367 * The @host_place_cb and @guest_place_cb functions are
368 * initially called for each entered places,
369 * then later each time a new place is entered with the current app ID.
374 * Function to notify about an available ego.
376 * Function to notify about a place entered as host.
378 * Function to notify about a place entered as guest.
380 * Closure for the callbacks.
382 * @return Handle that can be used to stop listening.
384 struct GNUNET_SOCIAL_App *
385 GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
387 GNUNET_SOCIAL_AppEgoCallback ego_cb,
388 GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
389 GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
400 GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app);
404 * Get the public key of @a ego.
409 * @return Public key of ego.
411 const struct GNUNET_CRYPTO_EcdsaPublicKey *
412 GNUNET_SOCIAL_ego_get_pub_key (const struct GNUNET_SOCIAL_Ego *ego);
416 * Get the name of @a ego.
421 * @return Public key of @a ego.
424 GNUNET_SOCIAL_ego_get_name (const struct GNUNET_SOCIAL_Ego *ego);
428 * Get the public key of a @a nym.
430 * Suitable, for example, to be used with GNUNET_SOCIAL_zone_add_nym().
433 * Pseudonym to map to a cryptographic identifier.
435 * @return Public key of nym.
437 const struct GNUNET_CRYPTO_EcdsaPublicKey *
438 GNUNET_SOCIAL_nym_get_pub_key (const struct GNUNET_SOCIAL_Nym *nym);
442 * Get the hash of the public key of a @a nym.
445 * Pseudonym to map to a cryptographic identifier.
447 * @return Hash of the public key of nym.
449 const struct GNUNET_HashCode *
450 GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
454 * Function called upon receiving a message indicating a call to a @e method.
456 * This function is called one or more times for each message until all data
457 * fragments arrive from the network.
462 * Message part, as it arrived from the network.
464 * Message counter, monotonically increasing from 1.
466 * The sender of the message.
467 * Can be NULL if the message is not connected to a pseudonym.
469 * OR'ed GNUNET_PSYC_MessageFlags
471 * Original method name from PSYC.
472 * May be more specific than the registered method name due to
473 * try-and-slice matching.
476 (*GNUNET_SOCIAL_MethodCallback) (void *cls,
477 const struct GNUNET_PSYC_MessageMethod *msg,
480 const struct GNUNET_SOCIAL_Nym *nym,
481 const char *method_name);
485 * Function called upon receiving a modifier of a message.
490 * Message ID this data fragment belongs to.
492 * Message part, as it arrived from the network.
494 * Operation to perform.
495 * 0 in case of a modifier continuation.
497 * Name of the modifier.
498 * NULL in case of a modifier continuation.
500 * Value of the modifier.
505 (*GNUNET_SOCIAL_ModifierCallback) (void *cls,
506 const struct GNUNET_MessageHeader *msg,
508 enum GNUNET_ENV_Operator oper,
512 uint16_t full_value_size);
516 * Function called upon receiving a data fragment of a message.
521 * Message ID this data fragment belongs to.
523 * Message part, as it arrived from the network.
525 * Byte offset of @a data in the overall data of the method.
527 * Number of bytes in @a data.
529 * Data stream given to the method.
532 * #GNUNET_NO if there are further fragments,
533 * #GNUNET_YES if this is the last fragment,
534 * #GNUNET_SYSERR indicates the message was cancelled by the sender.
537 (*GNUNET_SOCIAL_DataCallback) (void *cls,
538 const struct GNUNET_MessageHeader *msg,
540 uint64_t data_offset,
551 * Message part, as it arrived from the network.
553 * Message ID this data fragment belongs to.
555 * #GNUNET_YES if the message was cancelled,
556 * #GNUNET_NO if the message is complete.
559 (*GNUNET_SOCIAL_EndOfMessageCallback) (void *cls,
560 const struct GNUNET_MessageHeader *msg,
566 * Create a try-and-slice instance.
568 * A slicer processes incoming messages and notifies callbacks about matching
569 * methods or modifiers encountered.
571 * @return A new try-and-slice construct.
573 struct GNUNET_SOCIAL_Slicer *
574 GNUNET_SOCIAL_slicer_create (void);
578 * Add a method to the try-and-slice instance.
580 * The callbacks are called for messages with a matching @a method_name prefix.
583 * The try-and-slice instance to extend.
585 * Name of the given method, use empty string to match all.
587 * Method handler invoked upon a matching message.
589 * Modifier handler, invoked after @a method_cb
590 * for each modifier in the message.
592 * Data handler, invoked after @a modifier_cb for each data fragment.
594 * Invoked upon reaching the end of a matching message.
596 * Closure for the callbacks.
599 GNUNET_SOCIAL_slicer_method_add (struct GNUNET_SOCIAL_Slicer *slicer,
600 const char *method_name,
601 GNUNET_SOCIAL_MethodCallback method_cb,
602 GNUNET_SOCIAL_ModifierCallback modifier_cb,
603 GNUNET_SOCIAL_DataCallback data_cb,
604 GNUNET_SOCIAL_EndOfMessageCallback eom_cb,
608 * Remove a registered method from the try-and-slice instance.
610 * Removes one matching handler registered with the given
611 * @a method_name and callbacks.
614 * The try-and-slice instance.
616 * Name of the method to remove.
624 * End of message handler.
626 * @return #GNUNET_OK if a method handler was removed,
627 * #GNUNET_NO if no handler matched the given method name and callbacks.
630 GNUNET_SOCIAL_slicer_method_remove (struct GNUNET_SOCIAL_Slicer *slicer,
631 const char *method_name,
632 GNUNET_SOCIAL_MethodCallback method_cb,
633 GNUNET_SOCIAL_ModifierCallback modifier_cb,
634 GNUNET_SOCIAL_DataCallback data_cb,
635 GNUNET_SOCIAL_EndOfMessageCallback eom_cb);
639 * Watch a place for changed objects.
642 * The try-and-slice instance.
643 * @param object_filter
644 * Object prefix to match.
646 * Function to call when encountering a state modifier.
648 * Closure for callback.
651 GNUNET_SOCIAL_slicer_modifier_add (struct GNUNET_SOCIAL_Slicer *slicer,
652 const char *object_filter,
653 GNUNET_SOCIAL_ModifierCallback modifier_cb,
658 * Remove a registered modifier from the try-and-slice instance.
660 * Removes one matching handler registered with the given
661 * @a object_filter and callback.
664 * The try-and-slice instance.
665 * @param object_filter
666 * Object prefix to match.
668 * Function to call when encountering a state modifier changes.
671 GNUNET_SOCIAL_slicer_modifier_remove (struct GNUNET_SOCIAL_Slicer *slicer,
672 const char *object_filter,
673 GNUNET_SOCIAL_ModifierCallback modifier_cb);
677 * Destroy a given try-and-slice instance.
683 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
687 * Function called asking for nym to be admitted to the place.
689 * Should call either GNUNET_SOCIAL_host_admit() or
690 * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously). If this host
691 * cannot decide, it is fine to call neither function, in which case hopefully
692 * some other host of the place exists that will make the decision. The @a nym
693 * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
696 * @param cls Closure.
697 * @param nym Handle for the user who wants to enter.
698 * @param method_name Method name in the entry request.
699 * @param variable_count Number of elements in the @a variables array.
700 * @param variables Variables present in the message.
701 * @param data_size Number of bytes in @a data.
702 * @param data Payload given on enter (e.g. a password).
705 (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
706 struct GNUNET_SOCIAL_Nym *nym,
707 const char *method_name,
708 struct GNUNET_ENV_Environment *env,
714 * Function called when a @a nym leaves the place.
716 * This is also called if the @a nym was never given permission to enter
717 * (i.e. the @a nym stopped asking to get in).
722 * Handle for the user who left.
725 (*GNUNET_SOCIAL_FarewellCallback) (void *cls,
726 const struct GNUNET_SOCIAL_Nym *nym,
727 struct GNUNET_ENV_Environment *env);
731 * Function called after the host entered a home.
736 * #GNUNET_OK on success, or
737 * #GNUNET_SYSERR on error.
738 * @param place_pub_key
739 * Public key of home.
740 * @param max_message_id
741 * Last message ID sent to the channel.
742 * Or 0 if no messages have been sent to the place yet.
745 (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result,
746 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
747 uint64_t max_message_id);
751 * Enter a place as host.
753 * A place is created upon first entering, and it is active until permanently
754 * left using GNUNET_SOCIAL_host_leave().
757 * Configuration to contact the social service.
759 * Identity of the host.
761 * Private-public key pair of the place.
762 * NULL for ephemeral places.
764 * Policy specifying entry and history restrictions for the place.
766 * Slicer to handle incoming messages.
768 * Function called when the place is entered and ready to use.
769 * @param answer_door_cb
770 * Function to handle new nyms that want to enter.
772 * Function to handle departing nyms.
774 * Closure for the callbacks.
776 * @return Handle for the host.
778 struct GNUNET_SOCIAL_Host *
779 GNUNET_SOCIAL_host_enter (const struct GNUNET_SOCIAL_App *app,
780 const struct GNUNET_SOCIAL_Ego *ego,
781 enum GNUNET_PSYC_Policy policy,
782 struct GNUNET_SOCIAL_Slicer *slicer,
783 GNUNET_SOCIAL_HostEnterCallback enter_cb,
784 GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
785 GNUNET_SOCIAL_FarewellCallback farewell_cb,
790 * Reconnect to an already entered place as host.
793 * Host connection handle.
794 * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppHostPlaceCallback()
796 * Slicer to handle incoming messages.
798 * Function called when the place is entered and ready to use.
799 * @param answer_door_cb
800 * Function to handle new nyms that want to enter.
802 * Function to handle departing nyms.
804 * Closure for the callbacks.
806 * @return Handle for the host.
808 struct GNUNET_SOCIAL_Host *
809 GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn,
810 struct GNUNET_SOCIAL_Slicer *slicer,
811 GNUNET_SOCIAL_HostEnterCallback enter_cb,
812 GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
813 GNUNET_SOCIAL_FarewellCallback farewell_cb,
818 * Decision whether to admit @a nym into the place or refuse entry.
823 * Handle for the entity that wanted to enter.
825 * #GNUNET_YES if @a nym is admitted,
826 * #GNUNET_NO if @a nym is refused entry,
827 * #GNUNET_SYSERR if we cannot answer the request.
829 * Method name for the rejection message.
831 * Environment containing variables for the message, or NULL.
833 * Data for the rejection message to send back.
835 * Number of bytes in @a data for method.
836 * @return #GNUNET_OK on success,
837 * #GNUNET_SYSERR if the message is too large.
840 GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst,
841 struct GNUNET_SOCIAL_Nym *nym,
843 const struct GNUNET_PSYC_Message *entry_resp);
847 * Throw @a nym out of the place.
849 * Sends a _notice_place_leave announcement to the home.
851 * The @a nym reference will remain valid until the
852 * #GNUNET_SOCIAL_FarewellCallback is invoked,
853 * which should be very soon after this call.
858 * Handle for the entity to be ejected.
860 * Environment for the message or NULL.
861 * _nym is set to @e nym regardless whether an @e env is provided.
864 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
865 const struct GNUNET_SOCIAL_Nym *nym,
866 struct GNUNET_ENV_Environment *env);
870 * Flags for announcements by a host.
872 enum GNUNET_SOCIAL_AnnounceFlags
874 GNUNET_SOCIAL_ANNOUNCE_NONE = 0,
877 * Whether this announcement removes all objects from the place.
879 * New objects can be still added to the now empty place using the @e env
880 * parameter of the same announcement.
882 GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0
887 * Handle for an announcement request.
889 struct GNUNET_SOCIAL_Announcement;
893 * Send a message to all nyms that are present in the place.
895 * This function is restricted to the host. Nyms can only send requests
896 * to the host who can decide to relay it to everyone in the place.
901 * Method to use for the announcement.
903 * Environment containing variables for the message and operations
904 * on objects of the place.
905 * Has to remain available until the first call to @a notify_data.
908 * Function to call to get the payload of the announcement.
909 * @param notify_data_cls
910 * Closure for @a notify.
912 * Flags for this announcement.
914 * @return NULL on error (another announcement already in progress?).
916 struct GNUNET_SOCIAL_Announcement *
917 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
918 const char *method_name,
919 const struct GNUNET_ENV_Environment *env,
920 GNUNET_PSYC_TransmitNotifyData notify_data,
921 void *notify_data_cls,
922 enum GNUNET_SOCIAL_AnnounceFlags flags);
926 * Resume transmitting announcement.
929 * The announcement to resume.
932 GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a);
936 * Cancel announcement.
939 * The announcement to cancel.
942 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
946 * Allow relaying messages from guests matching a given @a method_prefix.
950 * @param method_prefix
951 * Method prefix to allow.
954 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
955 const char *method_prefix);
959 * Allow relaying changes to objects of the place.
961 * Only applies to messages with an allowed method name.
962 * @see GNUNET_SCOIAL_host_relay_allow_method()
966 * @param object_prefix
967 * Object prefix to allow modifying.
970 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
971 const char *object_prefix);
975 * Stop relaying messages from guests.
977 * Remove all allowed relay rules.
983 GNUNET_SOCIAL_host_relay_stop (struct GNUNET_SOCIAL_Host *host);
987 * Obtain handle for a hosted place.
989 * The returned handle can be used to access the place API.
992 * Handle for the host.
994 * @return Handle for the hosted place, valid as long as @a host is valid.
996 struct GNUNET_SOCIAL_Place *
997 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host);
1001 * Disconnect from a home.
1003 * Invalidates host handle.
1006 * The host to disconnect.
1007 * @param disconnect_cb
1008 * Function called after disconnected from the service.
1010 * Closure for @a disconnect_cb.
1013 GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst,
1014 GNUNET_ContinuationCallback disconnect_cb,
1019 * Stop hosting a home.
1021 * Sends a _notice_place_closed announcement to the home.
1022 * Invalidates host handle.
1027 * Environment for the message or NULL.
1028 * @param disconnect_cb
1029 * Function called after the host left the place
1030 * and disconnected from the service.
1032 * Closure for @a disconnect_cb.
1035 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst,
1036 const struct GNUNET_ENV_Environment *env,
1037 GNUNET_ContinuationCallback disconnect_cb,
1042 * Function called after the guest entered the local copy of the place.
1044 * History and object query functions can be used after this call,
1045 * but new messages can't be sent or received.
1050 * #GNUNET_OK on success, or
1051 * #GNUNET_SYSERR on error, e.g. could not connect to the service, or
1052 * could not resolve GNS name.
1053 * @param max_message_id
1054 * Last message ID sent to the place.
1055 * Or 0 if no messages have been sent to the place yet.
1058 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
1059 uint64_t max_message_id);
1063 * Function called upon a guest receives a decision about entry to the place.
1065 * @param is_admitted
1066 * Is the guest admitted to the place?
1067 * #GNUNET_YES if admitted,
1068 * #GNUNET_NO if refused entry
1069 * #GNUNET_SYSERR if the request could not be answered.
1070 * @param method_name
1071 * Method for the message sent along with the decision.
1072 * NULL if no message was sent.
1074 * Environment with variables for the message.
1075 * NULL if there are no variables.
1076 * It has to be freed using GNUNET_ENV_environment_destroy()
1077 * when it is not needed anymore.
1081 * Payload of the message.
1084 (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls,
1086 const struct GNUNET_PSYC_Message *entry_resp);
1090 * Request entry to a place as a guest.
1093 * Application handle.
1095 * Identity of the guest.
1096 * @param place_pub_key
1097 * Public key of the place to enter.
1099 * Flags for the entry.
1101 * Peer identity of the origin of the underlying multicast group.
1102 * @param relay_count
1103 * Number of elements in the @a relays array.
1105 * Relays for the underlying multicast group.
1106 * @param method_name
1107 * Method name for the message.
1109 * Environment containing variables for the message, or NULL.
1111 * Payload for the message to give to the enter callback.
1113 * Number of bytes in @a data.
1115 * Slicer to use for processing incoming requests from guests.
1117 * @return NULL on errors, otherwise handle for the guest.
1119 struct GNUNET_SOCIAL_Guest *
1120 GNUNET_SOCIAL_guest_enter (const struct GNUNET_SOCIAL_App *app,
1121 const struct GNUNET_SOCIAL_Ego *ego,
1122 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
1123 enum GNUNET_PSYC_SlaveJoinFlags flags,
1124 const struct GNUNET_PeerIdentity *origin,
1125 uint32_t relay_count,
1126 const struct GNUNET_PeerIdentity *relays,
1127 const struct GNUNET_PSYC_Message *entry_msg,
1128 struct GNUNET_SOCIAL_Slicer *slicer,
1129 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1130 GNUNET_SOCIAL_EntryDecisionCallback entry_dcsn_cb,
1135 * Request entry to a place by name as a guest.
1138 * Application handle.
1140 * Identity of the guest.
1142 * GNS name of the place to enter. Either in the form of
1143 * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to
1144 * the 'PLACE' record of the empty label ("+") in the GNS zone with the
1145 * nym's public key 'NYMPUBKEY', and can be used to request entry to a
1146 * pseudonym's place directly.
1148 * Password to decrypt the record, or NULL for cleartext records.
1150 * Entry request message.
1152 * Slicer to use for processing incoming requests from guests.
1153 * @param local_enter_cb
1154 * Called upon connection established to the social service.
1155 * @param entry_decision_cb
1156 * Called upon receiving entry decision.
1158 * @return NULL on errors, otherwise handle for the guest.
1160 struct GNUNET_SOCIAL_Guest *
1161 GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_SOCIAL_App *app,
1162 const struct GNUNET_SOCIAL_Ego *ego,
1163 const char *gns_name,
1164 const char *password,
1165 const struct GNUNET_PSYC_Message *join_msg,
1166 struct GNUNET_SOCIAL_Slicer *slicer,
1167 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1168 GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
1173 * Reconnect to an already entered place as guest.
1176 * Guest connection handle.
1177 * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppGuestPlaceCallback()
1179 * Flags for the entry.
1181 * Slicer to use for processing incoming requests from guests.
1182 * @param local_enter_cb
1183 * Called upon connection established to the social service.
1184 * @param entry_decision_cb
1185 * Called upon receiving entry decision.
1187 * @return NULL on errors, otherwise handle for the guest.
1189 struct GNUNET_SOCIAL_Guest *
1190 GNUNET_SOCIAL_guest_enter_reconnect (struct GNUNET_SOCIAL_GuestConnection *gconn,
1191 enum GNUNET_PSYC_SlaveJoinFlags flags,
1192 struct GNUNET_SOCIAL_Slicer *slicer,
1193 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1198 * Flags for talking to the host of a place.
1200 enum GNUNET_SOCIAL_TalkFlags
1202 GNUNET_SOCIAL_TALK_NONE = 0
1209 struct GNUNET_SOCIAL_TalkRequest;
1213 * Talk to the host of the place.
1216 * Place where we want to talk to the host.
1217 * @param method_name
1218 * Method to invoke on the host.
1220 * Environment containing variables for the message, or NULL.
1221 * @param notify_data
1222 * Function to use to get the payload for the method.
1223 * @param notify_data_cls
1224 * Closure for @a notify_data.
1226 * Flags for the message being sent.
1228 * @return NULL if we are already trying to talk to the host,
1229 * otherwise handle to cancel the request.
1231 struct GNUNET_SOCIAL_TalkRequest *
1232 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest,
1233 const char *method_name,
1234 const struct GNUNET_ENV_Environment *env,
1235 GNUNET_PSYC_TransmitNotifyData notify_data,
1236 void *notify_data_cls,
1237 enum GNUNET_SOCIAL_TalkFlags flags);
1241 * Resume talking to the host of the place.
1244 * Talk request to resume.
1247 GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr);
1251 * Cancel talking to the host of the place.
1254 * Talk request to cancel.
1257 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
1261 * Disconnect from a place.
1263 * Invalidates guest handle.
1266 * The guest to disconnect.
1267 * @param disconnect_cb
1268 * Function called after disconnected from the service.
1270 * Closure for @a disconnect_cb.
1273 GNUNET_SOCIAL_guest_disconnect (struct GNUNET_SOCIAL_Guest *gst,
1274 GNUNET_ContinuationCallback disconnect_cb,
1279 * Leave a place temporarily or permanently.
1281 * Notifies the owner of the place about leaving, and destroys the place handle.
1286 * Optional environment for the leave message if @a keep_active
1287 * is #GNUNET_NO. NULL if not needed.
1288 * @param disconnect_cb
1289 * Called upon disconnecting from the social service.
1292 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst,
1293 struct GNUNET_ENV_Environment *env,
1294 GNUNET_ContinuationCallback disconnect_cb,
1299 * Obtain handle for a place entered as guest.
1301 * The returned handle can be used to access the place API.
1303 * @param guest Handle for the guest.
1305 * @return Handle for the place, valid as long as @a guest is valid.
1307 struct GNUNET_SOCIAL_Place *
1308 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
1312 * A history request.
1314 struct GNUNET_SOCIAL_HistoryRequest;
1318 * Learn about the history of a place.
1320 * Messages are returned through the @a slicer function
1321 * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1324 * Place we want to learn more about.
1325 * @param start_message_id
1326 * First historic message we are interested in.
1327 * @param end_message_id
1328 * Last historic message we are interested in (inclusive).
1329 * @param method_prefix
1330 * Only retrieve messages with this method prefix.
1332 * OR'ed GNUNET_PSYC_HistoryReplayFlags
1334 * Slicer to use for retrieved messages.
1335 * Can be the same as the slicer of the place.
1337 * Function called after all messages retrieved.
1338 * NULL if not needed.
1339 * @param cls Closure for @a result_cb.
1341 struct GNUNET_SOCIAL_HistoryRequest *
1342 GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
1343 uint64_t start_message_id,
1344 uint64_t end_message_id,
1345 const char *method_prefix,
1347 struct GNUNET_SOCIAL_Slicer *slicer,
1348 GNUNET_ResultCallback result_cb,
1353 * Learn about the history of a place.
1355 * Sends messages through the slicer function of the place where
1356 * start_message_id <= message_id <= end_message_id.
1357 * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1359 * To get the latest message, use 0 for both the start and end message ID.
1362 * Place we want to learn more about.
1363 * @param message_limit
1364 * Maximum number of historic messages we are interested in.
1366 * Function called after all messages retrieved.
1367 * NULL if not needed.
1368 * @param cls Closure for @a result_cb.
1370 struct GNUNET_SOCIAL_HistoryRequest *
1371 GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
1372 uint64_t message_limit,
1373 const char *method_prefix,
1375 struct GNUNET_SOCIAL_Slicer *slicer,
1376 GNUNET_ResultCallback result_cb,
1380 * Cancel learning about the history of a place.
1383 * History lesson to cancel.
1386 GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
1389 struct GNUNET_SOCIAL_LookHandle;
1393 * Look at a particular object in the place.
1395 * The best matching object is returned (its name might be less specific than
1396 * what was requested).
1399 * The place to look the object at.
1401 * Full name of the object.
1403 * Set to the size of the returned value.
1405 * @return NULL if there is no such object at this place.
1407 struct GNUNET_SOCIAL_LookHandle *
1408 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
1409 const char *full_name,
1410 GNUNET_PSYC_StateVarCallback var_cb,
1411 GNUNET_ResultCallback result_cb,
1415 * Look for objects in the place with a matching name prefix.
1418 * The place to look its objects at.
1419 * @param name_prefix
1420 * Look at objects with names beginning with this value.
1422 * Function to call for each object found.
1424 * Closure for callback function.
1426 * @return Handle that can be used to stop looking at objects.
1428 struct GNUNET_SOCIAL_LookHandle *
1429 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
1430 const char *name_prefix,
1431 GNUNET_PSYC_StateVarCallback var_cb,
1432 GNUNET_ResultCallback result_cb,
1437 * Stop looking at objects.
1439 * @param lh Look handle to stop.
1442 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
1446 * Advertise a @e place in the GNS zone of @a ego.
1449 * Application handle.
1452 * @param place_pub_key
1453 * Public key of place to add.
1455 * The name for the PLACE record to put in the zone.
1457 * Password used to encrypt the record or NULL to keep it cleartext.
1458 * @param relay_count
1459 * Number of elements in the @a relays array.
1461 * List of relays to put in the PLACE record to advertise
1462 * as entry points to the place in addition to the origin.
1463 * @param expiration_time
1464 * Expiration time of the record, use 0 to remove the record.
1466 * Function called with the result of the operation.
1468 * Closure for @a result_cb
1470 * @return #GNUNET_OK if the request was sent,
1471 * #GNUNET_SYSERR on error, e.g. the name/password is too long.
1474 GNUNET_SOCIAL_zone_add_place (const struct GNUNET_SOCIAL_App *app,
1475 const struct GNUNET_SOCIAL_Ego *ego,
1477 const char *password,
1478 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
1479 const struct GNUNET_PeerIdentity *origin,
1480 uint32_t relay_count,
1481 const struct GNUNET_PeerIdentity *relays,
1482 struct GNUNET_TIME_Absolute expiration_time,
1483 GNUNET_ResultCallback result_cb,
1488 * Add public key to the GNS zone of the @e ego.
1495 * The name for the PKEY record to put in the zone.
1496 * @param nym_pub_key
1497 * Public key of nym to add.
1498 * @param expiration_time
1499 * Expiration time of the record, use 0 to remove the record.
1501 * Function called with the result of the operation.
1503 * Closure for @a result_cb
1505 * @return #GNUNET_OK if the request was sent,
1506 * #GNUNET_SYSERR on error, e.g. the name is too long.
1509 GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app,
1510 const struct GNUNET_SOCIAL_Ego *ego,
1512 const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key,
1513 struct GNUNET_TIME_Absolute expiration_time,
1514 GNUNET_ResultCallback result_cb,
1518 #if 0 /* keep Emacsens' auto-indent happy */
1525 /* ifndef GNUNET_SOCIAL_SERVICE_H */
1528 /** @} */ /* end of group social */