diff options
author | Bart Polot <bart.polot+voyager@gmail.com> | 2017-01-31 02:57:46 +0100 |
---|---|---|
committer | Bart Polot <bart.polot+voyager@gmail.com> | 2017-01-31 02:57:46 +0100 |
commit | b2c3389e8de9d24794d4b4bb499e14408101d433 (patch) | |
tree | c2e17fa09ab34082d5004cfc27388218019445c2 /src/include/gnunet_cadet_service.h | |
parent | 98fead2b759d2c7ac87e845d65b6b2f565ba12a3 (diff) | |
download | gnunet-b2c3389e8de9d24794d4b4bb499e14408101d433.tar.gz gnunet-b2c3389e8de9d24794d4b4bb499e14408101d433.zip |
CADET MQ API documentation improvements
Diffstat (limited to 'src/include/gnunet_cadet_service.h')
-rw-r--r-- | src/include/gnunet_cadet_service.h | 42 |
1 files changed, 19 insertions, 23 deletions
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 99d74f223..1b3aac7c9 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h | |||
@@ -697,26 +697,26 @@ GC_u2h (uint32_t port); | |||
697 | /******************************************************************************/ | 697 | /******************************************************************************/ |
698 | 698 | ||
699 | /** | 699 | /** |
700 | * Method called whenever a given peer connects in MQ-based CADET. | 700 | * Method called whenever a peer connects to a port in MQ-based CADET. |
701 | * | 701 | * |
702 | * @param cls Closure from @a GNUNET_CADET_open_porT. | 702 | * @param cls Closure from #GNUNET_CADET_open_porT. |
703 | * @param channel New handle to the channel. | 703 | * @param channel New handle to the channel. |
704 | * @param source Peer that started this channel. | 704 | * @param source Peer that started this channel. |
705 | * | 705 | * @return Closure for the incoming @a channel. It's given to: |
706 | * @return Closure for the incoming channel. It's given to: | 706 | * - The #GNUNET_CADET_DisconnectEventHandler (given to |
707 | * - The @a GNUNET_CADET_DisconnectEventHandler when the channel dies. | 707 | * #GNUNET_CADET_open_porT) when the channel dies. |
708 | * - Each the @a GNUNET_MQ_MessageCallback for each message. | 708 | * - Each the #GNUNET_MQ_MessageCallback handlers for each message |
709 | * received on the @a channel. | ||
709 | */ | 710 | */ |
710 | typedef void * | 711 | typedef void * |
711 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, | 712 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, |
712 | struct GNUNET_CADET_Channel *channel, | 713 | struct GNUNET_CADET_Channel *channel, |
713 | const struct GNUNET_PeerIdentity *source); | 714 | const struct GNUNET_PeerIdentity *source); |
714 | 715 | ||
715 | |||
716 | /** | 716 | /** |
717 | * Function called whenever an MQ-channel is destroyed, even if the destruction | 717 | * Function called whenever an MQ-channel is destroyed, even if the destruction |
718 | * was requested by @a GNUNET_CADET_channel_destroy. | 718 | * was requested by #GNUNET_CADET_channel_destroy. |
719 | * It must NOT call @a GNUNET_CADET_channel_destroy on the channel. | 719 | * It must NOT call #GNUNET_CADET_channel_destroy on the channel. |
720 | * | 720 | * |
721 | * It should clean up any associated state, including cancelling any pending | 721 | * It should clean up any associated state, including cancelling any pending |
722 | * transmission on this channel. | 722 | * transmission on this channel. |
@@ -728,7 +728,6 @@ typedef void | |||
728 | (*GNUNET_CADET_DisconnectEventHandler) (void *cls, | 728 | (*GNUNET_CADET_DisconnectEventHandler) (void *cls, |
729 | const struct GNUNET_CADET_Channel *channel); | 729 | const struct GNUNET_CADET_Channel *channel); |
730 | 730 | ||
731 | |||
732 | /** | 731 | /** |
733 | * Function called whenever an MQ-channel's transmission window size changes. | 732 | * Function called whenever an MQ-channel's transmission window size changes. |
734 | * | 733 | * |
@@ -736,29 +735,27 @@ typedef void | |||
736 | * and will mean the channel is connected to the destination. | 735 | * and will mean the channel is connected to the destination. |
737 | * | 736 | * |
738 | * For an incoming channel it will be called immediately after the | 737 | * For an incoming channel it will be called immediately after the |
739 | * @a GNUNET_CADET_ConnectEventHandler, also with a non-zero value. | 738 | * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value. |
740 | * | 739 | * |
741 | * @param cls Channel closure. | 740 | * @param cls Channel closure. |
742 | * @param channel Connection to the other end (henceforth invalid). | 741 | * @param channel Connection to the other end (henceforth invalid). |
743 | * @param window_size New window size. | 742 | * @param window_size New window size. If the is more messages than buffer size |
743 | * this value will be negative.. | ||
744 | */ | 744 | */ |
745 | typedef void | 745 | typedef void |
746 | (*GNUNET_CADET_WindowSizeEventHandler) (void *cls, | 746 | (*GNUNET_CADET_WindowSizeEventHandler) (void *cls, |
747 | const struct GNUNET_CADET_Channel *channel, | 747 | const struct GNUNET_CADET_Channel *channel, |
748 | int window_size); | 748 | int window_size); |
749 | 749 | ||
750 | |||
751 | /** | 750 | /** |
752 | * Connect to the MQ-based cadet service. | 751 | * Connect to the MQ-based cadet service. |
753 | * | 752 | * |
754 | * @param cfg Configuration to use. | 753 | * @param cfg Configuration to use. |
755 | * | ||
756 | * @return Handle to the cadet service NULL on error. | 754 | * @return Handle to the cadet service NULL on error. |
757 | */ | 755 | */ |
758 | struct GNUNET_CADET_Handle * | 756 | struct GNUNET_CADET_Handle * |
759 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); | 757 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); |
760 | 758 | ||
761 | |||
762 | /** | 759 | /** |
763 | * Open a port to receive incomming MQ-based channels. | 760 | * Open a port to receive incomming MQ-based channels. |
764 | * | 761 | * |
@@ -767,21 +764,20 @@ GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); | |||
767 | * @param connects Function called when an incoming channel is connected. | 764 | * @param connects Function called when an incoming channel is connected. |
768 | * @param connects_cls Closure for the @a connects handler. | 765 | * @param connects_cls Closure for the @a connects handler. |
769 | * @param window_changes Function called when the transmit window size changes. | 766 | * @param window_changes Function called when the transmit window size changes. |
767 | * Can be NULL. | ||
770 | * @param disconnects Function called when a channel is disconnected. | 768 | * @param disconnects Function called when a channel is disconnected. |
771 | * @param handlers Callbacks for messages we care about, NULL-terminated. | 769 | * @param handlers Callbacks for messages we care about, NULL-terminated. |
772 | * | ||
773 | * @return Port handle. | 770 | * @return Port handle. |
774 | */ | 771 | */ |
775 | struct GNUNET_CADET_Port * | 772 | struct GNUNET_CADET_Port * |
776 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, | 773 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, |
777 | const struct GNUNET_HashCode *port, | 774 | const struct GNUNET_HashCode *port, |
778 | GNUNET_CADET_ConnectEventHandler connects, | 775 | GNUNET_CADET_ConnectEventHandler connects, |
779 | void * connects_cls, | 776 | void *connects_cls, |
780 | GNUNET_CADET_WindowSizeEventHandler window_changes, | 777 | GNUNET_CADET_WindowSizeEventHandler window_changes, |
781 | GNUNET_CADET_DisconnectEventHandler disconnects, | 778 | GNUNET_CADET_DisconnectEventHandler disconnects, |
782 | const struct GNUNET_MQ_MessageHandler *handlers); | 779 | const struct GNUNET_MQ_MessageHandler *handlers); |
783 | 780 | ||
784 | |||
785 | /** | 781 | /** |
786 | * Create a new channel towards a remote peer. | 782 | * Create a new channel towards a remote peer. |
787 | * | 783 | * |
@@ -791,15 +787,17 @@ GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, | |||
791 | * | 787 | * |
792 | * @param h CADET handle. | 788 | * @param h CADET handle. |
793 | * @param channel_cls Closure for the channel. It's given to: | 789 | * @param channel_cls Closure for the channel. It's given to: |
790 | * - The management handler @a window_changes. | ||
794 | * - The disconnect handler @a disconnects | 791 | * - The disconnect handler @a disconnects |
795 | * - Each message type callback in @a handlers | 792 | * - Each message type callback in @a handlers |
796 | * @param destination Peer identity the channel should go to. | 793 | * @param destination Peer identity the channel should go to. |
797 | * @param port Identification of the destination port. | 794 | * @param port Identification of the destination port. |
798 | * @param options CadetOption flag field, with all desired option bits set to 1. | 795 | * @param options CadetOption flag field, with all desired option bits set to 1. |
799 | * @param window_changes Function called when the transmit window size changes. | 796 | * @param window_changes Function called when the transmit window size changes. |
797 | * Can be NULL if this data is of no interest. | ||
798 | * TODO Not yet implemented. | ||
800 | * @param disconnects Function called when the channel is disconnected. | 799 | * @param disconnects Function called when the channel is disconnected. |
801 | * @param handlers Callbacks for messages we care about, NULL-terminated. | 800 | * @param handlers Callbacks for messages we care about, NULL-terminated. |
802 | * | ||
803 | * @return Handle to the channel. | 801 | * @return Handle to the channel. |
804 | */ | 802 | */ |
805 | struct GNUNET_CADET_Channel * | 803 | struct GNUNET_CADET_Channel * |
@@ -812,13 +810,11 @@ GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, | |||
812 | GNUNET_CADET_DisconnectEventHandler disconnects, | 810 | GNUNET_CADET_DisconnectEventHandler disconnects, |
813 | const struct GNUNET_MQ_MessageHandler *handlers); | 811 | const struct GNUNET_MQ_MessageHandler *handlers); |
814 | 812 | ||
815 | |||
816 | /** | 813 | /** |
817 | * Obtain the message queue for a connected peer. | 814 | * Obtain the message queue for a connected channel. |
818 | * | 815 | * |
819 | * @param channel The channel handle from which to get the MQ. | 816 | * @param channel The channel handle from which to get the MQ. |
820 | * | 817 | * @return The message queue of the channel. |
821 | * @return NULL if @a channel is not yet connected. | ||
822 | */ | 818 | */ |
823 | struct GNUNET_MQ_Handle * | 819 | struct GNUNET_MQ_Handle * |
824 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); | 820 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); |