aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_psyc_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_psyc_service.h')
-rw-r--r--src/include/gnunet_psyc_service.h86
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 */
102enum GNUNET_PSYC_ChannelFlags 102enum 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 */
119enum GNUNET_PSYC_Policy 119enum 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
283struct GNUNET_PSYC_JoinHandle; 283struct 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 */
381struct GNUNET_PSYC_Master; 381struct 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
459enum GNUNET_PSYC_MasterTransmitFlags 459enum 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 */
484struct GNUNET_PSYC_MasterTransmitHandle; 484struct 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
514GNUNET_PSYC_master_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); 514GNUNET_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
523GNUNET_PSYC_master_transmit_cancel (struct GNUNET_PSYC_MasterTransmitHandle *th); 523GNUNET_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
532GNUNET_PSYC_master_stop (struct GNUNET_PSYC_Master *master); 532GNUNET_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 */
538struct GNUNET_PSYC_Slave; 538struct 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
606GNUNET_PSYC_slave_part (struct GNUNET_PSYC_Slave *slave); 606GNUNET_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 */
644struct GNUNET_PSYC_SlaveTransmitHandle; 644struct 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
673GNUNET_PSYC_slave_transmit_resume (struct GNUNET_PSYC_MasterTransmitHandle *th); 673GNUNET_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
682GNUNET_PSYC_slave_transmit_cancel (struct GNUNET_PSYC_SlaveTransmitHandle *th); 682GNUNET_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 */
688struct GNUNET_PSYC_Channel; 688struct 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 *
699GNUNET_PSYC_master_get_channel (struct GNUNET_PSYC_Master *master); 699GNUNET_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 *
709GNUNET_PSYC_slave_get_channel (struct GNUNET_PSYC_Slave *slave); 709GNUNET_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 */
797struct GNUNET_PSYC_Story; 797struct 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);
845struct GNUNET_PSYC_StateQuery; 845struct 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.