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  *        FIXME: not implemented yet.
 498  * @param result_cb
 499  *        Function called with the result of the operation.
 500  * @param result_cls
 501  *        Closure for @a result_cb
 502  */
 503 void
 504 GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host,
 505                               const char *name,
 506                               uint32_t peer_count,
 507                               const struct GNUNET_PeerIdentity *peers,
 508                               struct GNUNET_TIME_Absolute expiration_time,
 509                               const char *password,
 510                               GNUNET_NAMESTORE_ContinuationWithStatus result_cb,
 511                               void *result_cls);
 512
 513
 514 /**
 515  * Flags for announcements by a host.
 516  */
 517 enum GNUNET_SOCIAL_AnnounceFlags
 518 {
 519   GNUNET_SOCIAL_ANNOUNCE_NONE = 0,
 520
 521   /**
 522    * Whether this announcement removes all objects from the place.
 523    *
 524    * New objects can be still added to the now empty place using the @e env
 525    * parameter of the same announcement.
 526    */
 527   GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0
 528 };
 529
 530
 531 /**
 532  * Handle for an announcement request.
 533  */
 534 struct GNUNET_SOCIAL_Announcement;
 535
 536
 537 /**
 538  * Send a message to all nyms that are present in the place.
 539  *
 540  * This function is restricted to the host.  Nyms can only send requests
 541  * to the host who can decide to relay it to everyone in the place.
 542  *
 543  * @param host
 544  *        Host of the place.
 545  * @param method_name
 546  *        Method to use for the announcement.
 547  * @param env
 548  *        Environment containing variables for the message and operations
 549  *        on objects of the place.
 550  *        Has to remain available until the first call to @a notify_data.
 551  *        Can be NULL.
 552  * @param notify_data
 553  *        Function to call to get the payload of the announcement.
 554  * @param notify_data_cls
 555  *        Closure for @a notify.
 556  * @param flags
 557  *        Flags for this announcement.
 558  *
 559  * @return NULL on error (another announcement already in progress?).
 560  */
 561 struct GNUNET_SOCIAL_Announcement *
 562 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
 563                              const char *method_name,
 564                              const struct GNUNET_ENV_Environment *env,
 565                              GNUNET_PSYC_TransmitNotifyData notify_data,
 566                              void *notify_data_cls,
 567                              enum GNUNET_SOCIAL_AnnounceFlags flags);
 568
 569
 570 /**
 571  * Resume transmitting announcement.
 572  *
 573  * @param a
 574  *        The announcement to resume.
 575  */
 576 void
 577 GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a);
 578
 579
 580 /**
 581  * Cancel announcement.
 582  *
 583  * @param a
 584  *        The announcement to cancel.
 585  */
 586 void
 587 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 588
 589
 590 /**
 591  * Obtain handle for a hosted place.
 592  *
 593  * The returned handle can be used to access the place API.
 594  *
 595  * @param host
 596  *        Handle for the host.
 597  *
 598  * @return Handle for the hosted place, valid as long as @a host is valid.
 599  */
 600 struct GNUNET_SOCIAL_Place *
 601 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host);
 602
 603
 604 /**
 605  * Stop hosting a place.
 606  *
 607  * Invalidates host handle.
 608  *
 609  * @param host
 610  *        Host leaving the place.
 611  * @param keep_active
 612  *        Keep the place active after last host disconnected.
 613  * @param leave_cb
 614  *        Function called after the host left the place
 615  *        and disconnected from the social service.
 616  * @param leave_cls
 617  *        Closure for @a leave_cb.
 618  */
 619 void
 620 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host,
 621                           int keep_active,
 622                           GNUNET_ContinuationCallback leave_cb,
 623                           void *leave_cls);
 624
 625
 626 /**
 627  * Function called after the guest entered the local copy of the place.
 628  *
 629  * History and object query functions can be used after this call,
 630  * but new messages can't be sent or received.
 631  *
 632  * @param cls
 633  *        Closure.
 634  * @param result
 635  *        #GNUNET_OK on success, or
 636  *        #GNUNET_SYSERR on error, e.g. could not connect to the service, or
 637  *        could not resolve GNS name.
 638  * @param max_message_id
 639  *        Last message ID sent to the place.
 640  *        Or 0 if no messages have been sent to the place yet.
 641  */
 642 typedef void
 643 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
 644                                      uint64_t max_message_id);
 645
 646
 647 /**
 648  * Function called upon a guest receives a decision about entry to the place.
 649  *
 650  * @param is_admitted
 651  *   Is the guest admitted to the place?
 652  *   #GNUNET_YES    if admitted,
 653  *   #GNUNET_NO     if refused entry
 654  *   #GNUNET_SYSERR if the request could not be answered.
 655  * @param method_name
 656  *   Method for the message sent along with the decision.
 657  *   NULL if no message was sent.
 658  * @param env
 659  *   Environment with variables for the message.
 660  *   NULL if there are no variables.
 661  *   It has to be freed using GNUNET_ENV_environment_destroy()
 662  *   when it is not needed anymore.
 663  * @param data_size
 664  *   Size of @data.
 665  * @param data
 666  *   Payload of the message.
 667  */
 668 typedef void
 669 (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls,
 670                                         int is_admitted,
 671                                         const struct GNUNET_PSYC_Message *entry_resp);
 672
 673
 674 /**
 675  * Request entry to a place as a guest.
 676  *
 677  * @param cfg Configuration to contact the social service.
 678  * @param ego  Identity of the guest.
 679  * @param crypto_address Public key of the place to enter.
 680  * @param origin Peer identity of the origin of the underlying multicast group.
 681  * @param relay_count Number of elements in the @a relays array.
 682  * @param relays Relays for the underlying multicast group.
 683  * @param method_name Method name for the message.
 684  * @param env Environment containing variables for the message, or NULL.
 685  * @param data Payload for the message to give to the enter callback.
 686  * @param data_size Number of bytes in @a data.
 687  * @param slicer Slicer to use for processing incoming requests from guests.
 688  *
 689  * @return NULL on errors, otherwise handle for the guest.
 690  */
 691 struct GNUNET_SOCIAL_Guest *
 692 GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 693                            const struct GNUNET_IDENTITY_Ego *ego,
 694                            const struct GNUNET_CRYPTO_EddsaPublicKey *place_key,
 695                            const struct GNUNET_PeerIdentity *origin,
 696                            uint32_t relay_count,
 697                            const struct GNUNET_PeerIdentity *relays,
 698                            const struct GNUNET_PSYC_Message *entry_msg,
 699                            struct GNUNET_SOCIAL_Slicer *slicer,
 700                            GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
 701                            GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
 702                            void *cls);
 703
 704
 705 /**
 706  * Request entry to a place by name as a guest.
 707  *
 708  * @param cfg
 709  *        Configuration to contact the social service.
 710  * @param ego
 711  *        Identity of the guest.
 712  * @param gns_name
 713  *        GNS name of the place to enter.  Either in the form of
 714  *        'room.friend.gnu', or 'NYMPUBKEY.zkey'.  This latter case refers to
 715  *        the 'PLACE' record of the empty label ("+") in the GNS zone with the
 716  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
 717  *        pseudonym's place directly.
 718  * @param password
 719  *        Password to decrypt the record, or NULL for cleartext records.
 720  * @param join_msg
 721  *        Entry request message.
 722  * @param slicer
 723  *        Slicer to use for processing incoming requests from guests.
 724  * @param local_enter_cb
 725  *        Called upon connection established to the social service.
 726  * @param entry_decision_cb
 727  *        Called upon receiving entry decision.
 728  *
 729  * @return NULL on errors, otherwise handle for the guest.
 730  */
 731 struct GNUNET_SOCIAL_Guest *
 732 GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_CONFIGURATION_Handle *cfg,
 733                                    const struct GNUNET_IDENTITY_Ego *ego,
 734                                    const char *gns_name, const char *password,
 735                                    const struct GNUNET_PSYC_Message *join_msg,
 736                                    struct GNUNET_SOCIAL_Slicer *slicer,
 737                                    GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
 738                                    GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
 739                                    void *cls);
 740
 741
 742 /**
 743  * Flags for talking to the host of a place.
 744  */
 745 enum GNUNET_SOCIAL_TalkFlags
 746 {
 747   GNUNET_SOCIAL_TALK_NONE = 0
 748 };
 749
 750
 751 /**
 752  * A talk request.
 753  */
 754 struct GNUNET_SOCIAL_TalkRequest;
 755
 756
 757 /**
 758  * Talk to the host of the place.
 759  *
 760  * @param place
 761  *        Place where we want to talk to the host.
 762  * @param method_name
 763  *        Method to invoke on the host.
 764  * @param env
 765  *        Environment containing variables for the message, or NULL.
 766  * @param notify_data
 767  *        Function to use to get the payload for the method.
 768  * @param notify_data_cls
 769  *        Closure for @a notify_data.
 770  * @param flags
 771  *        Flags for the message being sent.
 772  *
 773  * @return NULL if we are already trying to talk to the host,
 774  *         otherwise handle to cancel the request.
 775  */
 776 struct GNUNET_SOCIAL_TalkRequest *
 777 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest,
 778                           const char *method_name,
 779                           const struct GNUNET_ENV_Environment *env,
 780                           GNUNET_PSYC_TransmitNotifyData notify_data,
 781                           void *notify_data_cls,
 782                           enum GNUNET_SOCIAL_TalkFlags flags);
 783
 784
 785 /**
 786  * Resume talking to the host of the place.
 787  *
 788  * @param tr
 789  *        Talk request to resume.
 790  */
 791 void
 792 GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr);
 793
 794
 795 /**
 796  * Cancel talking to the host of the place.
 797  *
 798  * @param tr
 799  *        Talk request to cancel.
 800  */
 801 void
 802 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 803
 804
 805 /**
 806  * Leave a place temporarily or permanently.
 807  *
 808  * Notifies the owner of the place about leaving, and destroys the place handle.
 809  *
 810  * @param place
 811  *        Place to leave.
 812  * @param keep_active
 813  *        Keep place active after last application disconnected.
 814  *        #GNUNET_YES or #GNUNET_NO
 815  * @param env
 816  *        Optional environment for the leave message if @a keep_active
 817  *        is #GNUNET_NO.  NULL if not needed.
 818  * @param leave_cb
 819  *        Called upon disconnecting from the social service.
 820  */
 821 void
 822 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst,
 823                            int keep_active,
 824                            struct GNUNET_ENV_Environment *env,
 825                            GNUNET_ContinuationCallback leave_cb,
 826                            void *leave_cls);
 827
 828
 829 /**
 830  * Obtain handle for a place entered as guest.
 831  *
 832  * The returned handle can be used to access the place API.
 833  *
 834  * @param guest  Handle for the guest.
 835  *
 836  * @return Handle for the place, valid as long as @a guest is valid.
 837  */
 838 struct GNUNET_SOCIAL_Place *
 839 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
 840
 841
 842 /**
 843  * A history request.
 844  */
 845 struct GNUNET_SOCIAL_HistoryRequest;
 846
 847
 848 /**
 849  * Learn about the history of a place.
 850  *
 851  * Messages are returned through the @a slicer function
 852  * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 853  *
 854  * @param place
 855  *        Place we want to learn more about.
 856  * @param start_message_id
 857  *        First historic message we are interested in.
 858  * @param end_message_id
 859  *        Last historic message we are interested in (inclusive).
 860  * @param method_prefix
 861  *        Only retrieve messages with this method prefix.
 862  * @param flags
 863  *        OR'ed GNUNET_PSYC_HistoryReplayFlags
 864  * @param slicer
 865  *        Slicer to use for retrieved messages.
 866  *        Can be the same as the slicer of the place.
 867  * @param result_cb
 868  *        Function called after all messages retrieved.
 869  *        NULL if not needed.
 870  * @param cls Closure for @a result_cb.
 871  */
 872 struct GNUNET_SOCIAL_HistoryRequest *
 873 GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
 874                                     uint64_t start_message_id,
 875                                     uint64_t end_message_id,
 876                                     const char *method_prefix,
 877                                     uint32_t flags,
 878                                     struct GNUNET_SOCIAL_Slicer *slicer,
 879                                     GNUNET_ResultCallback result_cb,
 880                                     void *cls);
 881
 882
 883 /**
 884  * Learn about the history of a place.
 885  *
 886  * Sends messages through the slicer function of the place where
 887  * start_message_id <= message_id <= end_message_id.
 888  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 889  *
 890  * To get the latest message, use 0 for both the start and end message ID.
 891  *
 892  * @param place
 893  *        Place we want to learn more about.
 894  * @param message_limit
 895  *        Maximum number of historic messages we are interested in.
 896  * @param result_cb
 897  *        Function called after all messages retrieved.
 898  *        NULL if not needed.
 899  * @param cls Closure for @a result_cb.
 900  */
 901 struct GNUNET_SOCIAL_HistoryRequest *
 902 GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
 903                                            uint64_t message_limit,
 904                                            const char *method_prefix,
 905                                            uint32_t flags,
 906                                            struct GNUNET_SOCIAL_Slicer *slicer,
 907                                            GNUNET_ResultCallback result_cb,
 908                                            void *cls);
 909
 910 /**
 911  * Cancel learning about the history of a place.
 912  *
 913  * @param hist
 914  *        History lesson to cancel.
 915  */
 916 void
 917 GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
 918
 919
 920 struct GNUNET_SOCIAL_LookHandle;
 921
 922
 923 /**
 924  * Look at a particular object in the place.
 925  *
 926  * The best matching object is returned (its name might be less specific than
 927  * what was requested).
 928  *
 929  * @param place
 930  *        The place to look the object at.
 931  * @param full_name
 932  *        Full name of the object.
 933  * @param value_size
 934  *        Set to the size of the returned value.
 935  *
 936  * @return NULL if there is no such object at this place.
 937  */
 938 struct GNUNET_SOCIAL_LookHandle *
 939 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
 940                              const char *full_name,
 941                              GNUNET_PSYC_StateVarCallback var_cb,
 942                              GNUNET_ResultCallback result_cb,
 943                              void *cls);
 944
 945 /**
 946  * Look for objects in the place with a matching name prefix.
 947  *
 948  * @param place
 949  *        The place to look its objects at.
 950  * @param name_prefix
 951  *        Look at objects with names beginning with this value.
 952  * @param var_cb
 953  *        Function to call for each object found.
 954  * @param cls
 955  *        Closure for callback function.
 956  *
 957  * @return Handle that can be used to stop looking at objects.
 958  */
 959 struct GNUNET_SOCIAL_LookHandle *
 960 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
 961                               const char *name_prefix,
 962                               GNUNET_PSYC_StateVarCallback var_cb,
 963                               GNUNET_ResultCallback result_cb,
 964                               void *cls);
 965
 966
 967 /**
 968  * Stop looking at objects.
 969  *
 970  * @param lh Look handle to stop.
 971  */
 972 void
 973 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 974
 975
 976 /**
 977  * Add public key to the GNS zone of the @e ego.
 978  *
 979  * @param cfg
 980  *        Configuration.
 981  * @param ego
 982  *        Ego.
 983  * @param name
 984  *        The name for the PKEY record to put in the zone.
 985  * @param pub_key
 986  *        Public key to add.
 987  * @param expiration_time
 988  *        Expiration time of the record, use 0 to remove the record.
 989  * @param result_cb
 990  *        Function called with the result of the operation.
 991  * @param result_cls
 992  *        Closure for @a result_cb
 993  */
 994 void
 995 GNUNET_SOCIAL_zone_add_pkey (const struct GNUNET_CONFIGURATION_Handle *cfg,
 996                              const struct GNUNET_IDENTITY_Ego *ego,
 997                              const char *name,
 998                              const struct GNUNET_CRYPTO_EcdsaPublicKey *pub_key,
 999                              struct GNUNET_TIME_Absolute expiration_time,
1000                              GNUNET_NAMESTORE_ContinuationWithStatus result_cb,
1001                              void *result_cls);
1002
1003
1004 #if 0                           /* keep Emacsens' auto-indent happy */
1005 {
1006 #endif
1007 #ifdef __cplusplus
1008 }
1009 #endif
1010
1011 /* ifndef GNUNET_SOCIAL_SERVICE_H */
1012 #endif
1013 /* end of gnunet_social_service.h */