[GNUnet-SVN] r27408 - gnunet/src/include

[gnunet]

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);