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  * @author Gabor X Toth
  23  * @author Christian Grothoff
  24  *
  25  * @file
  26  * Social service; implements social interactions through the PSYC service.
  27  */
  28
  29 /** @defgroup social Social service
  30 Social interactions through the PSYC service.
  31
  32 # Overview
  33
  34 The social service provides an API for social interactions based on a one-to-many messaging model.
  35 It manages subscriptions of applications to places, provides messaging functionality in places,
  36 allows access to the local message history and manages the GNS zone of _egos_ (user identities).
  37
  38 The service stores private and public keys of subscribed places, as well as files received in subscribed places.
  39
  40 # Concepts and terminology
  41
  42 ## Ego, Nym
  43
  44 An _ego_ is an identity of a user, a private-public key pair.
  45 A _nym_ is an identity of another user in the network, identified by its public key.
  46 Each user can have multiple identities.
  47
  48 struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities.
  49
  50 ## Place, Host, Guest
  51
  52 A _place_ is where social interactions happen.  It is owned and created by an _ego_.
  53 Creating a new place happens by an _ego_ entering a new place as a _host_,
  54 where _guests_ can enter later to receive messages sent to the place.
  55
  56 A place is identified by its public key.
  57
  58 - struct GNUNET_SOCIAL_Host represents a place entered as host,
  59 - struct GNUNET_SOCIAL_Guest is used for a place entered as guest.
  60 - A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place
  61   using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place()
  62   and can be used with API functions common to hosts and guests.
  63
  64 ## History
  65
  66 Messages sent to places are stored locally by the PSYCstore service, and can be queried any time.
  67 GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place,
  68 while GNUNET_SOCIAL_history_replay() is used to query a given message ID range.
  69
  70 ## GNU Name System
  71
  72 The GNU Name System is used for assigning human-readable names to nyms and places.
  73 There's a _GNS zone_ corresponding to each _nym_.
  74 An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively.
  75
  76 ## Announcement, talk request
  77
  78 The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce().
  79 Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk().
  80 The host receives talk requests of guests and can _relay_ them to the place,
  81 or process it using a message handler function.
  82
  83 # Using the API
  84
  85 ## Connecting to the service
  86
  87 A client first establishes an _application connection_ to the service using
  88 GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
  89 public keys of subscribed places and available egos and in response.
  90
  91 ## Reconnecting to places
  92
  93 Then the application can reconnect to its subscribed places by establishing
  94 _place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and
  95 GNUNET_SOCIAL_guest_enter_reconnect().
  96
  97 ## Subscribing to a place
  98
  99 Entering and subscribing a new host or guest place is done using
 100 GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter().
 101
 102 ## Disconnecting from a place
 103
 104 An application can disconnect from a place while the social service keeps its
 105 network connection active, using GNUNET_SOCIAL_host_disconnect() and
 106 GNUNET_SOCIAL_guest_disconnect().
 107
 108 ## Leaving a place
 109
 110 To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave().
 111 When leaving a place its network connections are closed and all applications are unsubscribed from the place.
 112
 113 # Methods
 114
 115 ## _message
 116
 117 A message sent to the place.
 118
 119 ### Environment
 120
 121 #### _id_reply_to
 122 message ID this message is in reply to.
 123
 124 #### _id_thread
 125
 126 thread ID, the first message ID in the thread.
 127
 128 #### _nym_author__
 129 nym of the author.
 130
 131 #### _sig_author
 132 signature of the message body and its variables by the author.
 133
 134 ## Data
 135
 136 Message body.
 137
 138 ## _notice_place
 139
 140 Notification about a place.
 141
 142 TODO: Applications can decide to auto-subscribe to certain places,
 143 e.g. files under a given size.
 144
 145 ### Environment
 146
 147 #### Using GNS
 148
 149 ##### _gns_place
 150 GNS name of the place in a globally unique .zkey zone
 151
 152 #### Without GNS
 153
 154 ##### _key_pub_place
 155 public key of place
 156
 157 ##### _peer_origin
 158 peer ID of origin
 159
 160 ##### _list_peer_relays
 161 list of peer IDs of relays
 162
 163 ## _notice_place_file
 164
 165 Notification about a place hosting a file.
 166
 167 ### Environment
 168
 169 The environment of _notice_place above, plus the following:
 170
 171 #### _size_file
 172 size of file
 173
 174 #### _mime_file
 175 MIME type of file
 176
 177 #### _name_file
 178 name of file
 179
 180 #### _description_file
 181 description of file
 182
 183 ## _file
 184
 185 Messages with a _file method contain a file,
 186 which is saved to disk upon receipt at the following location:
 187 $GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
 188
 189 ### Environment
 190
 191 #### _size_file
 192 size of file
 193
 194 #### _mime_file
 195 MIME type of file
 196
 197 #### _name_file
 198 name of file
 199
 200 #### _description_file
 201 description
 202
 203 @{
 204 */
 205
 206
 207 #ifndef GNUNET_SOCIAL_SERVICE_H
 208 #define GNUNET_SOCIAL_SERVICE_H
 209
 210 #ifdef __cplusplus
 211 extern "C"
 212 {
 213 #if 0                           /* keep Emacsens' auto-indent happy */
 214 }
 215 #endif
 216 #endif
 217
 218 #include <stdint.h>
 219 #include "gnunet_util_lib.h"
 220 #include "gnunet_env_lib.h"
 221 #include "gnunet_identity_service.h"
 222 #include "gnunet_namestore_service.h"
 223 #include "gnunet_psyc_service.h"
 224
 225
 226 /**
 227  * Version number of GNUnet Social API.
 228  */
 229 #define GNUNET_SOCIAL_VERSION 0x00000000
 230
 231 /**
 232  * Maximum size of client ID including '\0' terminator.
 233  */
 234 #define GNUNET_SOCIAL_APP_MAX_ID_SIZE 256
 235
 236 /**
 237  * Handle for an application.
 238  */
 239 struct GNUNET_SOCIAL_App;
 240
 241 /**
 242  * Handle for an ego (own identity)
 243  */
 244 struct GNUNET_SOCIAL_Ego;
 245
 246 /**
 247  * Handle for a pseudonym of another user in the network.
 248  */
 249 struct GNUNET_SOCIAL_Nym;
 250
 251 /**
 252  * Handle for a place where social interactions happen.
 253  */
 254 struct GNUNET_SOCIAL_Place;
 255
 256 /**
 257  * Host handle for a place that we entered.
 258  */
 259 struct GNUNET_SOCIAL_Host;
 260
 261 /**
 262  * Guest handle for place that we entered.
 263  */
 264 struct GNUNET_SOCIAL_Guest;
 265
 266 /**
 267  * Handle to an implementation of try-and-slice.
 268  */
 269 struct GNUNET_SOCIAL_Slicer;
 270
 271
 272
 273
 274 /**
 275  * Handle that can be used to reconnect to a place as host.
 276  */
 277 struct GNUNET_SOCIAL_HostConnection;
 278
 279 /**
 280  * Handle that can be used to reconnect to a place as guest.
 281  */
 282 struct GNUNET_SOCIAL_GuestConnection;
 283
 284 /**
 285  * Notification about an available identity.
 286  *
 287  * @param cls
 288  *        Closure.
 289  * @param pub_key
 290  *        Public key of ego.
 291  * @param name
 292  *        Name of ego.
 293  */
 294 typedef void
 295 (*GNUNET_SOCIAL_AppEgoCallback) (void *cls,
 296                                  struct GNUNET_SOCIAL_Ego *ego,
 297                                  const struct GNUNET_CRYPTO_EcdsaPublicKey *ego_pub_key,
 298                                  const char *name);
 299
 300
 301 /**
 302  * Entry status of a place.
 303  */
 304 enum GNUNET_SOCIAL_PlaceState
 305 {
 306   /**
 307    * Place was once entered but left since.
 308    */
 309   GNUNET_SOCIAL_PLACE_STATE_ARCHIVED = 0,
 310   /**
 311    * Place is entered but not subscribed.
 312    */
 313   GNUNET_SOCIAL_PLACE_STATE_ENTERED = 1,
 314   /**
 315    * Place is entered and subscribed.
 316    */
 317   GNUNET_SOCIAL_PLACE_STATE_SUBSCRIBED = 2,
 318 };
 319
 320
 321 /**
 322  * Notification about a home.
 323  *
 324  * @param cls
 325  *        Closure.
 326  * @param hconn
 327  *        Host connection, to be used with GNUNET_SOCIAL_host_enter_reconnect()
 328  * @param ego
 329  *        Ego used to enter the place.
 330  * @param place_pub_key
 331  *        Public key of the place.
 332  * @param place_state
 333  *        @see enum GNUNET_SOCIAL_PlaceState
 334  */
 335 typedef void
 336 (*GNUNET_SOCIAL_AppHostPlaceCallback) (void *cls,
 337                                        struct GNUNET_SOCIAL_HostConnection *hconn,
 338                                        struct GNUNET_SOCIAL_Ego *ego,
 339                                        const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
 340                                        enum GNUNET_SOCIAL_PlaceState place_state);
 341
 342 /**
 343  * Notification about a place.
 344  *
 345  * @param cls
 346  *        Closure.
 347  * @param gconn
 348  *        Guest connection, to be used with GNUNET_SOCIAL_guest_enter_reconnect()
 349  * @param ego
 350  *        Ego used to enter the place.
 351  * @param place_pub_key
 352  *        Public key of the place.
 353  * @param place_state
 354  *        @see enum GNUNET_SOCIAL_PlaceState
 355  */
 356 typedef void
 357 (*GNUNET_SOCIAL_AppGuestPlaceCallback) (void *cls,
 358                                         struct GNUNET_SOCIAL_GuestConnection *gconn,
 359                                         struct GNUNET_SOCIAL_Ego *ego,
 360                                         const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
 361                                         enum GNUNET_SOCIAL_PlaceState place_state);
 362
 363
 364 /**
 365  * Establish application connection to the social service.
 366  *
 367  * The @host_place_cb and @guest_place_cb functions are
 368  * initially called for each entered places,
 369  * then later each time a new place is entered with the current app ID.
 370  *
 371  * @param cfg
 372  *        Configuration.
 373  * @param ego_cb
 374  *        Function to notify about an available ego.
 375  * @param host_cb
 376  *        Function to notify about a place entered as host.
 377  * @param guest_cb
 378  *        Function to notify about a place entered as guest.
 379  * @param cls
 380  *        Closure for the callbacks.
 381  *
 382  * @return Handle that can be used to stop listening.
 383  */
 384 struct GNUNET_SOCIAL_App *
 385 GNUNET_SOCIAL_app_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 386                            const char *id,
 387                            GNUNET_SOCIAL_AppEgoCallback ego_cb,
 388                            GNUNET_SOCIAL_AppHostPlaceCallback host_cb,
 389                            GNUNET_SOCIAL_AppGuestPlaceCallback guest_cb,
 390                            void *cls);
 391
 392
 393 /**
 394  * Disconnect app.
 395  *
 396  * @param c
 397  *        App handle.
 398  */
 399 void
 400 GNUNET_SOCIAL_app_disconnect (struct GNUNET_SOCIAL_App *app);
 401
 402
 403 /**
 404  * Get the public key of @a ego.
 405  *
 406  * @param ego
 407  *        Ego.
 408  *
 409  * @return Public key of ego.
 410  */
 411 const struct GNUNET_CRYPTO_EcdsaPublicKey *
 412 GNUNET_SOCIAL_ego_get_pub_key (const struct GNUNET_SOCIAL_Ego *ego);
 413
 414
 415 /**
 416  * Get the name of @a ego.
 417  *
 418  * @param ego
 419  *        Ego.
 420  *
 421  * @return Public key of @a ego.
 422  */
 423 const char *
 424 GNUNET_SOCIAL_ego_get_name (const struct GNUNET_SOCIAL_Ego *ego);
 425
 426
 427 /**
 428  * Get the public key of a @a nym.
 429  *
 430  * Suitable, for example, to be used with GNUNET_SOCIAL_zone_add_nym().
 431  *
 432  * @param nym
 433  *        Pseudonym to map to a cryptographic identifier.
 434  *
 435  * @return Public key of nym.
 436  */
 437 const struct GNUNET_CRYPTO_EcdsaPublicKey *
 438 GNUNET_SOCIAL_nym_get_pub_key (const struct GNUNET_SOCIAL_Nym *nym);
 439
 440
 441 /**
 442  * Get the hash of the public key of a @a nym.
 443  *
 444  * @param nym
 445  *        Pseudonym to map to a cryptographic identifier.
 446  *
 447  * @return Hash of the public key of nym.
 448  */
 449 const struct GNUNET_HashCode *
 450 GNUNET_SOCIAL_nym_get_pub_key_hash (const struct GNUNET_SOCIAL_Nym *nym);
 451
 452
 453 /**
 454  * Function called upon receiving a message indicating a call to a @e method.
 455  *
 456  * This function is called one or more times for each message until all data
 457  * fragments arrive from the network.
 458  *
 459  * @param cls
 460  *        Closure.
 461  * @param msg
 462  *        Message part, as it arrived from the network.
 463  * @param message_id
 464  *        Message counter, monotonically increasing from 1.
 465  * @param nym
 466  *        The sender of the message.
 467  *        Can be NULL if the message is not connected to a pseudonym.
 468  * @param flags
 469  *        OR'ed GNUNET_PSYC_MessageFlags
 470  * @param method_name
 471  *        Original method name from PSYC.
 472  *        May be more specific than the registered method name due to
 473  *        try-and-slice matching.
 474  */
 475 typedef void
 476 (*GNUNET_SOCIAL_MethodCallback) (void *cls,
 477                                  const struct GNUNET_PSYC_MessageMethod *msg,
 478                                  uint64_t message_id,
 479                                  uint32_t flags,
 480                                  const struct GNUNET_SOCIAL_Nym *nym,
 481                                  const char *method_name);
 482
 483
 484 /**
 485  * Function called upon receiving a modifier of a message.
 486  *
 487  * @param cls
 488  *        Closure.
 489  * @param message_id
 490  *        Message ID this data fragment belongs to.
 491  * @param msg
 492  *        Message part, as it arrived from the network.
 493  * @param oper
 494  *        Operation to perform.
 495  *        0 in case of a modifier continuation.
 496  * @param name
 497  *        Name of the modifier.
 498  *        NULL in case of a modifier continuation.
 499  * @param value
 500  *        Value of the modifier.
 501  * @param value_size
 502  *        Size of @value.
 503  */
 504 typedef void
 505 (*GNUNET_SOCIAL_ModifierCallback) (void *cls,
 506                                    const struct GNUNET_MessageHeader *msg,
 507                                    uint64_t message_id,
 508                                    enum GNUNET_ENV_Operator oper,
 509                                    const char *name,
 510                                    const void *value,
 511                                    uint16_t value_size,
 512                                    uint16_t full_value_size);
 513
 514
 515 /**
 516  * Function called upon receiving a data fragment of a message.
 517  *
 518  * @param cls
 519  *        Closure.
 520  * @param message_id
 521  *        Message ID this data fragment belongs to.
 522  * @param msg
 523  *        Message part, as it arrived from the network.
 524  * @param data_offset
 525  *        Byte offset of @a data in the overall data of the method.
 526  * @param data_size
 527  *        Number of bytes in @a data.
 528  * @param data
 529  *        Data stream given to the method.
 530  * @param end
 531  *        End of message?
 532  *        #GNUNET_NO     if there are further fragments,
 533  *        #GNUNET_YES    if this is the last fragment,
 534  *        #GNUNET_SYSERR indicates the message was cancelled by the sender.
 535  */
 536 typedef void
 537 (*GNUNET_SOCIAL_DataCallback) (void *cls,
 538                                const struct GNUNET_MessageHeader *msg,
 539                                uint64_t message_id,
 540                                uint64_t data_offset,
 541                                const void *data,
 542                                uint16_t data_size);
 543
 544
 545 /**
 546  * End of message.
 547  *
 548  * @param cls
 549  *        Closure.
 550  * @param msg
 551  *        Message part, as it arrived from the network.
 552  * @param message_id
 553  *        Message ID this data fragment belongs to.
 554  * @param cancelled
 555  *        #GNUNET_YES if the message was cancelled,
 556  *        #GNUNET_NO  if the message is complete.
 557  */
 558 typedef void
 559 (*GNUNET_SOCIAL_EndOfMessageCallback) (void *cls,
 560                                        const struct GNUNET_MessageHeader *msg,
 561                                        uint64_t message_id,
 562                                        uint8_t cancelled);
 563
 564
 565 /**
 566  * Create a try-and-slice instance.
 567  *
 568  * A slicer processes incoming messages and notifies callbacks about matching
 569  * methods or modifiers encountered.
 570  *
 571  * @return A new try-and-slice construct.
 572  */
 573 struct GNUNET_SOCIAL_Slicer *
 574 GNUNET_SOCIAL_slicer_create (void);
 575
 576
 577 /**
 578  * Add a method to the try-and-slice instance.
 579  *
 580  * The callbacks are called for messages with a matching @a method_name prefix.
 581  *
 582  * @param slicer
 583  *        The try-and-slice instance to extend.
 584  * @param method_name
 585  *        Name of the given method, use empty string to match all.
 586  * @param method_cb
 587  *        Method handler invoked upon a matching message.
 588  * @param modifier_cb
 589  *        Modifier handler, invoked after @a method_cb
 590  *        for each modifier in the message.
 591  * @param data_cb
 592  *        Data handler, invoked after @a modifier_cb for each data fragment.
 593  * @param eom_cb
 594  *        Invoked upon reaching the end of a matching message.
 595  * @param cls
 596  *        Closure for the callbacks.
 597  */
 598 void
 599 GNUNET_SOCIAL_slicer_method_add (struct GNUNET_SOCIAL_Slicer *slicer,
 600                                  const char *method_name,
 601                                  GNUNET_SOCIAL_MethodCallback method_cb,
 602                                  GNUNET_SOCIAL_ModifierCallback modifier_cb,
 603                                  GNUNET_SOCIAL_DataCallback data_cb,
 604                                  GNUNET_SOCIAL_EndOfMessageCallback eom_cb,
 605                                  void *cls);
 606
 607 /**
 608  * Remove a registered method from the try-and-slice instance.
 609  *
 610  * Removes one matching handler registered with the given
 611  * @a method_name and callbacks.
 612  *
 613  * @param slicer
 614  *        The try-and-slice instance.
 615  * @param method_name
 616  *        Name of the method to remove.
 617  * @param method_cb
 618  *        Method handler.
 619  * @param modifier_cb
 620  *        Modifier handler.
 621  * @param data_cb
 622  *        Data handler.
 623  * @param eom_cb
 624  *        End of message handler.
 625  *
 626  * @return #GNUNET_OK if a method handler was removed,
 627  *         #GNUNET_NO if no handler matched the given method name and callbacks.
 628  */
 629 int
 630 GNUNET_SOCIAL_slicer_method_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 631                                     const char *method_name,
 632                                     GNUNET_SOCIAL_MethodCallback method_cb,
 633                                     GNUNET_SOCIAL_ModifierCallback modifier_cb,
 634                                     GNUNET_SOCIAL_DataCallback data_cb,
 635                                     GNUNET_SOCIAL_EndOfMessageCallback eom_cb);
 636
 637
 638 /**
 639  * Watch a place for changed objects.
 640  *
 641  * @param slicer
 642  *        The try-and-slice instance.
 643  * @param object_filter
 644  *        Object prefix to match.
 645  * @param modifier_cb
 646  *        Function to call when encountering a state modifier.
 647  * @param cls
 648  *        Closure for callback.
 649  */
 650 void
 651 GNUNET_SOCIAL_slicer_modifier_add (struct GNUNET_SOCIAL_Slicer *slicer,
 652                                    const char *object_filter,
 653                                    GNUNET_SOCIAL_ModifierCallback modifier_cb,
 654                                    void *cls);
 655
 656
 657 /**
 658  * Remove a registered modifier from the try-and-slice instance.
 659  *
 660  * Removes one matching handler registered with the given
 661  * @a object_filter and callback.
 662  *
 663  * @param slicer
 664  *        The try-and-slice instance.
 665  * @param object_filter
 666  *        Object prefix to match.
 667  * @param modifier_cb
 668  *        Function to call when encountering a state modifier changes.
 669  */
 670 int
 671 GNUNET_SOCIAL_slicer_modifier_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 672                                       const char *object_filter,
 673                                       GNUNET_SOCIAL_ModifierCallback modifier_cb);
 674
 675
 676 /**
 677  * Destroy a given try-and-slice instance.
 678  *
 679  * @param slicer
 680  *        Slicer to destroy
 681  */
 682 void
 683 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
 684
 685
 686 /**
 687  * Function called asking for nym to be admitted to the place.
 688  *
 689  * Should call either GNUNET_SOCIAL_host_admit() or
 690  * GNUNET_SOCIAL_host_reject_entry() (possibly asynchronously).  If this host
 691  * cannot decide, it is fine to call neither function, in which case hopefully
 692  * some other host of the place exists that will make the decision.  The @a nym
 693  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
 694  * for it.
 695  *
 696  * @param cls Closure.
 697  * @param nym Handle for the user who wants to enter.
 698  * @param method_name Method name in the entry request.
 699  * @param variable_count Number of elements in the @a variables array.
 700  * @param variables Variables present in the message.
 701  * @param data_size Number of bytes in @a data.
 702  * @param data Payload given on enter (e.g. a password).
 703  */
 704 typedef void
 705 (*GNUNET_SOCIAL_AnswerDoorCallback) (void *cls,
 706                                      struct GNUNET_SOCIAL_Nym *nym,
 707                                      const char *method_name,
 708                                      struct GNUNET_ENV_Environment *env,
 709                                      size_t data_size,
 710                                      const void *data);
 711
 712
 713 /**
 714  * Function called when a @a nym leaves the place.
 715  *
 716  * This is also called if the @a nym was never given permission to enter
 717  * (i.e. the @a nym stopped asking to get in).
 718  *
 719  * @param cls
 720  *        Closure.
 721  * @param nym
 722  *        Handle for the user who left.
 723  */
 724 typedef void
 725 (*GNUNET_SOCIAL_FarewellCallback) (void *cls,
 726                                    const struct GNUNET_SOCIAL_Nym *nym,
 727                                    struct GNUNET_ENV_Environment *env);
 728
 729
 730 /**
 731  * Function called after the host entered a home.
 732  *
 733  * @param cls
 734  *        Closure.
 735  * @param result
 736  *        #GNUNET_OK on success, or
 737  *        #GNUNET_SYSERR on error.
 738  * @param place_pub_key
 739  *        Public key of home.
 740  * @param max_message_id
 741  *        Last message ID sent to the channel.
 742  *        Or 0 if no messages have been sent to the place yet.
 743  */
 744 typedef void
 745 (*GNUNET_SOCIAL_HostEnterCallback) (void *cls, int result,
 746                                     const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
 747                                     uint64_t max_message_id);
 748
 749
 750 /**
 751  * Enter a place as host.
 752  *
 753  * A place is created upon first entering, and it is active until permanently
 754  * left using GNUNET_SOCIAL_host_leave().
 755  *
 756  * @param cfg
 757  *        Configuration to contact the social service.
 758  * @param ego
 759  *        Identity of the host.
 760  * @param place_key
 761  *        Private-public key pair of the place.
 762  *        NULL for ephemeral places.
 763  * @param policy
 764  *        Policy specifying entry and history restrictions for the place.
 765  * @param slicer
 766  *        Slicer to handle incoming messages.
 767  * @param enter_cb
 768  *        Function called when the place is entered and ready to use.
 769  * @param answer_door_cb
 770  *        Function to handle new nyms that want to enter.
 771  * @param farewell_cb
 772  *        Function to handle departing nyms.
 773  * @param cls
 774  *        Closure for the callbacks.
 775  *
 776  * @return Handle for the host.
 777  */
 778 struct GNUNET_SOCIAL_Host *
 779 GNUNET_SOCIAL_host_enter (const struct GNUNET_SOCIAL_App *app,
 780                           const struct GNUNET_SOCIAL_Ego *ego,
 781                           enum GNUNET_PSYC_Policy policy,
 782                           struct GNUNET_SOCIAL_Slicer *slicer,
 783                           GNUNET_SOCIAL_HostEnterCallback enter_cb,
 784                           GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
 785                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 786                           void *cls);
 787
 788
 789 /**
 790  * Reconnect to an already entered place as host.
 791  *
 792  * @param hconn
 793  *        Host connection handle.
 794  *        @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppHostPlaceCallback()
 795  * @param slicer
 796  *        Slicer to handle incoming messages.
 797  * @param enter_cb
 798  *        Function called when the place is entered and ready to use.
 799  * @param answer_door_cb
 800  *        Function to handle new nyms that want to enter.
 801  * @param farewell_cb
 802  *        Function to handle departing nyms.
 803  * @param cls
 804  *        Closure for the callbacks.
 805  *
 806  * @return Handle for the host.
 807  */
 808 struct GNUNET_SOCIAL_Host *
 809 GNUNET_SOCIAL_host_enter_reconnect (struct GNUNET_SOCIAL_HostConnection *hconn,
 810                                     struct GNUNET_SOCIAL_Slicer *slicer,
 811                                     GNUNET_SOCIAL_HostEnterCallback enter_cb,
 812                                     GNUNET_SOCIAL_AnswerDoorCallback answer_door_cb,
 813                                     GNUNET_SOCIAL_FarewellCallback farewell_cb,
 814                                     void *cls);
 815
 816
 817 /**
 818  * Decision whether to admit @a nym into the place or refuse entry.
 819  *
 820  * @param hst
 821  *        Host of the place.
 822  * @param nym
 823  *        Handle for the entity that wanted to enter.
 824  * @param is_admitted
 825  *        #GNUNET_YES    if @a nym is admitted,
 826  *        #GNUNET_NO     if @a nym is refused entry,
 827  *        #GNUNET_SYSERR if we cannot answer the request.
 828  * @param method_name
 829  *        Method name for the rejection message.
 830  * @param env
 831  *        Environment containing variables for the message, or NULL.
 832  * @param data
 833  *        Data for the rejection message to send back.
 834  * @param data_size
 835  *        Number of bytes in @a data for method.
 836  * @return #GNUNET_OK on success,
 837  *         #GNUNET_SYSERR if the message is too large.
 838  */
 839 int
 840 GNUNET_SOCIAL_host_entry_decision (struct GNUNET_SOCIAL_Host *hst,
 841                                    struct GNUNET_SOCIAL_Nym *nym,
 842                                    int is_admitted,
 843                                    const struct GNUNET_PSYC_Message *entry_resp);
 844
 845
 846 /**
 847  * Throw @a nym out of the place.
 848  *
 849  * Sends a _notice_place_leave announcement to the home.
 850  *
 851  * The @a nym reference will remain valid until the
 852  * #GNUNET_SOCIAL_FarewellCallback is invoked,
 853  * which should be very soon after this call.
 854  *
 855  * @param host
 856  *        Host of the place.
 857  * @param nym
 858  *        Handle for the entity to be ejected.
 859  * @param env
 860  *        Environment for the message or NULL.
 861  *        _nym is set to @e nym regardless whether an @e env is provided.
 862  */
 863 void
 864 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
 865                           const struct GNUNET_SOCIAL_Nym *nym,
 866                           struct GNUNET_ENV_Environment *env);
 867
 868
 869 /**
 870  * Flags for announcements by a host.
 871  */
 872 enum GNUNET_SOCIAL_AnnounceFlags
 873 {
 874   GNUNET_SOCIAL_ANNOUNCE_NONE = 0,
 875
 876   /**
 877    * Whether this announcement removes all objects from the place.
 878    *
 879    * New objects can be still added to the now empty place using the @e env
 880    * parameter of the same announcement.
 881    */
 882   GNUNET_SOCIAL_ANNOUNCE_CLEAR_OBJECTS = 1 << 0
 883 };
 884
 885
 886 /**
 887  * Handle for an announcement request.
 888  */
 889 struct GNUNET_SOCIAL_Announcement;
 890
 891
 892 /**
 893  * Send a message to all nyms that are present in the place.
 894  *
 895  * This function is restricted to the host.  Nyms can only send requests
 896  * to the host who can decide to relay it to everyone in the place.
 897  *
 898  * @param host
 899  *        Host of the place.
 900  * @param method_name
 901  *        Method to use for the announcement.
 902  * @param env
 903  *        Environment containing variables for the message and operations
 904  *        on objects of the place.
 905  *        Has to remain available until the first call to @a notify_data.
 906  *        Can be NULL.
 907  * @param notify_data
 908  *        Function to call to get the payload of the announcement.
 909  * @param notify_data_cls
 910  *        Closure for @a notify.
 911  * @param flags
 912  *        Flags for this announcement.
 913  *
 914  * @return NULL on error (another announcement already in progress?).
 915  */
 916 struct GNUNET_SOCIAL_Announcement *
 917 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
 918                              const char *method_name,
 919                              const struct GNUNET_ENV_Environment *env,
 920                              GNUNET_PSYC_TransmitNotifyData notify_data,
 921                              void *notify_data_cls,
 922                              enum GNUNET_SOCIAL_AnnounceFlags flags);
 923
 924
 925 /**
 926  * Resume transmitting announcement.
 927  *
 928  * @param a
 929  *        The announcement to resume.
 930  */
 931 void
 932 GNUNET_SOCIAL_host_announce_resume (struct GNUNET_SOCIAL_Announcement *a);
 933
 934
 935 /**
 936  * Cancel announcement.
 937  *
 938  * @param a
 939  *        The announcement to cancel.
 940  */
 941 void
 942 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 943
 944
 945 /**
 946  * Allow relaying messages from guests matching a given @a method_prefix.
 947  *
 948  * @param host
 949  *        The host.
 950  * @param method_prefix
 951  *        Method prefix to allow.
 952  */
 953 void
 954 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
 955                                        const char *method_prefix);
 956
 957
 958 /**
 959  * Allow relaying changes to objects of the place.
 960  *
 961  * Only applies to messages with an allowed method name.
 962  * @see GNUNET_SCOIAL_host_relay_allow_method()
 963  *
 964  * @param host
 965  *        The host.
 966  * @param object_prefix
 967  *        Object prefix to allow modifying.
 968  */
 969 void
 970 GNUNET_SOCIAL_host_relay_allow_method (struct GNUNET_SOCIAL_Host *host,
 971                                        const char *object_prefix);
 972
 973
 974 /**
 975  * Stop relaying messages from guests.
 976  *
 977  * Remove all allowed relay rules.
 978  *
 979  *
 980  *
 981  */
 982 void
 983 GNUNET_SOCIAL_host_relay_stop (struct GNUNET_SOCIAL_Host *host);
 984
 985
 986 /**
 987  * Obtain handle for a hosted place.
 988  *
 989  * The returned handle can be used to access the place API.
 990  *
 991  * @param host
 992  *        Handle for the host.
 993  *
 994  * @return Handle for the hosted place, valid as long as @a host is valid.
 995  */
 996 struct GNUNET_SOCIAL_Place *
 997 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host);
 998
 999
1000 /**
1001  * Disconnect from a home.
1002  *
1003  * Invalidates host handle.
1004  *
1005  * @param hst
1006  *        The host to disconnect.
1007  * @param disconnect_cb
1008  *        Function called after disconnected from the service.
1009  * @param cls
1010  *        Closure for @a disconnect_cb.
1011  */
1012 void
1013 GNUNET_SOCIAL_host_disconnect (struct GNUNET_SOCIAL_Host *hst,
1014                                GNUNET_ContinuationCallback disconnect_cb,
1015                                void *cls);
1016
1017
1018 /**
1019  * Stop hosting a home.
1020  *
1021  * Sends a _notice_place_closed announcement to the home.
1022  * Invalidates host handle.
1023  *
1024  * @param hst
1025  *        Host leaving.
1026  * @param env
1027  *        Environment for the message or NULL.
1028  * @param disconnect_cb
1029  *        Function called after the host left the place
1030  *        and disconnected from the service.
1031  * @param cls
1032  *        Closure for @a disconnect_cb.
1033  */
1034 void
1035 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *hst,
1036                           const struct GNUNET_ENV_Environment *env,
1037                           GNUNET_ContinuationCallback disconnect_cb,
1038                           void *cls);
1039
1040
1041 /**
1042  * Function called after the guest entered the local copy of the place.
1043  *
1044  * History and object query functions can be used after this call,
1045  * but new messages can't be sent or received.
1046  *
1047  * @param cls
1048  *        Closure.
1049  * @param result
1050  *        #GNUNET_OK on success, or
1051  *        #GNUNET_SYSERR on error, e.g. could not connect to the service, or
1052  *        could not resolve GNS name.
1053  * @param max_message_id
1054  *        Last message ID sent to the place.
1055  *        Or 0 if no messages have been sent to the place yet.
1056  */
1057 typedef void
1058 (*GNUNET_SOCIAL_GuestEnterCallback) (void *cls, int result,
1059                                      uint64_t max_message_id);
1060
1061
1062 /**
1063  * Function called upon a guest receives a decision about entry to the place.
1064  *
1065  * @param is_admitted
1066  *   Is the guest admitted to the place?
1067  *   #GNUNET_YES    if admitted,
1068  *   #GNUNET_NO     if refused entry
1069  *   #GNUNET_SYSERR if the request could not be answered.
1070  * @param method_name
1071  *   Method for the message sent along with the decision.
1072  *   NULL if no message was sent.
1073  * @param env
1074  *   Environment with variables for the message.
1075  *   NULL if there are no variables.
1076  *   It has to be freed using GNUNET_ENV_environment_destroy()
1077  *   when it is not needed anymore.
1078  * @param data_size
1079  *   Size of @data.
1080  * @param data
1081  *   Payload of the message.
1082  */
1083 typedef void
1084 (*GNUNET_SOCIAL_EntryDecisionCallback) (void *cls,
1085                                         int is_admitted,
1086                                         const struct GNUNET_PSYC_Message *entry_resp);
1087
1088
1089 /**
1090  * Request entry to a place as a guest.
1091  *
1092  * @param app
1093  *        Application handle.
1094  * @param ego
1095  *        Identity of the guest.
1096  * @param place_pub_key
1097  *        Public key of the place to enter.
1098  * @param flags
1099  *        Flags for the entry.
1100  * @param origin
1101  *        Peer identity of the origin of the underlying multicast group.
1102  * @param relay_count
1103  *        Number of elements in the @a relays array.
1104  * @param relays
1105  *        Relays for the underlying multicast group.
1106  * @param method_name
1107  *        Method name for the message.
1108  * @param env
1109  *        Environment containing variables for the message, or NULL.
1110  * @param data
1111  *        Payload for the message to give to the enter callback.
1112  * @param data_size
1113  *        Number of bytes in @a data.
1114  * @param slicer
1115  *        Slicer to use for processing incoming requests from guests.
1116  *
1117  * @return NULL on errors, otherwise handle for the guest.
1118  */
1119 struct GNUNET_SOCIAL_Guest *
1120 GNUNET_SOCIAL_guest_enter (const struct GNUNET_SOCIAL_App *app,
1121                            const struct GNUNET_SOCIAL_Ego *ego,
1122                            const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
1123                            enum GNUNET_PSYC_SlaveJoinFlags flags,
1124                            const struct GNUNET_PeerIdentity *origin,
1125                            uint32_t relay_count,
1126                            const struct GNUNET_PeerIdentity *relays,
1127                            const struct GNUNET_PSYC_Message *entry_msg,
1128                            struct GNUNET_SOCIAL_Slicer *slicer,
1129                            GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1130                            GNUNET_SOCIAL_EntryDecisionCallback entry_dcsn_cb,
1131                            void *cls);
1132
1133
1134 /**
1135  * Request entry to a place by name as a guest.
1136  *
1137  * @param app
1138  *        Application handle.
1139  * @param ego
1140  *        Identity of the guest.
1141  * @param gns_name
1142  *        GNS name of the place to enter.  Either in the form of
1143  *        'room.friend.gnu', or 'NYMPUBKEY.zkey'.  This latter case refers to
1144  *        the 'PLACE' record of the empty label ("+") in the GNS zone with the
1145  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
1146  *        pseudonym's place directly.
1147  * @param password
1148  *        Password to decrypt the record, or NULL for cleartext records.
1149  * @param join_msg
1150  *        Entry request message.
1151  * @param slicer
1152  *        Slicer to use for processing incoming requests from guests.
1153  * @param local_enter_cb
1154  *        Called upon connection established to the social service.
1155  * @param entry_decision_cb
1156  *        Called upon receiving entry decision.
1157  *
1158  * @return NULL on errors, otherwise handle for the guest.
1159  */
1160 struct GNUNET_SOCIAL_Guest *
1161 GNUNET_SOCIAL_guest_enter_by_name (const struct GNUNET_SOCIAL_App *app,
1162                                    const struct GNUNET_SOCIAL_Ego *ego,
1163                                    const char *gns_name,
1164                                    const char *password,
1165                                    const struct GNUNET_PSYC_Message *join_msg,
1166                                    struct GNUNET_SOCIAL_Slicer *slicer,
1167                                    GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1168                                    GNUNET_SOCIAL_EntryDecisionCallback entry_decision_cb,
1169                                    void *cls);
1170
1171
1172 /**
1173  * Reconnect to an already entered place as guest.
1174  *
1175  * @param gconn
1176  *        Guest connection handle.
1177  *        @see GNUNET_SOCIAL_app_connect() & GNUNET_SOCIAL_AppGuestPlaceCallback()
1178  * @param flags
1179  *        Flags for the entry.
1180  * @param slicer
1181  *        Slicer to use for processing incoming requests from guests.
1182  * @param local_enter_cb
1183  *        Called upon connection established to the social service.
1184  * @param entry_decision_cb
1185  *        Called upon receiving entry decision.
1186  *
1187  * @return NULL on errors, otherwise handle for the guest.
1188  */
1189 struct GNUNET_SOCIAL_Guest *
1190 GNUNET_SOCIAL_guest_enter_reconnect (struct GNUNET_SOCIAL_GuestConnection *gconn,
1191                                      enum GNUNET_PSYC_SlaveJoinFlags flags,
1192                                      struct GNUNET_SOCIAL_Slicer *slicer,
1193                                      GNUNET_SOCIAL_GuestEnterCallback local_enter_cb,
1194                                      void *cls);
1195
1196
1197 /**
1198  * Flags for talking to the host of a place.
1199  */
1200 enum GNUNET_SOCIAL_TalkFlags
1201 {
1202   GNUNET_SOCIAL_TALK_NONE = 0
1203 };
1204
1205
1206 /**
1207  * A talk request.
1208  */
1209 struct GNUNET_SOCIAL_TalkRequest;
1210
1211
1212 /**
1213  * Talk to the host of the place.
1214  *
1215  * @param place
1216  *        Place where we want to talk to the host.
1217  * @param method_name
1218  *        Method to invoke on the host.
1219  * @param env
1220  *        Environment containing variables for the message, or NULL.
1221  * @param notify_data
1222  *        Function to use to get the payload for the method.
1223  * @param notify_data_cls
1224  *        Closure for @a notify_data.
1225  * @param flags
1226  *        Flags for the message being sent.
1227  *
1228  * @return NULL if we are already trying to talk to the host,
1229  *         otherwise handle to cancel the request.
1230  */
1231 struct GNUNET_SOCIAL_TalkRequest *
1232 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Guest *guest,
1233                           const char *method_name,
1234                           const struct GNUNET_ENV_Environment *env,
1235                           GNUNET_PSYC_TransmitNotifyData notify_data,
1236                           void *notify_data_cls,
1237                           enum GNUNET_SOCIAL_TalkFlags flags);
1238
1239
1240 /**
1241  * Resume talking to the host of the place.
1242  *
1243  * @param tr
1244  *        Talk request to resume.
1245  */
1246 void
1247 GNUNET_SOCIAL_guest_talk_resume (struct GNUNET_SOCIAL_TalkRequest *tr);
1248
1249
1250 /**
1251  * Cancel talking to the host of the place.
1252  *
1253  * @param tr
1254  *        Talk request to cancel.
1255  */
1256 void
1257 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
1258
1259
1260 /**
1261  * Disconnect from a place.
1262  *
1263  * Invalidates guest handle.
1264  *
1265  * @param gst
1266  *        The guest to disconnect.
1267  * @param disconnect_cb
1268  *        Function called after disconnected from the service.
1269  * @param cls
1270  *        Closure for @a disconnect_cb.
1271  */
1272 void
1273 GNUNET_SOCIAL_guest_disconnect (struct GNUNET_SOCIAL_Guest *gst,
1274                                 GNUNET_ContinuationCallback disconnect_cb,
1275                                 void *cls);
1276
1277
1278 /**
1279  * Leave a place temporarily or permanently.
1280  *
1281  * Notifies the owner of the place about leaving, and destroys the place handle.
1282  *
1283  * @param place
1284  *        Place to leave.
1285  * @param env
1286  *        Optional environment for the leave message if @a keep_active
1287  *        is #GNUNET_NO.  NULL if not needed.
1288  * @param disconnect_cb
1289  *        Called upon disconnecting from the social service.
1290  */
1291 void
1292 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Guest *gst,
1293                            struct GNUNET_ENV_Environment *env,
1294                            GNUNET_ContinuationCallback disconnect_cb,
1295                            void *leave_cls);
1296
1297
1298 /**
1299  * Obtain handle for a place entered as guest.
1300  *
1301  * The returned handle can be used to access the place API.
1302  *
1303  * @param guest  Handle for the guest.
1304  *
1305  * @return Handle for the place, valid as long as @a guest is valid.
1306  */
1307 struct GNUNET_SOCIAL_Place *
1308 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Guest *guest);
1309
1310
1311 /**
1312  * A history request.
1313  */
1314 struct GNUNET_SOCIAL_HistoryRequest;
1315
1316
1317 /**
1318  * Learn about the history of a place.
1319  *
1320  * Messages are returned through the @a slicer function
1321  * and have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1322  *
1323  * @param place
1324  *        Place we want to learn more about.
1325  * @param start_message_id
1326  *        First historic message we are interested in.
1327  * @param end_message_id
1328  *        Last historic message we are interested in (inclusive).
1329  * @param method_prefix
1330  *        Only retrieve messages with this method prefix.
1331  * @param flags
1332  *        OR'ed GNUNET_PSYC_HistoryReplayFlags
1333  * @param slicer
1334  *        Slicer to use for retrieved messages.
1335  *        Can be the same as the slicer of the place.
1336  * @param result_cb
1337  *        Function called after all messages retrieved.
1338  *        NULL if not needed.
1339  * @param cls Closure for @a result_cb.
1340  */
1341 struct GNUNET_SOCIAL_HistoryRequest *
1342 GNUNET_SOCIAL_place_history_replay (struct GNUNET_SOCIAL_Place *plc,
1343                                     uint64_t start_message_id,
1344                                     uint64_t end_message_id,
1345                                     const char *method_prefix,
1346                                     uint32_t flags,
1347                                     struct GNUNET_SOCIAL_Slicer *slicer,
1348                                     GNUNET_ResultCallback result_cb,
1349                                     void *cls);
1350
1351
1352 /**
1353  * Learn about the history of a place.
1354  *
1355  * Sends messages through the slicer function of the place where
1356  * start_message_id <= message_id <= end_message_id.
1357  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
1358  *
1359  * To get the latest message, use 0 for both the start and end message ID.
1360  *
1361  * @param place
1362  *        Place we want to learn more about.
1363  * @param message_limit
1364  *        Maximum number of historic messages we are interested in.
1365  * @param result_cb
1366  *        Function called after all messages retrieved.
1367  *        NULL if not needed.
1368  * @param cls Closure for @a result_cb.
1369  */
1370 struct GNUNET_SOCIAL_HistoryRequest *
1371 GNUNET_SOCIAL_place_history_replay_latest (struct GNUNET_SOCIAL_Place *plc,
1372                                            uint64_t message_limit,
1373                                            const char *method_prefix,
1374                                            uint32_t flags,
1375                                            struct GNUNET_SOCIAL_Slicer *slicer,
1376                                            GNUNET_ResultCallback result_cb,
1377                                            void *cls);
1378
1379 /**
1380  * Cancel learning about the history of a place.
1381  *
1382  * @param hist
1383  *        History lesson to cancel.
1384  */
1385 void
1386 GNUNET_SOCIAL_place_history_replay_cancel (struct GNUNET_SOCIAL_HistoryRequest *hist);
1387
1388
1389 struct GNUNET_SOCIAL_LookHandle;
1390
1391
1392 /**
1393  * Look at a particular object in the place.
1394  *
1395  * The best matching object is returned (its name might be less specific than
1396  * what was requested).
1397  *
1398  * @param place
1399  *        The place to look the object at.
1400  * @param full_name
1401  *        Full name of the object.
1402  * @param value_size
1403  *        Set to the size of the returned value.
1404  *
1405  * @return NULL if there is no such object at this place.
1406  */
1407 struct GNUNET_SOCIAL_LookHandle *
1408 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *plc,
1409                              const char *full_name,
1410                              GNUNET_PSYC_StateVarCallback var_cb,
1411                              GNUNET_ResultCallback result_cb,
1412                              void *cls);
1413
1414 /**
1415  * Look for objects in the place with a matching name prefix.
1416  *
1417  * @param place
1418  *        The place to look its objects at.
1419  * @param name_prefix
1420  *        Look at objects with names beginning with this value.
1421  * @param var_cb
1422  *        Function to call for each object found.
1423  * @param cls
1424  *        Closure for callback function.
1425  *
1426  * @return Handle that can be used to stop looking at objects.
1427  */
1428 struct GNUNET_SOCIAL_LookHandle *
1429 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *plc,
1430                               const char *name_prefix,
1431                               GNUNET_PSYC_StateVarCallback var_cb,
1432                               GNUNET_ResultCallback result_cb,
1433                               void *cls);
1434
1435
1436 /**
1437  * Stop looking at objects.
1438  *
1439  * @param lh Look handle to stop.
1440  */
1441 void
1442 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
1443
1444
1445 /**
1446  * Advertise a @e place in the GNS zone of @a ego.
1447  *
1448  * @param app
1449  *        Application handle.
1450  * @param ego
1451  *        Ego.
1452  * @param place_pub_key
1453  *        Public key of place to add.
1454  * @param name
1455  *        The name for the PLACE record to put in the zone.
1456  * @param password
1457  *        Password used to encrypt the record or NULL to keep it cleartext.
1458  * @param relay_count
1459  *        Number of elements in the @a relays array.
1460  * @param relays
1461  *        List of relays to put in the PLACE record to advertise
1462  *        as entry points to the place in addition to the origin.
1463  * @param expiration_time
1464  *        Expiration time of the record, use 0 to remove the record.
1465  * @param result_cb
1466  *        Function called with the result of the operation.
1467  * @param result_cls
1468  *        Closure for @a result_cb
1469  *
1470  * @return #GNUNET_OK if the request was sent,
1471  *         #GNUNET_SYSERR on error, e.g. the name/password is too long.
1472  */
1473 int
1474 GNUNET_SOCIAL_zone_add_place (const struct GNUNET_SOCIAL_App *app,
1475                               const struct GNUNET_SOCIAL_Ego *ego,
1476                               const char *name,
1477                               const char *password,
1478                               const struct GNUNET_CRYPTO_EddsaPublicKey *place_pub_key,
1479                               const struct GNUNET_PeerIdentity *origin,
1480                               uint32_t relay_count,
1481                               const struct GNUNET_PeerIdentity *relays,
1482                               struct GNUNET_TIME_Absolute expiration_time,
1483                               GNUNET_ResultCallback result_cb,
1484                               void *result_cls);
1485
1486
1487 /**
1488  * Add public key to the GNS zone of the @e ego.
1489  *
1490  * @param cfg
1491  *        Configuration.
1492  * @param ego
1493  *        Ego.
1494  * @param name
1495  *        The name for the PKEY record to put in the zone.
1496  * @param nym_pub_key
1497  *        Public key of nym to add.
1498  * @param expiration_time
1499  *        Expiration time of the record, use 0 to remove the record.
1500  * @param result_cb
1501  *        Function called with the result of the operation.
1502  * @param result_cls
1503  *        Closure for @a result_cb
1504  *
1505  * @return #GNUNET_OK if the request was sent,
1506  *         #GNUNET_SYSERR on error, e.g. the name is too long.
1507  */
1508 int
1509 GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app,
1510                             const struct GNUNET_SOCIAL_Ego *ego,
1511                             const char *name,
1512                             const struct GNUNET_CRYPTO_EcdsaPublicKey *nym_pub_key,
1513                             struct GNUNET_TIME_Absolute expiration_time,
1514                             GNUNET_ResultCallback result_cb,
1515                             void *result_cls);
1516
1517
1518 #if 0                           /* keep Emacsens' auto-indent happy */
1519 {
1520 #endif
1521 #ifdef __cplusplus
1522 }
1523 #endif
1524
1525 /* ifndef GNUNET_SOCIAL_SERVICE_H */
1526 #endif
1527
1528 /** @} */  /* end of group social */