diff options
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_cadet_service.h | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 68d557d1c..8d10c3d8d 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h | |||
@@ -692,6 +692,164 @@ const struct GNUNET_HashCode * | |||
692 | GC_u2h (uint32_t port); | 692 | GC_u2h (uint32_t port); |
693 | 693 | ||
694 | 694 | ||
695 | /******************************************************************************/ | ||
696 | /******************************* MQ-BASED API *********************************/ | ||
697 | /******************************************************************************/ | ||
698 | |||
699 | /** | ||
700 | * Function called after #GNUNET_CADET_connecT has succeeded (or failed | ||
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 | * | ||
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. | ||
717 | * @param channel_cls Closure given to @a GNUNET_CADET_open_porT. | ||
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 | * | ||
728 | * @return initial channel context for the channel | ||
729 | * (can be NULL -- that's not an error) | ||
730 | */ | ||
731 | typedef void * | ||
732 | (*GNUNET_CADET_ConnectEventHandler) (void *cls, | ||
733 | struct GNUNET_CADET_Channel *channel, | ||
734 | const struct GNUNET_PeerIdentity *peer); | ||
735 | |||
736 | /** | ||
737 | * Function called whenever an mq-channel is destroyed. Should clean up | ||
738 | * any associated state, including cancelling any pending transmission on this | ||
739 | * channel. | ||
740 | * | ||
741 | * It must NOT call @a GNUNET_CADET_channel_destroy on the channel. | ||
742 | * | ||
743 | * @param cls Closure (set from @a GNUNET_CADET_connecT). | ||
744 | * @param channel Connection to the other end (henceforth invalid). | ||
745 | * @param channel_ctx Context (set from @a GNUNET_CADET_ConnectEventHandler). | ||
746 | */ | ||
747 | typedef void | ||
748 | (GNUNET_CADET_DisconnectEventHandler) (void *cls, | ||
749 | const struct GNUNET_CADET_Channel *channel, | ||
750 | void *channel_ctx); | ||
751 | |||
752 | /** | ||
753 | * 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 | * | ||
759 | * @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 | * | ||
771 | * @return handle to the cadet service NULL on error | ||
772 | * (in this case, init is never called) | ||
773 | */ | ||
774 | struct GNUNET_CADET_Handle * | ||
775 | 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 | |||
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 | |||
792 | /** | ||
793 | * Open a port to receive incomming mq-based channels. | ||
794 | * | ||
795 | * @param h CADET handle. | ||
796 | * @param port Hash representing the port number. | ||
797 | * @param new_channel Function called when an channel is received. | ||
798 | * @param new_channel_cls Closure for @a new_channel. | ||
799 | * NOTE: get rid of this cls? | ||
800 | * | ||
801 | * @return Port handle. | ||
802 | */ | ||
803 | struct GNUNET_CADET_Port * | ||
804 | GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, | ||
805 | const struct GNUNET_HashCode *port, | ||
806 | GNUNET_CADET_ConnectEventHandler new_channel, | ||
807 | void *new_channel_cls); | ||
808 | |||
809 | /** | ||
810 | * Close a port opened with @a GNUNET_CADET_open_porT. | ||
811 | * The @a new_channel callback will no longer be called. | ||
812 | * | ||
813 | * @param p Port handle. | ||
814 | */ | ||
815 | void | ||
816 | GNUNET_CADET_close_porT (struct GNUNET_CADET_Port *p); | ||
817 | |||
818 | /** | ||
819 | * Obtain the message queue for a connected peer. | ||
820 | * | ||
821 | * @param h the cadet handle | ||
822 | * @param channel the identity of the peer | ||
823 | * | ||
824 | * @return NULL if @a channel is not yet connected. | ||
825 | * NOTE: provide an mq before a channel is connected? | ||
826 | * provide a callback to notify a client a channel connected? | ||
827 | */ | ||
828 | struct GNUNET_MQ_Handle * | ||
829 | GNUNET_CADET_get_mq (const struct GNUNET_CADET_Handle *h, | ||
830 | const struct GNUNET_CADET_Channel *channel); | ||
831 | |||
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 | |||
847 | /******************************************************************************/ | ||
848 | /******************************* MQ-BASED API *********************************/ | ||
849 | /******************************************************************************/ | ||
850 | |||
851 | |||
852 | |||
695 | #if 0 /* keep Emacsens' auto-indent happy */ | 853 | #if 0 /* keep Emacsens' auto-indent happy */ |
696 | { | 854 | { |
697 | #endif | 855 | #endif |