2 * This file is part of GNUnet
3 * (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., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
22 * @file social/social_api.c
23 * @brief Social service; implements social interactions using the PSYC service.
24 * @author Gabor X Toth
30 #include "gnunet_util_lib.h"
31 #include "gnunet_env_lib.h"
32 #include "gnunet_psyc_service.h"
33 #include "gnunet_social_service.h"
38 * Handle for a pseudonym of another user in the network.
40 struct GNUNET_SOCIAL_Nym
47 * Handle for a place where social interactions happen.
49 struct GNUNET_SOCIAL_Place
56 * Host handle for a place that we entered.
58 struct GNUNET_SOCIAL_Host
65 * Guest handle for place that we entered.
67 struct GNUNET_SOCIAL_Guest
74 * Handle to an implementation of try-and-slice.
76 struct GNUNET_SOCIAL_Slicer
83 * Handle for an announcement request.
85 struct GNUNET_SOCIAL_Announcement
91 struct GNUNET_SOCIAL_WatchHandle
97 struct GNUNET_SOCIAL_LookHandle
106 struct GNUNET_SOCIAL_TalkRequest
115 struct GNUNET_SOCIAL_HistoryLesson
124 * Create a try-and-slice instance.
126 * @return A new try-and-slice construct.
128 struct GNUNET_SOCIAL_Slicer *
129 GNUNET_SOCIAL_slicer_create (void)
136 * Add a method to the try-and-slice instance.
138 * A slicer processes messages and calls methods that match a message. A match
139 * happens whenever the method name of a message starts with the method_name
140 * parameter given here.
142 * @param slicer The try-and-slice instance to extend.
143 * @param method_name Name of the given method, use empty string for default.
144 * @param method Method to invoke.
145 * @param method_cls Closure for method.
148 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
149 const char *method_name,
150 GNUNET_SOCIAL_MethodCallback method_cb,
158 * Remove a registered method from the try-and-slice instance.
160 * @param slicer The try-and-slice instance.
161 * @param method_name Name of the method to remove.
162 * @param method Method handler.
165 GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer,
166 const char *method_name,
167 GNUNET_SOCIAL_MethodCallback method_cb)
173 * Destroy a given try-and-slice instance.
175 * @param slicer slicer to destroy
178 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer)
185 * Enter a place as host.
187 * A place is created upon first entering, and it is active until permanently
188 * left using GNUNET_SOCIAL_host_leave().
190 * @param cfg Configuration to contact the social service.
191 * @param place_keyfile File with the private-public key pair of the place,
192 * created if the file does not exist; pass NULL for ephemeral places.
193 * @param policy Policy specifying entry and history restrictions of the place.
194 * @param ego Identity of the host.
195 * @param slicer Slicer to handle incoming messages.
196 * @param listener_cb Function to handle new nyms that want to enter.
197 * @param farewell_cb Function to handle departing nyms.
198 * @param cls Closure for @a listener_cb and @a farewell_cb.
200 * @return Handle for the host.
202 struct GNUNET_SOCIAL_Host *
203 GNUNET_SOCIAL_host_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
204 const char *place_keyfile,
205 enum GNUNET_PSYC_Policy policy,
206 struct GNUNET_IDENTITY_Ego *ego,
207 struct GNUNET_SOCIAL_Slicer *slicer,
208 GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
209 GNUNET_SOCIAL_FarewellCallback farewell_cb,
217 * Admit @a nym to the place.
219 * The @a nym reference will remain valid until either the @a host or @a nym
222 * @param host Host of the place.
223 * @param nym Handle for the entity that wants to enter.
226 GNUNET_SOCIAL_host_admit (struct GNUNET_SOCIAL_Host *host,
227 struct GNUNET_SOCIAL_Nym *nym)
234 * Throw @a nym out of the place.
236 * The @a nym reference will remain valid until the
237 * #GNUNET_SOCIAL_FarewellCallback is invoked,
238 * which should be very soon after this call.
240 * @param host Host of the place.
241 * @param nym Handle for the entity to be ejected.
244 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
245 struct GNUNET_SOCIAL_Nym *nym)
252 * Refuse @a nym entry into the place.
254 * @param host Host of the place.
255 * @param nym Handle for the entity that wanted to enter.
256 * @param method_name Method name for the rejection message.
257 * @param env Environment containing variables for the message, or NULL.
258 * @param data Data for the rejection message to send back.
259 * @param data_size Number of bytes in @a data for method.
262 GNUNET_SOCIAL_host_refuse_entry (struct GNUNET_SOCIAL_Host *host,
263 struct GNUNET_SOCIAL_Nym *nym,
264 const char *method_name,
265 const struct GNUNET_ENV_Environment *env,
274 * Get the public key of a @a nym.
276 * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
278 * @param nym Pseudonym to map to a cryptographic identifier.
279 * @param[out] nym_key Set to the public key of the nym.
282 GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym,
283 struct GNUNET_CRYPTO_EddsaPublicKey *nym_key)
290 * Obtain the private-public key pair of the host.
292 * @param host Host to get the key of.
293 * @param[out] host_key Set to the private-public key pair of the host. The
294 * public part is suitable for storing in GNS within a "PLACE"
295 * record, along with peer IDs to join at.
298 GNUNET_SOCIAL_host_get_key (struct GNUNET_SOCIAL_Host *host,
299 struct GNUNET_CRYPTO_EddsaPrivateKey *host_key)
306 * Advertise the place in the GNS zone of the @e ego of the @a host.
308 * @param host Host of the place.
309 * @param name The name for the PLACE record to put in the zone.
310 * @param peer_count Number of elements in the @a peers array.
311 * @param peers List of peers in the PLACE record that can be used to send join
313 * @param expiration_time Expiration time of the record, use 0 to remove the record.
314 * @param password Password used to encrypt the record.
317 GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host,
320 const struct GNUNET_PeerIdentity *peers,
321 struct GNUNET_TIME_Relative expiration_time,
322 const char *password)
329 * Send a message to all nyms that are present in the place.
331 * This function is restricted to the host. Nyms can only send requests
332 * to the host who can decide to relay it to everyone in the place.
334 * @param host Host of the place.
335 * @param method_name Method to use for the announcement.
336 * @param env Environment containing variables for the message and operations
337 * on objects of the place. Can be NULL.
338 * @param notify Function to call to get the payload of the announcement.
339 * @param notify_cls Closure for @a notify.
340 * @param flags Flags for this announcement.
342 * @return NULL on error (announcement already in progress?).
344 struct GNUNET_SOCIAL_Announcement *
345 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
346 const char *method_name,
347 const struct GNUNET_ENV_Environment *env,
348 GNUNET_CONNECTION_TransmitReadyNotify notify,
350 enum GNUNET_SOCIAL_AnnounceFlags flags)
357 * Cancel announcement.
359 * @param a The announcement to cancel.
362 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a)
369 * Obtain handle for a hosted place.
371 * The returned handle can be used to access the place API.
373 * @param host Handle for the host.
375 * @return Handle for the hosted place, valid as long as @a host is valid.
377 struct GNUNET_SOCIAL_Place *
378 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host)
385 * Stop hosting a place.
387 * Invalidates host handle.
389 * @param host Host leaving the place.
390 * @param keep_active Keep the place active after last host disconnected.
393 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host, int keep_active)
400 * Request entry to a place as a guest.
402 * @param cfg Configuration to contact the social service.
403 * @param ego Identity of the guest.
404 * @param address GNS name of the place to enter. Either in the form of
405 * 'room.friend.gnu', or 'NYMPUBKEY.zkey'. This latter case refers to
406 * the 'PLACE' record of the empty label ("+") in the GNS zone with the
407 * nym's public key 'NYMPUBKEY', and can be used to request entry to a
408 * pseudonym's place directly.
409 * @param method_name Method name for the message.
410 * @param env Environment containing variables for the message, or NULL.
411 * @param data Payload for the message to give to the enter callback.
412 * @param data_size Number of bytes in @a data.
413 * @param slicer Slicer to use for processing incoming requests from guests.
415 * @return NULL on errors, otherwise handle for the guest.
417 struct GNUNET_SOCIAL_Guest *
418 GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
419 struct GNUNET_IDENTITY_Ego *ego,
421 const char *method_name,
422 const struct GNUNET_ENV_Environment *env,
425 struct GNUNET_SOCIAL_Slicer *slicer)
431 * Request entry to a place as a guest.
433 * @param cfg Configuration to contact the social service.
434 * @param ego Identity of the guest.
435 * @param crypto_address Public key of the place to enter.
436 * @param origin Peer identity of the origin of the underlying multicast group.
437 * @param relay_count Number of elements in the @a relays array.
438 * @param relays Relays for the underlying multicast group.
439 * @param method_name Method name for the message.
440 * @param env Environment containing variables for the message, or NULL.
441 * @param data Payload for the message to give to the enter callback.
442 * @param data_size Number of bytes in @a data.
443 * @param slicer Slicer to use for processing incoming requests from guests.
445 * @return NULL on errors, otherwise handle for the guest.
447 struct GNUNET_SOCIAL_Guest *
448 GNUNET_SOCIAL_guest_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
449 struct GNUNET_IDENTITY_Ego *ego,
450 struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address,
451 struct GNUNET_PeerIdentity *origin,
453 struct GNUNET_PeerIdentity *relays,
454 const char *method_name,
455 const struct GNUNET_ENV_Environment *env,
458 struct GNUNET_SOCIAL_Slicer *slicer)
465 * Talk to the host of the place.
467 * @param place Place where we want to talk to the host.
468 * @param method_name Method to invoke on the host.
469 * @param env Environment containing variables for the message, or NULL.
470 * @param notify Function to use to get the payload for the method.
471 * @param notify_cls Closure for @a notify.
472 * @param flags Flags for the message being sent.
474 * @return NULL if we are already trying to talk to the host,
475 * otherwise handle to cancel the request.
477 struct GNUNET_SOCIAL_TalkRequest *
478 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Place *place,
479 const char *method_name,
480 const struct GNUNET_ENV_Environment *env,
481 GNUNET_CONNECTION_TransmitReadyNotify notify,
483 enum GNUNET_SOCIAL_TalkFlags flags)
490 * Cancel talking to the host of the place.
492 * @param tr Talk request to cancel.
495 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr)
502 * Leave a place permanently.
504 * Notifies the owner of the place about leaving, and destroys the place handle.
506 * @param place Place to leave permanently.
507 * @param keep_active Keep place active after last application disconnected.
510 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Place *place, int keep_active)
517 * Obtain handle for a place entered as guest.
519 * The returned handle can be used to access the place API.
521 * @param guest Handle for the guest.
523 * @return Handle for the place, valid as long as @a guest is valid.
525 struct GNUNET_SOCIAL_Place *
526 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Host *guest)
535 struct GNUNET_SOCIAL_HistoryLesson;
538 * Learn about the history of a place.
540 * Sends messages through the slicer function of the place where
541 * start_message_id <= message_id <= end_message_id.
542 * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
544 * To get the latest message, use 0 for both the start and end message ID.
546 * @param place Place we want to learn more about.
547 * @param start_message_id First historic message we are interested in.
548 * @param end_message_id Last historic message we are interested in (inclusive).
549 * @param slicer Slicer to use to process history. Can be the same as the
550 * slicer of the place, as the HISTORIC flag allows distinguishing
551 * old messages from fresh ones.
552 * @param finish_cb Function called after the last message in the history lesson
553 * is passed through the @a slicer. NULL if not needed.
554 * @param finish_cb_cls Closure for @a finish_cb.
555 * @return Handle to abort history lesson, never NULL (multiple lessons
556 * at the same time are allowed).
558 struct GNUNET_SOCIAL_HistoryLesson *
559 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
560 uint64_t start_message_id,
561 uint64_t end_message_id,
562 const struct GNUNET_SOCIAL_Slicer *slicer,
563 void (*finish_cb)(void *),
571 * Stop processing messages from the history lesson.
573 * Must not be called after the finish callback of the history lesson is called.
575 * @param hist History lesson to cancel.
578 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist)
584 struct GNUNET_SOCIAL_WatchHandle;
587 * Watch a place for changed objects.
589 * @param place Place to watch.
590 * @param object_filter Object prefix to match.
591 * @param state_cb Function to call when an object/state changes.
592 * @param state_cb_cls Closure for callback.
594 * @return Handle that can be used to cancel watching.
596 struct GNUNET_SOCIAL_WatchHandle *
597 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
598 const char *object_filter,
599 GNUNET_PSYC_StateCallback state_cb,
607 * Cancel watching a place for changed objects.
609 * @param wh Watch handle to cancel.
612 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh)
618 struct GNUNET_SOCIAL_LookHandle;
622 * Look at objects in the place with a matching name prefix.
624 * @param place The place to look its objects at.
625 * @param name_prefix Look at objects with names beginning with this value.
626 * @param state_cb Function to call for each object found.
627 * @param state_cb_cls Closure for callback function.
629 * @return Handle that can be used to stop looking at objects.
631 struct GNUNET_SOCIAL_LookHandle *
632 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
633 const char *name_prefix,
634 GNUNET_PSYC_StateCallback state_cb,
642 * Stop looking at objects.
644 * @param lh Look handle to stop.
647 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh)
655 * Look at a particular object in the place.
657 * The best matching object is returned (its name might be less specific than
658 * what was requested).
660 * @param place The place to look the object at.
661 * @param full_name Full name of the object.
662 * @param value_size Set to the size of the returned value.
663 * @return NULL if there is no such object at this place.
666 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
667 const char *full_name,
676 /* end of social_api.c */