X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_multicast_service.h;h=e187b963bb84625e99f7e418c60f1e63b51ad541;hb=74894fd51af4cc9011b28a8eaab9bb70fa1efcd7;hp=b4f9bc099bbbf3940ceb3ad3bb194d0123242dcd;hpb=d734cfd6677de174aa51a07437b0e0cae4c870be;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h index b4f9bc099..e187b963b 100644 --- a/src/include/gnunet_multicast_service.h +++ b/src/include/gnunet_multicast_service.h @@ -55,66 +55,6 @@ struct GNUNET_MULTICAST_Member; */ struct GNUNET_MULTICAST_Origin; -/** - * Policy flags for the group. - */ -enum GNUNET_MULTICAST_GroupFlags -{ - /** - * Admission must be confirmed by the origin. - */ - GNUNET_MULTICAST_GROUP_ADMISSION_CONTROL = 1 << 0, - - /** - * Past messages are only available to peers who were a member at the time - * they were sent to the group. - */ - GNUNET_MULTICAST_GROUP_RESTRICTED_HISTORY = 1 << 1, -}; - -/** - * Group membership policies. - */ -enum GNUNET_MULTICAST_GroupPolicy -{ - /** - * Anyone can join the group, without announcing his presence; - * all messages are always public and can be distributed freely. - * Joins may be announced, but this is not required. - */ - GNUNET_MULTICAST_GROUP_ANONYMOUS = 0, - - /** - * Origin must approve membership to the group, messages must only be - * distributed to current group members. This includes the group - * state as well as transient messages. - */ - GNUNET_MULTICAST_GROUP_PRIVATE - = GNUNET_MULTICAST_GROUP_ADMISSION_CONTROL - | GNUNET_MULTICAST_GROUP_RESTRICTED_HISTORY, - -#if IDEAS_FOR_FUTURE - /** - * Anyone can freely join the group (no approval required); - * however, messages must only be distributed to current group - * members, so the origin must still acknowledge that the member - * joined before transient messages are delivered. As approval is - * guaranteed, the presistent group state can be synchronized freely - * immediately, prior to origin confirmation. - */ - GNUNET_MULTICAST_GROUP_OPEN - = GNUNET_MULTICAST_GROUP_RESTRICTED_HISTORY, - - /** - * Origin must approve membership to the group, but past messages can be - * freely distributed to members. - */ - GNUNET_MULTICAST_GROUP_CLOSED - = GNUNET_MULTICAST_GROUP_ADMISSION_CONTROL, -, -#endif - -}; enum GNUNET_MULTICAST_MessageFlags { @@ -180,14 +120,6 @@ struct GNUNET_MULTICAST_MessageHeader */ uint64_t fragment_id GNUNET_PACKED; - /** - * Number of fragments before the current one that has the same @a message_id. - * - * 0 for the first fragment of a message. - * This allows replaying a message with all of its fragments. - */ - uint64_t fragment_delta GNUNET_PACKED; - /** * Byte offset of this @e fragment of the @e message. */ @@ -331,7 +263,7 @@ GNUNET_NETWORK_STRUCT_END * Handle that identifies a join request. * * Used to match calls to #GNUNET_MULTICAST_JoinCallback to the - * corresponding calls to GNUNET_MULTICAST_join_decision(). + * corresponding calls to #GNUNET_MULTICAST_join_decision(). */ struct GNUNET_MULTICAST_JoinHandle; @@ -345,6 +277,7 @@ struct GNUNET_MULTICAST_JoinHandle; * @param jh Join request handle. * @param is_admitted #GNUNET_YES if joining is approved, * #GNUNET_NO if it is disapproved + * @param admitted_since Message ID the member is admitted since. * @param relay_count Number of relays given. * @param relays Array of suggested peers that might be useful relays to use * when joining the multicast group (essentially a list of peers that @@ -361,6 +294,7 @@ struct GNUNET_MULTICAST_JoinHandle; void GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh, int is_admitted, + uint64_t admitted_since, unsigned int relay_count, const struct GNUNET_PeerIdentity *relays, const struct GNUNET_MessageHeader *join_response); @@ -394,7 +328,7 @@ struct GNUNET_MULTICAST_MembershipTestHandle; /** - * Call informing multicast about the decision taken for membership test. + * Call informing multicast about the decision taken for a membership test. * * @param mth Handle that was given for the query. * @param result #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member, @@ -412,14 +346,18 @@ GNUNET_MULTICAST_membership_test_result (struct GNUNET_MULTICAST_MembershipTestH * message can be replayed. * * @param cls Closure. - * @param member_id Identity of the member that we want to test. - * @param fragment_id Message fragment ID for which we want to do the test. + * @param member_key Identity of the member that we want to test. + * @param message_id Message ID for which to perform the test. + * @param group_generation Group generation of the message. It has relevance if + * the message consists of multiple fragments with different group + * generations. * @param mth Handle to give to GNUNET_MULTICAST_membership_test_answer(). */ typedef void (*GNUNET_MULTICAST_MembershipTestCallback) (void *cls, const struct GNUNET_CRYPTO_EccPublicKey *member_key, - uint64_t fragment_id, + uint64_t message_id, + uint64_t group_generation, struct GNUNET_MULTICAST_MembershipTestHandle *mth); @@ -454,7 +392,19 @@ typedef void */ typedef void (*GNUNET_MULTICAST_MessageCallback) (void *cls, - const struct GNUNET_MULTICAST_MessageHeader *msg); + const struct GNUNET_MessageHeader *msg); + + +/** + * Function called with the result of an asynchronous operation. + * + * @see GNUNET_MULTICAST_replay_fragment() + * + * @param result Result of the operation. + */ +typedef void +(*GNUNET_MULTICAST_ResultCallback) (void *cls, + int result); /** @@ -472,14 +422,42 @@ struct GNUNET_MULTICAST_ReplayHandle; * group is left, the replay handle must no longer be used. * * @param cls Closure (set from GNUNET_MULTICAST_origin_start() - * or GNUNET_MULTICAST_member_join()). + * or GNUNET_MULTICAST_member_join()). + * @param member_key The member requesting replay. * @param fragment_id Which message fragment should be replayed. + * @param flags Flags for the replay. * @param rh Handle to pass to message transmit function. */ typedef void -(*GNUNET_MULTICAST_ReplayCallback) (void *cls, - uint64_t fragment_id, - struct GNUNET_MULTICAST_ReplayHandle *rh); +(*GNUNET_MULTICAST_ReplayFragmentCallback) (void *cls, + const struct GNUNET_CRYPTO_EccPublicKey *member_key, + uint64_t fragment_id, + uint64_t flags, + struct GNUNET_MULTICAST_ReplayHandle *rh); + +/** + * Functions with this signature are called whenever the multicast service needs + * a message to be replayed. + * + * Implementations of this function MUST call GNUNET_MULTICAST_replay() ONCE + * (with a message or an error); however, if the origin is destroyed or the + * group is left, the replay handle must no longer be used. + * + * @param cls Closure (set from GNUNET_MULTICAST_origin_start() + * or GNUNET_MULTICAST_member_join()). + * @param member_key The member requesting replay. + * @param message_id Which message should be replayed. + * @param fragment_offset Offset of the fragment within of @a message_id to be replayed. + * @param flags Flags for the replay. + * @param rh Handle to pass to message transmit function. + */ +typedef void +(*GNUNET_MULTICAST_ReplayMessageCallback) (void *cls, + const struct GNUNET_CRYPTO_EccPublicKey *member_key, + uint64_t message_id, + uint64_t fragment_offset, + uint64_t flags, + struct GNUNET_MULTICAST_ReplayHandle *rh); /** @@ -494,28 +472,38 @@ enum GNUNET_MULTICAST_ReplayErrorCode GNUNET_MULTICAST_REC_OK = 0, /** - * Message fragment has been discarded (likely transient message that was too old). + * Message fragment not found in the message store. + * + * Either discarded if it is too old, or not arrived yet if this member has + * missed some messages. */ - GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1, + GNUNET_MULTICAST_REC_NOT_FOUND = 1, /** * Fragment ID counter was larger than the highest counter this * replay function has ever encountered; thus it is likely the * origin never sent it and we're at the HEAD of the multicast * stream as far as this node is concerned. + * + * FIXME: needed? */ GNUNET_MULTICAST_REC_PAST_HEAD = 2, + /** + * Access is denied to the requested fragment, membership test did not pass. + */ + GNUNET_MULTICAST_REC_ACCESS_DENIED = 3, + /** * Internal error (i.e. database error). Try some other peer. */ - GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3 + GNUNET_MULTICAST_REC_INTERNAL_ERROR = 4 }; /** - * Replay a message from the multicast group. + * Replay a message fragment for the multicast group. * * @param rh Replay handle identifying which replay operation was requested. * @param msg Replayed message fragment, NULL if unknown/error. @@ -523,9 +511,31 @@ enum GNUNET_MULTICAST_ReplayErrorCode */ void GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, - const struct GNUNET_MULTICAST_MessageHeader *msg, + const struct GNUNET_MessageHeader *msg, enum GNUNET_MULTICAST_ReplayErrorCode ec); +/** + * Function called to provide data for a transmission for a replay. + * + * @see GNUNET_MULTICAST_replay2() + */ +typedef int +(*GNUNET_MULTICAST_ReplayTransmitNotify)(void *cls, + size_t *data_size, + void *data); + +/** + * Replay a message for the multicast group. + * + * @param rh Replay handle identifying which replay operation was requested. + * @param notify Function to call to get the message. + * @param notify_cls Closure for @a notify. + */ +void +GNUNET_MULTICAST_replay2 (struct GNUNET_MULTICAST_ReplayHandle *rh, + GNUNET_MULTICAST_ReplayTransmitNotify notify, + void *notify_cls); + /** * Start a multicast group. @@ -533,18 +543,17 @@ GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, * Will advertise the origin in the P2P overlay network under the respective * public key so that other peer can find this peer to join it. Peers that * issue GNUNET_MULTICAST_member_join() can then transmit a join request to - * either an existing group member (if the @a policy is permissive) or to - * the origin. If the joining is approved, the member is cleared for @e replay - * and will begin to receive messages transmitted to the group. If joining is - * disapproved, the failed candidate will be given a response. Members in the - * group can send messages to the origin (one at a time). + * either an existing group member or to the origin. If the joining is + * approved, the member is cleared for @e replay and will begin to receive + * messages transmitted to the group. If joining is disapproved, the failed + * candidate will be given a response. Members in the group can send messages + * to the origin (one at a time). * * @param cfg Configuration to use. * @param priv_key ECC key that will be used to sign messages for this * multicast session; public key is used to identify the multicast group; * FIXME: we'll likely want to use NOT the p521 curve here, but a cheaper * one in the future. - * @param policy Group policy specifying join and history restrictions. * @param last_fragment_id Last fragment ID to continue counting fragments from * when restarting the origin. 0 for a new group. * @param join_cb Function called to approve / disapprove joining of a peer. @@ -560,7 +569,6 @@ GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh, struct GNUNET_MULTICAST_Origin * GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, const struct GNUNET_CRYPTO_EccPrivateKey *priv_key, - enum GNUNET_MULTICAST_GroupPolicy policy, uint64_t last_fragment_id, GNUNET_MULTICAST_JoinCallback join_cb, GNUNET_MULITCAST_MembershipTestCallback test_cb, @@ -569,6 +577,14 @@ GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, GNUNET_MULTICAST_MessageCallback message_cb, void *cls); +/** + * Function called to provide data for a transmission from the origin to all members. + */ +typedef int +(*GNUNET_MULTICAST_OriginTransmitNotify)(void *cls, + size_t *data_size, + void *data); + /** * Handle for a request to send a message to all multicast group members @@ -595,7 +611,7 @@ GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin, uint64_t message_id, uint64_t group_generation, size_t size, - GNUNET_CONNECTION_TransmitReadyNotify notify, + GNUNET_MULTICAST_OriginTransmitNotify notify, void *notify_cls); @@ -683,22 +699,53 @@ struct GNUNET_MULTICAST_MemberReplayHandle; /** - * Request a message to be replayed. + * Request a fragment to be replayed by fragment ID. * * Useful if messages below the @e max_known_fragment_id given when joining are * needed and not known to the client. * * @param member Membership handle. - * @param message_id ID of a message that this client would like to see replayed. - * @param message_cb Function to be called for the replayed message. - * @param message_cb_cls Closure for @a message_cb. + * @param fragment_id ID of a message fragment that this client would like to + see replayed. + * @param flags Additional flags for the replay request. It is used and defined + * by the replay callback. FIXME: which replay callback? FIXME: use enum? + * FIXME: why not pass reply cb here? * @return Replay request handle, NULL on error. */ struct GNUNET_MULTICAST_MemberReplayHandle * -GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member, +GNUNET_MULTICAST_member_replay_fragment (struct GNUNET_MULTICAST_Member *member, + uint64_t fragment_id, + uint64_t flags); + + +/** + * Request a message fr to be replayed. + * + * Useful if messages below the @e max_known_fragment_id given when joining are + * needed and not known to the client. + * + * @param member Membership handle. + * @param fragment_id ID of a message fragment that this client would like to + see replayed. + * @param message_id ID of a message that this client would like to see + * replayed. Typically only one of the @a fragment_id and @a message_id + * is given. Specifying a @a message_id would return the last fragment + * of the message, which allows requesting the preceding fragments of the + * message by looking at the @e fragment_delta header field. + * @param flags Additional flags for the replay request. It is used & defined + * by the replay callback. E.g. the PSYC service would use this to + * implement state synchronization. + * @param result_cb Function to be called for the replayed message. + * @param result_cb_cls Closure for @a message_cb. + * @return Replay request handle, NULL on error. + */ +struct GNUNET_MULTICAST_MemberReplayHandle * +GNUNET_MULTICAST_member_replay_message (struct GNUNET_MULTICAST_Member *member, uint64_t message_id, - GNUNET_MULTICAST_MessageCallback message_cb, - void *message_cb_cls); + uint64_t fragment_offset, + uint64_t flags, + GNUNET_MULTICAST_ResultCallback result_cb, + void *result_cb_cls); /** @@ -707,7 +754,7 @@ GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member, * @param rh Request to cancel. */ void -GNUNET_MULTICAST_member_request_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); +GNUNET_MULTICAST_member_replay_cancel (struct GNUNET_MULTICAST_MemberReplayHandle *rh); /** @@ -716,7 +763,7 @@ GNUNET_MULTICAST_member_request_replay_cancel (struct GNUNET_MULTICAST_MemberRep * Disconnects from all group members and invalidates the @a member handle. * * An application-dependent part message can be transmitted beforehand using - * GNUNET_MULTICAST_member_to_origin()) + * #GNUNET_MULTICAST_member_to_origin()) * * @param member Membership handle. */ @@ -724,6 +771,20 @@ void GNUNET_MULTICAST_member_part (struct GNUNET_MULTICAST_Member *member); +/** + * Function called to provide data for a transmission from a member to the origin. + * + * @param cls closure + * @param data_size number of bytes available in @a data + * @param data where to copy data for transmission + * @return number of bytes copied to data + */ +typedef int +(*GNUNET_MULTICAST_MemberTransmitNotify)(void *cls, + size_t *data_size, + void *data); + + /** * Handle for a message to be delivered from a member to the origin. */ @@ -744,7 +805,7 @@ struct GNUNET_MULTICAST_MemberRequestHandle * GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member, uint64_t message_id, size_t size, - GNUNET_CONNECTION_TransmitReadyNotify notify, + GNUNET_MULTICAST_MemberTransmitNotify notify, void *notify_cls);