diff options
Diffstat (limited to 'src/include/gnunet_social_service.h')
-rw-r--r-- | src/include/gnunet_social_service.h | 94 |
1 files changed, 47 insertions, 47 deletions
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h index f53a2c28b..88a52b709 100644 --- a/src/include/gnunet_social_service.h +++ b/src/include/gnunet_social_service.h | |||
@@ -18,7 +18,7 @@ | |||
18 | Boston, MA 02111-1307, USA. | 18 | Boston, MA 02111-1307, USA. |
19 | */ | 19 | */ |
20 | 20 | ||
21 | /** | 21 | /** |
22 | * @file include/gnunet_social_service.h | 22 | * @file include/gnunet_social_service.h |
23 | * @brief Social service; implements social functionality using the PSYC service. | 23 | * @brief Social service; implements social functionality using the PSYC service. |
24 | * @author Gabor X Toth | 24 | * @author Gabor X Toth |
@@ -41,34 +41,34 @@ extern "C" | |||
41 | #include "gnunet_multicast_service.h" | 41 | #include "gnunet_multicast_service.h" |
42 | 42 | ||
43 | 43 | ||
44 | /** | 44 | /** |
45 | * Version number of GNUnet Social API. | 45 | * Version number of GNUnet Social API. |
46 | */ | 46 | */ |
47 | #define GNUNET_SOCIAL_VERSION 0x00000000 | 47 | #define GNUNET_SOCIAL_VERSION 0x00000000 |
48 | 48 | ||
49 | 49 | ||
50 | /** | 50 | /** |
51 | * Handle for another user (who is likely pseudonymous) in the network. | 51 | * Handle for another user (who is likely pseudonymous) in the network. |
52 | */ | 52 | */ |
53 | struct GNUNET_SOCIAL_Nym; | 53 | struct GNUNET_SOCIAL_Nym; |
54 | 54 | ||
55 | /** | 55 | /** |
56 | * Handle for a place where social interactions happen. | 56 | * Handle for a place where social interactions happen. |
57 | */ | 57 | */ |
58 | struct GNUNET_SOCIAL_Place; | 58 | struct GNUNET_SOCIAL_Place; |
59 | 59 | ||
60 | /** | 60 | /** |
61 | * Handle for a place that one of our egos hosts. | 61 | * Handle for a place that one of our egos hosts. |
62 | */ | 62 | */ |
63 | struct GNUNET_SOCIAL_Home; | 63 | struct GNUNET_SOCIAL_Home; |
64 | 64 | ||
65 | /** | 65 | /** |
66 | * Handle to an implementation of try-and-slice. | 66 | * Handle to an implementation of try-and-slice. |
67 | */ | 67 | */ |
68 | struct GNUNET_SOCIAL_Slicer; | 68 | struct GNUNET_SOCIAL_Slicer; |
69 | 69 | ||
70 | 70 | ||
71 | /** | 71 | /** |
72 | * Method called from SOCIAL upon receiving a message indicating a call | 72 | * Method called from SOCIAL upon receiving a message indicating a call |
73 | * to a @e method. | 73 | * to a @e method. |
74 | * | 74 | * |
@@ -101,7 +101,7 @@ typedef int | |||
101 | enum GNUNET_PSYC_MessageFlags flags); | 101 | enum GNUNET_PSYC_MessageFlags flags); |
102 | 102 | ||
103 | 103 | ||
104 | /** | 104 | /** |
105 | * Create a try-and-slice instance. | 105 | * Create a try-and-slice instance. |
106 | * | 106 | * |
107 | * @return A new try-and-slice construct. | 107 | * @return A new try-and-slice construct. |
@@ -110,7 +110,7 @@ struct GNUNET_SOCIAL_Slicer * | |||
110 | GNUNET_SOCIAL_slicer_create (void); | 110 | GNUNET_SOCIAL_slicer_create (void); |
111 | 111 | ||
112 | 112 | ||
113 | /** | 113 | /** |
114 | * Add a method to the try-and-slice instance. | 114 | * Add a method to the try-and-slice instance. |
115 | * | 115 | * |
116 | * A slicer processes messages and calls methods that match a message. A match | 116 | * A slicer processes messages and calls methods that match a message. A match |
@@ -129,7 +129,7 @@ GNUNET_SOCIAL_slicer_add (struct GNUNET_SOCIAL_Slicer *slicer, | |||
129 | void *method_cls); | 129 | void *method_cls); |
130 | 130 | ||
131 | 131 | ||
132 | /** | 132 | /** |
133 | * Remove a registered method from the try-and-slice instance. | 133 | * Remove a registered method from the try-and-slice instance. |
134 | * | 134 | * |
135 | * @param slicer The try-and-slice instance. | 135 | * @param slicer The try-and-slice instance. |
@@ -141,7 +141,7 @@ GNUNET_SOCIAL_slicer_remove (struct GNUNET_SOCIAL_Slicer *slicer, | |||
141 | const char *method_name, | 141 | const char *method_name, |
142 | GNUNET_SOCIAL_Method method); | 142 | GNUNET_SOCIAL_Method method); |
143 | 143 | ||
144 | /** | 144 | /** |
145 | * Destroy a given try-and-slice instance. | 145 | * Destroy a given try-and-slice instance. |
146 | * | 146 | * |
147 | * @param slicer slicer to destroy | 147 | * @param slicer slicer to destroy |
@@ -150,7 +150,7 @@ void | |||
150 | GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer); | 150 | GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer); |
151 | 151 | ||
152 | 152 | ||
153 | /** | 153 | /** |
154 | * Function called asking for nym to be admitted to the place. | 154 | * Function called asking for nym to be admitted to the place. |
155 | * | 155 | * |
156 | * Should call either GNUNET_SOCIAL_home_admit() or | 156 | * Should call either GNUNET_SOCIAL_home_admit() or |
@@ -178,9 +178,9 @@ typedef void | |||
178 | size_t data_size); | 178 | size_t data_size); |
179 | 179 | ||
180 | 180 | ||
181 | /** | 181 | /** |
182 | * Function called when a @a nym leaves the place. | 182 | * Function called when a @a nym leaves the place. |
183 | * | 183 | * |
184 | * This is also called if the @a nym was never given permission to enter | 184 | * This is also called if the @a nym was never given permission to enter |
185 | * (i.e. the @a nym stopped asking to get in). | 185 | * (i.e. the @a nym stopped asking to get in). |
186 | * | 186 | * |
@@ -196,7 +196,7 @@ typedef void | |||
196 | GNUNET_PSYC_Modifier *variables); | 196 | GNUNET_PSYC_Modifier *variables); |
197 | 197 | ||
198 | 198 | ||
199 | /** | 199 | /** |
200 | * Enter a home where guests (nyms) can be hosted. | 200 | * Enter a home where guests (nyms) can be hosted. |
201 | * | 201 | * |
202 | * A home is created upon first entering, and exists until | 202 | * A home is created upon first entering, and exists until |
@@ -225,7 +225,7 @@ GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
225 | void *cls); | 225 | void *cls); |
226 | 226 | ||
227 | 227 | ||
228 | /** | 228 | /** |
229 | * Admit @a nym to the @a home. | 229 | * Admit @a nym to the @a home. |
230 | * | 230 | * |
231 | * The @a nym reference will remain valid until either the home is destroyed or | 231 | * The @a nym reference will remain valid until either the home is destroyed or |
@@ -239,7 +239,7 @@ GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home, | |||
239 | struct GNUNET_SOCIAL_Nym *nym); | 239 | struct GNUNET_SOCIAL_Nym *nym); |
240 | 240 | ||
241 | 241 | ||
242 | /** | 242 | /** |
243 | * Throw @a nym out of the @a home. | 243 | * Throw @a nym out of the @a home. |
244 | * | 244 | * |
245 | * The @a nym reference will remain valid until the | 245 | * The @a nym reference will remain valid until the |
@@ -254,7 +254,7 @@ GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home, | |||
254 | struct GNUNET_SOCIAL_Nym *nym); | 254 | struct GNUNET_SOCIAL_Nym *nym); |
255 | 255 | ||
256 | 256 | ||
257 | /** | 257 | /** |
258 | * Refuse @a nym entry into the @a home. | 258 | * Refuse @a nym entry into the @a home. |
259 | * | 259 | * |
260 | * @param home Home to disallow @a nym to enter. | 260 | * @param home Home to disallow @a nym to enter. |
@@ -273,7 +273,7 @@ GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home, | |||
273 | size_t data_size); | 273 | size_t data_size); |
274 | 274 | ||
275 | 275 | ||
276 | /** | 276 | /** |
277 | * Get the public key of a nym. | 277 | * Get the public key of a nym. |
278 | * | 278 | * |
279 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). | 279 | * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name(). |
@@ -286,9 +286,9 @@ GNUNET_SOCIAL_nym_get_key (struct GNUNET_SOCIAL_Nym *nym, | |||
286 | struct GNUNET_CRYPTO_EccPublicSignKey *nym_key); | 286 | struct GNUNET_CRYPTO_EccPublicSignKey *nym_key); |
287 | 287 | ||
288 | 288 | ||
289 | /** | 289 | /** |
290 | * Obtain the private-public key pair of the home. | 290 | * Obtain the private-public key pair of the home. |
291 | * | 291 | * |
292 | * @param home Home to get the key of. | 292 | * @param home Home to get the key of. |
293 | * @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. | 293 | * @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. |
294 | */ | 294 | */ |
@@ -297,7 +297,7 @@ GNUNET_SOCIAL_home_get_key (struct GNUNET_SOCIAL_Home *home, | |||
297 | struct GNUNET_CRYPTO_EccPrivateKey *home_key); | 297 | struct GNUNET_CRYPTO_EccPrivateKey *home_key); |
298 | 298 | ||
299 | 299 | ||
300 | /** | 300 | /** |
301 | * Advertise @a home under @a name in the GNS zone of the @e ego. | 301 | * Advertise @a home under @a name in the GNS zone of the @e ego. |
302 | * | 302 | * |
303 | * @param home The home to advertise. | 303 | * @param home The home to advertise. |
@@ -322,9 +322,9 @@ GNUNET_SOCIAL_home_advertise (struct GNUNET_SOCIAL_Home *home, | |||
322 | */ | 322 | */ |
323 | enum GNUNET_PSYC_AnnouncementFlags | 323 | enum GNUNET_PSYC_AnnouncementFlags |
324 | { | 324 | { |
325 | /** | 325 | /** |
326 | * Whether this announcement removes all objects from the home. | 326 | * Whether this announcement removes all objects from the home. |
327 | * | 327 | * |
328 | * New objects can be still added to the now empty home using the @e env | 328 | * New objects can be still added to the now empty home using the @e env |
329 | * parameter of the same announcement. | 329 | * parameter of the same announcement. |
330 | */ | 330 | */ |
@@ -332,13 +332,13 @@ enum GNUNET_PSYC_AnnouncementFlags | |||
332 | }; | 332 | }; |
333 | 333 | ||
334 | 334 | ||
335 | /** | 335 | /** |
336 | * Handle for an announcement request. | 336 | * Handle for an announcement request. |
337 | */ | 337 | */ |
338 | struct GNUNET_SOCIAL_Announcement; | 338 | struct GNUNET_SOCIAL_Announcement; |
339 | 339 | ||
340 | 340 | ||
341 | /** | 341 | /** |
342 | * Send a message to all nyms that are present in the home. | 342 | * Send a message to all nyms that are present in the home. |
343 | * | 343 | * |
344 | * This function is restricted to the home owner. Nyms can only send requests | 344 | * This function is restricted to the home owner. Nyms can only send requests |
@@ -362,7 +362,7 @@ GNUNET_SOCIAL_home_announce (struct GNUNET_SOCIAL_Home *home, | |||
362 | GNUNET_SOCIAL_AnnouncementFlags flags); | 362 | GNUNET_SOCIAL_AnnouncementFlags flags); |
363 | 363 | ||
364 | 364 | ||
365 | /** | 365 | /** |
366 | * Cancel announcement. | 366 | * Cancel announcement. |
367 | * | 367 | * |
368 | * @param a The announcement to cancel. | 368 | * @param a The announcement to cancel. |
@@ -371,7 +371,7 @@ void | |||
371 | GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); | 371 | GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); |
372 | 372 | ||
373 | 373 | ||
374 | /** | 374 | /** |
375 | * Convert our home to a place so we can access it via the place API. | 375 | * Convert our home to a place so we can access it via the place API. |
376 | * | 376 | * |
377 | * @param home Handle for the home. | 377 | * @param home Handle for the home. |
@@ -383,7 +383,7 @@ struct GNUNET_SOCIAL_Place * | |||
383 | GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home, int keep_active); | 383 | GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home, int keep_active); |
384 | 384 | ||
385 | 385 | ||
386 | /** | 386 | /** |
387 | * Leave a home. | 387 | * Leave a home. |
388 | 388 | ||
389 | * Invalidates home handle. | 389 | * Invalidates home handle. |
@@ -394,7 +394,7 @@ GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home, int keep_active); | |||
394 | void | 394 | void |
395 | GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home); | 395 | GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home); |
396 | 396 | ||
397 | /** | 397 | /** |
398 | * Request entry to a place (home hosted by someone else). | 398 | * Request entry to a place (home hosted by someone else). |
399 | * | 399 | * |
400 | * @param cfg Configuration to contact the social service. | 400 | * @param cfg Configuration to contact the social service. |
@@ -421,7 +421,7 @@ GNUNET_SOCIAL_place_enter (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
421 | size_t data_size, | 421 | size_t data_size, |
422 | struct GNUNET_SOCIAL_Slicer *slicer); | 422 | struct GNUNET_SOCIAL_Slicer *slicer); |
423 | 423 | ||
424 | /** | 424 | /** |
425 | * Request entry to a place (home hosted by someone else). | 425 | * Request entry to a place (home hosted by someone else). |
426 | * | 426 | * |
427 | * @param cfg Configuration to contact the social service. | 427 | * @param cfg Configuration to contact the social service. |
@@ -453,14 +453,14 @@ GNUNET_SOCIAL_place_enter2 (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
453 | 453 | ||
454 | struct GNUNET_SOCIAL_WatchHandle; | 454 | struct GNUNET_SOCIAL_WatchHandle; |
455 | 455 | ||
456 | /** | 456 | /** |
457 | * Watch a place for changed objects. | 457 | * Watch a place for changed objects. |
458 | * | 458 | * |
459 | * @param place Place to watch. | 459 | * @param place Place to watch. |
460 | * @param object_filter Object prefix to match. | 460 | * @param object_filter Object prefix to match. |
461 | * @param state_cb Function to call when an object/state changes. | 461 | * @param state_cb Function to call when an object/state changes. |
462 | * @param state_cb_cls Closure for callback. | 462 | * @param state_cb_cls Closure for callback. |
463 | * | 463 | * |
464 | * @return Handle that can be used to cancel watching. | 464 | * @return Handle that can be used to cancel watching. |
465 | */ | 465 | */ |
466 | struct GNUNET_SOCIAL_WatchHandle * | 466 | struct GNUNET_SOCIAL_WatchHandle * |
@@ -470,7 +470,7 @@ GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place, | |||
470 | void *state_cb_cls); | 470 | void *state_cb_cls); |
471 | 471 | ||
472 | 472 | ||
473 | /** | 473 | /** |
474 | * Cancel watching a place for changed objects. | 474 | * Cancel watching a place for changed objects. |
475 | * | 475 | * |
476 | * @param wh Watch handle to cancel. | 476 | * @param wh Watch handle to cancel. |
@@ -482,14 +482,14 @@ GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh); | |||
482 | struct GNUNET_SOCIAL_LookHandle; | 482 | struct GNUNET_SOCIAL_LookHandle; |
483 | 483 | ||
484 | 484 | ||
485 | /** | 485 | /** |
486 | * Look at objects in the place with a matching name prefix. | 486 | * Look at objects in the place with a matching name prefix. |
487 | * | 487 | * |
488 | * @param place The place to look its objects at. | 488 | * @param place The place to look its objects at. |
489 | * @param name_prefix Look at objects with names beginning with this value. | 489 | * @param name_prefix Look at objects with names beginning with this value. |
490 | * @param state_cb Function to call for each object found. | 490 | * @param state_cb Function to call for each object found. |
491 | * @param state_cb_cls Closure for callback function. | 491 | * @param state_cb_cls Closure for callback function. |
492 | * | 492 | * |
493 | * @return Handle that can be used to stop looking at objects. | 493 | * @return Handle that can be used to stop looking at objects. |
494 | */ | 494 | */ |
495 | struct GNUNET_SOCIAL_LookHandle * | 495 | struct GNUNET_SOCIAL_LookHandle * |
@@ -499,7 +499,7 @@ GNUNET_SOCIAL_place_look (struct GNUNET_SOCIAL_Place *place, | |||
499 | void *state_cb_cls); | 499 | void *state_cb_cls); |
500 | 500 | ||
501 | 501 | ||
502 | /** | 502 | /** |
503 | * Stop looking at objects. | 503 | * Stop looking at objects. |
504 | * | 504 | * |
505 | * @param lh Look handle to stop. | 505 | * @param lh Look handle to stop. |
@@ -509,7 +509,7 @@ GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh); | |||
509 | 509 | ||
510 | 510 | ||
511 | 511 | ||
512 | /** | 512 | /** |
513 | * Look at a particular object in the place. | 513 | * Look at a particular object in the place. |
514 | * | 514 | * |
515 | * The best matching object is returned (its name might be less specific than | 515 | * The best matching object is returned (its name might be less specific than |
@@ -532,12 +532,12 @@ GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place, | |||
532 | enum GNUNET_SOCIAL_TalkFlags; | 532 | enum GNUNET_SOCIAL_TalkFlags; |
533 | 533 | ||
534 | 534 | ||
535 | /** | 535 | /** |
536 | * A talk request. | 536 | * A talk request. |
537 | */ | 537 | */ |
538 | struct GNUNET_SOCIAL_TalkRequest; | 538 | struct GNUNET_SOCIAL_TalkRequest; |
539 | 539 | ||
540 | /** | 540 | /** |
541 | * Talk to the host of the place. | 541 | * Talk to the host of the place. |
542 | * | 542 | * |
543 | * @param place Place where we want to talk to the host. | 543 | * @param place Place where we want to talk to the host. |
@@ -558,7 +558,7 @@ GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place, | |||
558 | GNUNET_SOCIAL_TalkFlags flags); | 558 | GNUNET_SOCIAL_TalkFlags flags); |
559 | 559 | ||
560 | 560 | ||
561 | /** | 561 | /** |
562 | * Cancel talking to the host of the place. | 562 | * Cancel talking to the host of the place. |
563 | * | 563 | * |
564 | * @param tr Talk request to cancel. | 564 | * @param tr Talk request to cancel. |
@@ -567,12 +567,12 @@ void | |||
567 | GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); | 567 | GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); |
568 | 568 | ||
569 | 569 | ||
570 | /** | 570 | /** |
571 | * A history lesson. | 571 | * A history lesson. |
572 | */ | 572 | */ |
573 | struct GNUNET_SOCIAL_HistoryLesson; | 573 | struct GNUNET_SOCIAL_HistoryLesson; |
574 | 574 | ||
575 | /** | 575 | /** |
576 | * Learn about the history of a place. | 576 | * Learn about the history of a place. |
577 | * | 577 | * |
578 | * Sends messages through the slicer function of the place where | 578 | * Sends messages through the slicer function of the place where |
@@ -580,7 +580,7 @@ struct GNUNET_SOCIAL_HistoryLesson; | |||
580 | * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. | 580 | * The messages will have the #GNUNET_PSYC_MESSAGE_HISTORIC flag set. |
581 | * | 581 | * |
582 | * To get the latest message, use 0 for both the start and end message ID. | 582 | * To get the latest message, use 0 for both the start and end message ID. |
583 | * | 583 | * |
584 | * @param place Place we want to learn more about. | 584 | * @param place Place we want to learn more about. |
585 | * @param start_message_id First historic message we are interested in. | 585 | * @param start_message_id First historic message we are interested in. |
586 | * @param end_message_id Last historic message we are interested in (inclusive). | 586 | * @param end_message_id Last historic message we are interested in (inclusive). |
@@ -602,7 +602,7 @@ GNUNET_SOCIAL_place_get_history (struct GNUNET_SOCIAL_Place *place, | |||
602 | void *finish_cb_cls); | 602 | void *finish_cb_cls); |
603 | 603 | ||
604 | 604 | ||
605 | /** | 605 | /** |
606 | * Stop processing messages from the history lesson. | 606 | * Stop processing messages from the history lesson. |
607 | * | 607 | * |
608 | * Must not be called after the finish callback of the history lesson is called. | 608 | * Must not be called after the finish callback of the history lesson is called. |
@@ -613,11 +613,11 @@ void | |||
613 | GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist); | 613 | GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist); |
614 | 614 | ||
615 | 615 | ||
616 | /** | 616 | /** |
617 | * Leave a place permanently. | 617 | * Leave a place permanently. |
618 | * | 618 | * |
619 | * Notifies the owner of the place about leaving, and destroys the place handle. | 619 | * Notifies the owner of the place about leaving, and destroys the place handle. |
620 | * | 620 | * |
621 | * @param place Place to leave permanently. | 621 | * @param place Place to leave permanently. |
622 | * @param keep_active Keep place active after last application disconnected. | 622 | * @param keep_active Keep place active after last application disconnected. |
623 | */ | 623 | */ |