diff options
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r-- | src/include/gnunet_psyc_service.h | 86 |
1 files changed, 43 insertions, 43 deletions
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h index 4addfa4d9..e9f935de7 100644 --- a/src/include/gnunet_psyc_service.h +++ b/src/include/gnunet_psyc_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_psyc_service.h | 22 | * @file include/gnunet_psyc_service.h |
23 | * @brief PSYC service; high-level access to the PSYC protocol | 23 | * @brief PSYC service; high-level access to the PSYC protocol |
24 | * note that clients of this API are NOT expected to | 24 | * note that clients of this API are NOT expected to |
@@ -90,13 +90,13 @@ extern "C" | |||
90 | #include "gnunet_multicast_service.h" | 90 | #include "gnunet_multicast_service.h" |
91 | 91 | ||
92 | 92 | ||
93 | /** | 93 | /** |
94 | * Version number of GNUnet-PSYC API. | 94 | * Version number of GNUnet-PSYC API. |
95 | */ | 95 | */ |
96 | #define GNUNET_PSYC_VERSION 0x00000000 | 96 | #define GNUNET_PSYC_VERSION 0x00000000 |
97 | 97 | ||
98 | 98 | ||
99 | /** | 99 | /** |
100 | * Policy flags for a channel. | 100 | * Policy flags for a channel. |
101 | */ | 101 | */ |
102 | enum GNUNET_PSYC_ChannelFlags | 102 | enum GNUNET_PSYC_ChannelFlags |
@@ -113,7 +113,7 @@ enum GNUNET_PSYC_ChannelFlags | |||
113 | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1, | 113 | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY = 1 << 1, |
114 | }; | 114 | }; |
115 | 115 | ||
116 | /** | 116 | /** |
117 | * PSYC channel policies. | 117 | * PSYC channel policies. |
118 | */ | 118 | */ |
119 | enum GNUNET_PSYC_Policy | 119 | enum GNUNET_PSYC_Policy |
@@ -125,7 +125,7 @@ enum GNUNET_PSYC_Policy | |||
125 | */ | 125 | */ |
126 | GNUNET_PSYC_CHANNEL_ANONYMOUS = 0, | 126 | GNUNET_PSYC_CHANNEL_ANONYMOUS = 0, |
127 | 127 | ||
128 | /** | 128 | /** |
129 | * The master must approve membership to the channel, messages must only be | 129 | * The master must approve membership to the channel, messages must only be |
130 | * distributed to current channel slaves. This includes the channel | 130 | * distributed to current channel slaves. This includes the channel |
131 | * state as well as transient messages. | 131 | * state as well as transient messages. |
@@ -135,7 +135,7 @@ enum GNUNET_PSYC_Policy | |||
135 | | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY, | 135 | | GNUNET_PSYC_CHANNEL_RESTRICTED_HISTORY, |
136 | 136 | ||
137 | #if IDEAS_FOR_FUTURE | 137 | #if IDEAS_FOR_FUTURE |
138 | /** | 138 | /** |
139 | * Anyone can freely join the channel (no approval required); | 139 | * Anyone can freely join the channel (no approval required); |
140 | * however, messages must only be distributed to current channel | 140 | * however, messages must only be distributed to current channel |
141 | * slaves, so the master must still acknowledge that the slave | 141 | * slaves, so the master must still acknowledge that the slave |
@@ -170,7 +170,7 @@ enum GNUNET_PSYC_MessageFlags | |||
170 | */ | 170 | */ |
171 | GNUNET_PSYC_MESSAGE_LAST_FRAGMENT = 1 << 1, | 171 | GNUNET_PSYC_MESSAGE_LAST_FRAGMENT = 1 << 1, |
172 | 172 | ||
173 | /** | 173 | /** |
174 | * OR'ed flags if message is not fragmented. | 174 | * OR'ed flags if message is not fragmented. |
175 | */ | 175 | */ |
176 | GNUNET_PSYC_MESSAGE_NOT_FRAGMENTED | 176 | GNUNET_PSYC_MESSAGE_NOT_FRAGMENTED |
@@ -274,7 +274,7 @@ struct GNUNET_PSYC_MessageData | |||
274 | uint8_t status; | 274 | uint8_t status; |
275 | }; | 275 | }; |
276 | 276 | ||
277 | /** | 277 | /** |
278 | * Handle that identifies a join request. | 278 | * Handle that identifies a join request. |
279 | * | 279 | * |
280 | * Used to match calls to #GNUNET_PSYC_JoinCallback to the | 280 | * Used to match calls to #GNUNET_PSYC_JoinCallback to the |
@@ -283,7 +283,7 @@ struct GNUNET_PSYC_MessageData | |||
283 | struct GNUNET_PSYC_JoinHandle; | 283 | struct GNUNET_PSYC_JoinHandle; |
284 | 284 | ||
285 | 285 | ||
286 | /** | 286 | /** |
287 | * Method called from PSYC upon receiving a message indicating a call to a | 287 | * Method called from PSYC upon receiving a message indicating a call to a |
288 | * @e method. | 288 | * @e method. |
289 | * | 289 | * |
@@ -316,7 +316,7 @@ typedef int | |||
316 | enum GNUNET_PSYC_MessageFlags flags); | 316 | enum GNUNET_PSYC_MessageFlags flags); |
317 | 317 | ||
318 | 318 | ||
319 | /** | 319 | /** |
320 | * Method called from PSYC upon receiving a join request. | 320 | * Method called from PSYC upon receiving a join request. |
321 | * | 321 | * |
322 | * @param cls Closure. | 322 | * @param cls Closure. |
@@ -341,7 +341,7 @@ typedef int | |||
341 | struct GNUNET_PSYC_JoinHandle *jh); | 341 | struct GNUNET_PSYC_JoinHandle *jh); |
342 | 342 | ||
343 | 343 | ||
344 | /** | 344 | /** |
345 | * Function to call with the decision made for a join request. | 345 | * Function to call with the decision made for a join request. |
346 | * | 346 | * |
347 | * Must be called once and only once in response to an invocation of the | 347 | * Must be called once and only once in response to an invocation of the |
@@ -375,13 +375,13 @@ GNUNET_PSYC_join_decision (struct GNUNET_PSYC_JoinHandle *jh, | |||
375 | size_t data_size); | 375 | size_t data_size); |
376 | 376 | ||
377 | 377 | ||
378 | /** | 378 | /** |
379 | * Handle for the master of a PSYC channel. | 379 | * Handle for the master of a PSYC channel. |
380 | */ | 380 | */ |
381 | struct GNUNET_PSYC_Master; | 381 | struct GNUNET_PSYC_Master; |
382 | 382 | ||
383 | 383 | ||
384 | /** | 384 | /** |
385 | * Function called after the channel master started. | 385 | * Function called after the channel master started. |
386 | * | 386 | * |
387 | * @param cls Closure. | 387 | * @param cls Closure. |
@@ -391,7 +391,7 @@ typedef void | |||
391 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id); | 391 | (*GNUNET_PSYC_MasterStartCallback) (void *cls, uint64_t max_message_id); |
392 | 392 | ||
393 | 393 | ||
394 | /** | 394 | /** |
395 | * Start a PSYC master channel. | 395 | * Start a PSYC master channel. |
396 | * | 396 | * |
397 | * Will start a multicast group identified by the given ECC key. Messages | 397 | * Will start a multicast group identified by the given ECC key. Messages |
@@ -429,7 +429,7 @@ GNUNET_PSYC_master_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
429 | void *cls); | 429 | void *cls); |
430 | 430 | ||
431 | 431 | ||
432 | /** | 432 | /** |
433 | * Function called to provide data for a transmission via PSYC. | 433 | * Function called to provide data for a transmission via PSYC. |
434 | * | 434 | * |
435 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) | 435 | * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO) |
@@ -459,13 +459,13 @@ typedef int | |||
459 | enum GNUNET_PSYC_MasterTransmitFlags | 459 | enum GNUNET_PSYC_MasterTransmitFlags |
460 | { | 460 | { |
461 | GNUNET_PSYC_MASTER_TRANSMIT_NONE = 0, | 461 | GNUNET_PSYC_MASTER_TRANSMIT_NONE = 0, |
462 | /** | 462 | /** |
463 | * Whether this message should reset the channel state, | 463 | * Whether this message should reset the channel state, |
464 | * i.e. remove all previously stored state variables. | 464 | * i.e. remove all previously stored state variables. |
465 | */ | 465 | */ |
466 | GNUNET_PSYC_MASTER_TRANSMIT_RESET_STATE = 1 << 0, | 466 | GNUNET_PSYC_MASTER_TRANSMIT_RESET_STATE = 1 << 0, |
467 | 467 | ||
468 | /** | 468 | /** |
469 | * Whether we need to increment the group generation counter after | 469 | * Whether we need to increment the group generation counter after |
470 | * transmitting this message. | 470 | * transmitting this message. |
471 | */ | 471 | */ |
@@ -478,13 +478,13 @@ enum GNUNET_PSYC_MasterTransmitFlags | |||
478 | }; | 478 | }; |
479 | 479 | ||
480 | 480 | ||
481 | /** | 481 | /** |
482 | * Handle for a pending PSYC transmission operation. | 482 | * Handle for a pending PSYC transmission operation. |
483 | */ | 483 | */ |
484 | struct GNUNET_PSYC_MasterTransmitHandle; | 484 | struct GNUNET_PSYC_MasterTransmitHandle; |
485 | 485 | ||
486 | 486 | ||
487 | /** | 487 | /** |
488 | * Send a message to call a method to all members in the PSYC channel. | 488 | * Send a message to call a method to all members in the PSYC channel. |
489 | * | 489 | * |
490 | * @param master Handle to the PSYC channel. | 490 | * @param master Handle to the PSYC channel. |
@@ -505,7 +505,7 @@ GNUNET_PSYC_master_transmit (struct GNUNET_PSYC_Master *master, | |||
505 | enum GNUNET_PSYC_MasterTransmitFlags flags); | 505 | enum GNUNET_PSYC_MasterTransmitFlags flags); |
506 | 506 | ||
507 | 507 | ||
508 | /** | 508 | /** |
509 | * Resume transmission to the channel. | 509 | * Resume transmission to the channel. |
510 | * | 510 | * |
511 | * @param th Handle of the request that is being resumed. | 511 | * @param th Handle of the request that is being resumed. |
@@ -514,7 +514,7 @@ void | |||
514 | GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); | 514 | GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); |
515 | 515 | ||
516 | 516 | ||
517 | /** | 517 | /** |
518 | * Abort transmission request to channel. | 518 | * Abort transmission request to channel. |
519 | * | 519 | * |
520 | * @param th Handle of the request that is being aborted. | 520 | * @param th Handle of the request that is being aborted. |
@@ -523,7 +523,7 @@ void | |||
523 | GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th); | 523 | GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th); |
524 | 524 | ||
525 | 525 | ||
526 | /** | 526 | /** |
527 | * Stop a PSYC master channel. | 527 | * Stop a PSYC master channel. |
528 | * | 528 | * |
529 | * @param master PSYC channel master to stop. | 529 | * @param master PSYC channel master to stop. |
@@ -532,13 +532,13 @@ void | |||
532 | GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *master); | 532 | GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *master); |
533 | 533 | ||
534 | 534 | ||
535 | /** | 535 | /** |
536 | * Handle for a PSYC channel slave. | 536 | * Handle for a PSYC channel slave. |
537 | */ | 537 | */ |
538 | struct GNUNET_PSYC_Slave; | 538 | struct GNUNET_PSYC_Slave; |
539 | 539 | ||
540 | 540 | ||
541 | /** | 541 | /** |
542 | * Function called after the slave joined. | 542 | * Function called after the slave joined. |
543 | * | 543 | * |
544 | * @param cls Closure. | 544 | * @param cls Closure. |
@@ -548,7 +548,7 @@ typedef void | |||
548 | (*GNUNET_PSYC_SlaveJoinCallback) (void *cls, uint64_t max_message_id); | 548 | (*GNUNET_PSYC_SlaveJoinCallback) (void *cls, uint64_t max_message_id); |
549 | 549 | ||
550 | 550 | ||
551 | /** | 551 | /** |
552 | * Join a PSYC channel. | 552 | * Join a PSYC channel. |
553 | * | 553 | * |
554 | * The entity joining is always the local peer. The user must immediately use | 554 | * The entity joining is always the local peer. The user must immediately use |
@@ -594,7 +594,7 @@ GNUNET_PSYC_slave_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
594 | size_t data_size); | 594 | size_t data_size); |
595 | 595 | ||
596 | 596 | ||
597 | /** | 597 | /** |
598 | * Part a PSYC channel. | 598 | * Part a PSYC channel. |
599 | * | 599 | * |
600 | * Will terminate the connection to the PSYC service. Polite clients should | 600 | * Will terminate the connection to the PSYC service. Polite clients should |
@@ -606,7 +606,7 @@ void | |||
606 | GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave); | 606 | GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave); |
607 | 607 | ||
608 | 608 | ||
609 | /** | 609 | /** |
610 | * Function called to provide data for a transmission to the channel master | 610 | * Function called to provide data for a transmission to the channel master |
611 | * (a.k.a. the @e host of the channel). | 611 | * (a.k.a. the @e host of the channel). |
612 | * | 612 | * |
@@ -638,13 +638,13 @@ enum GNUNET_PSYC_SlaveTransmitFlags | |||
638 | }; | 638 | }; |
639 | 639 | ||
640 | 640 | ||
641 | /** | 641 | /** |
642 | * Handle for a pending PSYC transmission operation. | 642 | * Handle for a pending PSYC transmission operation. |
643 | */ | 643 | */ |
644 | struct GNUNET_PSYC_SlaveTransmitHandle; | 644 | struct GNUNET_PSYC_SlaveTransmitHandle; |
645 | 645 | ||
646 | 646 | ||
647 | /** | 647 | /** |
648 | * Request a message to be sent to the channel master. | 648 | * Request a message to be sent to the channel master. |
649 | * | 649 | * |
650 | * @param slave Slave handle. | 650 | * @param slave Slave handle. |
@@ -664,7 +664,7 @@ GNUNET_PSYC_slave_transmit (struct GNUNET_PSYC_Slave *slave, | |||
664 | enum GNUNET_PSYC_SlaveTransmitFlags flags); | 664 | enum GNUNET_PSYC_SlaveTransmitFlags flags); |
665 | 665 | ||
666 | 666 | ||
667 | /** | 667 | /** |
668 | * Resume transmission to the master. | 668 | * Resume transmission to the master. |
669 | * | 669 | * |
670 | * @param th Handle of the request that is being resumed. | 670 | * @param th Handle of the request that is being resumed. |
@@ -673,7 +673,7 @@ void | |||
673 | GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); | 673 | GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); |
674 | 674 | ||
675 | 675 | ||
676 | /** | 676 | /** |
677 | * Abort transmission request to master. | 677 | * Abort transmission request to master. |
678 | * | 678 | * |
679 | * @param th Handle of the request that is being aborted. | 679 | * @param th Handle of the request that is being aborted. |
@@ -682,13 +682,13 @@ void | |||
682 | GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th); | 682 | GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th); |
683 | 683 | ||
684 | 684 | ||
685 | /** | 685 | /** |
686 | * Handle to access PSYC channel operations for both the master and slaves. | 686 | * Handle to access PSYC channel operations for both the master and slaves. |
687 | */ | 687 | */ |
688 | struct GNUNET_PSYC_Channel; | 688 | struct GNUNET_PSYC_Channel; |
689 | 689 | ||
690 | 690 | ||
691 | /** | 691 | /** |
692 | * Convert a channel @a master to a @e channel handle to access the @e channel | 692 | * Convert a channel @a master to a @e channel handle to access the @e channel |
693 | * APIs. | 693 | * APIs. |
694 | * | 694 | * |
@@ -699,7 +699,7 @@ struct GNUNET_PSYC_Channel * | |||
699 | GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); | 699 | GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); |
700 | 700 | ||
701 | 701 | ||
702 | /** | 702 | /** |
703 | * Convert @a slave to a @e channel handle to access the @e channel APIs. | 703 | * Convert @a slave to a @e channel handle to access the @e channel APIs. |
704 | * | 704 | * |
705 | * @param slave Slave handle. | 705 | * @param slave Slave handle. |
@@ -709,7 +709,7 @@ struct GNUNET_PSYC_Channel * | |||
709 | GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); | 709 | GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); |
710 | 710 | ||
711 | 711 | ||
712 | /** | 712 | /** |
713 | * Add a slave to the channel's membership list. | 713 | * Add a slave to the channel's membership list. |
714 | * | 714 | * |
715 | * Note that this will NOT generate any PSYC traffic, it will merely update the | 715 | * Note that this will NOT generate any PSYC traffic, it will merely update the |
@@ -738,7 +738,7 @@ GNUNET_PSYC_channel_slave_add (struct GNUNET_PSYC_Channel *channel, | |||
738 | uint64_t effective_since); | 738 | uint64_t effective_since); |
739 | 739 | ||
740 | 740 | ||
741 | /** | 741 | /** |
742 | * Remove a slave from the channel's membership list. | 742 | * Remove a slave from the channel's membership list. |
743 | * | 743 | * |
744 | * Note that this will NOT generate any PSYC traffic, it will merely update the | 744 | * Note that this will NOT generate any PSYC traffic, it will merely update the |
@@ -766,7 +766,7 @@ GNUNET_PSYC_channel_slave_remove (struct GNUNET_PSYC_Channel *channel, | |||
766 | uint64_t announced_at); | 766 | uint64_t announced_at); |
767 | 767 | ||
768 | 768 | ||
769 | /** | 769 | /** |
770 | * Function called to inform a member about stored state values for a channel. | 770 | * Function called to inform a member about stored state values for a channel. |
771 | * | 771 | * |
772 | * @param cls Closure. | 772 | * @param cls Closure. |
@@ -791,13 +791,13 @@ typedef void | |||
791 | (*GNUNET_PSYC_FinishCallback) (void *cls); | 791 | (*GNUNET_PSYC_FinishCallback) (void *cls); |
792 | 792 | ||
793 | 793 | ||
794 | /** | 794 | /** |
795 | * Handle to a story telling operation. | 795 | * Handle to a story telling operation. |
796 | */ | 796 | */ |
797 | struct GNUNET_PSYC_Story; | 797 | struct GNUNET_PSYC_Story; |
798 | 798 | ||
799 | 799 | ||
800 | /** | 800 | /** |
801 | * Request to be told the message history of the channel. | 801 | * Request to be told the message history of the channel. |
802 | * | 802 | * |
803 | * Historic messages (but NOT the state at the time) will be replayed (given to | 803 | * Historic messages (but NOT the state at the time) will be replayed (given to |
@@ -827,7 +827,7 @@ GNUNET_PSYC_channel_story_tell (struct GNUNET_PSYC_Channel *channel, | |||
827 | void *cls); | 827 | void *cls); |
828 | 828 | ||
829 | 829 | ||
830 | /** | 830 | /** |
831 | * Abort story telling. | 831 | * Abort story telling. |
832 | * | 832 | * |
833 | * This function must not be called from within method handlers (as given to | 833 | * This function must not be called from within method handlers (as given to |
@@ -845,7 +845,7 @@ GNUNET_PSYC_channel_story_tell_cancel (struct GNUNET_PSYC_Story *story); | |||
845 | struct GNUNET_PSYC_StateQuery; | 845 | struct GNUNET_PSYC_StateQuery; |
846 | 846 | ||
847 | 847 | ||
848 | /** | 848 | /** |
849 | * Retrieve the best matching channel state variable. | 849 | * Retrieve the best matching channel state variable. |
850 | * | 850 | * |
851 | * If the requested variable name is not present in the state, the nearest | 851 | * If the requested variable name is not present in the state, the nearest |
@@ -867,7 +867,7 @@ GNUNET_PSYC_channel_state_get (struct GNUNET_PSYC_Channel *channel, | |||
867 | void *cb_cls); | 867 | void *cb_cls); |
868 | 868 | ||
869 | 869 | ||
870 | /** | 870 | /** |
871 | * Return all channel state variables whose name matches a given prefix. | 871 | * Return all channel state variables whose name matches a given prefix. |
872 | * | 872 | * |
873 | * A name matches if it starts with the given @a name_prefix, thus requesting | 873 | * A name matches if it starts with the given @a name_prefix, thus requesting |
@@ -890,7 +890,7 @@ GNUNET_PSYC_channel_state_get_prefix (struct GNUNET_PSYC_Channel *channel, | |||
890 | void *cb_cls); | 890 | void *cb_cls); |
891 | 891 | ||
892 | 892 | ||
893 | /** | 893 | /** |
894 | * Cancel a state query operation. | 894 | * Cancel a state query operation. |
895 | * | 895 | * |
896 | * @param query Handle for the operation to cancel. | 896 | * @param query Handle for the operation to cancel. |