2 This file is part of GNUnet.
3 Copyright (C) 2013 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Gabor X Toth
21 * @author Christian Grothoff
24 * Social service; implements social interactions through the PSYC service.
27 /** @defgroup social Social service
28 Social interactions through the PSYC service.
32 The social service provides an API for social interactions based on a one-to-many messaging model.
33 It manages subscriptions of applications to places, provides messaging functionality in places,
34 allows access to the local message history and manages the GNS zone of _egos_ (user identities).
36 The service stores private and public keys of subscribed places, as well as files received in subscribed places.
38 # Concepts and terminology
42 An _ego_ is an identity of a user, a private-public key pair.
43 A _nym_ is an identity of another user in the network, identified by its public key.
44 Each user can have multiple identities.
46 struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities.
50 A _place_ is where social interactions happen. It is owned and created by an _ego_.
51 Creating a new place happens by an _ego_ entering a new place as a _host_,
52 where _guests_ can enter later to receive messages sent to the place.
54 A place is identified by its public key.
56 - struct GNUNET_SOCIAL_Host represents a place entered as host,
57 - struct GNUNET_SOCIAL_Guest is used for a place entered as guest.
58 - A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place
59 using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place()
60 and can be used with API functions common to hosts and guests.
64 Messages sent to places are stored locally by the PSYCstore service, and can be queried any time.
65 GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place,
66 while GNUNET_SOCIAL_history_replay() is used to query a given message ID range.
70 The GNU Name System is used for assigning human-readable names to nyms and places.
71 There's a _GNS zone_ corresponding to each _nym_.
72 An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively.
74 ## Announcement, talk request
76 The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce().
77 Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk().
78 The host receives talk requests of guests and can _relay_ them to the place,
79 or process it using a message handler function.
83 ## Connecting to the service
85 A client first establishes an _application connection_ to the service using
86 GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
87 public keys of subscribed places and available egos in response.
89 ## Reconnecting to places
91 Then the application can reconnect to its subscribed places by establishing
92 _place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and
93 GNUNET_SOCIAL_guest_enter_reconnect().
95 ## Subscribing to a place
97 Entering and subscribing a new host or guest place is done using
98 GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter().
100 ## Disconnecting from a place
102 An application can disconnect from a place while the social service keeps its
103 network connection active, using GNUNET_SOCIAL_host_disconnect() and
104 GNUNET_SOCIAL_guest_disconnect().
108 To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave().
109 When leaving a place its network connections are closed and all applications are unsubscribed from the place.
115 Human conversation in a private or public place.
120 Message ID this message is in reply to.
123 Thread ID, the first message ID in the thread.
128 FIXME: Are nyms a different data type from egos and person entities?
129 Do they have a different format than any other entity address?
130 Questions and thoughts on how to fix this in "questions.org"
133 Signature of the message body and its variables by the author.
141 Notification about a place.
143 TODO: Applications can decide to auto-subscribe to certain places,
144 e.g. files under a given size.
151 GNS name of the place in a globally unique .zkey zone
153 FIXME: A custom _gns PSYC data type should be avoidable by parsing
154 and interpreting PSYC uniforms appropriately.
155 Thoughts on this in "questions.org"
162 FIXME: _key_pub can't be the data type for GNUnet-specific cryptographic
163 addressing. Questions and thoughts on how to fix this in "questions.org"
168 ##### _list_peer_relays
169 List of peer IDs of relays
171 ## _notice_place_file
173 Notification about a place hosting a file.
177 The environment of _notice_place above, plus the following:
188 #### _description_file
193 Messages with a _file method contain a file,
194 which is saved to disk upon reception at the following location:
195 $GNUNET_DATA_HOME/social/files/<H(place_pub)>/<H(message_id)>
208 #### _description_file
215 #ifndef GNUNET_SOCIAL_SERVICE_H
216 #define GNUNET_SOCIAL_SERVICE_H
221 #if 0 /* keep Emacsens' auto-indent happy */
227 #include "gnunet_util_lib.h"
228 #include "gnunet_psyc_util_lib.h"
229 #include "gnunet_identity_service.h"
230 #include "gnunet_namestore_service.h"
231 #include "gnunet_psyc_service.h"
235 * Version number of GNUnet Social API.
237 #define GNUNET_SOCIAL_VERSION 0x00000000
240 * Maximum size of client ID including '\0' terminator.
242 #define GNUNET_SOCIAL_APP_MAX_ID_SIZE 256
244 enum GNUNET_SOCIAL_MsgProcFlags {
245 GNUNET_SOCIAL_MSG_PROC_NONE = 0,
246 GNUNET_SOCIAL_MSG_PROC_RELAY = 1,
247 GNUNET_SOCIAL_MSG_PROC_SAVE= 2,
251 * Handle for an application.
253 struct GNUNET_SOCIAL_App;
256 * Handle for an ego (own identity)
258 struct GNUNET_SOCIAL_Ego;
261 * Handle for a pseudonym of another user in the network.
263 struct GNUNET_SOCIAL_Nym;
266 * Handle for a place where social interactions happen.
268 struct GNUNET_SOCIAL_Place;
271 * Host handle for a place that we entered.
273 struct GNUNET_SOCIAL_Host;
276 * Guest handle for place that we entered.
278 struct GNUNET_SOCIAL_Guest;
281 * Handle that can be used to reconnect to a place as host.
283 struct GNUNET_SOCIAL_HostConnection;
286 * Handle that can be used to reconnect to a place as guest.
288 struct GNUNET_SOCIAL_GuestConnection;
291 * Notification about an available identity.
301 (*GNUNET_SOCIAL_AppEgoCallback) (void *cls,
302 struct GNUNET_SOCIAL_Ego *ego,
303 const struct GNUNET_CRYPTO_EcdsaPublicKey *ego_pub_key,
308 * Entry status of a place per application.
310 enum GNUNET_SOCIAL_AppPlaceState
313 * The place was once entered by the ego, but left since.
314 * It's possible to establish a local connection to the place
315 * without re-entering to fetch history from the PSYCstore.
316 * @see enum GNUNET_PSYC_SlaveJoinFlags and GNUNET_SOCIAL_guest_enter()
318 GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
321 * The place is entered by the ego,
322 * but this application is not subscribed to it.
324 GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
327 * The place is entered by the ego and
328 * and this application is subscribed to it.
330 GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
335 * Called after receiving initial list of egos and places.
338 (*GNUNET_SOCIAL_AppConnectedCallback) (void *cls);
342 * Notification about a home.
347 * Host connection, to be used with GNUNET_SOCIAL_host_enter_reconnect()
349 * Ego used to enter the place.
350 * @param place_pub_key
351 * Public key of the place.
353 * @see enum GNUNET_SOCIAL_AppPlaceState
356 (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
357 struct GNUNET_SOCIAL_HostConnection *hconn,
358 struct GNUNET_SOCIAL_Ego *ego,
359 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
360 enum GNUNET_SOCIAL_AppPlaceState place_state);
363 * Notification about a place.
368 * Guest connection, to be used with GNUNET_SOCIAL_guest_enter_reconnect()
370 * Ego used to enter the place.
371 * @param place_pub_key
372 * Public key of the place.
374 * @see enum GNUNET_SOCIAL_AppPlaceState
377 (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
378 struct GNUNET_SOCIAL_GuestConnection *gconn,
379 struct GNUNET_SOCIAL_Ego *ego,
380 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
381 enum GNUNET_SOCIAL_AppPlaceState place_state);
385 * Establish application connection to the social service.
387 * The @host_cb and @guest_cb functions are
388 * initially called for each entered places,
389 * then later each time a new place is entered with the current app ID.
394 * Function to notify about an available ego.
396 * Function to notify about a place entered as host.
398 * Function to notify about a place entered as guest.
400 * Closure for the callbacks.
402 * @return Handle that can be used to stop listening.
404 struct GNUNET_SOCIAL_App *
405 GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
407 GNUNET_SOCIAL_AppEgoCallback ego_cb,
408 GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
409 GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
410 GNUNET_SOCIAL_AppConnectedCallback connected_cb,
418 * Application handle.
419 * @param disconnect_cb
420 * Disconnect callback.
421 * @param disconnect_cls
422 * Disconnect closure.
425 GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app,
426 GNUNET_ContinuationCallback disconnect_cb,
427 void *disconnect_cls);
431 * Get the public key of @a ego.
436 * @return Public key of ego.
438 const struct GNUNET_CRYPTO_EcdsaPublicKey *
439 GNUNET_SOCIAL_ego_get_pub_key (const struct GNUNET_SOCIAL_Ego *ego);
443 * Get the name of @a ego.
448 * @return Public key of @a ego.
451 GNUNET_SOCIAL_ego_get_name (const struct GNUNET_SOCIAL_Ego *ego);
455 * Get the public key of a @a nym.
457 * Suitable, for example, to be used with GNUNET_SOCIAL_zone_add_nym().
460 * Pseudonym to map to a cryptographic identifier.
462 * @return Public key of nym.
464 const struct GNUNET_CRYPTO_EcdsaPublicKey *
465 GNUNET_SOCIAL_nym_get_pub_key (const struct GNUNET_SOCIAL_Nym *nym);
469 * Get the hash of the public key of a @a nym.
472 * Pseudonym to map to a cryptographic identifier.
474 * @return Hash of the public key of nym.
476 const struct GNUNET_HashCode *
477 GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
481 * Function called asking for nym to be admitted to the place.
483 * Should call either GNUNET_SOCIAL_host_admit() or
484 * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously). If this host
485 * cannot decide, it is fine to call neither function, in which case hopefully
486 * some other host of the place exists that will make the decision. The @a nym
487 * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
493 * Handle for the user who wants to enter.
495 * Method name in the entry request.
496 * @param variable_count
497 * Number of elements in the @a variables array.
499 * Variables present in the message.
501 * Payload given on enter (e.g. a password).
503 * Number of bytes in @a data.
506 (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
507 struct GNUNET_SOCIAL_Nym *nym,
508 const char *method_name,
509 struct GNUNET_PSYC_Environment *env,
515 * Function called when a @a nym leaves the place.
517 * This is also called if the @a nym was never given permission to enter
518 * (i.e. the @a nym stopped asking to get in).
523 * Handle for the user who left.
526 (*GNUNET_SOCIAL_FarewellCallback) (void *cls,
527 const struct GNUNET_SOCIAL_Nym *nym,
528 struct GNUNET_PSYC_Environment *env);
532 * Function called after the host entered a home.
537 * #GNUNET_OK on success, or
538 * #GNUNET_SYSERR on error.
539 * @param place_pub_key
540 * Public key of home.
541 * @param max_message_id
542 * Last message ID sent to the channel.
543 * Or 0 if no messages have been sent to the place yet.
546 (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result,
547 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
548 uint64_t max_message_id);
552 * Enter a place as host.
554 * A place is created upon first entering, and it is active until permanently
555 * left using GNUNET_SOCIAL_host_leave().
558 * Configuration to contact the social service.
560 * Identity of the host.
562 * Private-public key pair of the place.
563 * NULL for ephemeral places.
565 * Policy specifying entry and history restrictions for the place.
567 * Slicer to handle incoming messages.
569 * Function called when the place is entered and ready to use.
570 * @param answer_door_cb
571 * Function to handle new nyms that want to enter.
573 * Function to handle departing nyms.
575 * Closure for the callbacks.
577 * @return Handle for the host.
579 struct GNUNET_SOCIAL_Host *
580 GNUNET_SOCIAL_host_enter (const struct GNUNET_SOCIAL_App *app,
581 const struct GNUNET_SOCIAL_Ego *ego,
582 enum GNUNET_PSYC_Policy policy,
583 struct GNUNET_PSYC_Slicer *slicer,
584 GNUNET_SOCIAL_HostEnterCallback enter_cb,
585 GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
586 GNUNET_SOCIAL_FarewellCallback farewell_cb,
591 * Reconnect to an already entered place as host.
594 * Host connection handle.
595 * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppHostPlaceCallback()
597 * Slicer to handle incoming messages.
599 * Function called when the place is entered and ready to use.
600 * @param answer_door_cb
601 * Function to handle new nyms that want to enter.
603 * Function to handle departing nyms.
605 * Closure for the callbacks.
607 * @return Handle for the host.
609 struct GNUNET_SOCIAL_Host *
610 GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn,
611 struct GNUNET_PSYC_Slicer *slicer,
612 GNUNET_SOCIAL_HostEnterCallback enter_cb,
613 GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
614 GNUNET_SOCIAL_FarewellCallback farewell_cb,
619 * Decision whether to admit @a nym into the place or refuse entry.
624 * Handle for the entity that wanted to enter.
626 * #GNUNET_YES if @a nym is admitted,
627 * #GNUNET_NO if @a nym is refused entry,
628 * #GNUNET_SYSERR if we cannot answer the request.
630 * Entry response message, or NULL.
631 * @return #GNUNET_OK on success,
632 * #GNUNET_SYSERR if the message is too large.
635 GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst,
636 struct GNUNET_SOCIAL_Nym *nym,
638 const struct GNUNET_PSYC_Message *entry_resp);
642 * Throw @a nym out of the place.
644 * Sends a _notice_place_leave announcement to the home.
646 * The @a nym reference will remain valid until the
647 * #GNUNET_SOCIAL_FarewellCallback is invoked,
648 * which should be very soon after this call.
653 * Handle for the entity to be ejected.
655 * Environment for the message or NULL.
656 * _nym is set to @e nym regardless whether an @e env is provided.
659 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
660 const struct GNUNET_SOCIAL_Nym *nym,
661 struct GNUNET_PSYC_Environment *env);
665 * Flags for announcements by a host.
667 enum GNUNET_SOCIAL_AnnounceFlags
669 GNUNET_SOCIAL_ANNOUNCE_NONE = 0,
672 * Whether this announcement removes all objects from the place.
674 * New objects can be still added to the now empty place using the @e env
675 * parameter of the same announcement.
677 GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0
682 * Handle for an announcement request.
684 struct GNUNET_SOCIAL_Announcement;
688 * Send a message to all nyms that are present in the place.
690 * This function is restricted to the host. Nyms can only send requests
691 * to the host who can decide to relay it to everyone in the place.
696 * Method to use for the announcement.
698 * Environment containing variables for the message and operations
699 * on objects of the place.
700 * Has to remain available until the first call to @a notify_data.
703 * Function to call to get the payload of the announcement.
704 * @param notify_data_cls
705 * Closure for @a notify.
707 * Flags for this announcement.
709 * @return NULL on error (another announcement already in progress?).
711 struct GNUNET_SOCIAL_Announcement *
712 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
713 const char *method_name,
714 const struct GNUNET_PSYC_Environment *env,
715 GNUNET_PSYC_TransmitNotifyData notify_data,
716 void *notify_data_cls,
717 enum GNUNET_SOCIAL_AnnounceFlags flags);
721 * Resume transmitting announcement.
724 * The announcement to resume.
727 GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a);
731 * Cancel announcement.
734 * The announcement to cancel.
737 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
741 * Allow relaying messages from guests matching a given @a method_prefix.
745 * @param method_prefix
746 * Method prefix to allow.
749 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
750 const char *method_prefix);
754 * Allow relaying changes to objects of the place.
756 * Only applies to messages with an allowed method name.
757 * @see GNUNET_SCOIAL_host_relay_allow_method()
761 * @param object_prefix
762 * Object prefix to allow modifying.
765 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
766 const char *object_prefix);
770 * Stop relaying messages from guests.
772 * Remove all allowed relay rules.
778 GNUNET_SOCIAL_host_relay_stop (struct GNUNET_SOCIAL_Host *host);
782 * Obtain handle for a hosted place.
784 * The returned handle can be used to access the place API.
787 * Handle for the host.
789 * @return Handle for the hosted place, valid as long as @a host is valid.
791 struct GNUNET_SOCIAL_Place *
792 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host);
796 * Disconnect from a home.
798 * Invalidates host handle.
801 * The host to disconnect.
802 * @param disconnect_cb
803 * Function called after disconnected from the service.
805 * Closure for @a disconnect_cb.
808 GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst,
809 GNUNET_ContinuationCallback disconnect_cb,
814 * Stop hosting a home.
816 * Sends a _notice_place_closing announcement to the home.
817 * Invalidates host handle.
822 * Environment for the message or NULL.
823 * @param disconnect_cb
824 * Function called after the host left the place
825 * and disconnected from the service.
827 * Closure for @a disconnect_cb.
830 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst,
831 const struct GNUNET_PSYC_Environment *env,
832 GNUNET_ContinuationCallback disconnect_cb,
837 * Function called after the guest entered the local copy of the place.
839 * History and object query functions can be used after this call,
840 * but new messages can't be sent or received.
845 * #GNUNET_OK on success, or
846 * #GNUNET_SYSERR on error, e.g. could not connect to the service, or
847 * could not resolve GNS name.
848 * @param place_pub_key
849 * Public key of place.
850 * @param max_message_id
851 * Last message ID sent to the place.
852 * Or 0 if no messages have been sent to the place yet.
855 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
856 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
857 uint64_t max_message_id);
861 * Function called upon a guest receives a decision about entry to the place.
864 * Is the guest admitted to the place?
865 * #GNUNET_YES if admitted,
866 * #GNUNET_NO if refused entry,
867 * #GNUNET_SYSERR if the request could not be answered.
869 * Entry response message.
872 (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls,
874 const struct GNUNET_PSYC_Message *entry_resp);
878 * Request entry to a place as a guest.
881 * Application handle.
883 * Identity of the guest.
884 * @param place_pub_key
885 * Public key of the place to enter.
887 * Flags for the entry.
889 * Peer identity of the origin of the underlying multicast group.
891 * Number of elements in the @a relays array.
893 * Relays for the underlying multicast group.
897 * Slicer to use for processing incoming requests from guests.
899 * @return NULL on errors, otherwise handle for the guest.
901 struct GNUNET_SOCIAL_Guest *
902 GNUNET_SOCIAL_guest_enter (const struct GNUNET_SOCIAL_App *app,
903 const struct GNUNET_SOCIAL_Ego *ego,
904 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
905 enum GNUNET_PSYC_SlaveJoinFlags flags,
906 const struct GNUNET_PeerIdentity *origin,
907 uint32_t relay_count,
908 const struct GNUNET_PeerIdentity *relays,
909 const struct GNUNET_PSYC_Message *entry_msg,
910 struct GNUNET_PSYC_Slicer *slicer,
911 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
912 GNUNET_SOCIAL_EntryDecisionCallback entry_dcsn_cb,
917 * Request entry to a place by name as a guest.
920 * Application handle.
922 * Identity of the guest.
924 * GNS name of the place to enter. Either in the form of
925 * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to
926 * the 'PLACE' record of the empty label ("+") in the GNS zone with the
927 * nym's public key 'NYMPUBKEY', and can be used to request entry to a
928 * pseudonym's place directly.
930 * Password to decrypt the record, or NULL for cleartext records.
932 * Entry request message.
934 * Slicer to use for processing incoming requests from guests.
935 * @param local_enter_cb
936 * Called upon connection established to the social service.
937 * @param entry_decision_cb
938 * Called upon receiving entry decision.
940 * @return NULL on errors, otherwise handle for the guest.
942 struct GNUNET_SOCIAL_Guest *
943 GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_SOCIAL_App *app,
944 const struct GNUNET_SOCIAL_Ego *ego,
945 const char *gns_name,
946 const char *password,
947 const struct GNUNET_PSYC_Message *join_msg,
948 struct GNUNET_PSYC_Slicer *slicer,
949 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
950 GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
955 * Reconnect to an already entered place as guest.
958 * Guest connection handle.
959 * @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppGuestPlaceCallback()
961 * Flags for the entry.
963 * Slicer to use for processing incoming requests from guests.
964 * @param local_enter_cb
965 * Called upon connection established to the social service.
966 * @param entry_decision_cb
967 * Called upon receiving entry decision.
969 * @return NULL on errors, otherwise handle for the guest.
971 struct GNUNET_SOCIAL_Guest *
972 GNUNET_SOCIAL_guest_enter_reconnect (struct GNUNET_SOCIAL_GuestConnection *gconn,
973 enum GNUNET_PSYC_SlaveJoinFlags flags,
974 struct GNUNET_PSYC_Slicer *slicer,
975 GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
980 * Flags for talking to the host of a place.
982 enum GNUNET_SOCIAL_TalkFlags
984 GNUNET_SOCIAL_TALK_NONE = 0
991 struct GNUNET_SOCIAL_TalkRequest;
995 * Talk to the host of the place.
998 * Place where we want to talk to the host.
1000 * Method to invoke on the host.
1002 * Environment containing variables for the message, or NULL.
1003 * @param notify_data
1004 * Function to use to get the payload for the method.
1005 * @param notify_data_cls
1006 * Closure for @a notify_data.
1008 * Flags for the message being sent.
1010 * @return NULL if we are already trying to talk to the host,
1011 * otherwise handle to cancel the request.
1013 struct GNUNET_SOCIAL_TalkRequest *
1014 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest,
1015 const char *method_name,
1016 const struct GNUNET_PSYC_Environment *env,
1017 GNUNET_PSYC_TransmitNotifyData notify_data,
1018 void *notify_data_cls,
1019 enum GNUNET_SOCIAL_TalkFlags flags);
1023 * Resume talking to the host of the place.
1026 * Talk request to resume.
1029 GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr);
1033 * Cancel talking to the host of the place.
1036 * Talk request to cancel.
1039 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
1043 * Disconnect from a place.
1045 * Invalidates guest handle.
1048 * The guest to disconnect.
1049 * @param disconnect_cb
1050 * Function called after disconnected from the service.
1052 * Closure for @a disconnect_cb.
1055 GNUNET_SOCIAL_guest_disconnect (struct GNUNET_SOCIAL_Guest *gst,
1056 GNUNET_ContinuationCallback disconnect_cb,
1061 * Leave a place temporarily or permanently.
1063 * Notifies the owner of the place about leaving, and destroys the place handle.
1068 * Optional environment for the leave message if @a keep_active
1069 * is #GNUNET_NO. NULL if not needed.
1070 * @param disconnect_cb
1071 * Called upon disconnecting from the social service.
1074 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst,
1075 struct GNUNET_PSYC_Environment *env,
1076 GNUNET_ContinuationCallback disconnect_cb,
1081 * Obtain handle for a place entered as guest.
1083 * The returned handle can be used to access the place API.
1085 * @param guest Handle for the guest.
1087 * @return Handle for the place, valid as long as @a guest is valid.
1089 struct GNUNET_SOCIAL_Place *
1090 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
1094 * A history request.
1096 struct GNUNET_SOCIAL_HistoryRequest;
1100 * Get the public key of a place.
1105 * @return Public key of the place.
1107 const struct GNUNET_CRYPTO_EddsaPublicKey *
1108 GNUNET_SOCIAL_place_get_pub_key (const struct GNUNET_SOCIAL_Place *plc);
1112 * Set message processing @a flags for a @a method_prefix.
1116 * @param method_prefix
1117 * Method prefix @a flags apply to.
1119 * The flags that apply to a matching @a method_prefix.
1122 GNUNET_SOCIAL_place_msg_proc_set (struct GNUNET_SOCIAL_Place *plc,
1123 const char *method_prefix,
1124 enum GNUNET_SOCIAL_MsgProcFlags flags);
1127 * Clear all message processing flags previously set for this place.
1130 GNUNET_SOCIAL_place_msg_proc_clear (struct GNUNET_SOCIAL_Place *plc);
1134 * Learn about the history of a place.
1136 * Messages are returned through the @a slicer function
1137 * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1140 * Place we want to learn more about.
1141 * @param start_message_id
1142 * First historic message we are interested in.
1143 * @param end_message_id
1144 * Last historic message we are interested in (inclusive).
1145 * @param method_prefix
1146 * Only retrieve messages with this method prefix.
1148 * OR'ed GNUNET_PSYC_HistoryReplayFlags
1150 * Slicer to use for retrieved messages.
1151 * Can be the same as the slicer of the place.
1153 * Function called after all messages retrieved.
1154 * NULL if not needed.
1155 * @param cls Closure for @a result_cb.
1157 struct GNUNET_SOCIAL_HistoryRequest *
1158 GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
1159 uint64_t start_message_id,
1160 uint64_t end_message_id,
1161 const char *method_prefix,
1163 struct GNUNET_PSYC_Slicer *slicer,
1164 GNUNET_ResultCallback result_cb,
1169 * Learn about the history of a place.
1171 * Sends messages through the slicer function of the place where
1172 * start_message_id <= message_id <= end_message_id.
1173 * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1175 * To get the latest message, use 0 for both the start and end message ID.
1178 * Place we want to learn more about.
1179 * @param message_limit
1180 * Maximum number of historic messages we are interested in.
1182 * Function called after all messages retrieved.
1183 * NULL if not needed.
1184 * @param cls Closure for @a result_cb.
1186 struct GNUNET_SOCIAL_HistoryRequest *
1187 GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
1188 uint64_t message_limit,
1189 const char *method_prefix,
1191 struct GNUNET_PSYC_Slicer *slicer,
1192 GNUNET_ResultCallback result_cb,
1196 * Cancel learning about the history of a place.
1199 * History lesson to cancel.
1202 GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
1205 struct GNUNET_SOCIAL_LookHandle;
1209 * Look at a particular object in the place.
1211 * The best matching object is returned (its name might be less specific than
1212 * what was requested).
1215 * The place to look the object at.
1217 * Full name of the object.
1219 * @return NULL if there is no such object at this place.
1221 struct GNUNET_SOCIAL_LookHandle *
1222 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
1223 const char *full_name,
1224 GNUNET_PSYC_StateVarCallback var_cb,
1225 GNUNET_ResultCallback result_cb,
1229 * Look for objects in the place with a matching name prefix.
1232 * The place to look its objects at.
1233 * @param name_prefix
1234 * Look at objects with names beginning with this value.
1236 * Function to call for each object found.
1238 * Closure for callback function.
1240 * @return Handle that can be used to stop looking at objects.
1242 struct GNUNET_SOCIAL_LookHandle *
1243 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
1244 const char *name_prefix,
1245 GNUNET_PSYC_StateVarCallback var_cb,
1246 GNUNET_ResultCallback result_cb,
1251 * Stop looking at objects.
1253 * @param lh Look handle to stop.
1256 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
1260 * Advertise a @e place in the GNS zone of @a ego.
1263 * Application handle.
1266 * @param place_pub_key
1267 * Public key of place to add.
1269 * The name for the PLACE record to put in the zone.
1271 * Password used to encrypt the record or NULL to keep it cleartext.
1272 * @param relay_count
1273 * Number of elements in the @a relays array.
1275 * List of relays to put in the PLACE record to advertise
1276 * as entry points to the place in addition to the origin.
1277 * @param expiration_time
1278 * Expiration time of the record, use 0 to remove the record.
1280 * Function called with the result of the operation.
1282 * Closure for @a result_cb
1284 * @return #GNUNET_OK if the request was sent,
1285 * #GNUNET_SYSERR on error, e.g. the name/password is too long.
1288 GNUNET_SOCIAL_zone_add_place (const struct GNUNET_SOCIAL_App *app,
1289 const struct GNUNET_SOCIAL_Ego *ego,
1291 const char *password,
1292 const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
1293 const struct GNUNET_PeerIdentity *origin,
1294 uint32_t relay_count,
1295 const struct GNUNET_PeerIdentity *relays,
1296 struct GNUNET_TIME_Absolute expiration_time,
1297 GNUNET_ResultCallback result_cb,
1302 * Add public key to the GNS zone of the @e ego.
1309 * The name for the PKEY record to put in the zone.
1310 * @param nym_pub_key
1311 * Public key of nym to add.
1312 * @param expiration_time
1313 * Expiration time of the record, use 0 to remove the record.
1315 * Function called with the result of the operation.
1317 * Closure for @a result_cb
1319 * @return #GNUNET_OK if the request was sent,
1320 * #GNUNET_SYSERR on error, e.g. the name is too long.
1323 GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app,
1324 const struct GNUNET_SOCIAL_Ego *ego,
1326 const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key,
1327 struct GNUNET_TIME_Absolute expiration_time,
1328 GNUNET_ResultCallback result_cb,
1332 #if 0 /* keep Emacsens' auto-indent happy */
1339 /* ifndef GNUNET_SOCIAL_SERVICE_H */
1342 /** @} */ /* end of group */