src/social/social_api.c

   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 social/social_api.c
  23  * @brief Social service; implements social interactions using the PSYC service.
  24  * @author Gabor X Toth
  25  */
  26
  27 #include <inttypes.h>
  28
  29 #include "platform.h"
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_env_lib.h"
  32 #include "gnunet_psyc_service.h"
  33 #include "gnunet_social_service.h"
  34 #include "social.h"
  35
  36
  37 /**
  38  * Handle for a pseudonym of another user in the network.
  39  */
  40 struct GNUNET_SOCIAL_Nym
  41 {
  42
  43 };
  44
  45
  46 /**
  47  * Handle for a place where social interactions happen.
  48  */
  49 struct GNUNET_SOCIAL_Place
  50 {
  51
  52 };
  53
  54
  55 /**
  56  * Host handle for a place that we entered.
  57  */
  58 struct GNUNET_SOCIAL_Host
  59 {
  60
  61 };
  62
  63
  64 /**
  65  * Guest handle for place that we entered.
  66  */
  67 struct GNUNET_SOCIAL_Guest
  68 {
  69
  70 };
  71
  72
  73 /**
  74  * Handle to an implementation of try-and-slice.
  75  */
  76 struct GNUNET_SOCIAL_Slicer
  77 {
  78
  79 };
  80
  81
  82 /**
  83  * Handle for an announcement request.
  84  */
  85 struct GNUNET_SOCIAL_Announcement
  86 {
  87
  88 };
  89
  90
  91 struct GNUNET_SOCIAL_WatchHandle
  92 {
  93
  94 };
  95
  96
  97 struct GNUNET_SOCIAL_LookHandle
  98 {
  99
 100 };
 101
 102
 103 /**
 104  * A talk request.
 105  */
 106 struct GNUNET_SOCIAL_TalkRequest
 107 {
 108
 109 };
 110
 111
 112 /**
 113  * A history lesson.
 114  */
 115 struct GNUNET_SOCIAL_HistoryLesson
 116 {
 117
 118 };
 119
 120
 121
 122
 123 /**
 124  * Create a try-and-slice instance.
 125  *
 126  * @return A new try-and-slice construct.
 127  */
 128 struct GNUNET_SOCIAL_Slicer *
 129 GNUNET_SOCIAL_slicer_create (void)
 130 {
 131   return NULL;
 132 }
 133
 134
 135 /**
 136  * Add a method to the try-and-slice instance.
 137  *
 138  * A slicer processes messages and calls methods that match a message. A match
 139  * happens whenever the method name of a message starts with the method_name
 140  * parameter given here.
 141  *
 142  * @param slicer The try-and-slice instance to extend.
 143  * @param method_name Name of the given method, use empty string for default.
 144  * @param method Method to invoke.
 145  * @param method_cls Closure for method.
 146  */
 147 void
 148 GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer,
 149                           const char *method_name,
 150                           GNUNET_SOCIAL_MethodCallback method_cb,
 151                           void *cls)
 152 {
 153
 154 }
 155
 156
 157 /**
 158  * Remove a registered method from the try-and-slice instance.
 159  *
 160  * @param slicer The try-and-slice instance.
 161  * @param method_name Name of the method to remove.
 162  * @param method Method handler.
 163  */
 164 void
 165 GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer,
 166                              const char *method_name,
 167                              GNUNET_SOCIAL_MethodCallback method_cb)
 168 {
 169
 170 }
 171
 172 /**
 173  * Destroy a given try-and-slice instance.
 174  *
 175  * @param slicer slicer to destroy
 176  */
 177 void
 178 GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer)
 179 {
 180
 181 }
 182
 183
 184 /**
 185  * Enter a place as host.
 186  *
 187  * A place is created upon first entering, and it is active until permanently
 188  * left using GNUNET_SOCIAL_host_leave().
 189  *
 190  * @param cfg  Configuration to contact the social service.
 191  * @param place_keyfile  File with the private-public key pair of the place,
 192  *        created if the file does not exist; pass NULL for ephemeral places.
 193  * @param policy  Policy specifying entry and history restrictions of the place.
 194  * @param ego  Identity of the host.
 195  * @param slicer  Slicer to handle incoming messages.
 196  * @param listener_cb  Function to handle new nyms that want to enter.
 197  * @param farewell_cb  Function to handle departing nyms.
 198  * @param cls  Closure for @a listener_cb and @a farewell_cb.
 199  *
 200  * @return Handle for the host.
 201  */
 202 struct GNUNET_SOCIAL_Host *
 203 GNUNET_SOCIAL_host_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 204                           const char *place_keyfile,
 205                           enum GNUNET_PSYC_Policy policy,
 206                           struct GNUNET_IDENTITY_Ego *ego,
 207                           struct GNUNET_SOCIAL_Slicer *slicer,
 208                           GNUNET_SOCIAL_AnswerDoorCallback listener_cb,
 209                           GNUNET_SOCIAL_FarewellCallback farewell_cb,
 210                           void *cls)
 211 {
 212   return NULL;
 213 }
 214
 215
 216 /**
 217  * Admit @a nym to the place.
 218  *
 219  * The @a nym reference will remain valid until either the @a host or @a nym
 220  * leaves the place.
 221  *
 222  * @param host  Host of the place.
 223  * @param nym  Handle for the entity that wants to enter.
 224  */
 225 void
 226 GNUNET_SOCIAL_host_admit (struct GNUNET_SOCIAL_Host *host,
 227                           struct GNUNET_SOCIAL_Nym *nym)
 228 {
 229
 230 }
 231
 232
 233 /**
 234  * Throw @a nym out of the place.
 235  *
 236  * The @a nym reference will remain valid until the
 237  * #GNUNET_SOCIAL_FarewellCallback is invoked,
 238  * which should be very soon after this call.
 239  *
 240  * @param host  Host of the place.
 241  * @param nym  Handle for the entity to be ejected.
 242  */
 243 void
 244 GNUNET_SOCIAL_host_eject (struct GNUNET_SOCIAL_Host *host,
 245                           struct GNUNET_SOCIAL_Nym *nym)
 246 {
 247
 248 }
 249
 250
 251 /**
 252  * Refuse @a nym entry into the place.
 253  *
 254  * @param host  Host of the place.
 255  * @param nym Handle for the entity that wanted to enter.
 256  * @param method_name Method name for the rejection message.
 257  * @param env Environment containing variables for the message, or NULL.
 258  * @param data Data for the rejection message to send back.
 259  * @param data_size Number of bytes in @a data for method.
 260  */
 261 void
 262 GNUNET_SOCIAL_host_refuse_entry (struct GNUNET_SOCIAL_Host *host,
 263                                  struct GNUNET_SOCIAL_Nym *nym,
 264                                  const char *method_name,
 265                                  const struct GNUNET_ENV_Environment *env,
 266                                  const void *data,
 267                                  size_t data_size)
 268 {
 269
 270 }
 271
 272
 273 /**
 274  * Get the public key of a @a nym.
 275  *
 276  * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
 277  *
 278  * @param nym Pseudonym to map to a cryptographic identifier.
 279  * @param[out] nym_key Set to the public key of the nym.
 280  */
 281 void
 282 GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym,
 283                            struct GNUNET_CRYPTO_EddsaPublicKey *nym_key)
 284 {
 285
 286 }
 287
 288
 289 /**
 290  * Obtain the private-public key pair of the host.
 291  *
 292  * @param host  Host to get the key of.
 293  * @param[out] host_key  Set to the private-public key pair of the host.  The
 294  *                 public part is suitable for storing in GNS within a "PLACE"
 295  *                 record, along with peer IDs to join at.
 296  */
 297 void
 298 GNUNET_SOCIAL_host_get_key (struct GNUNET_SOCIAL_Host *host,
 299                             struct GNUNET_CRYPTO_EddsaPrivateKey *host_key)
 300 {
 301
 302 }
 303
 304
 305 /**
 306  * Advertise the place in the GNS zone of the @e ego of the @a host.
 307  *
 308  * @param host  Host of the place.
 309  * @param name The name for the PLACE record to put in the zone.
 310  * @param peer_count Number of elements in the @a peers array.
 311  * @param peers List of peers in the PLACE record that can be used to send join
 312  *        requests to.
 313  * @param expiration_time Expiration time of the record, use 0 to remove the record.
 314  * @param password Password used to encrypt the record.
 315  */
 316 void
 317 GNUNET_SOCIAL_host_advertise (struct GNUNET_SOCIAL_Host *host,
 318                               const char *name,
 319                               size_t peer_count,
 320                               const struct GNUNET_PeerIdentity *peers,
 321                               struct GNUNET_TIME_Relative expiration_time,
 322                               const char *password)
 323 {
 324
 325 }
 326
 327
 328 /**
 329  * Send a message to all nyms that are present in the place.
 330  *
 331  * This function is restricted to the host.  Nyms can only send requests
 332  * to the host who can decide to relay it to everyone in the place.
 333  *
 334  * @param host  Host of the place.
 335  * @param method_name Method to use for the announcement.
 336  * @param env  Environment containing variables for the message and operations
 337  *          on objects of the place.  Can be NULL.
 338  * @param notify Function to call to get the payload of the announcement.
 339  * @param notify_cls Closure for @a notify.
 340  * @param flags Flags for this announcement.
 341  *
 342  * @return NULL on error (announcement already in progress?).
 343  */
 344 struct GNUNET_SOCIAL_Announcement *
 345 GNUNET_SOCIAL_host_announce (struct GNUNET_SOCIAL_Host *host,
 346                              const char *method_name,
 347                              const struct GNUNET_ENV_Environment *env,
 348                              GNUNET_CONNECTION_TransmitReadyNotify notify,
 349                              void *notify_cls,
 350                              enum GNUNET_SOCIAL_AnnounceFlags flags)
 351 {
 352   return NULL;
 353 }
 354
 355
 356 /**
 357  * Cancel announcement.
 358  *
 359  * @param a The announcement to cancel.
 360  */
 361 void
 362 GNUNET_SOCIAL_host_announce_cancel (struct GNUNET_SOCIAL_Announcement *a)
 363 {
 364
 365 }
 366
 367
 368 /**
 369  * Obtain handle for a hosted place.
 370  *
 371  * The returned handle can be used to access the place API.
 372  *
 373  * @param host  Handle for the host.
 374  *
 375  * @return Handle for the hosted place, valid as long as @a host is valid.
 376  */
 377 struct GNUNET_SOCIAL_Place *
 378 GNUNET_SOCIAL_host_get_place (struct GNUNET_SOCIAL_Host *host)
 379 {
 380   return NULL;
 381 }
 382
 383
 384 /**
 385  * Stop hosting a place.
 386  *
 387  * Invalidates host handle.
 388  *
 389  * @param host  Host leaving the place.
 390  * @param keep_active  Keep the place active after last host disconnected.
 391  */
 392 void
 393 GNUNET_SOCIAL_host_leave (struct GNUNET_SOCIAL_Host *host, int keep_active)
 394 {
 395
 396 }
 397
 398
 399 /**
 400  * Request entry to a place as a guest.
 401  *
 402  * @param cfg  Configuration to contact the social service.
 403  * @param ego  Identity of the guest.
 404  * @param address GNS name of the place to enter.  Either in the form of
 405  *        'room.friend.gnu', or 'NYMPUBKEY.zkey'.  This latter case refers to
 406  *        the 'PLACE' record of the empty label ("+") in the GNS zone with the
 407  *        nym's public key 'NYMPUBKEY', and can be used to request entry to a
 408  *        pseudonym's place directly.
 409  * @param method_name Method name for the message.
 410  * @param env Environment containing variables for the message, or NULL.
 411  * @param data Payload for the message to give to the enter callback.
 412  * @param data_size Number of bytes in @a data.
 413  * @param slicer Slicer to use for processing incoming requests from guests.
 414  *
 415  * @return NULL on errors, otherwise handle for the guest.
 416  */
 417 struct GNUNET_SOCIAL_Guest *
 418 GNUNET_SOCIAL_guest_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 419                            struct GNUNET_IDENTITY_Ego *ego,
 420                            char *address,
 421                            const char *method_name,
 422                            const struct GNUNET_ENV_Environment *env,
 423                            const void *data,
 424                            size_t data_size,
 425                            struct GNUNET_SOCIAL_Slicer *slicer)
 426 {
 427   return NULL;
 428 }
 429
 430 /**
 431  * Request entry to a place as a guest.
 432  *
 433  * @param cfg Configuration to contact the social service.
 434  * @param ego  Identity of the guest.
 435  * @param crypto_address Public key of the place to enter.
 436  * @param origin Peer identity of the origin of the underlying multicast group.
 437  * @param relay_count Number of elements in the @a relays array.
 438  * @param relays Relays for the underlying multicast group.
 439  * @param method_name Method name for the message.
 440  * @param env Environment containing variables for the message, or NULL.
 441  * @param data Payload for the message to give to the enter callback.
 442  * @param data_size Number of bytes in @a data.
 443  * @param slicer Slicer to use for processing incoming requests from guests.
 444  *
 445  * @return NULL on errors, otherwise handle for the guest.
 446  */
 447 struct GNUNET_SOCIAL_Guest *
 448 GNUNET_SOCIAL_guest_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
 449                             struct GNUNET_IDENTITY_Ego *ego,
 450                             struct GNUNET_CRYPTO_EddsaPublicKey *crypto_address,
 451                             struct GNUNET_PeerIdentity *origin,
 452                             size_t relay_count,
 453                             struct GNUNET_PeerIdentity *relays,
 454                             const char *method_name,
 455                             const struct GNUNET_ENV_Environment *env,
 456                             const void *data,
 457                             size_t data_size,
 458                             struct GNUNET_SOCIAL_Slicer *slicer)
 459 {
 460   return NULL;
 461 }
 462
 463
 464 /**
 465  * Talk to the host of the place.
 466  *
 467  * @param place Place where we want to talk to the host.
 468  * @param method_name Method to invoke on the host.
 469  * @param env Environment containing variables for the message, or NULL.
 470  * @param notify Function to use to get the payload for the method.
 471  * @param notify_cls Closure for @a notify.
 472  * @param flags Flags for the message being sent.
 473  *
 474  * @return NULL if we are already trying to talk to the host,
 475  *         otherwise handle to cancel the request.
 476  */
 477 struct GNUNET_SOCIAL_TalkRequest *
 478 GNUNET_SOCIAL_guest_talk (struct GNUNET_SOCIAL_Place *place,
 479                           const char *method_name,
 480                           const struct GNUNET_ENV_Environment *env,
 481                           GNUNET_CONNECTION_TransmitReadyNotify notify,
 482                           void *notify_cls,
 483                           enum GNUNET_SOCIAL_TalkFlags flags)
 484 {
 485   return NULL;
 486 }
 487
 488
 489 /**
 490  * Cancel talking to the host of the place.
 491  *
 492  * @param tr Talk request to cancel.
 493  */
 494 void
 495 GNUNET_SOCIAL_guest_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr)
 496 {
 497
 498 }
 499
 500
 501 /**
 502  * Leave a place permanently.
 503  *
 504  * Notifies the owner of the place about leaving, and destroys the place handle.
 505  *
 506  * @param place Place to leave permanently.
 507  * @param keep_active Keep place active after last application disconnected.
 508  */
 509 void
 510 GNUNET_SOCIAL_guest_leave (struct GNUNET_SOCIAL_Place *place, int keep_active)
 511 {
 512
 513 }
 514
 515
 516 /**
 517  * Obtain handle for a place entered as guest.
 518  *
 519  * The returned handle can be used to access the place API.
 520  *
 521  * @param guest  Handle for the guest.
 522  *
 523  * @return Handle for the place, valid as long as @a guest is valid.
 524  */
 525 struct GNUNET_SOCIAL_Place *
 526 GNUNET_SOCIAL_guest_get_place (struct GNUNET_SOCIAL_Host *guest)
 527 {
 528   return NULL;
 529 }
 530
 531
 532 /**
 533  * A history lesson.
 534  */
 535 struct GNUNET_SOCIAL_HistoryLesson;
 536
 537 /**
 538  * Learn about the history of a place.
 539  *
 540  * Sends messages through the slicer function of the place where
 541  * start_message_id <= message_id <= end_message_id.
 542  * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set.
 543  *
 544  * To get the latest message, use 0 for both the start and end message ID.
 545  *
 546  * @param place Place we want to learn more about.
 547  * @param start_message_id First historic message we are interested in.
 548  * @param end_message_id Last historic message we are interested in (inclusive).
 549  * @param slicer Slicer to use to process history.  Can be the same as the
 550  *               slicer of the place, as the HISTORIC flag allows distinguishing
 551  *               old messages from fresh ones.
 552  * @param finish_cb Function called after the last message in the history lesson
 553  *              is passed through the @a slicer. NULL if not needed.
 554  * @param finish_cb_cls Closure for @a finish_cb.
 555  * @return Handle to abort history lesson, never NULL (multiple lessons
 556  *         at the same time are allowed).
 557  */
 558 struct GNUNET_SOCIAL_HistoryLesson *
 559 GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place,
 560                                  uint64_t start_message_id,
 561                                  uint64_t end_message_id,
 562                                  const struct GNUNET_SOCIAL_Slicer *slicer,
 563                                  void (*finish_cb)(void *),
 564                                  void *finish_cb_cls)
 565 {
 566   return NULL;
 567 }
 568
 569
 570 /**
 571  * Stop processing messages from the history lesson.
 572  *
 573  * Must not be called after the finish callback of the history lesson is called.
 574  *
 575  * @param hist History lesson to cancel.
 576  */
 577 void
 578 GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist)
 579 {
 580
 581 }
 582
 583
 584 struct GNUNET_SOCIAL_WatchHandle;
 585
 586 /**
 587  * Watch a place for changed objects.
 588  *
 589  * @param place Place to watch.
 590  * @param object_filter Object prefix to match.
 591  * @param state_cb Function to call when an object/state changes.
 592  * @param state_cb_cls Closure for callback.
 593  *
 594  * @return Handle that can be used to cancel watching.
 595  */
 596 struct GNUNET_SOCIAL_WatchHandle *
 597 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
 598                            const char *object_filter,
 599                            GNUNET_PSYC_StateCallback state_cb,
 600                            void *state_cb_cls)
 601 {
 602   return NULL;
 603 }
 604
 605
 606 /**
 607  * Cancel watching a place for changed objects.
 608  *
 609  * @param wh Watch handle to cancel.
 610  */
 611 void
 612 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh)
 613 {
 614
 615 }
 616
 617
 618 struct GNUNET_SOCIAL_LookHandle;
 619
 620
 621 /**
 622  * Look at objects in the place with a matching name prefix.
 623  *
 624  * @param place The place to look its objects at.
 625  * @param name_prefix Look at objects with names beginning with this value.
 626  * @param state_cb Function to call for each object found.
 627  * @param state_cb_cls Closure for callback function.
 628  *
 629  * @return Handle that can be used to stop looking at objects.
 630  */
 631 struct GNUNET_SOCIAL_LookHandle *
 632 GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place,
 633                           const char *name_prefix,
 634                           GNUNET_PSYC_StateCallback state_cb,
 635                           void *state_cb_cls)
 636 {
 637   return NULL;
 638 }
 639
 640
 641 /**
 642  * Stop looking at objects.
 643  *
 644  * @param lh Look handle to stop.
 645  */
 646 void
 647 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh)
 648 {
 649
 650 }
 651
 652
 653
 654 /**
 655  * Look at a particular object in the place.
 656  *
 657  * The best matching object is returned (its name might be less specific than
 658  * what was requested).
 659  *
 660  * @param place The place to look the object at.
 661  * @param full_name Full name of the object.
 662  * @param value_size Set to the size of the returned value.
 663  * @return NULL if there is no such object at this place.
 664  */
 665 const void *
 666 GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
 667                              const char *full_name,
 668                              size_t *value_size)
 669 {
 670   return NULL;
 671 }
 672
 673
 674
 675
 676 /* end of social_api.c */