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
  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 /**
  50  * Handle for a place where social interactions happen.
  51  */
  52 struct GNUNET_SOCIAL_Place;
  53
  54 /**
  55  * Handle for a place that one of our egos hosts.
  56  */
  57 struct GNUNET_SOCIAL_Home;
  58
  59 /**
  60  * Handle for our own presence in the network (we can of course have
  61  * alter-egos).
  62  */
  63 struct GNUNET_SOCIAL_Ego;
  64
  65 /**
  66  * Handle for another user (who is likely pseudonymous) in the network.
  67  */
  68 struct GNUNET_SOCIAL_Nym;
  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 '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  * @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 'data' in the overall data of the method
  87  * @param data_size number of bytes in '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 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  * @param slicer try-and-slice instance to extend
 114  * @param method_name name of the given method, use empty string for default
 115  * @param method method to invoke
 116  * @param method_cls closure for method
 117  */
 118 void
 119 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
 120                           const char *method_name,
 121                           GNUNET_SOCIAL_Method method,
 122                           void *method_cls);
 123
 124
 125 /**
 126  * Destroy a given try-and-slice instance.
 127  *
 128  * @param slicer slicer to destroy
 129  */
 130 void
 131 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
 132
 133
 134 /**
 135  * Create an ego using the private key from the given
 136  * file.  If the file does not exist, a fresh key is
 137  * created.
 138  *
 139  * @param keyfile name of the file with the private key for the ego,
 140  *                NULL for ephemeral egos
 141  * @return handle to the ego, NULL on error
 142  */
 143 struct GNUNET_SOCIAL_Ego *
 144 GNUNET_SOCIAL_ego_create (const char *keyfile);
 145
 146
 147 /**
 148  * Destroy a handle to an ego.
 149  *
 150  * @param ego ego to destroy
 151  */
 152 void
 153 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
 154
 155
 156 /**
 157  * Function called asking for nym to be admitted to the room.  Should
 158  * call either 'GNUNET_SOCIAL_home_admit' or
 159  * 'GNUNET_SOCIAL_home_reject_entry' (possibly asynchronously).  If
 160  * this owner cannot decide, it is fine to call neither function, in
 161  * which case hopefully some other owner of the home exists that will
 162  * make the decision. The 'nym' reference remains valid until the
 163  * 'GNUNET_SOCIAL_FarewellCallback' is invoked for it.
 164  *
 165  * @param cls closure
 166  * @param nym handle for the user who wants to join
 167  * @param join_msg_size number of bytes in 'join_msg'
 168  * @param join_msg payload given on join
 169  */
 170 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
 171                                                  struct GNUNET_SOCIAL_Nym *nym,
 172                                                  size_t join_msg_size,
 173                                                  const void *join_msg);
 174
 175
 176 /**
 177  * Function called when a 'nym' leaves the room.  This is
 178  * also called if the 'nym' was never given permission to
 179  * enter (i.e. the 'nym' stopped asking to get in).
 180  *
 181  * @param cls closure
 182  * @param nym handle for the user who left
 183  */
 184 typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
 185                                                struct GNUNET_SOCIAL_Nym *nym);
 186
 187
 188 /**
 189  * Create a new home to host guests (nyms).
 190  *
 191  * @param cfg configuration to contact the social service
 192  * @param home_keyfile file with the private key for the home,
 193  *              created if the file does not exist;
 194  *              pass NULL for ephemeral homes
 195  * @param join_policy what is our policy for allowing people in?
 196  * @param ego owner of the home (host)
 197  * @param slicer slicer to handle guests talking
 198  * @param listener_cb function to handle new nyms that want to join
 199  * @param farewell_cb function to handle departing nyms
 200  * @param cls closure for 'listener_cb' and 'farewell_cb'
 201  * @return handle for a new home
 202  */
 203 struct GNUNET_SOCIAL_Home *
 204 GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 205                           const char *home_keyfile,
 206                           enum GNUNET_MULTICAST_JoinPolicy join_policy,
 207                           struct GNUNET_SOCIAL_Ego *ego,
 208                           struct GNUNET_SOCIAL_Slicer *slicer,
 209                           GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
 210                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 211                           void *cls);
 212
 213
 214 /**
 215  * Admit 'nym' to the 'home'.  'nym' will remain valid until either
 216  * the home is destroyed or 'nym' leaves.
 217  *
 218  * @param home home to allow 'nym' to join
 219  * @param nym handle for the entity that wants to join
 220  */
 221 void
 222 GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
 223                           struct GNUNET_SOCIAL_Nym *nym);
 224
 225
 226 /**
 227  * Throw 'nym' out of the 'home'.  'nym' will remain valid
 228  * until the 'GNUNET_SOCIAL_FarewellCallback' is invoked, which
 229  * should be very soon after this call.
 230  *
 231  * @param home home to allow 'nym' to join
 232  * @param nym handle for the entity that wants to join
 233  */
 234 void
 235 GNUNET_SOCIAL_home_evict (struct GNUNET_SOCIAL_Home *home,
 236                           struct GNUNET_SOCIAL_Nym *nym);
 237
 238
 239 /**
 240  * Refuse 'nym' entry into the 'home'.
 241  *
 242  * @param home home to disallow 'nym' to join
 243  * @param nym handle for the entity that wanted to join
 244  */
 245 void
 246 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
 247                                  struct GNUNET_SOCIAL_Nym *nym);
 248
 249
 250 /**
 251  * Get the identity of a user (suitable, for example, to be used
 252  * with 'GNUNET_NAMESTORE_zone_to_name').
 253  *
 254  * @param nym pseydonym to map to a cryptographic identifier
 255  * @param identity set to the identity of the nym (short hash of the public key)
 256  */
 257 void
 258 GNUNET_SOCIAL_nym_get_identity (struct GNUNET_SOCIAL_Nym *nym,
 259                                 struct GNUNET_CRYPTO_ShortHashCode *identity);
 260
 261
 262 /**
 263  * Obtain the (cryptographic, binary) address for the home.
 264  *
 265  * @param home home to get the (public) address from
 266  * @param crypto_address address suitable for storing in GADS,
 267  *        i.e. in 'HEX.place' or within the respective GADS record type ("PLACE")
 268  */
 269 void
 270 GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
 271                                 struct GNUNET_HashCode *crypto_address);
 272
 273
 274 /**
 275  * (re)decorate the home by changing objects in it.  If
 276  * the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then
 277  * the decoration only applies to the next announcement
 278  * by the home owner.
 279  *
 280  * @param home the home to decorate
 281  * @param operation operation to perform on the object
 282  * @param object_name name of the object to modify
 283  * @param object_value_size size of the given 'object_value'
 284  * @param object_value value to use for the modification
 285  */
 286 void
 287 GNUNET_SOCIAL_home_decorate (struct GNUNET_SOCIAL_Home *home,
 288                              enum GNUNET_PSYC_Operator operation,
 289                              const char *object_name,
 290                              size_t object_value_size,
 291                              const void *object_value);
 292
 293
 294 /**
 295  * Handle for an announcement request.
 296  */
 297 struct GNUNET_SOCIAL_Announcement;
 298
 299
 300 /**
 301  * This function allows the home owner to send a message to all
 302  * nyms that are present in the home.
 303  *
 304  * @param home home to address the announcement to
 305  * @param full_method_name method to use for the announcement
 306  * @param notify function to call to get the payload of the announcement
 307  * @param notify_cls closure for 'notify'
 308  * @return NULL on error (announcement already in progress?)
 309  */
 310 struct GNUNET_SOCIAL_Announcement *
 311 GNUNET_SOCIAL_place_announce (struct GNUNET_SOCIAL_Home *home,
 312                               const char *full_method_name,
 313                               GNUNET_PSYC_OriginReadyNotify notify,
 314                               void *notify_cls);
 315
 316
 317 /**
 318  * Cancel announcement.
 319  *
 320  * @param a the announcement to cancel
 321  */
 322 void
 323 GNUNET_SOCIAL_place_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 324
 325
 326 /**
 327  * Convert our home to a place so we can access it via the place API.
 328  *
 329  * @param home handle for the home
 330  * @return place handle for the same home, valid as long as 'home' is valid;
 331  *         do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your home!
 332  */
 333 struct GNUNET_SOCIAL_Place *
 334 GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
 335
 336
 337 /**
 338  * Leave a home, visitors can stay.
 339  *
 340  * @param home home to leave (handle becomes invalid).
 341  */
 342 void
 343 GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
 344
 345
 346 /**
 347  * Destroy a home, all guests will be evicted.
 348  *
 349  * @param home home to destroy
 350  */
 351 void
 352 GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
 353
 354
 355 /**
 356  * Join a place (home hosted by someone else).
 357  *
 358  * @param cfg configuration to contact the social service
 359  * @param ego owner of the home (host)
 360  * @param address address of the place to join (GADS name, i.e. 'room.friend.gads'),
 361  *        if the name has the form 'HEX.place', GADS is not
 362  *        used and HEX is assumed to be the hash of the public
 363  *        key already; 'HEX.zkey' however would refer to
 364  *        the 'PLACE' record in the GADS zone with the public key
 365  *        'HEX'.
 366  * @param join_msg_size number of bytes in 'join_msg'
 367  * @param join_msg message to give to the join callback
 368  * @return NULL on errors, otherwise handle to the place
 369  */
 370 struct GNUNET_SOCIAL_Place *
 371 GNUNET_SOCIAL_place_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
 372                           struct GNUNET_SOCIAL_Ego *ego,
 373                           const char *address,
 374                           struct GNUNET_SOCIAL_Slicer *slicer,
 375                           size_t join_msg_size,
 376                           const void *join_msg);
 377
 378
 379 /**
 380  *
 381  */
 382 struct GNUNET_SOCIAL_WatchHandle;
 383
 384 /**
 385  *
 386  *
 387  * @param
 388  * @param
 389  * @param
 390  * @param
 391  */
 392 struct GNUNET_SOCIAL_WatchHandle *
 393 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
 394                            const char *object_filter,
 395                            GNUNET_PSYC_StateCallback state_cb,
 396                            void *state_cb_cls);
 397
 398
 399 /**
 400  *
 401  *
 402  * @param
 403  */
 404 void
 405 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
 406
 407
 408 /**
 409  *
 410  */
 411 struct GNUNET_SOCIAL_LookHandle;
 412
 413 /**
 414  * Look at all objects in the place.
 415  *
 416  */
 417 struct GNUNET_SOCIAL_LookHandle *
 418 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
 419                           GNUNET_PSYC_StateCallback state_cb,
 420                           void *state_cb_cls);
 421
 422
 423 /**
 424  * Look at matching objects in the place.
 425  *
 426  */
 427 struct GNUNET_SOCIAL_LookHandle *
 428 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
 429                               const char *object_filter,
 430                               GNUNET_PSYC_StateCallback state_cb,
 431                               void *state_cb_cls);
 432
 433
 434 /**
 435  *
 436  *
 437  * @param lh
 438  */
 439 void
 440 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 441
 442
 443
 444 /**
 445  * Look at a particular object in the place.
 446  *
 447  * @param place
 448  * @param object_name
 449  * @param value_size set to the size of the returned value
 450  * @return NULL if there is no such object at this place
 451  */
 452 const void *
 453 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
 454                              const char *object_name,
 455                              size_t *value_size);
 456
 457
 458 /**
 459  * Frame the (next) talk by setting some variables for it.
 460  *
 461  * @param place
 462  * @param variable_name
 463  * @param value_size number of bytes in 'value'
 464  * @param value
 465  */
 466 void
 467 GNUNET_SOCIAL_place_frame_talk (struct GNUNET_SOCIAL_Place *place,
 468                                 const char *variable_name,
 469                                 size_t value_size,
 470                                 const void *value);
 471
 472
 473 /**
 474  *
 475  */
 476 struct GNUNET_SOCIAL_TalkRequest;
 477
 478
 479 /**
 480  * Talk to the host of the place.
 481  *
 482  * @param place place at which we want to talk to the host
 483  * @param method_name method to invoke on the host
 484  * @param cb function to use to get the payload for the method
 485  * @param cb_cls closure for 'cb'
 486  * @return NULL if we are already trying to talk to the host,
 487  *         otherwise handle to cancel the request
 488  */
 489 struct GNUNET_SOCIAL_TalkRequest *
 490 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
 491                           const char *method_name,
 492                           GNUNET_PSYC_OriginReadyNotify cb,
 493                           void *cb_cls);
 494
 495
 496 /**
 497  *
 498  *
 499  * @param tr
 500  */
 501 void
 502 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 503
 504
 505 /**
 506  *
 507  */
 508 struct GNUNET_SOCIAL_HistoryLesson;
 509
 510
 511 /**
 512  *
 513  *
 514  * @param place place we want to learn more about
 515  * @param start_message_id first historic message we are interested in
 516  * @param end_message_id last historic message we are interested in (inclusive)
 517  * @param slicer slicer to use to process history
 518  * @return handle to abort history lesson, never NULL (multiple lesssons
 519  *        at the same time are allowed)
 520  */
 521 struct GNUNET_SOCIAL_HistoryLesson *
 522 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
 523                                  uint64_t start_message_id,
 524                                  uint64_t end_message_id,
 525                                  struct GNUNET_SOCIAL_Slicer *slicer);
 526
 527
 528 /**
 529  * Stop processing messages from the history lesson.  Must also be
 530  * called explicitly after all of the requested messages have been
 531  * received.
 532  *
 533  * @param hist history lesson to cancel
 534  */
 535 void
 536 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
 537
 538
 539 /**
 540  * Leave a place (destroys the place handle).  Can either move our
 541  * user into an 'away' state (in which we continue to record ongoing
 542  * conversations and state changes if our peer is running), or
 543  * leave the place entirely and stop following the conversation.
 544  *
 545  * @param place place to leave
 546  * @param keep_following GNUNET_YES to ask the social service to continue
 547  *        to follow the conversation, GNUNET_NO to fully leave the place
 548  */
 549 void
 550 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place,
 551                            int keep_following);
 552
 553
 554
 555 #if 0                           /* keep Emacsens' auto-indent happy */
 556 {
 557 #endif
 558 #ifdef __cplusplus
 559 }
 560 #endif
 561
 562 /* ifndef GNUNET_SOCIAL_SERVICE_H */
 563 #endif
 564 /* end of gnunet_social_service.h */