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  * @param method method name to invoke on caller
 245  * @param message_size number of bytes in 'message' for method
 246  * @param message rejection message to send back
 247  */
 248 void
 249 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
 250                                  struct GNUNET_SOCIAL_Nym *nym,
 251                                  const char *method,
 252                                  size_t message_size,
 253                                  const void *message);
 254
 255
 256 /**
 257  * Get the identity of a user (suitable, for example, to be used
 258  * with 'GNUNET_NAMESTORE_zone_to_name').
 259  *
 260  * @param nym pseydonym to map to a cryptographic identifier
 261  * @param identity set to the identity of the nym (short hash of the public key)
 262  */
 263 void
 264 GNUNET_SOCIAL_nym_get_identity (struct GNUNET_SOCIAL_Nym *nym,
 265                                 struct GNUNET_CRYPTO_ShortHashCode *identity);
 266
 267
 268 /**
 269  * Obtain the (cryptographic, binary) address for the home.
 270  *
 271  * @param home home to get the (public) address from
 272  * @param crypto_address address suitable for storing in GADS,
 273  *        i.e. in 'HEX.place' or within the respective GADS record type ("PLACE")
 274  */
 275 void
 276 GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
 277                                 struct GNUNET_HashCode *crypto_address);
 278
 279
 280 /**
 281  * (re)decorate the home by changing objects in it.  If
 282  * the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then
 283  * the decoration only applies to the next announcement
 284  * by the home owner.
 285  *
 286  * @param home the home to decorate
 287  * @param operation operation to perform on the object
 288  * @param object_name name of the object to modify
 289  * @param object_value_size size of the given 'object_value'
 290  * @param object_value value to use for the modification
 291  */
 292 void
 293 GNUNET_SOCIAL_home_decorate (struct GNUNET_SOCIAL_Home *home,
 294                              enum GNUNET_PSYC_Operator operation,
 295                              const char *object_name,
 296                              size_t object_value_size,
 297                              const void *object_value);
 298
 299
 300 /**
 301  * Handle for an announcement request.
 302  */
 303 struct GNUNET_SOCIAL_Announcement;
 304
 305
 306 /**
 307  * This function allows the home owner to send a message to all
 308  * nyms that are present in the home.
 309  *
 310  * @param home home to address the announcement to
 311  * @param full_method_name method to use for the announcement
 312  * @param notify function to call to get the payload of the announcement
 313  * @param notify_cls closure for 'notify'
 314  * @return NULL on error (announcement already in progress?)
 315  */
 316 struct GNUNET_SOCIAL_Announcement *
 317 GNUNET_SOCIAL_place_announce (struct GNUNET_SOCIAL_Home *home,
 318                               const char *full_method_name,
 319                               GNUNET_PSYC_OriginReadyNotify notify,
 320                               void *notify_cls);
 321
 322
 323 /**
 324  * Cancel announcement.
 325  *
 326  * @param a the announcement to cancel
 327  */
 328 void
 329 GNUNET_SOCIAL_place_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 330
 331
 332 /**
 333  * Convert our home to a place so we can access it via the place API.
 334  *
 335  * @param home handle for the home
 336  * @return place handle for the same home, valid as long as 'home' is valid;
 337  *         do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your home!
 338  */
 339 struct GNUNET_SOCIAL_Place *
 340 GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
 341
 342
 343 /**
 344  * Leave a home, visitors can stay.
 345  *
 346  * @param home home to leave (handle becomes invalid).
 347  */
 348 void
 349 GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
 350
 351
 352 /**
 353  * Destroy a home, all guests will be evicted.
 354  *
 355  * @param home home to destroy
 356  */
 357 void
 358 GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
 359
 360
 361 /**
 362  * Join a place (home hosted by someone else).
 363  *
 364  * @param cfg configuration to contact the social service
 365  * @param ego owner of the home (host)
 366  * @param address address of the place to join (GADS name, i.e. 'room.friend.gads'),
 367  *        if the name has the form 'HEX.place', GADS is not
 368  *        used and HEX is assumed to be the hash of the public
 369  *        key already; 'HEX.zkey' however would refer to
 370  *        the 'PLACE' record in the GADS zone with the public key
 371  *        'HEX'.
 372  * @param join_msg_size number of bytes in 'join_msg'
 373  * @param join_msg message to give to the join callback
 374  * @return NULL on errors, otherwise handle to the place
 375  */
 376 struct GNUNET_SOCIAL_Place *
 377 GNUNET_SOCIAL_place_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
 378                           struct GNUNET_SOCIAL_Ego *ego,
 379                           const char *address,
 380                           struct GNUNET_SOCIAL_Slicer *slicer,
 381                           size_t join_msg_size,
 382                           const void *join_msg);
 383
 384
 385 /**
 386  *
 387  */
 388 struct GNUNET_SOCIAL_WatchHandle;
 389
 390 /**
 391  *
 392  *
 393  * @param
 394  * @param
 395  * @param
 396  * @param
 397  */
 398 struct GNUNET_SOCIAL_WatchHandle *
 399 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
 400                            const char *object_filter,
 401                            GNUNET_PSYC_StateCallback state_cb,
 402                            void *state_cb_cls);
 403
 404
 405 /**
 406  *
 407  *
 408  * @param
 409  */
 410 void
 411 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
 412
 413
 414 /**
 415  *
 416  */
 417 struct GNUNET_SOCIAL_LookHandle;
 418
 419 /**
 420  * Look at all objects in the place.
 421  *
 422  */
 423 struct GNUNET_SOCIAL_LookHandle *
 424 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
 425                           GNUNET_PSYC_StateCallback state_cb,
 426                           void *state_cb_cls);
 427
 428
 429 /**
 430  * Look at matching objects in the place.
 431  *
 432  */
 433 struct GNUNET_SOCIAL_LookHandle *
 434 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
 435                               const char *object_filter,
 436                               GNUNET_PSYC_StateCallback state_cb,
 437                               void *state_cb_cls);
 438
 439
 440 /**
 441  *
 442  *
 443  * @param lh
 444  */
 445 void
 446 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 447
 448
 449
 450 /**
 451  * Look at a particular object in the place.
 452  *
 453  * @param place
 454  * @param object_name
 455  * @param value_size set to the size of the returned value
 456  * @return NULL if there is no such object at this place
 457  */
 458 const void *
 459 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
 460                              const char *object_name,
 461                              size_t *value_size);
 462
 463
 464 /**
 465  * Frame the (next) talk by setting some variables for it.
 466  *
 467  * @param place
 468  * @param variable_name
 469  * @param value_size number of bytes in 'value'
 470  * @param value
 471  */
 472 void
 473 GNUNET_SOCIAL_place_frame_talk (struct GNUNET_SOCIAL_Place *place,
 474                                 const char *variable_name,
 475                                 size_t value_size,
 476                                 const void *value);
 477
 478
 479 /**
 480  *
 481  */
 482 struct GNUNET_SOCIAL_TalkRequest;
 483
 484
 485 /**
 486  * Talk to the host of the place.
 487  *
 488  * @param place place at which we want to talk to the host
 489  * @param method_name method to invoke on the host
 490  * @param cb function to use to get the payload for the method
 491  * @param cb_cls closure for 'cb'
 492  * @return NULL if we are already trying to talk to the host,
 493  *         otherwise handle to cancel the request
 494  */
 495 struct GNUNET_SOCIAL_TalkRequest *
 496 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
 497                           const char *method_name,
 498                           GNUNET_PSYC_OriginReadyNotify cb,
 499                           void *cb_cls);
 500
 501
 502 /**
 503  *
 504  *
 505  * @param tr
 506  */
 507 void
 508 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 509
 510
 511 /**
 512  *
 513  */
 514 struct GNUNET_SOCIAL_HistoryLesson;
 515
 516
 517 /**
 518  *
 519  *
 520  * @param place place we want to learn more about
 521  * @param start_message_id first historic message we are interested in
 522  * @param end_message_id last historic message we are interested in (inclusive)
 523  * @param slicer slicer to use to process history
 524  * @return handle to abort history lesson, never NULL (multiple lesssons
 525  *        at the same time are allowed)
 526  */
 527 struct GNUNET_SOCIAL_HistoryLesson *
 528 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
 529                                  uint64_t start_message_id,
 530                                  uint64_t end_message_id,
 531                                  struct GNUNET_SOCIAL_Slicer *slicer);
 532
 533
 534 /**
 535  * Stop processing messages from the history lesson.  Must also be
 536  * called explicitly after all of the requested messages have been
 537  * received.
 538  *
 539  * @param hist history lesson to cancel
 540  */
 541 void
 542 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
 543
 544
 545 /**
 546  * Leave a place (destroys the place handle).  Can either move our
 547  * user into an 'away' state (in which we continue to record ongoing
 548  * conversations and state changes if our peer is running), or
 549  * leave the place entirely and stop following the conversation.
 550  *
 551  * @param place place to leave
 552  * @param keep_following GNUNET_YES to ask the social service to continue
 553  *        to follow the conversation, GNUNET_NO to fully leave the place
 554  */
 555 void
 556 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place,
 557                            int keep_following);
 558
 559
 560
 561 #if 0                           /* keep Emacsens' auto-indent happy */
 562 {
 563 #endif
 564 #ifdef __cplusplus
 565 }
 566 #endif
 567
 568 /* ifndef GNUNET_SOCIAL_SERVICE_H */
 569 #endif
 570 /* end of gnunet_social_service.h */