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