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