diff options
author | Gabor X Toth <*@tg-x.net> | 2015-09-26 17:10:03 +0000 |
---|---|---|
committer | Gabor X Toth <*@tg-x.net> | 2015-09-26 17:10:03 +0000 |
commit | e990039b4ddf89d37a8771dc5aca791e52df45ed (patch) | |
tree | 171afe7526839c62423ab6efc023ea3b53d48073 /src/multicast | |
parent | 5a042e00e06de726a21d9db05ddeb2ac16ca7c0c (diff) | |
download | gnunet-e990039b4ddf89d37a8771dc5aca791e52df45ed.tar.gz gnunet-e990039b4ddf89d37a8771dc5aca791e52df45ed.zip |
multicast: doc formatting
Diffstat (limited to 'src/multicast')
-rw-r--r-- | src/multicast/multicast_api.c | 164 |
1 files changed, 108 insertions, 56 deletions
diff --git a/src/multicast/multicast_api.c b/src/multicast/multicast_api.c index 9f0c77f36..c437b71c9 100644 --- a/src/multicast/multicast_api.c +++ b/src/multicast/multicast_api.c | |||
@@ -535,19 +535,24 @@ member_cleanup (void *cls) | |||
535 | * Must be called once and only once in response to an invocation of the | 535 | * Must be called once and only once in response to an invocation of the |
536 | * #GNUNET_MULTICAST_JoinRequestCallback. | 536 | * #GNUNET_MULTICAST_JoinRequestCallback. |
537 | * | 537 | * |
538 | * @param join Join request handle. | 538 | * @param join |
539 | * @param is_admitted #GNUNET_YES if the join is approved, | 539 | * Join request handle. |
540 | * #GNUNET_NO if it is disapproved, | 540 | * @param is_admitted |
541 | * #GNUNET_SYSERR if we cannot answer the request. | 541 | * #GNUNET_YES if the join is approved, |
542 | * @param relay_count Number of relays given. | 542 | * #GNUNET_NO if it is disapproved, |
543 | * @param relays Array of suggested peers that might be useful relays to use | 543 | * #GNUNET_SYSERR if we cannot answer the request. |
544 | * @param relay_count | ||
545 | * Number of relays given. | ||
546 | * @param relays | ||
547 | * Array of suggested peers that might be useful relays to use | ||
544 | * when joining the multicast group (essentially a list of peers that | 548 | * when joining the multicast group (essentially a list of peers that |
545 | * are already part of the multicast group and might thus be willing | 549 | * are already part of the multicast group and might thus be willing |
546 | * to help with routing). If empty, only this local peer (which must | 550 | * to help with routing). If empty, only this local peer (which must |
547 | * be the multicast origin) is a good candidate for building the | 551 | * be the multicast origin) is a good candidate for building the |
548 | * multicast tree. Note that it is unnecessary to specify our own | 552 | * multicast tree. Note that it is unnecessary to specify our own |
549 | * peer identity in this array. | 553 | * peer identity in this array. |
550 | * @param join_resp Message to send in response to the joining peer; | 554 | * @param join_resp |
555 | * Message to send in response to the joining peer; | ||
551 | * can also be used to redirect the peer to a different group at the | 556 | * can also be used to redirect the peer to a different group at the |
552 | * application layer; this response is to be transmitted to the | 557 | * application layer; this response is to be transmitted to the |
553 | * peer that issued the request even if admission is denied. | 558 | * peer that issued the request even if admission is denied. |
@@ -592,8 +597,10 @@ GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *join, | |||
592 | /** | 597 | /** |
593 | * Call informing multicast about the decision taken for a membership test. | 598 | * Call informing multicast about the decision taken for a membership test. |
594 | * | 599 | * |
595 | * @param mth Handle that was given for the query. | 600 | * @param mth |
596 | * @param result #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member, | 601 | * Handle that was given for the query. |
602 | * @param result | ||
603 | * #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member, | ||
597 | * #GNUNET_SYSERR if we cannot answer the membership test. | 604 | * #GNUNET_SYSERR if we cannot answer the membership test. |
598 | */ | 605 | */ |
599 | void | 606 | void |
@@ -653,7 +660,8 @@ GNUNET_MULTICAST_replay_response (struct GNUNET_MULTICAST_ReplayHandle *rh, | |||
653 | * | 660 | * |
654 | * Invalidates the replay handle. | 661 | * Invalidates the replay handle. |
655 | * | 662 | * |
656 | * @param rh Replay session to end. | 663 | * @param rh |
664 | * Replay session to end. | ||
657 | */ | 665 | */ |
658 | void | 666 | void |
659 | GNUNET_MULTICAST_replay_response_end (struct GNUNET_MULTICAST_ReplayHandle *rh) | 667 | GNUNET_MULTICAST_replay_response_end (struct GNUNET_MULTICAST_ReplayHandle *rh) |
@@ -677,9 +685,12 @@ GNUNET_MULTICAST_replay_response_end (struct GNUNET_MULTICAST_ReplayHandle *rh) | |||
677 | /** | 685 | /** |
678 | * Replay a message for the multicast group. | 686 | * Replay a message for the multicast group. |
679 | * | 687 | * |
680 | * @param rh Replay handle identifying which replay operation was requested. | 688 | * @param rh |
681 | * @param notify Function to call to get the message. | 689 | * Replay handle identifying which replay operation was requested. |
682 | * @param notify_cls Closure for @a notify. | 690 | * @param notify |
691 | * Function to call to get the message. | ||
692 | * @param notify_cls | ||
693 | * Closure for @a notify. | ||
683 | */ | 694 | */ |
684 | void | 695 | void |
685 | GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | 696 | GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, |
@@ -701,20 +712,30 @@ GNUNET_MULTICAST_replay_response2 (struct GNUNET_MULTICAST_ReplayHandle *rh, | |||
701 | * candidate will be given a response. Members in the group can send messages | 712 | * candidate will be given a response. Members in the group can send messages |
702 | * to the origin (one at a time). | 713 | * to the origin (one at a time). |
703 | * | 714 | * |
704 | * @param cfg Configuration to use. | 715 | * @param cfg |
705 | * @param priv_key ECC key that will be used to sign messages for this | 716 | * Configuration to use. |
717 | * @param priv_key | ||
718 | * ECC key that will be used to sign messages for this | ||
706 | * multicast session; public key is used to identify the multicast group; | 719 | * multicast session; public key is used to identify the multicast group; |
707 | * @param max_fragment_id Maximum fragment ID already sent to the group. | 720 | * @param max_fragment_id |
721 | * Maximum fragment ID already sent to the group. | ||
708 | * 0 for a new group. | 722 | * 0 for a new group. |
709 | * @param join_request_cb Function called to approve / disapprove joining of a peer. | 723 | * @param join_request_cb |
710 | * @param member_test_cb Function multicast can use to test group membership. | 724 | * Function called to approve / disapprove joining of a peer. |
711 | * @param replay_frag_cb Function that can be called to replay a message fragment. | 725 | * @param member_test_cb |
712 | * @param replay_msg_cb Function that can be called to replay a message. | 726 | * Function multicast can use to test group membership. |
713 | * @param request_cb Function called with message fragments from group members. | 727 | * @param replay_frag_cb |
714 | * @param message_cb Function called with the message fragments sent to the | 728 | * Function that can be called to replay a message fragment. |
729 | * @param replay_msg_cb | ||
730 | * Function that can be called to replay a message. | ||
731 | * @param request_cb | ||
732 | * Function called with message fragments from group members. | ||
733 | * @param message_cb | ||
734 | * Function called with the message fragments sent to the | ||
715 | * network by GNUNET_MULTICAST_origin_to_all(). These message fragments | 735 | * network by GNUNET_MULTICAST_origin_to_all(). These message fragments |
716 | * should be stored for answering replay requests later. | 736 | * should be stored for answering replay requests later. |
717 | * @param cls Closure for the various callbacks that follow. | 737 | * @param cls |
738 | * Closure for the various callbacks that follow. | ||
718 | * | 739 | * |
719 | * @return Handle for the origin, NULL on error. | 740 | * @return Handle for the origin, NULL on error. |
720 | */ | 741 | */ |
@@ -763,7 +784,8 @@ GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
763 | /** | 784 | /** |
764 | * Stop a multicast group. | 785 | * Stop a multicast group. |
765 | * | 786 | * |
766 | * @param origin Multicast group to stop. | 787 | * @param origin |
788 | * Multicast group to stop. | ||
767 | */ | 789 | */ |
768 | void | 790 | void |
769 | GNUNET_MULTICAST_origin_stop (struct GNUNET_MULTICAST_Origin *orig, | 791 | GNUNET_MULTICAST_origin_stop (struct GNUNET_MULTICAST_Origin *orig, |
@@ -822,12 +844,17 @@ origin_to_all (struct GNUNET_MULTICAST_Origin *orig) | |||
822 | /** | 844 | /** |
823 | * Send a message to the multicast group. | 845 | * Send a message to the multicast group. |
824 | * | 846 | * |
825 | * @param orig Handle to the multicast group. | 847 | * @param orig |
826 | * @param message_id Application layer ID for the message. Opaque to multicast. | 848 | * Handle to the multicast group. |
827 | * @param group_generation Group generation of the message. | 849 | * @param message_id |
828 | * Documented in struct GNUNET_MULTICAST_MessageHeader. | 850 | * Application layer ID for the message. Opaque to multicast. |
829 | * @param notify Function to call to get the message. | 851 | * @param group_generation |
830 | * @param notify_cls Closure for @a notify. | 852 | * Group generation of the message. |
853 | * Documented in struct GNUNET_MULTICAST_MessageHeader. | ||
854 | * @param notify | ||
855 | * Function to call to get the message. | ||
856 | * @param notify_cls | ||
857 | * Closure for @a notify. | ||
831 | * | 858 | * |
832 | * @return Message handle on success, | 859 | * @return Message handle on success, |
833 | * NULL on error (i.e. another request is already pending). | 860 | * NULL on error (i.e. another request is already pending). |
@@ -860,7 +887,8 @@ GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *orig, | |||
860 | /** | 887 | /** |
861 | * Resume message transmission to multicast group. | 888 | * Resume message transmission to multicast group. |
862 | * | 889 | * |
863 | * @param th Transmission to cancel. | 890 | * @param th |
891 | * Transmission to cancel. | ||
864 | */ | 892 | */ |
865 | void | 893 | void |
866 | GNUNET_MULTICAST_origin_to_all_resume (struct GNUNET_MULTICAST_OriginTransmitHandle *th) | 894 | GNUNET_MULTICAST_origin_to_all_resume (struct GNUNET_MULTICAST_OriginTransmitHandle *th) |
@@ -872,7 +900,8 @@ GNUNET_MULTICAST_origin_to_all_resume (struct GNUNET_MULTICAST_OriginTransmitHan | |||
872 | /** | 900 | /** |
873 | * Cancel request for message transmission to multicast group. | 901 | * Cancel request for message transmission to multicast group. |
874 | * | 902 | * |
875 | * @param th Transmission to cancel. | 903 | * @param th |
904 | * Transmission to cancel. | ||
876 | */ | 905 | */ |
877 | void | 906 | void |
878 | GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_OriginTransmitHandle *th) | 907 | GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_OriginTransmitHandle *th) |
@@ -892,32 +921,46 @@ GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_OriginTransmitHan | |||
892 | * anytime by the multicast service to support relaying messages to other | 921 | * anytime by the multicast service to support relaying messages to other |
893 | * members of the group. | 922 | * members of the group. |
894 | * | 923 | * |
895 | * @param cfg Configuration to use. | 924 | * @param cfg |
896 | * @param group_key ECC public key that identifies the group to join. | 925 | * Configuration to use. |
897 | * @param member_key ECC key that identifies the member and used to sign | 926 | * @param group_key |
898 | * requests sent to the origin. | 927 | * ECC public key that identifies the group to join. |
899 | * @param origin Peer ID of the origin to send unicast requsets to. If NULL, | 928 | * @param member_key |
929 | * ECC key that identifies the member | ||
930 | * and used to sign requests sent to the origin. | ||
931 | * @param origin | ||
932 | * Peer ID of the origin to send unicast requsets to. If NULL, | ||
900 | * unicast requests are sent back via multiple hops on the reverse path | 933 | * unicast requests are sent back via multiple hops on the reverse path |
901 | * of multicast messages. | 934 | * of multicast messages. |
902 | * @param relay_count Number of peers in the @a relays array. | 935 | * @param relay_count |
903 | * @param relays Peer identities of members of the group, which serve as relays | 936 | * Number of peers in the @a relays array. |
937 | * @param relays | ||
938 | * Peer identities of members of the group, which serve as relays | ||
904 | * and can be used to join the group at. and send the @a join_request to. | 939 | * and can be used to join the group at. and send the @a join_request to. |
905 | * If empty, the @a join_request is sent directly to the @a origin. | 940 | * If empty, the @a join_request is sent directly to the @a origin. |
906 | * @param join_msg Application-dependent join message to be passed to the peer | 941 | * @param join_msg |
907 | * @a origin. | 942 | * Application-dependent join message to be passed to the peer @a origin. |
908 | * @param join_request_cb Function called to approve / disapprove joining of a peer. | 943 | * @param join_request_cb |
909 | * @param join_decision_cb Function called to inform about the join decision. | 944 | * Function called to approve / disapprove joining of a peer. |
910 | * @param member_test_cb Function multicast can use to test group membership. | 945 | * @param join_decision_cb |
911 | * @param replay_frag_cb Function that can be called to replay message fragments | 946 | * Function called to inform about the join decision. |
947 | * @param member_test_cb | ||
948 | * Function multicast can use to test group membership. | ||
949 | * @param replay_frag_cb | ||
950 | * Function that can be called to replay message fragments | ||
912 | * this peer already knows from this group. NULL if this | 951 | * this peer already knows from this group. NULL if this |
913 | * client is unable to support replay. | 952 | * client is unable to support replay. |
914 | * @param replay_msg_cb Function that can be called to replay message fragments | 953 | * @param replay_msg_cb |
954 | * Function that can be called to replay message fragments | ||
915 | * this peer already knows from this group. NULL if this | 955 | * this peer already knows from this group. NULL if this |
916 | * client is unable to support replay. | 956 | * client is unable to support replay. |
917 | * @param message_cb Function to be called for all message fragments we | 957 | * @param message_cb |
958 | * Function to be called for all message fragments we | ||
918 | * receive from the group, excluding those our @a replay_cb | 959 | * receive from the group, excluding those our @a replay_cb |
919 | * already has. | 960 | * already has. |
920 | * @param cls Closure for callbacks. | 961 | * @param cls |
962 | * Closure for callbacks. | ||
963 | * | ||
921 | * @return Handle for the member, NULL on error. | 964 | * @return Handle for the member, NULL on error. |
922 | */ | 965 | */ |
923 | struct GNUNET_MULTICAST_Member * | 966 | struct GNUNET_MULTICAST_Member * |
@@ -982,7 +1025,8 @@ GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
982 | * An application-dependent part message can be transmitted beforehand using | 1025 | * An application-dependent part message can be transmitted beforehand using |
983 | * #GNUNET_MULTICAST_member_to_origin()) | 1026 | * #GNUNET_MULTICAST_member_to_origin()) |
984 | * | 1027 | * |
985 | * @param member Membership handle. | 1028 | * @param member |
1029 | * Membership handle. | ||
986 | */ | 1030 | */ |
987 | void | 1031 | void |
988 | GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *mem, | 1032 | GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *mem, |
@@ -1089,7 +1133,8 @@ GNUNET_MULTICAST_member_replay_message (struct GNUNET_MULTICAST_Member *mem, | |||
1089 | /** | 1133 | /** |
1090 | * Cancel a replay request. | 1134 | * Cancel a replay request. |
1091 | * | 1135 | * |
1092 | * @param rh Request to cancel. | 1136 | * @param rh |
1137 | * Request to cancel. | ||
1093 | */ | 1138 | */ |
1094 | void | 1139 | void |
1095 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh) | 1140 | GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh) |
@@ -1138,10 +1183,15 @@ member_to_origin (struct GNUNET_MULTICAST_Member *mem) | |||
1138 | /** | 1183 | /** |
1139 | * Send a message to the origin of the multicast group. | 1184 | * Send a message to the origin of the multicast group. |
1140 | * | 1185 | * |
1141 | * @param mem Membership handle. | 1186 | * @param mem |
1142 | * @param request_id Application layer ID for the request. Opaque to multicast. | 1187 | * Membership handle. |
1143 | * @param notify Callback to call to get the message. | 1188 | * @param request_id |
1144 | * @param notify_cls Closure for @a notify. | 1189 | * Application layer ID for the request. Opaque to multicast. |
1190 | * @param notify | ||
1191 | * Callback to call to get the message. | ||
1192 | * @param notify_cls | ||
1193 | * Closure for @a notify. | ||
1194 | * | ||
1145 | * @return Handle to cancel request, NULL on error (i.e. request already pending). | 1195 | * @return Handle to cancel request, NULL on error (i.e. request already pending). |
1146 | */ | 1196 | */ |
1147 | struct GNUNET_MULTICAST_MemberTransmitHandle * | 1197 | struct GNUNET_MULTICAST_MemberTransmitHandle * |
@@ -1170,7 +1220,8 @@ GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *mem, | |||
1170 | /** | 1220 | /** |
1171 | * Resume message transmission to origin. | 1221 | * Resume message transmission to origin. |
1172 | * | 1222 | * |
1173 | * @param th Transmission to cancel. | 1223 | * @param th |
1224 | * Transmission to cancel. | ||
1174 | */ | 1225 | */ |
1175 | void | 1226 | void |
1176 | GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmitHandle *th) | 1227 | GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmitHandle *th) |
@@ -1182,7 +1233,8 @@ GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmit | |||
1182 | /** | 1233 | /** |
1183 | * Cancel request for message transmission to origin. | 1234 | * Cancel request for message transmission to origin. |
1184 | * | 1235 | * |
1185 | * @param th Transmission to cancel. | 1236 | * @param th |
1237 | * Transmission to cancel. | ||
1186 | */ | 1238 | */ |
1187 | void | 1239 | void |
1188 | GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th) | 1240 | GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th) |