aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_social_service.h
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2013-10-06 20:55:28 +0000
committerChristian Grothoff <christian@grothoff.org>2013-10-06 20:55:28 +0000
commit61c39c60565b386e0e12ea669556b030e8cd7180 (patch)
tree59109aeab8297bdc996faca8c4e38ec7426c36cf /src/include/gnunet_social_service.h
parent780eb09dd8040ecf8649d40ddf8314464e0fc48e (diff)
downloadgnunet-61c39c60565b386e0e12ea669556b030e8cd7180.tar.gz
gnunet-61c39c60565b386e0e12ea669556b030e8cd7180.zip
-remove trailing whitespace
Diffstat (limited to 'src/include/gnunet_social_service.h')
-rw-r--r--src/include/gnunet_social_service.h94
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 */
53struct GNUNET_SOCIAL_Nym; 53struct 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 */
58struct GNUNET_SOCIAL_Place; 58struct 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 */
63struct GNUNET_SOCIAL_Home; 63struct 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 */
68struct GNUNET_SOCIAL_Slicer; 68struct 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 *
110GNUNET_SOCIAL_slicer_create (void); 110GNUNET_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
150GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer); 150GNUNET_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 */
323enum GNUNET_PSYC_AnnouncementFlags 323enum 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 */
338struct GNUNET_SOCIAL_Announcement; 338struct 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
371GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a); 371GNUNET_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 *
383GNUNET_SOCIAL_home_get_place (struct GNUNET_SOCIAL_Home *home, int keep_active); 383GNUNET_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);
394void 394void
395GNUNET_SOCIAL_home_leave (struct GNUNET_SOCIAL_Home *home); 395GNUNET_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
454struct GNUNET_SOCIAL_WatchHandle; 454struct 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 */
466struct GNUNET_SOCIAL_WatchHandle * 466struct 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);
482struct GNUNET_SOCIAL_LookHandle; 482struct 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 */
495struct GNUNET_SOCIAL_LookHandle * 495struct 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,
532enum GNUNET_SOCIAL_TalkFlags; 532enum GNUNET_SOCIAL_TalkFlags;
533 533
534 534
535/** 535/**
536 * A talk request. 536 * A talk request.
537 */ 537 */
538struct GNUNET_SOCIAL_TalkRequest; 538struct 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
567GNUNET_SOCIAL_place_talk_cancel (struct GNUNET_SOCIAL_TalkRequest *tr); 567GNUNET_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 */
573struct GNUNET_SOCIAL_HistoryLesson; 573struct 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
613GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist); 613GNUNET_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 */