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 data_off Byte offset of @a data in the overall data of the method.
  88  * @param data_size Number of bytes in @a data.
  89  * @param data Data stream given to the method (might not be zero-terminated
  90  *             if data is binary).
  91  * @param frag Fragmentation status for the data.
  92  */
  93 typedef int (*GNUNET_SOCIAL_Method)(void *cls,
  94                                     const char *full_method_name,
  95                                     uint64_t message_id,
  96                                     uint64_t data_off,
  97                                     size_t data_size,
  98                                     const void *data,
  99                                     enum GNUNET_PSYC_FragmentStatus frag);
 100
 101
 102 /**
 103  * Create a try-and-slice instance.
 104  *
 105  * @return A new try-and-slice construct.
 106  */
 107 struct GNUNET_SOCIAL_Slicer *
 108 GNUNET_SOCIAL_slicer_create (void);
 109
 110
 111 /**
 112  * Add a method to the try-and-slice instance.
 113  *
 114  * A slicer processes messages and calls methods that match a message. A match
 115  * happens whenever the method name of a message starts with the method_name
 116  * parameter given here.
 117  *
 118  * @param slicer The try-and-slice instance to extend.
 119  * @param method_name Name of the given method, use empty string for default.
 120  * @param method Method to invoke.
 121  * @param method_cls Closure for method.
 122  */
 123 void
 124 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
 125                           const char *method_name,
 126                           GNUNET_SOCIAL_Method method,
 127                           void *method_cls);
 128
 129 /* FIXME: No slicer_remove for now, is it needed? */
 130
 131 /**
 132  * Destroy a given try-and-slice instance.
 133  *
 134  * @param slicer slicer to destroy
 135  */
 136 void
 137 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
 138
 139
 140 /**
 141  * Create an ego.
 142  *
 143  * Create an ego using the private key from the given file.  If the file does
 144  * not exist, a fresh key is created.
 145  *
 146  * @param keyfile Name of the file with the private key for the ego,
 147  *                NULL for ephemeral egos.
 148  * @return Handle to the ego, NULL on error.
 149  */
 150 struct GNUNET_SOCIAL_Ego *
 151 GNUNET_SOCIAL_ego_create (const char *keyfile);
 152
 153
 154 /**
 155  * Destroy a handle to an ego.
 156  *
 157  * @param ego Ego to destroy.
 158  */
 159 void
 160 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
 161
 162
 163 /**
 164  * Function called asking for nym to be admitted to the place.
 165  *
 166  * Should call either GNUNET_SOCIAL_home_admit() or
 167  * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously).  If this owner
 168  * cannot decide, it is fine to call neither function, in which case hopefully
 169  * some other owner of the home exists that will make the decision. The @a nym
 170  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
 171  * for it.
 172  *
 173  * @param cls Closure.
 174  * @param nym Handle for the user who wants to join.
 175  * @param msg_size Number of bytes in @a msg.
 176  * @param msg Payload given on enter (e.g. a password).
 177  */
 178 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
 179                                                  struct GNUNET_SOCIAL_Nym *nym,
 180                                                  size_t msg_size,
 181                                                  const void *msg);
 182
 183
 184 /**
 185  * Function called when a @a nym leaves the place.
 186  *
 187  * This is also called if the @a nym was never given permission to enter
 188  * (i.e. the @a nym stopped asking to get in).
 189  *
 190  * @param cls Closure.
 191  * @param nym Handle for the user who left.
 192  */
 193 typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
 194                                                struct GNUNET_SOCIAL_Nym *nym);
 195
 196
 197 /**
 198  * Enter a home where guests (nyms) can be hosted.
 199  *
 200  * A home is created upon first entering, and exists until
 201  * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using
 202  * GNUNET_SOCIAL_home_leave().
 203  *
 204  * @param cfg Configuration to contact the social service.
 205  * @param home_keyfile File with the private key for the home,
 206  *              created if the file does not exist;
 207  *              pass NULL for ephemeral homes.
 208  * @param join_policy What is our policy for allowing people in?
 209  * @param ego Owner of the home (host).
 210  * @param slicer Slicer to handle guests talking.
 211  * @param listener_cb Function to handle new nyms that want to join.
 212  * @param farewell_cb Function to handle departing nyms.
 213  * @param cls Closure for @a listener_cb and @a farewell_cb.
 214  * @return Handle for a new home.
 215  */
 216 struct GNUNET_SOCIAL_Home *
 217 GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 218                           const char *home_keyfile,
 219                           enum GNUNET_MULTICAST_JoinPolicy join_policy,
 220                           struct GNUNET_SOCIAL_Ego *ego,
 221                           struct GNUNET_SOCIAL_Slicer *slicer,
 222                           GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
 223                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 224                           void *cls);
 225
 226
 227 /**
 228  * Admit @a nym to the @a home.
 229  *
 230  * The @a nym reference will remain valid until either the home is destroyed or
 231  * @a nym leaves.
 232  *
 233  * @param home Home to allow @a nym to join.
 234  * @param nym Handle for the entity that wants to join.
 235  */
 236 void
 237 GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
 238                           struct GNUNET_SOCIAL_Nym *nym);
 239
 240
 241 /**
 242  * Throw @a nym out of the @a home.
 243  *
 244  * The @a nym reference will remain valid until the
 245  * #GNUNET_SOCIAL_FarewellCallback is invoked,
 246  * which should be very soon after this call.
 247  *
 248  * @param home Home to eject @a nym from.
 249  * @param nym Handle for the entity to be ejected.
 250  */
 251 void
 252 GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home,
 253                           struct GNUNET_SOCIAL_Nym *nym);
 254
 255
 256 /**
 257  * Refuse @a nym entry into the @a home.
 258  *
 259  * @param home Home to disallow @a nym to join.
 260  * @param nym Handle for the entity that wanted to join.
 261  * @param method Method name to invoke on caller.
 262  * @param message_size Number of bytes in @a message for method.
 263  * @param message Rejection message to send back.
 264  *
 265  * FIXME: allow setting variables as well for the message
 266  */
 267 void
 268 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
 269                                  struct GNUNET_SOCIAL_Nym *nym,
 270                                  const char *method,
 271                                  size_t message_size,
 272                                  const void *message);
 273
 274
 275 /**
 276  * Get the identity of a user.
 277  *
 278  * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
 279  *
 280  * @param nym Pseudonym to map to a cryptographic identifier.
 281  * @param[out] identity Set to the identity of the nym (short hash of the public key).
 282  */
 283 void
 284 GNUNET_SOCIAL_nym_get_identity (struct GNUNET_SOCIAL_Nym *nym,
 285                                 struct GNUNET_CRYPTO_ShortHashCode *identity);
 286
 287
 288 /**
 289  * Obtain the (cryptographic, binary) address for the home.
 290  *
 291  * @param home Home to get the (public) address from.
 292  * @param[out] crypto_address Address suitable for storing in GADS, i.e. in
 293  *        'HEX.place' or within the respective GADS record type ("PLACE")
 294  */
 295 void
 296 GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
 297                                 struct GNUNET_HashCode *crypto_address);
 298
 299
 300
 301 /**
 302  * Advertise @a home under @a name in the GADS zone of the @e ego.
 303  *
 304  * @param home The home to advertise.
 305  * @param name The name to put in the zone.
 306  * @param expiration_time Expiration time of the record, use 0 to remove the record.
 307  */
 308 void
 309 GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home,
 310                               const char *name,
 311                               GNUNET_TIME_Relative expiration_time);
 312
 313
 314
 315 /**
 316  * (Re)decorate the home by changing objects in it.
 317  *
 318  * If the operation is #GNUNET_PSYC_OP_SET then the decoration only
 319  * applies to the next announcement by the home owner.
 320  *
 321  * @param home The home to decorate.
 322  * @param operation Operation to perform on the object.
 323  * @param object_name Name of the object to modify.
 324  * @param object_value_size Size of the given @a object_value.
 325  * @param object_value Value to use for the modification.
 326  */
 327 void
 328 GNUNET_SOCIAL_home_decorate (struct GNUNET_SOCIAL_Home *home,
 329                              enum GNUNET_PSYC_Operator operation,
 330                              const char *object_name,
 331                              size_t object_value_size,
 332                              const void *object_value);
 333
 334
 335 /**
 336  * Handle for an announcement request.
 337  */
 338 struct GNUNET_SOCIAL_Announcement;
 339
 340
 341 /**
 342  * Send a message to all nyms that are present in the home.
 343  *
 344  * This function is restricted to the home owner.  Nyms can only send requests
 345  * to the home owner who can decide to relay it to other guests.
 346  *
 347  * @param home Home to address the announcement to.
 348  * @param method_name Method to use for the announcement.
 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                              GNUNET_PSYC_OriginReadyNotify notify,
 357                              void *notify_cls);
 358
 359
 360 /**
 361  * Cancel announcement.
 362  *
 363  * @param a The announcement to cancel.
 364  */
 365 void
 366 GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 367
 368
 369 /**
 370  * Convert our home to a place so we can access it via the place API.
 371  *
 372  * @param home Handle for the home.
 373  * @return Place handle for the same home, valid as long as @a home is valid;
 374  *         do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home!
 375  */
 376 struct GNUNET_SOCIAL_Place *
 377 GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
 378
 379
 380 /**
 381  * Leave a home temporarily, visitors can stay.
 382  *
 383  * After leaving, handling of incoming messages are left to other clients of the
 384  * social service, and stops after the last client exits.
 385  *
 386  * @param home Home to leave temporarily (handle becomes invalid).
 387  */
 388 void
 389 GNUNET_SOCIAL_home_away (struct GNUNET_SOCIAL_Home *home);
 390
 391
 392 /**
 393  * Destroy a home, all guests will be ejected.
 394  *
 395  * @param home Home to destroy.
 396  */
 397 void
 398 GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
 399
 400 /**
 401  * Request entry to a place (home hosted by someone else).
 402  *
 403  * @param cfg Configuration to contact the social service.
 404  * @param ego Owner of the home (host).
 405  * @param address Address of the place to enter (GADS name, i.e. 'room.friend.gads'),
 406  *        if the name has the form 'HEX.place', GADS is not
 407  *        used and HEX is assumed to be the hash of the public
 408  *        key already; 'HEX.zkey' however would refer to
 409  *        the 'PLACE' record in the GADS zone with the public key
 410  *        'HEX'.
 411  * @param msg_size Number of bytes in @a msg.
 412  * @param msg Message to give to the enter callback.
 413  * @param slicer Slicer to use for processing incoming requests from guests.
 414  * @return NULL on errors, otherwise handle to the place.
 415  */
 416 struct GNUNET_SOCIAL_Place *
 417 GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 418                            struct GNUNET_SOCIAL_Ego *ego,
 419                            char *address,
 420                            size_t msg_size,
 421                            const void *msg,
 422                            struct GNUNET_SOCIAL_Slicer *slicer);
 423
 424 /**
 425  * Request entry to a place (home hosted by someone else).
 426  *
 427  * @param cfg Configuration to contact the social service.
 428  * @param ego Owner of the home (host).
 429  * @param crypto_address Public key of the place to enter.
 430  * @param peer Peer to send request to.
 431  * @param slicer Slicer to use for processing incoming requests from guests.
 432  * @param msg_size Number of bytes in @a msg.
 433  * @param msg Message to give to the enter callback.
 434  * @return NULL on errors, otherwise handle to the place.
 435  */
 436 struct GNUNET_SOCIAL_Place *
 437 GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
 438                            struct GNUNET_SOCIAL_Ego *ego,
 439                            struct GNUNET_HashCode *crypto_address,
 440                            struct GNUNET_PeerIdentity *peer,
 441                            struct GNUNET_SOCIAL_Slicer *slicer,
 442                            size_t msg_size,
 443                            const void *msg);
 444
 445
 446 struct GNUNET_SOCIAL_WatchHandle;
 447
 448 /**
 449  * Watch a place for changed objects.
 450  *
 451  * @param place Place to watch.
 452  * @param object_filter Object prefix to match.
 453  * @param state_cb Function to call when an object/state changes.
 454  * @param state_cb_cls Closure for callback.
 455  *
 456  * @return Handle that can be used to cancel watching.
 457  */
 458 struct GNUNET_SOCIAL_WatchHandle *
 459 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
 460                            const char *object_filter,
 461                            GNUNET_PSYC_StateCallback state_cb,
 462                            void *state_cb_cls);
 463
 464
 465 /**
 466  * Cancel watching a place for changed objects.
 467  *
 468  * @param wh Watch handle to cancel.
 469  */
 470 void
 471 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
 472
 473
 474 struct GNUNET_SOCIAL_LookHandle;
 475
 476 /**
 477  * Look at all objects in the place.
 478  *
 479  * @param place The place to look its objects at.
 480  * @param state_cb Function to call for each object found.
 481  * @param state_cb_cls Closure for callback function.
 482  *
 483  * @return Handle that can be used to stop looking at objects.
 484  */
 485 struct GNUNET_SOCIAL_LookHandle *
 486 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
 487                           GNUNET_PSYC_StateCallback state_cb,
 488                           void *state_cb_cls);
 489
 490
 491 /**
 492  * Look at matching objects in the place.
 493  *
 494  * @param place The place to look its objects at.
 495  * @param object_filter Only look at objects with names beginning with this filter value.
 496  * @param state_cb Function to call for each object found.
 497  * @param state_cb_cls Closure for callback function.
 498  *
 499  * @return Handle that can be used to stop looking at objects.
 500  */
 501 struct GNUNET_SOCIAL_LookHandle *
 502 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
 503                               const char *object_filter,
 504                               GNUNET_PSYC_StateCallback state_cb,
 505                               void *state_cb_cls);
 506
 507
 508 /**
 509  * Stop looking at objects.
 510  *
 511  * @param lh Look handle to stop.
 512  */
 513 void
 514 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 515
 516
 517
 518 /**
 519  * Look at a particular object in the place.
 520  *
 521  * @param place The place to look the object at.
 522  * @param object_name Full name of the object.
 523  * @param value_size Set to the size of the returned value.
 524  * @return NULL if there is no such object at this place.
 525  */
 526 const void *
 527 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
 528                              const char *object_name,
 529                              size_t *value_size);
 530
 531
 532 /**
 533  * Frame the (next) talk by setting some variables for it.
 534  *
 535  * FIXME: use a TalkFrame struct instead that can be passed to
 536  * place_talk, nym_talk and home_reject_entry.
 537  *
 538  * @param place Place to talk in.
 539  * @param variable_name Name of variable to set.
 540  * @param value_size Number of bytes in @a value.
 541  * @param value Value of variable.
 542  */
 543 void
 544 GNUNET_SOCIAL_place_frame_talk (struct GNUNET_SOCIAL_Place *place,
 545                                 const char *variable_name,
 546                                 size_t value_size,
 547                                 const void *value);
 548
 549
 550 /**
 551  * A talk request.
 552  */
 553 struct GNUNET_SOCIAL_TalkRequest;
 554
 555 /**
 556  * Talk to the host of the place.
 557  *
 558  * @param place Place where we want to talk to the host.
 559  * @param method_name Method to invoke on the host.
 560  * @param cb Function to use to get the payload for the method.
 561  * @param cb_cls Closure for @a cb.
 562  * @return NULL if we are already trying to talk to the host,
 563  *         otherwise handle to cancel the request.
 564  */
 565 struct GNUNET_SOCIAL_TalkRequest *
 566 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
 567                           const char *method_name,
 568                           GNUNET_PSYC_OriginReadyNotify cb,
 569                           void *cb_cls);
 570
 571
 572 /**
 573  * Cancel talking to the host of the place.
 574  *
 575  * @param tr Talk request to cancel.
 576  */
 577 void
 578 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 579
 580
 581 /**
 582  * A history lesson.
 583  */
 584 struct GNUNET_SOCIAL_HistoryLesson;
 585
 586 /**
 587  * Learn about the history of a place.
 588  *
 589  * Sends messages through the given slicer function where
 590  * start_message_id <= message_id <= end_message_id.
 591  *
 592  * To get the latest message, use 0 for both the start and end message ID.
 593  *
 594  * @param place Place we want to learn more about.
 595  * @param start_message_id First historic message we are interested in.
 596  * @param end_message_id Last historic message we are interested in (inclusive).
 597  * @param slicer Slicer to use to process history.
 598  * @return Handle to abort history lesson, never NULL (multiple lessons
 599  *        at the same time are allowed).
 600  */
 601 struct GNUNET_SOCIAL_HistoryLesson *
 602 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
 603                                  uint64_t start_message_id,
 604                                  uint64_t end_message_id,
 605                                  struct GNUNET_SOCIAL_Slicer *slicer);
 606
 607
 608 /**
 609  * Stop processing messages from the history lesson.
 610  *
 611  * Must also be called explicitly after all of the requested messages have been
 612  * received.
 613  *
 614  * @param hist History lesson to cancel.
 615  */
 616 void
 617 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
 618
 619
 620 /**
 621  * Leave a place permanently.
 622  *
 623  * Notifies the owner of the place about leaving, and destroys the place handle.
 624  *
 625  * @param place Place to leave permanently.
 626  */
 627 void
 628 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place);
 629
 630
 631 /**
 632  * Leave a place temporarily.
 633  *
 634  * Stop following the conversation for the @a place and destroy the @a place
 635  * handle.  Only affects the application calling this function, other clients of
 636  * the service continue receiving the messages.
 637  *
 638  * @param place Place to leave temporarily.
 639  */
 640 void
 641 GNUNET_SOCIAL_place_away (struct GNUNET_SOCIAL_Place *place);
 642
 643
 644 #if 0                           /* keep Emacsens' auto-indent happy */
 645 {
 646 #endif
 647 #ifdef __cplusplus
 648 }
 649 #endif
 650
 651 /* ifndef GNUNET_SOCIAL_SERVICE_H */
 652 #endif
 653 /* end of gnunet_social_service.h */