*/
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
{
*/
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.
*/
* 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;
* @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
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);
/**
- * 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,
* 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);
*/
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);
/**
* 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);
/**
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.
*/
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.
* 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.
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,
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
uint64_t message_id,
uint64_t group_generation,
size_t size,
- GNUNET_CONNECTION_TransmitReadyNotify notify,
+ GNUNET_MULTICAST_OriginTransmitNotify notify,
void *notify_cls);
/**
- * 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);
/**
* @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);
/**
* 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.
*/
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.
*/
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);