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