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