[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] r27408 - gnunet/src/include
From: |
gnunet |
Subject: |
[GNUnet-SVN] r27408 - gnunet/src/include |
Date: |
Tue, 11 Jun 2013 11:32:07 +0200 |
Author: grothoff
Date: 2013-06-11 11:32:07 +0200 (Tue, 11 Jun 2013)
New Revision: 27408
Modified:
gnunet/src/include/gnunet_multicast_service.h
gnunet/src/include/gnunet_psyc_service.h
Log:
-more work on multicast/psyc API designs
Modified: gnunet/src/include/gnunet_multicast_service.h
===================================================================
--- gnunet/src/include/gnunet_multicast_service.h 2013-06-11 08:43:13 UTC
(rev 27407)
+++ gnunet/src/include/gnunet_multicast_service.h 2013-06-11 09:32:07 UTC
(rev 27408)
@@ -22,11 +22,6 @@
* @file include/gnunet_multicast_service.h
* @brief multicast service; establish tunnels to distant peers
* @author Christian Grothoff
- *
- * TODO:
- * - need to support async message transmission, etc.
- * - need to do sanity check that this is consistent
- * with current ideas for the PSYC layer's needs
*/
#ifndef GNUNET_MULTICAST_SERVICE_H
@@ -147,9 +142,13 @@
};
+GNUNET_NETWORK_STRUCT_BEGIN
+
/**
* Header of a multicast message. This format is public as the replay
- * mechanism must replay messages using the same format.
+ * mechanism must replay messages using the same format. This is
+ * needed as we want to integrity-check messages within the multicast
+ * layer to avoid multicasting mal-formed messages.
*/
struct GNUNET_MULTICAST_MessageHeader
{
@@ -165,10 +164,11 @@
* among honest peers; updated at each hop and thus not signed
* and not secure)
*/
- uint32_t hop_counter;
+ uint32_t hop_counter GNUNET_PACKED;
/**
- * ECC signature of the message.
+ * ECC signature of the message. Signature must match the public
+ * key of the multicast group.
*/
struct GNUNET_CRYPTO_EccSignature signature;
@@ -180,13 +180,13 @@
/**
* Number of the message, monotonically increasing.
*/
- uint64_t message_id;
+ uint64_t message_id GNUNET_PACKED;
/**
* Counter that monotonically increases whenever a member
* leaves the group.
*/
- uint64_t group_generation;
+ uint64_t group_generation GNUNET_PACKED;
/**
* Difference between the current message_id and the message_id of
@@ -206,7 +206,7 @@
* re-create the full state with state update messages following the
* state reset message.
*/
- uint64_t state_delta;
+ uint64_t state_delta GNUNET_PACKED;
/**
* Header for the message body. Three message types are
@@ -220,7 +220,9 @@
/* followed by message body */
};
+GNUNET_NETWORK_STRUCT_END
+
/**
* Replay a message from the multicast group.
*
@@ -235,8 +237,46 @@
/**
+ * Handle that identifies a join request (to match calls to the
+ * 'GNUNET_MULTICAST_MembershipChangeCallback' to the corresponding
+ * calls to 'GNUNET_MULTICAST_join_decision').
+ */
+struct GNUNET_MULTICAST_JoinHande;
+
+
+/**
+ * Function to call with the decision made for a membership change
+ * request. Must be called once and only once in response to an
+ * invocation of the 'GNUNET_MULTICAST_MembershipChangeCallback'.
+ *
+ * @param jh join request handle
+ * @param join_response message to send in response to the joining peer;
+ * can also be used to redirect the peer to a different group at the
+ * application layer; this response is to be transmitted to the
+ * peer that issued the request even if admission is denied.
+ * @param is_admitted GNUNET_OK if joining is approved, GNUNET_SYSERR if it is
disapproved;
+ * GNUNET_NO for peers leaving
+ * @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
+ * are already part of the multicast group and might thus be willing
+ * to help with routing). If empty, only this local peer (which must
+ * be the multicast origin) is a good candidate for building the
+ * multicast tree. Note that it is unnecessary to specify our own
+ * peer identity in this array.
+ */
+void
+GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh,
+ const struct GNUNET_MessageHeader
*join_response,
+ int is_admitted,
+ unsigned int relay_count,
+ const struct GNUNET_PeerIdentity *relays);
+
+
+/**
* Method called whenever another peer wants to join or has left a
- * multicast group.
+ * multicast group. Implementations of this function must call
+ * 'GNUNET_MULTICAST_join_decision' with the decision.
*
* @param cls closure
* @param peer identity of the peer that wants to join or leave
@@ -245,13 +285,13 @@
* bind user identity/pseudonym to peer identity, application-level
* message to origin, etc.)
* @param is_joining GNUNET_YES if the peer wants to join, GNUNET_NO if the
peer left
- * @return GNUNET_OK if joining is approved, GNUNET_SYSERR if it is
disapproved;
- * GNUNET_NO should be returned for peers leaving
+ * @param jh join handle to pass to 'GNUNET_MULTICAST_join_decison'
*/
typedef int (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
const struct
GNUNET_PeerIdentity *peer,
const struct
GNUNET_MessageHeader *join_req,
- int is_joining);
+ int is_joining,
+ struct
GNUNET_MULTICAST_JoinHandle *jh);
/**
@@ -287,18 +327,32 @@
/**
* Function called whenever a group member is receiving a message from
- * the origin.
+ * the origin. If admission to the group is denied, this function is
+ * called once with the response of the 'origin' (as given to
+ * 'GNUNET_MULTICAST_join_decision') and then a second time with "NULL"
+ * to indicate that the connection failed for good.
*
* @param cls closure (set from GNUNET_MULTICAST_member_join)
+ * @param message_id unique number of the message
* @param msg message from the origin, NULL if the origin shut down
* (or we were kicked out, and we should thus call
GNUNET_MULTICAST_member_leave next)
*/
typedef void (*GNUNET_MULTICAST_MessageCallback) (void *cls,
+ uint64_t message_id,
const struct
GNUNET_MULTICAST_MessageHeader *msg);
/**
- * Start a multicast group.
+ * 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 'join_policy' is
+ * permissive) or to the origin. If the joining is approved, the
+ * member is cleared for '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 cls closure for the various callbacks that follow
@@ -325,18 +379,38 @@
/**
+ * Handle for a request to send a message to all multicast group members
+ * (from the origin).
+ */
+struct GNUNET_MULTICAST_MulticastRequest;
+
+
+/**
* Send a message to the multicast group.
*
* @param origin handle to the multicast group
- * @param msg_body body of the message to transmit
- * FIXME: change to notify_transmit_ready-style to wait for ACKs?
+ * @param size number of bytes to transmit
+ * @param cb function to call to get the message
+ * @param cb_cls closure for 'cb'
+ * @return NULL on error (i.e. request already pending)
*/
-void
+struct GNUNET_MULTICAST_MulticastRequest *
GNUNET_MULTICAST_origin_send_to_all (struct GNUNET_MULTICAST_Origin *origin,
- const struct GNUNET_MessageHeader
*msg_body);
+ size_t size,
+ GNUNET_CONNECTION_TransmitReadyNotify cb,
+ void *cb_cls);
/**
+ * Cancel request for message transmission to multicast group.
+ *
+ * @param mr request to cancel
+ */
+void
+GNUNET_MULTICAST_origin_send_to_all_cancel (struct
GNUNET_MULTICAST_MulticastRequest *mr);
+
+
+/**
* End a multicast group.
*
* @param origin multicast group to terminate
@@ -346,7 +420,15 @@
/**
- * Join a multicast group. The entity joining is always the local peer.
+ * Join a multicast group. The entity joining is always the local
+ * peer. Further information about the candidate can be provided in
+ * the 'join_req' message. If the join fails, the 'message_cb' is
+ * invoked with a (failure) response and then with 'NULL'. If the
+ * join succeeds, outstanding (state) messages and ongoing multicast
+ * messages will be given to the 'message_cb' until the member decides
+ * to leave the group. The 'test_cb' and 'replay_cb' functions may be
+ * called at anytime by the multicast service to support relaying
+ * messages to other members of the group.
*
* @param cfg configuration to use
* @param cls closure for callbacks
@@ -396,16 +478,17 @@
* the 'max_known_*_id's given when joining are needed and not
* known to the client.
*
- * FIXME: we currently use the 'replay_cb' from the member_join call;
- * we might alternatively add a different cb here.
- *
* @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 'message_cb'
* @return replay request handle, NULL on error
*/
struct GNUNET_MULTICAST_ReplayRequest *
GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
- uint64_t message_id);
+ uint64_t message_id,
+ GNUNET_MULTICAST_MessageCallback
message_cb,
+ void *message_cb_cls);
/**
@@ -433,19 +516,31 @@
/**
- * Send a message to the origin of the multicast group. FIXME: how
- * will we do routing/flow-control of responses?
+ * Send a message to the origin of the multicast group.
*
* @param member membership handle
- * @param msg message to send to the origin
- * FIXME: change to notify_transmit_ready-style to wait for ACKs...
+ * @param size number of bytes we want to send to origin
+ * @param cb callback to call to get the message
+ * @param cb_cls closure for 'cb'
+ * @return handle to cancel request, NULL on error (i.e. request already
pending)
*/
-void
+struct GNUNET_MULTICAST_ResponseRequest *
GNUNET_MULTICAST_member_message_to_origin (struct GNUNET_MULTICAST_Member
*member,
- const struct GNUNET_MessageHeader
*msg);
+ size_t size,
+
GNUNET_CONNECTION_TransmitReadyNotify cb,
+ void *cb_cls);
+/**
+ * Cancel request for message transmission to origin.
+ *
+ * @param rr request to cancel
+ */
+void
+GNUNET_MULTICAST_member_message_to_origin_cancel (struct
GNUNET_MULTICAST_ResponseRequest *rr);
+
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
Modified: gnunet/src/include/gnunet_psyc_service.h
===================================================================
--- gnunet/src/include/gnunet_psyc_service.h 2013-06-11 08:43:13 UTC (rev
27407)
+++ gnunet/src/include/gnunet_psyc_service.h 2013-06-11 09:32:07 UTC (rev
27408)
@@ -118,7 +118,7 @@
uint64_t message_id,
uint64_t group_generation,
size_t data_size,
- const char *data);
+ const void *data);
/**
@@ -129,7 +129,7 @@
/**
* Start a PSYC channel. Will create a multicast group identified by
- * the given public key. Messages recevied from group members will be
+ * the given ECC key. Messages recevied from group members will be
* given to the respective handler methods. If a new member wants to
* join a group, the "join" method handler will be invoked; the join
* handler must then generate a "join" message to approve the joining
@@ -171,45 +171,46 @@
* Possible operations on PSYC state (persistent) and variables (per message).
*/
enum GNUNET_PSYC_Operator
- {
- /**
- * Replace the full state with the new value ("=").
- */
- GNUNET_PSYC_SOT_SET_STATE = 0,
+{
+ /**
+ * Replace the full state with the new value ("=").
+ */
+ GNUNET_PSYC_SOT_SET_STATE = 0,
+
+ /**
+ * Delete the complete entry from the state (given data must be
+ * empty). Equivalent to 'SET' with emtpy data, but more
+ * explicit ("=");
+ */
+ GNUNET_PSYC_SOT_DELETE = 0,
+
+ /**
+ * Set the value of a variable to a new value (":").
+ */
+ GNUNET_PSYC_SOT_SET_VARIABLE,
+
+ /**
+ * Add the given value to the set of values in the state ("+").
+ */
+ GNUNET_PSYC_SOT_ADD_STATE,
+
+ /**
+ * Remove the given value from the set of values in the state ("-").
+ */
+ GNUNET_PSYC_SOT_REMOVE_STATE
+
+};
- /**
- * Delete the complete entry from the state (given data must be
- * empty). Equivalent to 'SET' with emtpy data, but more
- * explicit ("=");
- */
- GNUNET_PSYC_SOT_DELETE = 0,
- /**
- * Set the value of a variable to a new value (":").
- */
- GNUNET_PSYC_SOT_SET_VARIABLE,
-
- /**
- * Add the given value to the set of values in the state ("+").
- */
- GNUNET_PSYC_SOT_ADD_STATE,
-
- /**
- * Remove the given value from the set of values in the state ("-").
- */
- GNUNET_PSYC_SOT_REMOVE_STATE
-
- };
-
-
/**
- * Update channel state or variables. The state of a channel must fit
- * into the memory of each member (and the channel); large values that
- * require streaming must only be passed as the stream arguments to
- * methods. State updates might not be transmitted to group members
- * until the next call to 'GNUNET_PSYC_channel_broadcast_call_method'.
- * Variable updates must be given just before the call to the
- * respective method that needs the variables.
+ * Update channel state (or set a variable). The state of a channel
+ * must fit into the memory of each member (and the channel); large
+ * values that require streaming must only be passed as the stream
+ * arguments to methods. State updates might not be transmitted to
+ * group members until the next call to
+ * 'GNUNET_PSYC_channel_broadcast_call_method'. Variable updates must
+ * be given just before the call to the respective method that needs
+ * the variables.
*
* @param channel handle to the PSYC group / channel
* @param full_state_name name of the field in the channel state to change
@@ -315,6 +316,16 @@
/**
+ * Convert 'member' to a 'group' handle to access the 'group' APIs.
+ *
+ * @param member membership handle
+ * @return group handle, valid for as long as 'member' is valid
+ */
+struct GNUNET_PSYC_Group *
+GNUNET_PSYC_member_get_group (struct GNUNET_PSYC_Member *member);
+
+
+/**
* Add a member to the group. Note that this will NOT generate any
* PSYC traffic, it will merely update the local data base to modify
* how we react to 'membership test' queries. The channel still needs to
@@ -493,19 +504,19 @@
/**
* Set a (temporary, ":") variable for the next message being transmitted
- * via 'GNUNET_PSYC_member_send_to_host'. If GNUNET_PSYC_member_send_to_host
+ * via 'GNUNET_PSYC_member_send_to_host'. If 'GNUNET_PSYC_member_send_to_host'
* is called and then cancelled, all variables that were set using this
* function will be unset (lost/forgotten). To clear a variable state after
* setting it, you can also call this function again with NULL/0 for the value.
*
* @param member membership handle
- * @param state_name name of the state to set
+ * @param variable_name name of the variable to set
* @param value value to set for the given variable
* @param value_size number of bytes in 'value'
*/
uint64_t
GNUNET_PSYC_member_host_variable_set (struct GNUNET_PSYC_Member *member,
- const char *state_name,
+ const char *variable_name,
const void *value,
size_t value_size);
@@ -563,12 +574,16 @@
/**
- * Call the given state callback on all matching states in the channel
- * state. The callback is invoked synchronously on all matching
- * states (as the state is fully replicated in the library in this
- * process; channel states should be small, large data is to be passed
- * as streaming data to methods).
+ * Call the given callback on all matching values (including
+ * variables) in the channel state. The callback is invoked
+ * synchronously on all matching states (as the state is fully
+ * replicated in the library in this process; channel states should be
+ * small, large data is to be passed as streaming data to methods).
*
+ * A name matches if it includes the 'state_name' prefix, thus
+ * requesting the empty state ("") will match all values; requesting
+ * "a_b" will also return values stored under "a_b_c".
+ *
* @param member membership handle
* @param state_name name of the state to query (full name
* might be longer, this is only the prefix that must match)
@@ -578,34 +593,34 @@
* message ID)
*/
uint64_t
-GNUNET_PSYC_member_state_get (struct GNUNET_PSYC_Member *member,
- const char *state_name,
- GNUNET_PSYC_StateCallback cb,
- void *cb_cls);
+GNUNET_PSYC_member_state_get_all (struct GNUNET_PSYC_Member *member,
+ const char *state_name,
+ GNUNET_PSYC_StateCallback cb,
+ void *cb_cls);
/**
- * Obtain the current value of a variable. This function should only
- * be called during a GNUNET_PSYC_Method invocation (and even then
- * only if the origin is the state owner), as variables are only valid
- * for the duration of a method invocation. If this function is
- * called outside of the scope of such a method invocation, it will
- * return NULL.
+ * Obtain the current value of the best-matching value in the state
+ * (including variables). Note that variables are only valid during a
+ * GNUNET_PSYC_Method invocation, as variables are only valid for the
+ * duration of a method invocation.
*
- * FIXME: do variables have a hierarchy as well? If so,
- * we should document the lookup semantics.
+ * If the requested variable name does not have an exact state in
+ * the state, the nearest less-specific name is matched; for example,
+ * requesting "a_b" will match "a" if "a_b" does not exist.
*
* @param member membership handle
* @param variable_name name of the variable to query
* @param return_value_size set to number of bytes in variable,
* needed as variables might contain binary data and
* might also not be 0-terminated; set to 0 on errors
- * @return NULL on error, pointer to variable state otherwise
+ * @return NULL on error (no matching state or variable), pointer
+ to the respective value otherwise
*/
const void *
-GNUNET_PSYC_member_variable_get (struct GNUNET_PSYC_Member *member,
- const char *variable_name,
- size_t *return_value_size);
+GNUNET_PSYC_member_state_get (struct GNUNET_PSYC_Member *member,
+ const char *variable_name,
+ size_t *return_value_size);
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [GNUnet-SVN] r27408 - gnunet/src/include,
gnunet <=