c248eb81f348c4028d7ed0b6ce810b6cc6ac5123
[oweals/gnunet.git] / src / include / gnunet_social_service.h
1 /*
2      This file is part of GNUnet.
3      (C) 2013 Christian Grothoff (and other contributing authors)
4
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.
9
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.
14
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.
19 */
20
21 /** 
22  * @file include/gnunet_social_service.h
23  * @brief Social service; implements social functionality using the PSYC service.
24  * @author Gabor X Toth
25  * @author Christian Grothoff
26  */
27 #ifndef GNUNET_SOCIAL_SERVICE_H
28 #define GNUNET_SOCIAL_SERVICE_H
29
30 #ifdef __cplusplus
31 extern "C"
32 {
33 #if 0                           /* keep Emacsens' auto-indent happy */
34 }
35 #endif
36 #endif
37
38 #include "gnunet_util_lib.h"
39 #include "gnunet_psyc_lib.h"
40 #include "gnunet_psyc_service.h"
41 #include "gnunet_multicast_service.h"
42
43
44 /** 
45  * Version number of GNUnet Social API.
46  */
47 #define GNUNET_SOCIAL_VERSION 0x00000000
48
49 /** 
50  * Handle for our own presence in the network (we can of course have
51  * alter-egos).
52  */
53 struct GNUNET_SOCIAL_Ego;
54
55 /** 
56  * Handle for another user (who is likely pseudonymous) in the network.
57  */
58 struct GNUNET_SOCIAL_Nym;
59
60 /** 
61  * Handle for a place where social interactions happen.
62  */
63 struct GNUNET_SOCIAL_Place;
64
65 /** 
66  * Handle for a place that one of our egos hosts.
67  */
68 struct GNUNET_SOCIAL_Home;
69
70 /** 
71  * Handle to an implementation of try-and-slice.
72  */
73 struct GNUNET_SOCIAL_Slicer;
74
75
76 /** 
77  * Method called from SOCIAL upon receiving a message indicating a call
78  * to a @e method.
79  *
80  * @param cls Closure.
81  * @param full_method_name Original method name from PSYC (may be more
82  *        specific than the registered method name due to try-and-slice matching).
83
84  * @param message_id Unique message counter for this message
85  *                   (unique only in combination with the given sender for
86  *                    this channel).
87  * @param header_length Number of modifiers in header.
88  * @param header Modifiers present in the message. FIXME: use environment instead?
89  * @param data_offset Byte offset of @a data in the overall data of the method.
90  * @param data_size Number of bytes in @a data.
91  * @param data Data stream given to the method (might not be zero-terminated
92  *             if data is binary).
93  * @param flags Message flags indicating fragmentation status.
94  */
95 typedef int (*GNUNET_SOCIAL_Method)(void *cls,
96                                     const char *full_method_name,
97                                     uint64_t message_id,
98                                     size_t header_length,
99                                     GNUNET_PSYC_Modifier *header,
100                                     uint64_t data_offset,
101                                     size_t data_size,
102                                     const void *data,
103                                     enum GNUNET_PSYC_MessageFlags flags);
104
105
106 /** 
107  * Create a try-and-slice instance.
108  *
109  * @return A new try-and-slice construct.
110  */
111 struct GNUNET_SOCIAL_Slicer *
112 GNUNET_SOCIAL_slicer_create (void);
113
114
115 /** 
116  * Add a method to the try-and-slice instance.
117  *
118  * A slicer processes messages and calls methods that match a message. A match
119  * happens whenever the method name of a message starts with the method_name
120  * parameter given here.
121  *
122  * @param slicer The try-and-slice instance to extend.
123  * @param method_name Name of the given method, use empty string for default.
124  * @param method Method to invoke.
125  * @param method_cls Closure for method.
126  */
127 void
128 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
129                           const char *method_name,
130                           GNUNET_SOCIAL_Method method,
131                           void *method_cls);
132
133
134 /** 
135  * Remove a registered method from the try-and-slice instance.
136  *
137  * @param slicer The try-and-slice instance.
138  * @param method_name Name of the method to remove.
139  * @param method Method handler.
140  */
141 void
142 GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer,
143                              const char *method_name,
144                              GNUNET_SOCIAL_Method method);
145
146 /** 
147  * Destroy a given try-and-slice instance.
148  *
149  * @param slicer slicer to destroy
150  */
151 void
152 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
153
154
155 /** 
156  * Create an ego using the given private key.
157  *
158  * The identity service is used to manage egos, the
159  * GNUNET_IDENTITY_ego_get_key() function returns an ego's private key that can
160  * be passed into this function.
161  *
162  * @param key Private key for the ego, NULL for ephemeral egos.
163  * @return Handle to the ego, NULL on error.
164  */
165 struct GNUNET_SOCIAL_Ego *
166 GNUNET_SOCIAL_ego_create (const struct GNUNET_CRYPTO_EccPrivateKey *key);
167
168
169 /** 
170  * Destroy a handle to an ego.
171  *
172  * @param ego Ego to destroy.
173  */
174 void
175 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
176
177
178 /** 
179  * Function called asking for nym to be admitted to the place.
180  *
181  * Should call either GNUNET_SOCIAL_home_admit() or
182  * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously).  If this owner
183  * cannot decide, it is fine to call neither function, in which case hopefully
184  * some other owner of the home exists that will make the decision. The @a nym
185  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
186  * for it.
187  *
188  * @param cls Closure.
189  * @param nym Handle for the user who wants to enter.
190  * @param header_length Number of modifiers in header.
191  * @param header Modifiers present in the message.
192  * @param data_size Number of bytes in @a data.
193  * @param data Payload given on enter (e.g. a password).
194  */
195 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
196                                                  struct GNUNET_SOCIAL_Nym *nym,
197                                                  size_t header_length,
198                                                  GNUNET_PSYC_Modifier *header,
199                                                  size_t data_size,
200                                                  const void *data);
201
202
203 /** 
204  * Function called when a @a nym leaves the place.
205  * 
206  * This is also called if the @a nym was never given permission to enter
207  * (i.e. the @a nym stopped asking to get in).
208  *
209  * @param cls Closure.
210  * @param nym Handle for the user who left.
211  * @param header_length Number of modifiers in header.
212  * @param header Modifiers present in the message.
213  */
214 typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
215                                                struct GNUNET_SOCIAL_Nym *nym,
216                                                size_t header_length,
217                                                GNUNET_PSYC_Modifier *header);
218
219
220 /** 
221  * Enter a home where guests (nyms) can be hosted.
222  *
223  * A home is created upon first entering, and exists until
224  * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using
225  * GNUNET_SOCIAL_home_leave().
226  *
227  * @param cfg Configuration to contact the social service.
228  * @param home_keyfile File with the private-public key pair of the home,
229  *        created if the file does not exist; pass NULL for ephemeral homes.
230  * @param policy Policy specifying entry and history restrictions of the home.
231  * @param ego Owner of the home (host).
232  * @param slicer Slicer to handle guests talking.
233  * @param listener_cb Function to handle new nyms that want to enter.
234  * @param farewell_cb Function to handle departing nyms.
235  * @param cls Closure for @a listener_cb and @a farewell_cb.
236  * @return Handle for a new home.
237  */
238 struct GNUNET_SOCIAL_Home *
239 GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
240                           const char *home_keyfile,
241                           enum GNUNET_MULTICAST_GroupPolicy policy,
242                           struct GNUNET_SOCIAL_Ego *ego,
243                           struct GNUNET_SOCIAL_Slicer *slicer,
244                           GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
245                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
246                           void *cls);
247
248
249 /** 
250  * Admit @a nym to the @a home.
251  *
252  * The @a nym reference will remain valid until either the home is destroyed or
253  * @a nym leaves.
254  *
255  * @param home Home to allow @a nym to enter.
256  * @param nym Handle for the entity that wants to enter.
257  */
258 void
259 GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
260                           struct GNUNET_SOCIAL_Nym *nym);
261
262
263 /** 
264  * Throw @a nym out of the @a home.
265  *
266  * The @a nym reference will remain valid until the
267  * #GNUNET_SOCIAL_FarewellCallback is invoked,
268  * which should be very soon after this call.
269  *
270  * @param home Home to eject @a nym from.
271  * @param nym Handle for the entity to be ejected.
272  */
273 void
274 GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home,
275                           struct GNUNET_SOCIAL_Nym *nym);
276
277
278 /** 
279  * Refuse @a nym entry into the @a home.
280  *
281  * @param home Home to disallow @a nym to enter.
282  * @param nym Handle for the entity that wanted to enter.
283  * @param method_name Method name for the rejection message.
284  * @param env Environment containing variables for the message, or NULL.
285  * @param data_size Number of bytes in @a data for method.
286  * @param data Data for the rejection message to send back.
287  */
288 void
289 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
290                                  struct GNUNET_SOCIAL_Nym *nym,
291                                  const char *method_name,
292                                  const struct GNUNET_ENV_Environment *env,
293                                  size_t data_size,
294                                  const void *data);
295
296
297 /** 
298  * Get the public key of a nym.
299  *
300  * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
301  *
302  * @param nym Pseudonym to map to a cryptographic identifier.
303  * @param[out] identity Set to the public key of the nym.
304  */
305 void
306 GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym,
307                            struct GNUNET_CRYPTO_EccPublicKey *nym_key);
308
309
310 /** 
311  * Obtain the private-public key pair of the home.
312  * 
313  * @param home Home to get the key of.
314  * @param[out] home_key Set to the private-public key pair of the home.  The public part is suitable for storing in GADS within a "PLACE" record, along with peer IDs to join at.
315  */
316 void
317 GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home,
318                             struct GNUNET_CRYPTO_EccPrivateKey *home_key);
319
320
321 /** 
322  * Advertise @a home under @a name in the GADS zone of the @e ego.
323  *
324  * @param home The home to advertise.
325  * @param name The name to put in the zone.
326  * @param expiration_time Expiration time of the record, use 0 to remove the record.
327  */
328 void
329 GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home,
330                               const char *name,
331                               GNUNET_TIME_Relative expiration_time);
332
333
334 /** 
335  * Handle for an announcement request.
336  */
337 struct GNUNET_SOCIAL_Announcement;
338
339
340 /** 
341  * Send a message to all nyms that are present in the home.
342  *
343  * This function is restricted to the home owner.  Nyms can only send requests
344  * to the home owner who can decide to relay it to other guests.
345  *
346  * @param home Home to address the announcement to.
347  * @param method_name Method to use for the announcement.
348  * @param env Environment containing variables for the message, or NULL.
349  * @param notify Function to call to get the payload of the announcement.
350  * @param notify_cls Closure for @a notify.
351  * @return NULL on error (announcement already in progress?).
352  */
353 struct GNUNET_SOCIAL_Announcement *
354 GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home,
355                              const char *method_name,
356                              const struct GNUNET_ENV_Environment *env,
357                              GNUNET_CONNECTION_TransmitReadyNotify notify,
358                              void *notify_cls);
359
360
361 /** 
362  * Cancel announcement.
363  *
364  * @param a The announcement to cancel.
365  */
366 void
367 GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
368
369
370 /** 
371  * Convert our home to a place so we can access it via the place API.
372  *
373  * @param home Handle for the home.
374  * @return Place handle for the same home, valid as long as @a home is valid;
375  *         do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home!
376  */
377 struct GNUNET_SOCIAL_Place *
378 GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home);
379
380
381 /** 
382  * Leave a home temporarily, visitors can stay.
383  *
384  * After leaving, handling of incoming messages are left to other clients of the
385  * social service, and stops after the last client exits.
386  *
387  * @param home Home to leave temporarily (handle becomes invalid).
388  */
389 void
390 GNUNET_SOCIAL_home_away (struct GNUNET_SOCIAL_Home *home);
391
392
393 /** 
394  * Leave a home.
395
396  * Invalidates home handle.
397  * Guests will be disconnected until the home is restarted.
398  *
399  * @param home Home to leave.
400  */
401 void
402 GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
403
404 /** 
405  * Request entry to a place (home hosted by someone else).
406  *
407  * @param cfg Configuration to contact the social service.
408  * @param ego Owner of the home (host).
409  * @param address GADS name of the place to enter.  Either in the form of
410  *        'room.friend.gads', or 'NYMPUBKEY.zkey'.  This latter case refers to
411  *        the 'PLACE' record of the empty label ("+") in the GADS zone with the
412  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
413  *        pseudonym's place directly.
414  * @param env Environment containing variables for the message, or NULL.
415  * @param data_size Number of bytes in @a data.
416  * @param data Payload for the message to give to the enter callback.
417  * @param slicer Slicer to use for processing incoming requests from guests.
418  * @return NULL on errors, otherwise handle to the place.
419  */
420 struct GNUNET_SOCIAL_Place *
421 GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
422                            struct GNUNET_SOCIAL_Ego *ego,
423                            char *address,
424                            const struct GNUNET_ENV_Environment *env,
425                            size_t data_size,
426                            const void *data,
427                            struct GNUNET_SOCIAL_Slicer *slicer);
428
429 /** 
430  * Request entry to a place (home hosted by someone else).
431  *
432  * @param cfg Configuration to contact the social service.
433  * @param ego Owner of the home (host).
434  * @param crypto_address Public key of the place to enter.
435  * @param peer Peer to send request to.
436  * @param slicer Slicer to use for processing incoming requests from guests.
437  * @param env Environment containing variables for the message, or NULL.
438  * @param data_size Number of bytes in @a data.
439  * @param data Payload for the message to give to the enter callback.
440  * @return NULL on errors, otherwise handle to the place.
441  */
442 struct GNUNET_SOCIAL_Place *
443 GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
444                            struct GNUNET_SOCIAL_Ego *ego,
445                            struct GNUNET_CRYPTO_EccPublicKey *crypto_address,
446                            struct GNUNET_PeerIdentity *peer,
447                            struct GNUNET_SOCIAL_Slicer *slicer,
448                            const struct GNUNET_ENV_Environment *env,
449                            size_t data_size,
450                            const void *data);
451
452
453 struct GNUNET_SOCIAL_WatchHandle;
454
455 /** 
456  * Watch a place for changed objects.
457  *
458  * @param place Place to watch.
459  * @param object_filter Object prefix to match.
460  * @param state_cb Function to call when an object/state changes.
461  * @param state_cb_cls Closure for callback.
462  * 
463  * @return Handle that can be used to cancel watching.
464  */
465 struct GNUNET_SOCIAL_WatchHandle *
466 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
467                            const char *object_filter,
468                            GNUNET_PSYC_StateCallback state_cb,
469                            void *state_cb_cls);
470
471
472 /** 
473  * Cancel watching a place for changed objects.
474  *
475  * @param wh Watch handle to cancel.
476  */
477 void
478 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
479
480
481 struct GNUNET_SOCIAL_LookHandle;
482
483 /** 
484  * Look at all objects in the place.
485  *
486  * @param place The place to look its objects at.
487  * @param state_cb Function to call for each object found.
488  * @param state_cb_cls Closure for callback function.
489  * 
490  * @return Handle that can be used to stop looking at objects.
491  */
492 struct GNUNET_SOCIAL_LookHandle *
493 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
494                           GNUNET_PSYC_StateCallback state_cb,
495                           void *state_cb_cls);
496
497
498 /** 
499  * Look at matching objects in the place.
500  *
501  * @param place The place to look its objects at.
502  * @param object_filter Only look at objects with names beginning with this filter value.
503  * @param state_cb Function to call for each object found.
504  * @param state_cb_cls Closure for callback function.
505  * 
506  * @return Handle that can be used to stop looking at objects.
507  */
508 struct GNUNET_SOCIAL_LookHandle *
509 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
510                               const char *object_filter,
511                               GNUNET_PSYC_StateCallback state_cb,
512                               void *state_cb_cls);
513
514
515 /** 
516  * Stop looking at objects.
517  *
518  * @param lh Look handle to stop.
519  */
520 void
521 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
522
523
524
525 /** 
526  * Look at a particular object in the place.
527  *
528  * @param place The place to look the object at.
529  * @param object_name Full name of the object.
530  * @param value_size Set to the size of the returned value.
531  * @return NULL if there is no such object at this place.
532  */
533 const void *
534 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
535                              const char *object_name,
536                              size_t *value_size);
537
538
539 /** 
540  * A talk request.
541  */
542 struct GNUNET_SOCIAL_TalkRequest;
543
544 /** 
545  * Talk to the host of the place.
546  *
547  * @param place Place where we want to talk to the host.
548  * @param method_name Method to invoke on the host.
549  * @param env Environment containing variables for the message, or NULL.
550  * @param notify Function to use to get the payload for the method.
551  * @param notify_cls Closure for @a notify.
552  * @return NULL if we are already trying to talk to the host,
553  *         otherwise handle to cancel the request.
554  */
555 struct GNUNET_SOCIAL_TalkRequest *
556 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
557                           const char *method_name,
558                           const struct GNUNET_ENV_Environment *env,
559                           GNUNET_CONNECTION_TransmitReadyNotify notify,
560                           void *notify_cls);
561
562
563 /** 
564  * Cancel talking to the host of the place.
565  *
566  * @param tr Talk request to cancel.
567  */
568 void
569 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
570
571
572 /** 
573  * A history lesson.
574  */
575 struct GNUNET_SOCIAL_HistoryLesson;
576
577 /** 
578  * Learn about the history of a place.
579  *
580  * Sends messages through the slicer function of the place where
581  * start_message_id <= message_id <= end_message_id.
582  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
583  *
584  * To get the latest message, use 0 for both the start and end message ID.
585  * 
586  * @param place Place we want to learn more about.
587  * @param start_message_id First historic message we are interested in.
588  * @param end_message_id Last historic message we are interested in (inclusive).
589  * @param slicer Slicer to use to process history.  Can be the same as the
590  *               slicer of the place, as the HISTORIC flag allows distinguishing
591  *               old messages from fresh ones.
592  * @param finish_cb Function called after the last message if the history lesson
593  *              is passed through the @a slicer. NULL if not needed.
594  * @param finish_cb_cls Closure for @a finish_cb.
595  * @return Handle to abort history lesson, never NULL (multiple lessons
596  *         at the same time are allowed).
597  */
598 struct GNUNET_SOCIAL_HistoryLesson *
599 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
600                                  uint64_t start_message_id,
601                                  uint64_t end_message_id,
602                                  const struct GNUNET_SOCIAL_Slicer *slicer,
603                                  void (*finish_cb)(void *),
604                                  void *finish_cb_cls);
605
606
607 /** 
608  * Stop processing messages from the history lesson.
609  *
610  * Must not be called after the finish callback of the history lesson is called.
611  *
612  * @param hist History lesson to cancel.
613  */
614 void
615 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
616
617
618 /** 
619  * Leave a place permanently.
620  *
621  * Notifies the owner of the place about leaving, and destroys the place handle.
622  * 
623  * @param place Place to leave permanently.
624  */
625 void
626 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place);
627
628
629 /** 
630  * Leave a place temporarily.
631  *
632  * Stop following the conversation for the @a place and destroy the @a place
633  * handle.  Only affects the application calling this function, other clients of
634  * the service continue receiving the messages.
635  *
636  * @param place Place to leave temporarily.
637  */
638 void
639 GNUNET_SOCIAL_place_away (struct GNUNET_SOCIAL_Place *place);
640
641
642 #if 0                           /* keep Emacsens' auto-indent happy */
643 {
644 #endif
645 #ifdef __cplusplus
646 }
647 #endif
648
649 /* ifndef GNUNET_SOCIAL_SERVICE_H */
650 #endif
651 /* end of gnunet_social_service.h */