src/include/gnunet_social_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_social_service.h
  23  * @brief Social service; implements social interactions 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_env_lib.h"
  40 #include "gnunet_identity_service.h"
  41 #include "gnunet_namestore_service.h"
  42 #include "gnunet_psyc_service.h"
  43
  44
  45 /**
  46  * Version number of GNUnet Social API.
  47  */
  48 #define GNUNET_SOCIAL_VERSION 0x00000000
  49
  50
  51 /**
  52  * Handle for a pseudonym of another user in the network.
  53  */
  54 struct GNUNET_SOCIAL_Nym;
  55
  56 /**
  57  * Handle for a place where social interactions happen.
  58  */
  59 struct GNUNET_SOCIAL_Place;
  60
  61 /**
  62  * Host handle for a place that we entered.
  63  */
  64 struct GNUNET_SOCIAL_Host;
  65
  66 /**
  67  * Guest handle for place that we entered.
  68  */
  69 struct GNUNET_SOCIAL_Guest;
  70
  71 /**
  72  * Handle to an implementation of try-and-slice.
  73  */
  74 struct GNUNET_SOCIAL_Slicer;
  75
  76
  77 /**
  78  * Function called upon receiving a message indicating a call to a @e method.
  79  *
  80  * This function is called one or more times for each message until all data
  81  * fragments arrive from the network.
  82  *
  83  * @param cls
  84  *        Closure.
  85  * @param msg
  86  *        Message part, as it arrived from the network.
  87  * @param message_id
  88  *        Message counter, monotonically increasing from 1.
  89  * @param nym
  90  *        The sender of the message.
  91  *        Can be NULL if the message is not connected to a pseudonym.
  92  * @param flags
  93  *        OR'ed GNUNET_PSYC_MessageFlags
  94  * @param method_name
  95  *        Original method name from PSYC.
  96  *        May be more specific than the registered method name due to
  97  *        try-and-slice matching.
  98  */
  99 typedef void
 100 (*GNUNET_SOCIAL_MethodCallback) (void *cls,
 101                                  const struct GNUNET_PSYC_MessageMethod *msg,
 102                                  uint64_t message_id,
 103                                  uint32_t flags,
 104                                  const struct GNUNET_SOCIAL_Nym *nym,
 105                                  const char *method_name);
 106
 107
 108 /**
 109  * Function called upon receiving a modifier of a message.
 110  *
 111  * @param cls
 112  *        Closure.
 113  * @param message_id
 114  *        Message ID this data fragment belongs to.
 115  * @param msg
 116  *        Message part, as it arrived from the network.
 117  * @param oper
 118  *        Operation to perform.
 119  *        0 in case of a modifier continuation.
 120  * @param name
 121  *        Name of the modifier.
 122  *        NULL in case of a modifier continuation.
 123  * @param value
 124  *        Value of the modifier.
 125  * @param value_size
 126  *        Size of @value.
 127  */
 128 typedef void
 129 (*GNUNET_SOCIAL_ModifierCallback) (void *cls,
 130                                    const struct GNUNET_MessageHeader *msg,
 131                                    uint64_t message_id,
 132                                    enum GNUNET_ENV_Operator oper,
 133                                    const char *name,
 134                                    const void *value,
 135                                    uint16_t value_size,
 136                                    uint16_t full_value_size);
 137
 138
 139 /**
 140  * Function called upon receiving a data fragment of a message.
 141  *
 142  * @param cls
 143  *        Closure.
 144  * @param message_id
 145  *        Message ID this data fragment belongs to.
 146  * @param msg
 147  *        Message part, as it arrived from the network.
 148  * @param data_offset
 149  *        Byte offset of @a data in the overall data of the method.
 150  * @param data_size
 151  *        Number of bytes in @a data.
 152  * @param data
 153  *        Data stream given to the method.
 154  * @param end
 155  *        End of message?
 156  *        #GNUNET_NO     if there are further fragments,
 157  *        #GNUNET_YES    if this is the last fragment,
 158  *        #GNUNET_SYSERR indicates the message was cancelled by the sender.
 159  */
 160 typedef void
 161 (*GNUNET_SOCIAL_DataCallback) (void *cls,
 162                                const struct GNUNET_MessageHeader *msg,
 163                                uint64_t message_id,
 164                                uint64_t data_offset,
 165                                const void *data,
 166                                uint16_t data_size);
 167
 168
 169 /**
 170  * End of message.
 171  *
 172  * @param cls
 173  *        Closure.
 174  * @param msg
 175  *        Message part, as it arrived from the network.
 176  * @param message_id
 177  *        Message ID this data fragment belongs to.
 178  * @param cancelled.
 179  *        #GNUNET_YES if the message was cancelled,
 180  *        #GNUNET_NO  if the message is complete.
 181  */
 182 typedef void
 183 (*GNUNET_SOCIAL_EndOfMessageCallback) (void *cls,
 184                                        const struct GNUNET_MessageHeader *msg,
 185                                        uint64_t message_id,
 186                                        uint8_t cancelled);
 187
 188
 189 /**
 190  * Create a try-and-slice instance.
 191  *
 192  * A slicer processes incoming messages and notifies callbacks about matching
 193  * methods or modifiers encountered.
 194  *
 195  * @return A new try-and-slice construct.
 196  */
 197 struct GNUNET_SOCIAL_Slicer *
 198 GNUNET_SOCIAL_slicer_create (void);
 199
 200
 201 /**
 202  * Add a method to the try-and-slice instance.
 203  *
 204  * The callbacks are called for messages with a matching @a method_name prefix.
 205  *
 206  * @param slicer
 207  *        The try-and-slice instance to extend.
 208  * @param method_name
 209  *        Name of the given method, use empty string to match all.
 210  * @param method_cb
 211  *        Method handler invoked upon a matching message.
 212  * @param modifier_cb
 213  *        Modifier handler, invoked after @a method_cb
 214  *        for each modifier in the message.
 215  * @param data_cb
 216  *        Data handler, invoked after @a modifier_cb for each data fragment.
 217  * @param eom_cb
 218  *        Invoked upon reaching the end of a matching message.
 219  * @param cls
 220  *        Closure for the callbacks.
 221  */
 222 void
 223 GNUNET_SOCIAL_slicer_method_add (struct GNUNET_SOCIAL_Slicer *slicer,
 224                                  const char *method_name,
 225                                  GNUNET_SOCIAL_MethodCallback method_cb,
 226                                  GNUNET_SOCIAL_ModifierCallback modifier_cb,
 227                                  GNUNET_SOCIAL_DataCallback data_cb,
 228                                  GNUNET_SOCIAL_EndOfMessageCallback eom_cb,
 229                                  void *cls);
 230
 231 /**
 232  * Remove a registered method from the try-and-slice instance.
 233  *
 234  * Removes one matching handler registered with the given
 235  * @a method_name and callbacks.
 236  *
 237  * @param slicer
 238  *        The try-and-slice instance.
 239  * @param method_name
 240  *        Name of the method to remove.
 241  * @param method_cb
 242  *        Method handler.
 243  * @param modifier_cb
 244  *        Modifier handler.
 245  * @param data_cb
 246  *        Data handler.
 247  * @param eom_cb
 248  *        End of message handler.
 249  *
 250  * @return #GNUNET_OK if a method handler was removed,
 251  *         #GNUNET_NO if no handler matched the given method name and callbacks.
 252  */
 253 int
 254 GNUNET_SOCIAL_slicer_method_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 255                                     const char *method_name,
 256                                     GNUNET_SOCIAL_MethodCallback method_cb,
 257                                     GNUNET_SOCIAL_ModifierCallback modifier_cb,
 258                                     GNUNET_SOCIAL_DataCallback data_cb,
 259                                     GNUNET_SOCIAL_EndOfMessageCallback eom_cb);
 260
 261
 262 /**
 263  * Watch a place for changed objects.
 264  *
 265  * @param slicer
 266  *        The try-and-slice instance.
 267  * @param object_filter
 268  *        Object prefix to match.
 269  * @param modifier_cb
 270  *        Function to call when encountering a state modifier.
 271  * @param cls
 272  *        Closure for callback.
 273  */
 274 void
 275 GNUNET_SOCIAL_slicer_modifier_add (struct GNUNET_SOCIAL_Slicer *slicer,
 276                                    const char *object_filter,
 277                                    GNUNET_SOCIAL_ModifierCallback modifier_cb,
 278                                    void *cls);
 279
 280
 281 /**
 282  * Remove a registered modifier from the try-and-slice instance.
 283  *
 284  * Removes one matching handler registered with the given
 285  * @a object_filter and callback.
 286  *
 287  * @param slicer
 288  *        The try-and-slice instance.
 289  * @param object_filter
 290  *        Object prefix to match.
 291  * @param modifier_cb
 292  *        Function to call when encountering a state modifier changes.
 293  */
 294 int
 295 GNUNET_SOCIAL_slicer_modifier_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 296                                       const char *object_filter,
 297                                       GNUNET_SOCIAL_ModifierCallback modifier_cb);
 298
 299
 300 /**
 301  * Destroy a given try-and-slice instance.
 302  *
 303  * @param slicer
 304  *        Slicer to destroy
 305  */
 306 void
 307 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
 308
 309
 310 /**
 311  * Function called asking for nym to be admitted to the place.
 312  *
 313  * Should call either GNUNET_SOCIAL_host_admit() or
 314  * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously).  If this host
 315  * cannot decide, it is fine to call neither function, in which case hopefully
 316  * some other host of the place exists that will make the decision.  The @a nym
 317  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
 318  * for it.
 319  *
 320  * @param cls Closure.
 321  * @param nym Handle for the user who wants to enter.
 322  * @param method_name Method name in the entry request.
 323  * @param variable_count Number of elements in the @a variables array.
 324  * @param variables Variables present in the message.
 325  * @param data_size Number of bytes in @a data.
 326  * @param data Payload given on enter (e.g. a password).
 327  */
 328 typedef void
 329 (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
 330                                      struct GNUNET_SOCIAL_Nym *nym,
 331                                      const char *method_name,
 332                                      struct GNUNET_ENV_Environment *env,
 333                                      size_t data_size,
 334                                      const void *data);
 335
 336
 337 /**
 338  * Function called when a @a nym leaves the place.
 339  *
 340  * This is also called if the @a nym was never given permission to enter
 341  * (i.e. the @a nym stopped asking to get in).
 342  *
 343  * @param cls
 344  *        Closure.
 345  * @param nym
 346  *        Handle for the user who left.
 347  */
 348 typedef void
 349 (*GNUNET_SOCIAL_FarewellCallback) (void *cls,
 350                                    const struct GNUNET_SOCIAL_Nym *nym,
 351                                    struct GNUNET_ENV_Environment *env);
 352
 353
 354 /**
 355  * Function called after the host entered the place.
 356  *
 357  * @param cls
 358  *        Closure.
 359  * @param result
 360  *        #GNUNET_OK on success, or
 361  *        #GNUNET_SYSERR on error.
 362  * @param max_message_id
 363  *        Last message ID sent to the channel.
 364  *        Or 0 if no messages have been sent to the place yet.
 365  */
 366 typedef void
 367 (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result,
 368                                     uint64_t max_message_id);
 369
 370
 371 /**
 372  * Enter a place as host.
 373  *
 374  * A place is created upon first entering, and it is active until permanently
 375  * left using GNUNET_SOCIAL_host_leave().
 376  *
 377  * @param cfg
 378  *        Configuration to contact the social service.
 379  * @param ego
 380  *        Identity of the host.
 381  * @param place_key
 382  *        Private-public key pair of the place.
 383  *        NULL for ephemeral places.
 384  * @param policy
 385  *        Policy specifying entry and history restrictions for the place.
 386  * @param slicer
 387  *        Slicer to handle incoming messages.
 388  * @param answer_door_cb
 389  *        Function to handle new nyms that want to enter.
 390  * @param farewell_cb
 391  *        Function to handle departing nyms.
 392  * @param cls
 393  *        Closure for the callbacks.
 394  *
 395  * @return Handle for the host.
 396  */
 397 struct GNUNET_SOCIAL_Host *
 398 GNUNET_SOCIAL_host_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 399                           const struct GNUNET_IDENTITY_Ego *ego,
 400                           const struct GNUNET_CRYPTO_EddsaPrivateKey *place_key,
 401                           enum GNUNET_PSYC_Policy policy,
 402                           struct GNUNET_SOCIAL_Slicer *slicer,
 403                           GNUNET_SOCIAL_HostEnterCallback enter_cb,
 404                           GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
 405                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 406                           void *cls);
 407
 408
 409 /**
 410  * Decision whether to admit @a nym into the place or refuse entry.
 411  *
 412  * @param hst
 413  *        Host of the place.
 414  * @param nym
 415  *        Handle for the entity that wanted to enter.
 416  * @param is_admitted
 417  *        #GNUNET_YES    if @a nym is admitted,
 418  *        #GNUNET_NO     if @a nym is refused entry,
 419  *        #GNUNET_SYSERR if we cannot answer the request.
 420  * @param method_name
 421  *        Method name for the rejection message.
 422  * @param env
 423  *        Environment containing variables for the message, or NULL.
 424  * @param data
 425  *        Data for the rejection message to send back.
 426  * @param data_size
 427  *        Number of bytes in @a data for method.
 428  * @return #GNUNET_OK on success,
 429  *         #GNUNET_SYSERR if the message is too large.
 430  */
 431 int
 432 GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst,
 433                                    struct GNUNET_SOCIAL_Nym *nym,
 434                                    int is_admitted,
 435                                    const struct GNUNET_PSYC_Message *entry_resp);
 436
 437
 438 /**
 439  * Throw @a nym out of the place.
 440  *
 441  * The @a nym reference will remain valid until the
 442  * #GNUNET_SOCIAL_FarewellCallback is invoked,
 443  * which should be very soon after this call.
 444  *
 445  * @param host
 446  *        Host of the place.
 447  * @param nym
 448  *        Handle for the entity to be ejected.
 449  */
 450 void
 451 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
 452                           const struct GNUNET_SOCIAL_Nym *nym);
 453
 454
 455 /**
 456  * Get the public key of a @a nym.
 457  *
 458  * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
 459  *
 460  * @param nym
 461  *        Pseudonym to map to a cryptographic identifier.
 462  *
 463  * @return Public key of nym.
 464  */
 465 const struct GNUNET_CRYPTO_EcdsaPublicKey *
 466 GNUNET_SOCIAL_nym_get_key (const struct GNUNET_SOCIAL_Nym *nym);
 467
 468
 469 /**
 470  * Get the hash of the public key of a @a nym.
 471  *
 472  * @param nym
 473  *        Pseudonym to map to a cryptographic identifier.
 474  *
 475  * @return Hash of the public key of nym.
 476  */
 477 const struct GNUNET_HashCode *
 478 GNUNET_SOCIAL_nym_get_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
 479
 480
 481 /**
 482  * Advertise the place in the GNS zone of the @e ego of the @a host.
 483  *
 484  * @param hst
 485  *        Host of the place.
 486  * @param name
 487  *        The name for the PLACE record to put in the zone.
 488  * @param peer_count
 489  *        Number of elements in the @a peers array.
 490  * @param peers
 491  *        List of peers to put in the PLACE record to advertise
 492  *        as entry points to the place in addition to the origin.
 493  * @param expiration_time
 494  *        Expiration time of the record, use 0 to remove the record.
 495  * @param password
 496  *        Password used to encrypt the record.
 497  * @param result_cb
 498  *        Function called with the result of the operation.
 499  * @param result_cls
 500  *        Closure for @a result_cb
 501  */
 502 void
 503 GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host,
 504                               const char *name,
 505                               size_t peer_count,
 506                               const struct GNUNET_PeerIdentity *peers,
 507                               struct GNUNET_TIME_Relative expiration_time,
 508                               const char *password,
 509                               GNUNET_NAMESTORE_ContinuationWithStatus result_cb,
 510                               void *result_cls);
 511
 512
 513 /**
 514  * Flags for announcements by a host.
 515  */
 516 enum GNUNET_SOCIAL_AnnounceFlags
 517 {
 518   GNUNET_SOCIAL_ANNOUNCE_NONE = 0,
 519
 520   /**
 521    * Whether this announcement removes all objects from the place.
 522    *
 523    * New objects can be still added to the now empty place using the @e env
 524    * parameter of the same announcement.
 525    */
 526   GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0
 527 };
 528
 529
 530 /**
 531  * Handle for an announcement request.
 532  */
 533 struct GNUNET_SOCIAL_Announcement;
 534
 535
 536 /**
 537  * Send a message to all nyms that are present in the place.
 538  *
 539  * This function is restricted to the host.  Nyms can only send requests
 540  * to the host who can decide to relay it to everyone in the place.
 541  *
 542  * @param host
 543  *        Host of the place.
 544  * @param method_name
 545  *        Method to use for the announcement.
 546  * @param env
 547  *        Environment containing variables for the message and operations
 548  *        on objects of the place.
 549  *        Has to remain available until the first call to @a notify_data.
 550  *        Can be NULL.
 551  * @param notify_data
 552  *        Function to call to get the payload of the announcement.
 553  * @param notify_data_cls
 554  *        Closure for @a notify.
 555  * @param flags
 556  *        Flags for this announcement.
 557  *
 558  * @return NULL on error (another announcement already in progress?).
 559  */
 560 struct GNUNET_SOCIAL_Announcement *
 561 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
 562                              const char *method_name,
 563                              const struct GNUNET_ENV_Environment *env,
 564                              GNUNET_PSYC_TransmitNotifyData notify_data,
 565                              void *notify_data_cls,
 566                              enum GNUNET_SOCIAL_AnnounceFlags flags);
 567
 568
 569 /**
 570  * Resume transmitting announcement.
 571  *
 572  * @param a
 573  *        The announcement to resume.
 574  */
 575 void
 576 GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a);
 577
 578
 579 /**
 580  * Cancel announcement.
 581  *
 582  * @param a
 583  *        The announcement to cancel.
 584  */
 585 void
 586 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 587
 588
 589 /**
 590  * Obtain handle for a hosted place.
 591  *
 592  * The returned handle can be used to access the place API.
 593  *
 594  * @param host
 595  *        Handle for the host.
 596  *
 597  * @return Handle for the hosted place, valid as long as @a host is valid.
 598  */
 599 struct GNUNET_SOCIAL_Place *
 600 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host);
 601
 602
 603 /**
 604  * Stop hosting a place.
 605  *
 606  * Invalidates host handle.
 607  *
 608  * @param host
 609  *        Host leaving the place.
 610  * @param keep_active
 611  *        Keep the place active after last host disconnected.
 612  * @param leave_cb
 613  *        Function called after the host left the place
 614  *        and disconnected from the social service.
 615  * @param leave_cls
 616  *        Closure for @a leave_cb.
 617  */
 618 void
 619 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host,
 620                           int keep_active,
 621                           GNUNET_ContinuationCallback leave_cb,
 622                           void *leave_cls);
 623
 624
 625 /**
 626  * Function called after the guest entered the local copy of the place.
 627  *
 628  * History and object query functions can be used after this call,
 629  * but new messages can't be sent or received.
 630  *
 631  * @param cls
 632  *        Closure.
 633  * @param result
 634  *        #GNUNET_OK on success, or
 635  *        #GNUNET_SYSERR on error, e.g. could not connect to the service, or
 636  *        could not resolve GNS name.
 637  * @param max_message_id
 638  *        Last message ID sent to the place.
 639  *        Or 0 if no messages have been sent to the place yet.
 640  */
 641 typedef void
 642 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
 643                                      uint64_t max_message_id);
 644
 645
 646 /**
 647  * Function called upon a guest receives a decision about entry to the place.
 648  *
 649  * @param is_admitted
 650  *   Is the guest admitted to the place?
 651  *   #GNUNET_YES    if admitted,
 652  *   #GNUNET_NO     if refused entry
 653  *   #GNUNET_SYSERR if the request could not be answered.
 654  * @param method_name
 655  *   Method for the message sent along with the decision.
 656  *   NULL if no message was sent.
 657  * @param env
 658  *   Environment with variables for the message.
 659  *   NULL if there are no variables.
 660  *   It has to be freed using GNUNET_ENV_environment_destroy()
 661  *   when it is not needed anymore.
 662  * @param data_size
 663  *   Size of @data.
 664  * @param data
 665  *   Payload of the message.
 666  */
 667 typedef void
 668 (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls,
 669                                         int is_admitted,
 670                                         const struct GNUNET_PSYC_Message *entry_resp);
 671
 672
 673 /**
 674  * Request entry to a place as a guest.
 675  *
 676  * @param cfg Configuration to contact the social service.
 677  * @param ego  Identity of the guest.
 678  * @param crypto_address Public key of the place to enter.
 679  * @param origin Peer identity of the origin of the underlying multicast group.
 680  * @param relay_count Number of elements in the @a relays array.
 681  * @param relays Relays for the underlying multicast group.
 682  * @param method_name Method name for the message.
 683  * @param env Environment containing variables for the message, or NULL.
 684  * @param data Payload for the message to give to the enter callback.
 685  * @param data_size Number of bytes in @a data.
 686  * @param slicer Slicer to use for processing incoming requests from guests.
 687  *
 688  * @return NULL on errors, otherwise handle for the guest.
 689  */
 690 struct GNUNET_SOCIAL_Guest *
 691 GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 692                            const struct GNUNET_IDENTITY_Ego *ego,
 693                            const struct GNUNET_CRYPTO_EddsaPublicKey *place_key,
 694                            const struct GNUNET_PeerIdentity *origin,
 695                            uint32_t relay_count,
 696                            const struct GNUNET_PeerIdentity *relays,
 697                            const struct GNUNET_PSYC_Message *entry_msg,
 698                            struct GNUNET_SOCIAL_Slicer *slicer,
 699                            GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
 700                            GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
 701                            void *cls);
 702
 703
 704 /**
 705  * Request entry to a place as a guest using a GNS name.
 706  *
 707  * @param cfg  Configuration to contact the social service.
 708  * @param ego  Identity of the guest.
 709  * @param address GNS name of the place to enter.  Either in the form of
 710  *        'room.friend.gnu', or 'NYMPUBKEY.zkey'.  This latter case refers to
 711  *        the 'PLACE' record of the empty label ("+") in the GNS zone with the
 712  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
 713  *        pseudonym's place directly.
 714  * @param method_name Method name for the message.
 715  * @param env Environment containing variables for the message, or NULL.
 716  * @param data Payload for the message to give to the enter callback.
 717  * @param data_size Number of bytes in @a data.
 718  * @param slicer Slicer to use for processing incoming requests from guests.
 719  *
 720  * @return NULL on errors, otherwise handle for the guest.
 721  */
 722 struct GNUNET_SOCIAL_Guest *
 723 GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_CONFIGURATION_Handle *cfg,
 724                                    struct GNUNET_IDENTITY_Ego *ego,
 725                                    char *gns_name,
 726                                    const struct GNUNET_PSYC_Message *join_msg,
 727                                    struct GNUNET_SOCIAL_Slicer *slicer,
 728                                    GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
 729                                    GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
 730                                    void *cls);
 731
 732
 733 /**
 734  * Flags for talking to the host of a place.
 735  */
 736 enum GNUNET_SOCIAL_TalkFlags
 737 {
 738   GNUNET_SOCIAL_TALK_NONE = 0
 739 };
 740
 741
 742 /**
 743  * A talk request.
 744  */
 745 struct GNUNET_SOCIAL_TalkRequest;
 746
 747
 748 /**
 749  * Talk to the host of the place.
 750  *
 751  * @param place
 752  *        Place where we want to talk to the host.
 753  * @param method_name
 754  *        Method to invoke on the host.
 755  * @param env
 756  *        Environment containing variables for the message, or NULL.
 757  * @param notify_data
 758  *        Function to use to get the payload for the method.
 759  * @param notify_data_cls
 760  *        Closure for @a notify_data.
 761  * @param flags
 762  *        Flags for the message being sent.
 763  *
 764  * @return NULL if we are already trying to talk to the host,
 765  *         otherwise handle to cancel the request.
 766  */
 767 struct GNUNET_SOCIAL_TalkRequest *
 768 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest,
 769                           const char *method_name,
 770                           const struct GNUNET_ENV_Environment *env,
 771                           GNUNET_PSYC_TransmitNotifyData notify_data,
 772                           void *notify_data_cls,
 773                           enum GNUNET_SOCIAL_TalkFlags flags);
 774
 775
 776 /**
 777  * Resume talking to the host of the place.
 778  *
 779  * @param tr
 780  *        Talk request to resume.
 781  */
 782 void
 783 GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr);
 784
 785
 786 /**
 787  * Cancel talking to the host of the place.
 788  *
 789  * @param tr
 790  *        Talk request to cancel.
 791  */
 792 void
 793 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 794
 795
 796 /**
 797  * Leave a place temporarily or permanently.
 798  *
 799  * Notifies the owner of the place about leaving, and destroys the place handle.
 800  *
 801  * @param place
 802  *        Place to leave.
 803  * @param keep_active
 804  *        Keep place active after last application disconnected.
 805  *        #GNUNET_YES or #GNUNET_NO
 806  * @param env
 807  *        Optional environment for the leave message if @a keep_active
 808  *        is #GNUNET_NO.  NULL if not needed.
 809  * @param leave_cb
 810  *        Called upon disconnecting from the social service.
 811  */
 812 void
 813 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst,
 814                            int keep_active,
 815                            struct GNUNET_ENV_Environment *env,
 816                            GNUNET_ContinuationCallback leave_cb,
 817                            void *leave_cls);
 818
 819
 820 /**
 821  * Obtain handle for a place entered as guest.
 822  *
 823  * The returned handle can be used to access the place API.
 824  *
 825  * @param guest  Handle for the guest.
 826  *
 827  * @return Handle for the place, valid as long as @a guest is valid.
 828  */
 829 struct GNUNET_SOCIAL_Place *
 830 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
 831
 832
 833 /**
 834  * A history request.
 835  */
 836 struct GNUNET_SOCIAL_HistoryRequest;
 837
 838
 839 /**
 840  * Learn about the history of a place.
 841  *
 842  * Messages are returned through the @a slicer function
 843  * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 844  *
 845  * @param place
 846  *        Place we want to learn more about.
 847  * @param start_message_id
 848  *        First historic message we are interested in.
 849  * @param end_message_id
 850  *        Last historic message we are interested in (inclusive).
 851  * @param method_prefix
 852  *        Only retrieve messages with this method prefix.
 853  * @param flags
 854  *        OR'ed GNUNET_PSYC_HistoryReplayFlags
 855  * @param slicer
 856  *        Slicer to use for retrieved messages.
 857  *        Can be the same as the slicer of the place.
 858  * @param result_cb
 859  *        Function called after all messages retrieved.
 860  *        NULL if not needed.
 861  * @param cls Closure for @a result_cb.
 862  */
 863 struct GNUNET_SOCIAL_HistoryRequest *
 864 GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
 865                                     uint64_t start_message_id,
 866                                     uint64_t end_message_id,
 867                                     const char *method_prefix,
 868                                     uint32_t flags,
 869                                     struct GNUNET_SOCIAL_Slicer *slicer,
 870                                     GNUNET_ResultCallback result_cb,
 871                                     void *cls);
 872
 873
 874 /**
 875  * Learn about the history of a place.
 876  *
 877  * Sends messages through the slicer function of the place where
 878  * start_message_id <= message_id <= end_message_id.
 879  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 880  *
 881  * To get the latest message, use 0 for both the start and end message ID.
 882  *
 883  * @param place
 884  *        Place we want to learn more about.
 885  * @param message_limit
 886  *        Maximum number of historic messages we are interested in.
 887  * @param result_cb
 888  *        Function called after all messages retrieved.
 889  *        NULL if not needed.
 890  * @param cls Closure for @a result_cb.
 891  */
 892 struct GNUNET_SOCIAL_HistoryRequest *
 893 GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
 894                                            uint64_t message_limit,
 895                                            const char *method_prefix,
 896                                            uint32_t flags,
 897                                            struct GNUNET_SOCIAL_Slicer *slicer,
 898                                            GNUNET_ResultCallback result_cb,
 899                                            void *cls);
 900
 901 /**
 902  * Cancel learning about the history of a place.
 903  *
 904  * @param hist
 905  *        History lesson to cancel.
 906  */
 907 void
 908 GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
 909
 910
 911 struct GNUNET_SOCIAL_LookHandle;
 912
 913
 914 /**
 915  * Look at a particular object in the place.
 916  *
 917  * The best matching object is returned (its name might be less specific than
 918  * what was requested).
 919  *
 920  * @param place
 921  *        The place to look the object at.
 922  * @param full_name
 923  *        Full name of the object.
 924  * @param value_size
 925  *        Set to the size of the returned value.
 926  *
 927  * @return NULL if there is no such object at this place.
 928  */
 929 struct GNUNET_SOCIAL_LookHandle *
 930 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
 931                              const char *full_name,
 932                              GNUNET_PSYC_StateVarCallback var_cb,
 933                              GNUNET_ResultCallback result_cb,
 934                              void *cls);
 935
 936 /**
 937  * Look for objects in the place with a matching name prefix.
 938  *
 939  * @param place
 940  *        The place to look its objects at.
 941  * @param name_prefix
 942  *        Look at objects with names beginning with this value.
 943  * @param var_cb
 944  *        Function to call for each object found.
 945  * @param cls
 946  *        Closure for callback function.
 947  *
 948  * @return Handle that can be used to stop looking at objects.
 949  */
 950 struct GNUNET_SOCIAL_LookHandle *
 951 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
 952                               const char *name_prefix,
 953                               GNUNET_PSYC_StateVarCallback var_cb,
 954                               GNUNET_ResultCallback result_cb,
 955                               void *cls);
 956
 957
 958 /**
 959  * Stop looking at objects.
 960  *
 961  * @param lh Look handle to stop.
 962  */
 963 void
 964 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 965
 966
 967 #if 0                           /* keep Emacsens' auto-indent happy */
 968 {
 969 #endif
 970 #ifdef __cplusplus
 971 }
 972 #endif
 973
 974 /* ifndef GNUNET_SOCIAL_SERVICE_H */
 975 #endif
 976 /* end of gnunet_social_service.h */