diff options
author | Bart Polot <bart.polot+voyager@gmail.com> | 2017-01-26 15:53:20 +0100 |
---|---|---|
committer | Bart Polot <bart.polot+voyager@gmail.com> | 2017-01-26 15:53:20 +0100 |
commit | 356cd09ec4f7d2c02300d5eae8bec8e6b8e49635 (patch) | |
tree | 1adc9d00cbdeb7ad47a54146da90fea50596b581 /src/include | |
parent | 3ba5a176f9fec927fbb8b60c24dd333e783df18f (diff) | |
download | gnunet-356cd09ec4f7d2c02300d5eae8bec8e6b8e49635.tar.gz gnunet-356cd09ec4f7d2c02300d5eae8bec8e6b8e49635.zip |
- second iteration for new CADET API
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_cadet_service.h | 162 |
1 files changed, 60 insertions, 102 deletions
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 8d10c3d8d..5d6e1c1d1 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h | |||
@@ -697,152 +697,110 @@ GC_u2h (uint32_t port); | |||
697 | /******************************************************************************/ | 697 | /******************************************************************************/ |
698 | 698 | ||
699 | /** | 699 | /** |
700 | * Function called after #GNUNET_CADET_connecT has succeeded (or failed | 700 | * Method called whenever a given peer connects in MQ-based CADET. |
701 | * for good). Implementations of this function must not call | ||
702 | * #GNUNET_CADET_disconnecT (other than by scheduling a new task to | ||
703 | * do this later). | ||
704 | * | 701 | * |
705 | * @param cls closure | ||
706 | * @param connected #GNUNET_YES if successfully connected, #GNUNET_NO otherwise. | ||
707 | */ | ||
708 | typedef void | ||
709 | (*GNUNET_CADET_StartupCallback) (void *cls, int connected); | ||
710 | |||
711 | |||
712 | /** | ||
713 | * Method called whenever a given peer connects in mq-based CADET. | ||
714 | * | ||
715 | * @param cls Closure given to @a GNUNET_CADET_connecT. | ||
716 | * @param channel New handle to the channel. | 702 | * @param channel New handle to the channel. |
717 | * @param channel_cls Closure given to @a GNUNET_CADET_open_porT. | 703 | * @param source Peer that started this channel. |
718 | * NOTE: do we need two cls? I'd get rid of this one. | ||
719 | * @param peer Peer that started this channel. | ||
720 | * | ||
721 | * NOTE: to keep symmetry between incoming and outgoing channels, this call | ||
722 | * does not provide the *mq, since we cannot cleanly return an mq | ||
723 | * from @a GNUNET_CADET_channel_create. | ||
724 | * The client must always call @a GNUNET_CADET_get_mq to the *mq | ||
725 | * Alternatively, we can provide the mq here and add and out **mq | ||
726 | * to @a GNUNET_CADET_channel_create | ||
727 | * | 704 | * |
728 | * @return initial channel context for the channel | 705 | * @return Closure for the incoming channel. It's given to: |
729 | * (can be NULL -- that's not an error) | 706 | * - The @a GNUNET_CADET_DisconnectEventHandler when the channel dies. |
707 | * - Each the @a GNUNET_MQ_MessageCallback for each message. | ||
730 | */ | 708 | */ |
731 | typedef void * | 709 | typedef void * |
732 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, | 710 | (*GNUNET_CADET_ConnectEventHandler) (struct GNUNET_CADET_Channel *channel, |
733 | struct GNUNET_CADET_Channel *channel, | 711 | const struct GNUNET_PeerIdentity *source); |
734 | const struct GNUNET_PeerIdentity *peer); | 712 | |
735 | 713 | ||
736 | /** | 714 | /** |
737 | * Function called whenever an mq-channel is destroyed. Should clean up | 715 | * Function called whenever an MQ-channel is destroyed, even if the destruction |
738 | * any associated state, including cancelling any pending transmission on this | 716 | * was requested by @a GNUNET_CADET_channel_destroy. |
739 | * channel. | ||
740 | * | ||
741 | * It must NOT call @a GNUNET_CADET_channel_destroy on the channel. | 717 | * It must NOT call @a GNUNET_CADET_channel_destroy on the channel. |
742 | * | 718 | * |
743 | * @param cls Closure (set from @a GNUNET_CADET_connecT). | 719 | * It should clean up any associated state, including cancelling any pending |
720 | * transmission on this channel. | ||
721 | * | ||
722 | * FIXME: what about MQ-pending transmissions? | ||
723 | * | ||
724 | * @param cls Channel closure. | ||
744 | * @param channel Connection to the other end (henceforth invalid). | 725 | * @param channel Connection to the other end (henceforth invalid). |
745 | * @param channel_ctx Context (set from @a GNUNET_CADET_ConnectEventHandler). | ||
746 | */ | 726 | */ |
747 | typedef void | 727 | typedef void |
748 | (GNUNET_CADET_DisconnectEventHandler) (void *cls, | 728 | (GNUNET_CADET_DisconnectEventHandler) (void *cls, |
749 | const struct GNUNET_CADET_Channel *channel, | 729 | const struct GNUNET_CADET_Channel *channel); |
750 | void *channel_ctx); | 730 | |
751 | 731 | ||
752 | /** | 732 | /** |
753 | * Connect to the mq-based cadet service. | 733 | * Connect to the MQ-based cadet service. |
754 | * | ||
755 | * NOTE: it would be more elegant to provide a separate @a handlers and | ||
756 | * @a disconnects for each port, giving them to @a GNUNET_CADET_open_porT, | ||
757 | * but how do we handle *incoming* channels? | ||
758 | * | 734 | * |
759 | * @param cfg Configuration to use. | 735 | * @param cfg Configuration to use. |
760 | * @param cls Closure for the various callbacks that follow (including | ||
761 | * handlers in the handlers array). | ||
762 | * @param init callback to call once we have successfully connected | ||
763 | * to the cadet service | ||
764 | * @param disconnects Function called when a channel is destroyed. | ||
765 | * It is called immediately if the channel is destroyed by | ||
766 | * calling @a GNUNET_CADET_channel_destroy. | ||
767 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
768 | * Messages of a type that is not in the handlers array | ||
769 | * are ignored if received. | ||
770 | * | 736 | * |
771 | * @return handle to the cadet service NULL on error | 737 | * @return Handle to the cadet service NULL on error. |
772 | * (in this case, init is never called) | ||
773 | */ | 738 | */ |
774 | struct GNUNET_CADET_Handle * | 739 | struct GNUNET_CADET_Handle * |
775 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg, | 740 | GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); |
776 | void *cls, | ||
777 | GNUNET_CADET_StartupCallback init, | ||
778 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
779 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
780 | 741 | ||
781 | /** | ||
782 | * Disconnect from the mq-based cadet service. All channels will be destroyed. | ||
783 | * All channel disconnect callbacks will be called on any still connected peers, | ||
784 | * notifying about their disconnection. The registered inbound channel cleaner | ||
785 | * will be called should any inbound channels still exist. | ||
786 | * | ||
787 | * @param handle connection to cadet to disconnect | ||
788 | */ | ||
789 | void | ||
790 | GNUNET_CADET_disconnecT (struct GNUNET_CADET_Handle *handle); | ||
791 | 742 | ||
792 | /** | 743 | /** |
793 | * Open a port to receive incomming mq-based channels. | 744 | * Open a port to receive incomming MQ-based channels. |
794 | * | 745 | * |
795 | * @param h CADET handle. | 746 | * @param h CADET handle. |
796 | * @param port Hash representing the port number. | 747 | * @param port Hash identifying the port. |
797 | * @param new_channel Function called when an channel is received. | 748 | * @param connects Function called when an incoming channel is connected. |
798 | * @param new_channel_cls Closure for @a new_channel. | 749 | * FIXME: add connects_cls to give the incoming handler a closure? |
799 | * NOTE: get rid of this cls? | 750 | * @param disconnects Function called when a channel is disconnected. |
751 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
800 | * | 752 | * |
801 | * @return Port handle. | 753 | * @return Port handle. |
802 | */ | 754 | */ |
803 | struct GNUNET_CADET_Port * | 755 | struct GNUNET_CADET_Port * |
804 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, | 756 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, |
805 | const struct GNUNET_HashCode *port, | 757 | const struct GNUNET_HashCode *port, |
806 | GNUNET_CADET_ConnectEventHandler new_channel, | 758 | GNUNET_CADET_ConnectEventHandler connects, |
807 | void *new_channel_cls); | 759 | GNUNET_CADET_DisconnectEventHandler disconnects, |
760 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
761 | |||
808 | 762 | ||
809 | /** | 763 | /** |
810 | * Close a port opened with @a GNUNET_CADET_open_porT. | 764 | * Create a new channel towards a remote peer. |
811 | * The @a new_channel callback will no longer be called. | ||
812 | * | 765 | * |
813 | * @param p Port handle. | 766 | * If the destination port is not open by any peer or the destination peer |
767 | * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called | ||
768 | * for this channel. | ||
769 | * | ||
770 | * @param h CADET handle. | ||
771 | * @param channel_cls Closure for the channel. It's given to: | ||
772 | * - The disconnect handler @a disconnects | ||
773 | * - Each message type callback in @a handlers | ||
774 | * @param destination Peer identity the channel should go to. | ||
775 | * @param port Identification of the destination port. | ||
776 | * @param options CadetOption flag field, with all desired option bits set to 1. | ||
777 | * @param disconnects Function called when the channel is disconnected. | ||
778 | * @param handlers Callbacks for messages we care about, NULL-terminated. | ||
779 | * | ||
780 | * @return Handle to the channel. | ||
814 | */ | 781 | */ |
815 | void | 782 | struct GNUNET_CADET_Channel * |
816 | GNUNET_CADET_close_porT (struct GNUNET_CADET_Port *p); | 783 | GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, |
784 | void *channel_cls, | ||
785 | const struct GNUNET_PeerIdentity *destination, | ||
786 | const struct GNUNET_HashCode *port, | ||
787 | enum GNUNET_CADET_ChannelOption options, | ||
788 | GNUNET_CADET_DisconnectEventHandler disconnects, | ||
789 | const struct GNUNET_MQ_MessageHandler *handlers); | ||
790 | |||
817 | 791 | ||
818 | /** | 792 | /** |
819 | * Obtain the message queue for a connected peer. | 793 | * Obtain the message queue for a connected peer. |
820 | * | 794 | * |
821 | * @param h the cadet handle | 795 | * @param channel The channel handle from which to get the MQ. |
822 | * @param channel the identity of the peer | ||
823 | * | 796 | * |
824 | * @return NULL if @a channel is not yet connected. | 797 | * @return NULL if @a channel is not yet connected. |
825 | * NOTE: provide an mq before a channel is connected? | 798 | * FIXME: provide an mq before a channel is connected? |
826 | * provide a callback to notify a client a channel connected? | 799 | * provide a callback to notify a client a channel connected? |
827 | */ | 800 | */ |
828 | struct GNUNET_MQ_Handle * | 801 | struct GNUNET_MQ_Handle * |
829 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Handle *h, | 802 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); |
830 | const struct GNUNET_CADET_Channel *channel); | ||
831 | 803 | ||
832 | /* NOTE: | ||
833 | * GNUNET_CADET_channel_create and _destroy can stay the same. | ||
834 | * Monitor API can stay the same (low-priority). | ||
835 | |||
836 | struct GNUNET_CADET_Channel * | ||
837 | GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, | ||
838 | void *channel_ctx, | ||
839 | const struct GNUNET_PeerIdentity *peer, | ||
840 | const struct GNUNET_HashCode *port, | ||
841 | enum GNUNET_CADET_ChannelOption options); | ||
842 | void | ||
843 | GNUNET_CADET_channel_destroy (struct GNUNET_CADET_Channel *channel); | ||
844 | |||
845 | */ | ||
846 | 804 | ||
847 | /******************************************************************************/ | 805 | /******************************************************************************/ |
848 | /******************************* MQ-BASED API *********************************/ | 806 | /******************************* MQ-BASED API *********************************/ |