src/include/gnunet_social_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2013 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_social_service.h
  23  * @brief Social service; implements social functionality using the PSYC service.
  24  * @author Gabor X Toth
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SOCIAL_SERVICE_H
  28 #define GNUNET_SOCIAL_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 #include "gnunet_util_lib.h"
  39 #include "gnunet_psyc_lib.h"
  40 #include "gnunet_psyc_service.h"
  41 #include "gnunet_multicast_service.h"
  42
  43
  44 /**
  45  * Version number of GNUnet Social API.
  46  */
  47 #define GNUNET_SOCIAL_VERSION 0x00000000
  48
  49 /**
  50  * Handle for our own presence in the network (we can of course have
  51  * alter-egos).
  52  */
  53 struct GNUNET_SOCIAL_Ego;
  54
  55 /**
  56  * Handle for another user (who is likely pseudonymous) in the network.
  57  */
  58 struct GNUNET_SOCIAL_Nym;
  59
  60 /**
  61  * Handle for a place where social interactions happen.
  62  */
  63 struct GNUNET_SOCIAL_Place;
  64
  65 /**
  66  * Handle for a place that one of our egos hosts.
  67  */
  68 struct GNUNET_SOCIAL_Home;
  69
  70 /**
  71  * Handle to an implementation of try-and-slice.
  72  */
  73 struct GNUNET_SOCIAL_Slicer;
  74
  75
  76 /**
  77  * Method called from SOCIAL upon receiving a message indicating a call
  78  * to a @e method.
  79  *
  80  * @param cls Closure.
  81  * @param full_method_name Original method name from PSYC (may be more
  82  *        specific than the registered method name due to try-and-slice matching).
  83
  84  * @param message_id Unique message counter for this message
  85  *                   (unique only in combination with the given sender for
  86  *                    this channel).
  87  * @param modifier_count Number of elements in the @a modifiers array.
  88  * @param modifiers Modifiers present in the message. FIXME: use environment instead?
  89  * @param data_offset Byte offset of @a data in the overall data of the method.
  90  * @param data_size Number of bytes in @a data.
  91  * @param data Data stream given to the method (might not be zero-terminated
  92  *             if data is binary).
  93  * @param flags Message flags indicating fragmentation status.
  94  */
  95 typedef int (*GNUNET_SOCIAL_Method)(void *cls,
  96                                     const char *full_method_name,
  97                                     uint64_t message_id,
  98                                     size_t modifier_count,
  99                                     GNUNET_PSYC_Modifier *modifiers,
 100                                     uint64_t data_offset,
 101                                     size_t data_size,
 102                                     const void *data,
 103                                     enum GNUNET_PSYC_MessageFlags flags);
 104
 105
 106 /**
 107  * Create a try-and-slice instance.
 108  *
 109  * @return A new try-and-slice construct.
 110  */
 111 struct GNUNET_SOCIAL_Slicer *
 112 GNUNET_SOCIAL_slicer_create (void);
 113
 114
 115 /**
 116  * Add a method to the try-and-slice instance.
 117  *
 118  * A slicer processes messages and calls methods that match a message. A match
 119  * happens whenever the method name of a message starts with the method_name
 120  * parameter given here.
 121  *
 122  * @param slicer The try-and-slice instance to extend.
 123  * @param method_name Name of the given method, use empty string for default.
 124  * @param method Method to invoke.
 125  * @param method_cls Closure for method.
 126  */
 127 void
 128 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
 129                           const char *method_name,
 130                           GNUNET_SOCIAL_Method method,
 131                           void *method_cls);
 132
 133
 134 /**
 135  * Remove a registered method from the try-and-slice instance.
 136  *
 137  * @param slicer The try-and-slice instance.
 138  * @param method_name Name of the method to remove.
 139  * @param method Method handler.
 140  */
 141 void
 142 GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 143                              const char *method_name,
 144                              GNUNET_SOCIAL_Method method);
 145
 146 /**
 147  * Destroy a given try-and-slice instance.
 148  *
 149  * @param slicer slicer to destroy
 150  */
 151 void
 152 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
 153
 154
 155 /**
 156  * Create an ego using the given private key.
 157  *
 158  * The identity service is used to manage egos, the
 159  * GNUNET_IDENTITY_ego_get_key() function returns an ego's private key that can
 160  * be passed into this function.
 161  *
 162  * @param key Private key for the ego, NULL for ephemeral egos.
 163  * @return Handle to the ego, NULL on error.
 164  */
 165 struct GNUNET_SOCIAL_Ego *
 166 GNUNET_SOCIAL_ego_create (const struct GNUNET_CRYPTO_EccPrivateKey *key);
 167
 168
 169 /**
 170  * Destroy a handle to an ego.
 171  *
 172  * @param ego Ego to destroy.
 173  */
 174 void
 175 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
 176
 177
 178 /**
 179  * Function called asking for nym to be admitted to the place.
 180  *
 181  * Should call either GNUNET_SOCIAL_home_admit() or
 182  * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously).  If this owner
 183  * cannot decide, it is fine to call neither function, in which case hopefully
 184  * some other owner of the home exists that will make the decision. The @a nym
 185  * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
 186  * for it.
 187  *
 188  * @param cls Closure.
 189  * @param nym Handle for the user who wants to enter.
 190  * @param variable_count Number of elements in the @a variables array.
 191  * @param variables Variables present in the message.
 192  * @param data_size Number of bytes in @a data.
 193  * @param data Payload given on enter (e.g. a password).
 194  */
 195 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
 196                                                  struct GNUNET_SOCIAL_Nym *nym,
 197                                                  size_t variable_count,
 198                                                  GNUNET_PSYC_Modifier *variables,
 199                                                  size_t data_size,
 200                                                  const void *data);
 201
 202
 203 /**
 204  * Function called when a @a nym leaves the place.
 205  *
 206  * This is also called if the @a nym was never given permission to enter
 207  * (i.e. the @a nym stopped asking to get in).
 208  *
 209  * @param cls Closure.
 210  * @param nym Handle for the user who left.
 211  * @param variable_count Number of elements in the @a variables array.
 212  * @param variables Variables present in the message.
 213  */
 214 typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
 215                                                struct GNUNET_SOCIAL_Nym *nym,
 216                                                size_t variable_count,
 217                                                GNUNET_PSYC_Modifier *variables);
 218
 219
 220 /**
 221  * Enter a home where guests (nyms) can be hosted.
 222  *
 223  * A home is created upon first entering, and exists until
 224  * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using
 225  * GNUNET_SOCIAL_home_leave().
 226  *
 227  * @param cfg Configuration to contact the social service.
 228  * @param home_keyfile File with the private-public key pair of the home,
 229  *        created if the file does not exist; pass NULL for ephemeral homes.
 230  * @param policy Policy specifying entry and history restrictions of the home.
 231  * @param ego Owner of the home (host).
 232  * @param slicer Slicer to handle guests talking.
 233  * @param listener_cb Function to handle new nyms that want to enter.
 234  * @param farewell_cb Function to handle departing nyms.
 235  * @param cls Closure for @a listener_cb and @a farewell_cb.
 236  * @return Handle for a new home.
 237  */
 238 struct GNUNET_SOCIAL_Home *
 239 GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 240                           const char *home_keyfile,
 241                           enum GNUNET_MULTICAST_GroupPolicy policy,
 242                           struct GNUNET_SOCIAL_Ego *ego,
 243                           struct GNUNET_SOCIAL_Slicer *slicer,
 244                           GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
 245                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 246                           void *cls);
 247
 248
 249 /**
 250  * Admit @a nym to the @a home.
 251  *
 252  * The @a nym reference will remain valid until either the home is destroyed or
 253  * @a nym leaves.
 254  *
 255  * @param home Home to allow @a nym to enter.
 256  * @param nym Handle for the entity that wants to enter.
 257  */
 258 void
 259 GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
 260                           struct GNUNET_SOCIAL_Nym *nym);
 261
 262
 263 /**
 264  * Throw @a nym out of the @a home.
 265  *
 266  * The @a nym reference will remain valid until the
 267  * #GNUNET_SOCIAL_FarewellCallback is invoked,
 268  * which should be very soon after this call.
 269  *
 270  * @param home Home to eject @a nym from.
 271  * @param nym Handle for the entity to be ejected.
 272  */
 273 void
 274 GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home,
 275                           struct GNUNET_SOCIAL_Nym *nym);
 276
 277
 278 /**
 279  * Refuse @a nym entry into the @a home.
 280  *
 281  * @param home Home to disallow @a nym to enter.
 282  * @param nym Handle for the entity that wanted to enter.
 283  * @param method_name Method name for the rejection message.
 284  * @param env Environment containing variables for the message, or NULL.
 285  * @param data_size Number of bytes in @a data for method.
 286  * @param data Data for the rejection message to send back.
 287  */
 288 void
 289 GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
 290                                  struct GNUNET_SOCIAL_Nym *nym,
 291                                  const char *method_name,
 292                                  const struct GNUNET_ENV_Environment *env,
 293                                  size_t data_size,
 294                                  const void *data);
 295
 296
 297 /**
 298  * Get the public key of a nym.
 299  *
 300  * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
 301  *
 302  * @param nym Pseudonym to map to a cryptographic identifier.
 303  * @param[out] nym_key Set to the public key of the nym.
 304  */
 305 void
 306 GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym,
 307                            struct GNUNET_CRYPTO_EccPublicKey *nym_key);
 308
 309
 310 /**
 311  * Obtain the private-public key pair of the home.
 312  *
 313  * @param home Home to get the key of.
 314  * @param[out] home_key Set to the private-public key pair of the home.  The public part is suitable for storing in GADS within a "PLACE" record, along with peer IDs to join at.
 315  */
 316 void
 317 GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home,
 318                             struct GNUNET_CRYPTO_EccPrivateKey *home_key);
 319
 320
 321 /**
 322  * Advertise @a home under @a name in the GADS zone of the @e ego.
 323  *
 324  * @param home The home to advertise.
 325  * @param name The name to put in the zone.
 326  * @param expiration_time Expiration time of the record, use 0 to remove the record.
 327  */
 328 void
 329 GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home,
 330                               const char *name,
 331                               GNUNET_TIME_Relative expiration_time);
 332
 333
 334 /**
 335  * Flags for announcements in a home.
 336  */
 337 enum GNUNET_PSYC_AnnouncementFlags
 338 {
 339   /**
 340    * Whether this announcement removes all objects from the home.
 341    *
 342    * New objects can be still added to the now empty home using the @e env
 343    * parameter of the same announcement.
 344    */
 345   GNUNET_SOCIAL_ANNOUNCEMENT_CLEAR_OBJECTS = 1 << 0
 346 };
 347
 348
 349 /**
 350  * Handle for an announcement request.
 351  */
 352 struct GNUNET_SOCIAL_Announcement;
 353
 354
 355 /**
 356  * Send a message to all nyms that are present in the home.
 357  *
 358  * This function is restricted to the home owner.  Nyms can only send requests
 359  * to the home owner who can decide to relay it to other guests.
 360  *
 361  * @param home Home to address the announcement to.
 362  * @param method_name Method to use for the announcement.
 363  * @param env Environment containing variables for the message and operations on
 364  *        objects of the home, or NULL.
 365  * @param notify Function to call to get the payload of the announcement.
 366  * @param notify_cls Closure for @a notify.
 367  * @param flags Flags for this announcement.
 368  * @return NULL on error (announcement already in progress?).
 369  */
 370 struct GNUNET_SOCIAL_Announcement *
 371 GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home,
 372                              const char *method_name,
 373                              const struct GNUNET_ENV_Environment *env,
 374                              GNUNET_CONNECTION_TransmitReadyNotify notify,
 375                              void *notify_cls,
 376                              GNUNET_SOCIAL_AnnouncementFlags flags);
 377
 378
 379 /**
 380  * Cancel announcement.
 381  *
 382  * @param a The announcement to cancel.
 383  */
 384 void
 385 GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
 386
 387
 388 /**
 389  * Convert our home to a place so we can access it via the place API.
 390  *
 391  * @param home Handle for the home.
 392  * @return Place handle for the same home, valid as long as @a home is valid;
 393  *         do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home!
 394  */
 395 struct GNUNET_SOCIAL_Place *
 396 GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home);
 397
 398
 399 /**
 400  * Leave a home temporarily, visitors can stay.
 401  *
 402  * After leaving, handling of incoming messages are left to other clients of the
 403  * social service, and stops after the last client exits.
 404  *
 405  * @param home Home to leave temporarily (handle becomes invalid).
 406  */
 407 void
 408 GNUNET_SOCIAL_home_away (struct GNUNET_SOCIAL_Home *home);
 409
 410
 411 /**
 412  * Leave a home.
 413
 414  * Invalidates home handle.
 415  * Guests will be disconnected until the home is restarted.
 416  *
 417  * @param home Home to leave.
 418  */
 419 void
 420 GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home);
 421
 422 /**
 423  * Request entry to a place (home hosted by someone else).
 424  *
 425  * @param cfg Configuration to contact the social service.
 426  * @param ego Owner of the home (host).
 427  * @param address GADS name of the place to enter.  Either in the form of
 428  *        'room.friend.gads', or 'NYMPUBKEY.zkey'.  This latter case refers to
 429  *        the 'PLACE' record of the empty label ("+") in the GADS zone with the
 430  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
 431  *        pseudonym's place directly.
 432  * @param env Environment containing variables for the message, or NULL.
 433  * @param data_size Number of bytes in @a data.
 434  * @param data Payload for the message to give to the enter callback.
 435  * @param slicer Slicer to use for processing incoming requests from guests.
 436  * @return NULL on errors, otherwise handle to the place.
 437  */
 438 struct GNUNET_SOCIAL_Place *
 439 GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 440                            struct GNUNET_SOCIAL_Ego *ego,
 441                            char *address,
 442                            const struct GNUNET_ENV_Environment *env,
 443                            size_t data_size,
 444                            const void *data,
 445                            struct GNUNET_SOCIAL_Slicer *slicer);
 446
 447 /**
 448  * Request entry to a place (home hosted by someone else).
 449  *
 450  * @param cfg Configuration to contact the social service.
 451  * @param ego Owner of the home (host).
 452  * @param crypto_address Public key of the place to enter.
 453  * @param peer Peer to send request to.
 454  * @param slicer Slicer to use for processing incoming requests from guests.
 455  * @param env Environment containing variables for the message, or NULL.
 456  * @param data_size Number of bytes in @a data.
 457  * @param data Payload for the message to give to the enter callback.
 458  * @return NULL on errors, otherwise handle to the place.
 459  */
 460 struct GNUNET_SOCIAL_Place *
 461 GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
 462                            struct GNUNET_SOCIAL_Ego *ego,
 463                            struct GNUNET_CRYPTO_EccPublicKey *crypto_address,
 464                            struct GNUNET_PeerIdentity *peer,
 465                            struct GNUNET_SOCIAL_Slicer *slicer,
 466                            const struct GNUNET_ENV_Environment *env,
 467                            size_t data_size,
 468                            const void *data);
 469
 470
 471 struct GNUNET_SOCIAL_WatchHandle;
 472
 473 /**
 474  * Watch a place for changed objects.
 475  *
 476  * @param place Place to watch.
 477  * @param object_filter Object prefix to match.
 478  * @param state_cb Function to call when an object/state changes.
 479  * @param state_cb_cls Closure for callback.
 480  *
 481  * @return Handle that can be used to cancel watching.
 482  */
 483 struct GNUNET_SOCIAL_WatchHandle *
 484 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
 485                            const char *object_filter,
 486                            GNUNET_PSYC_StateCallback state_cb,
 487                            void *state_cb_cls);
 488
 489
 490 /**
 491  * Cancel watching a place for changed objects.
 492  *
 493  * @param wh Watch handle to cancel.
 494  */
 495 void
 496 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
 497
 498
 499 struct GNUNET_SOCIAL_LookHandle;
 500
 501 /**
 502  * Look at all objects in the place.
 503  *
 504  * @param place The place to look its objects at.
 505  * @param state_cb Function to call for each object found.
 506  * @param state_cb_cls Closure for callback function.
 507  *
 508  * @return Handle that can be used to stop looking at objects.
 509  */
 510 struct GNUNET_SOCIAL_LookHandle *
 511 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
 512                           GNUNET_PSYC_StateCallback state_cb,
 513                           void *state_cb_cls);
 514
 515
 516 /**
 517  * Look at matching objects in the place.
 518  *
 519  * @param place The place to look its objects at.
 520  * @param object_filter Only look at objects with names beginning with this filter value.
 521  * @param state_cb Function to call for each object found.
 522  * @param state_cb_cls Closure for callback function.
 523  *
 524  * @return Handle that can be used to stop looking at objects.
 525  */
 526 struct GNUNET_SOCIAL_LookHandle *
 527 GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
 528                               const char *object_filter,
 529                               GNUNET_PSYC_StateCallback state_cb,
 530                               void *state_cb_cls);
 531
 532
 533 /**
 534  * Stop looking at objects.
 535  *
 536  * @param lh Look handle to stop.
 537  */
 538 void
 539 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
 540
 541
 542
 543 /**
 544  * Look at a particular object in the place.
 545  *
 546  * @param place The place to look the object at.
 547  * @param object_name Full name of the object.
 548  * @param value_size Set to the size of the returned value.
 549  * @return NULL if there is no such object at this place.
 550  */
 551 const void *
 552 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
 553                              const char *object_name,
 554                              size_t *value_size);
 555
 556
 557 /**
 558  * Flags for talking to the host of a place.
 559  */
 560 enum GNUNET_SOCIAL_TalkFlags;
 561
 562
 563 /**
 564  * A talk request.
 565  */
 566 struct GNUNET_SOCIAL_TalkRequest;
 567
 568 /**
 569  * Talk to the host of the place.
 570  *
 571  * @param place Place where we want to talk to the host.
 572  * @param method_name Method to invoke on the host.
 573  * @param env Environment containing variables for the message, or NULL.
 574  * @param notify Function to use to get the payload for the method.
 575  * @param notify_cls Closure for @a notify.
 576  * @param flags Flags for the message being sent.
 577  * @return NULL if we are already trying to talk to the host,
 578  *         otherwise handle to cancel the request.
 579  */
 580 struct GNUNET_SOCIAL_TalkRequest *
 581 GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
 582                           const char *method_name,
 583                           const struct GNUNET_ENV_Environment *env,
 584                           GNUNET_CONNECTION_TransmitReadyNotify notify,
 585                           void *notify_cls,
 586                           GNUNET_SOCIAL_TalkFlags flags);
 587
 588
 589 /**
 590  * Cancel talking to the host of the place.
 591  *
 592  * @param tr Talk request to cancel.
 593  */
 594 void
 595 GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr);
 596
 597
 598 /**
 599  * A history lesson.
 600  */
 601 struct GNUNET_SOCIAL_HistoryLesson;
 602
 603 /**
 604  * Learn about the history of a place.
 605  *
 606  * Sends messages through the slicer function of the place where
 607  * start_message_id <= message_id <= end_message_id.
 608  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 609  *
 610  * To get the latest message, use 0 for both the start and end message ID.
 611  *
 612  * @param place Place we want to learn more about.
 613  * @param start_message_id First historic message we are interested in.
 614  * @param end_message_id Last historic message we are interested in (inclusive).
 615  * @param slicer Slicer to use to process history.  Can be the same as the
 616  *               slicer of the place, as the HISTORIC flag allows distinguishing
 617  *               old messages from fresh ones.
 618  * @param finish_cb Function called after the last message if the history lesson
 619  *              is passed through the @a slicer. NULL if not needed.
 620  * @param finish_cb_cls Closure for @a finish_cb.
 621  * @return Handle to abort history lesson, never NULL (multiple lessons
 622  *         at the same time are allowed).
 623  */
 624 struct GNUNET_SOCIAL_HistoryLesson *
 625 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
 626                                  uint64_t start_message_id,
 627                                  uint64_t end_message_id,
 628                                  const struct GNUNET_SOCIAL_Slicer *slicer,
 629                                  void (*finish_cb)(void *),
 630                                  void *finish_cb_cls);
 631
 632
 633 /**
 634  * Stop processing messages from the history lesson.
 635  *
 636  * Must not be called after the finish callback of the history lesson is called.
 637  *
 638  * @param hist History lesson to cancel.
 639  */
 640 void
 641 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist);
 642
 643
 644 /**
 645  * Leave a place permanently.
 646  *
 647  * Notifies the owner of the place about leaving, and destroys the place handle.
 648  *
 649  * @param place Place to leave permanently.
 650  */
 651 void
 652 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place);
 653
 654
 655 /**
 656  * Leave a place temporarily.
 657  *
 658  * Stop following the conversation for the @a place and destroy the @a place
 659  * handle.  Only affects the application calling this function, other clients of
 660  * the service continue receiving the messages.
 661  *
 662  * @param place Place to leave temporarily.
 663  */
 664 void
 665 GNUNET_SOCIAL_place_away (struct GNUNET_SOCIAL_Place *place);
 666
 667
 668 #if 0                           /* keep Emacsens' auto-indent happy */
 669 {
 670 #endif
 671 #ifdef __cplusplus
 672 }
 673 #endif
 674
 675 /* ifndef GNUNET_SOCIAL_SERVICE_H */
 676 #endif
 677 /* end of gnunet_social_service.h */