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

[gnunet]

Author: tg
Date: 2013-06-27 12:05:03 +0200 (Thu, 27 Jun 2013)
New Revision: 27647

Modified:
   gnunet/src/include/gnunet_multicast_service.h
   gnunet/src/include/gnunet_protocols.h
Log:
multicast: messages types; function & callback for ping/pong messages; separate 
join/leave callbacks

Modified: gnunet/src/include/gnunet_multicast_service.h
===================================================================
--- gnunet/src/include/gnunet_multicast_service.h       2013-06-27 10:01:34 UTC 
(rev 27646)
+++ gnunet/src/include/gnunet_multicast_service.h       2013-06-27 10:05:03 UTC 
(rev 27647)
@@ -95,61 +95,6 @@
 };
 
 
-/** 
- * Opaque handle to a replay request from the multicast service.
- */
-struct GNUNET_MULTICAST_ReplayHandle;
-
-
-/** 
- * 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 message_id Which message should be replayed.
- * @param rh Handle to pass to message transmit function.
- */
-typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls,
-                                                uint64_t message_id,
-                                                struct 
GNUNET_MULTICAST_ReplayHandle *rh);
-
-
-/** 
- * Possible error codes during replay.
- */
-enum GNUNET_MULTICAST_ReplayErrorCode
-{
-
-  /** 
-   * Everything is fine.
-   */ 
-  GNUNET_MULTICAST_REC_OK = 0,
-
-  /** 
-   * Message has been discarded (likely transient message that was too old).
-   */ 
-  GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1,
-
-  /** 
-   * Message 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.
-   */ 
-  GNUNET_MULTICAST_REC_PAST_HEAD = 2,
-
-  /** 
-   * Internal error (i.e. database error).  Try some other peer.
-   */ 
-  GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3
-
-};
-
-
 GNUNET_NETWORK_STRUCT_BEGIN
 
 /** 
@@ -242,32 +187,19 @@
 
 
 /** 
- * Replay a message from the multicast group.
- *
- * @param rh Replay handle identifying which replay operation was requested.
- * @param msg Replayed message, NULL if unknown/error.
- * @param ec Error code.
- */
-void
-GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
-                        const struct GNUNET_MULTICAST_MessageHeader *msg,
-                        enum GNUNET_MULTICAST_ReplayErrorCode ec);
-
-
-/** 
  * Handle that identifies a join request.
  *
- * Used to match calls to #GNUNET_MULTICAST_MembershipChangeCallback to the
+ * Used to match calls to #GNUNET_MULTICAST_JoinCallback to the
  * corresponding calls to GNUNET_MULTICAST_join_decision().
  */
-struct GNUNET_MULTICAST_JoinHande;
+struct GNUNET_MULTICAST_JoinHandle;
 
 
 /** 
  * 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.
+ * #GNUNET_MULTICAST_JoinCallback.
  *
  * @param jh Join request handle.
  * @param join_response Message to send in response to the joining peer;
@@ -295,28 +227,40 @@
 
 
 /** 
- * Method called whenever another peer wants to join or has left a multicast
- * group.
+ * Method called whenever another peer wants to join the 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.
- * @param join_req Application-dependent join message from the new user
+ * @param peer Identity of the peer that wants to join.
+ * @param msg Application-dependent join message from the new user
  *        (might, for example, contain a user,
  *        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.
  * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison().
  */
-typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
-                                                         const struct 
GNUNET_PeerIdentity *peer,
-                                                         const struct 
GNUNET_MessageHeader *join_req,
-                                                         int is_joining,
-                                                         struct 
GNUNET_MULTICAST_JoinHandle *jh);
+typedef void (*GNUNET_MULTICAST_JoinCallback)(void *cls,
+                                              const struct GNUNET_PeerIdentity 
*peer,
+                                              const struct 
GNUNET_MessageHeader *msg,
+                                              struct 
GNUNET_MULTICAST_JoinHandle *jh);
 
+/** 
+ * Method called whenever another peer wants to leave the multicast group.
+ *
+ * A leave request must be always be honoured.
+ *
+ * @param cls Closure.
+ * @param peer Identity of the peer that wants to leave.
+ * @param msg Application-dependent leave message from the leaving user.
+ * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison().
+ */
+typedef void (*GNUNET_MULTICAST_LeaveCallback)(void *cls,
+                                               const struct 
GNUNET_PeerIdentity *peer,
+                                               const struct 
GNUNET_MessageHeader *msg,
+                                               struct 
GNUNET_MULTICAST_JoinHandle *jh);
 
+
 /** 
  * Handle to pass back for the answer of a membership test.
  */
@@ -355,22 +299,23 @@
  *
  * @param cls Closure (set from GNUNET_MULTICAST_origin_start).
  * @param sender Identity of the sender.
- * @param response_id Unique counter for the response from this sender to this 
origin.
+ * @param request_id Unique counter for the request from this sender to this 
origin.
  * @param msg Message to the origin.
  */
-typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls,
-                                                  const struct 
GNUNET_PeerIdentity *sender,
-                                                  uint64_t response_id,
-                                                  const struct 
GNUNET_MessageHeader *msg);
+typedef void (*GNUNET_MULTICAST_RequestCallback) (void *cls,
+                                                  const struct 
GNUNET_PeerIdentity *sender,
+                                                  uint64_t request_id,
+                                                  const struct 
GNUNET_MessageHeader *msg);
 
 
 /** 
  * Function called whenever a group member is receiving a message from
- * the origin.  If admission to the group is denied, this function is
- * called once with the response of the @e origin (as given to 
- * GNUNET_MULTICAST_join_decision()) and then a second time with NULL
- * to indicate that the connection failed for good.
+ * the origin.
  *
+ * If admission to the group is denied, this function is called once with the
+ * response of the @e 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, 0 for response to join 
request,
  *        normal message IDs in either direction start at 1.
@@ -384,6 +329,112 @@
 
 
 /** 
+ * Opaque handle to a replay request from the multicast service.
+ */
+struct GNUNET_MULTICAST_ReplayHandle;
+
+
+/** 
+ * 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 message_id Which message should be replayed.
+ * @param rh Handle to pass to message transmit function.
+ */
+typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls,
+                                                uint64_t message_id,
+                                                struct 
GNUNET_MULTICAST_ReplayHandle *rh);
+
+
+/** 
+ * Possible error codes during replay.
+ */
+enum GNUNET_MULTICAST_ReplayErrorCode
+{
+
+  /** 
+   * Everything is fine.
+   */ 
+  GNUNET_MULTICAST_REC_OK = 0,
+
+  /** 
+   * Message has been discarded (likely transient message that was too old).
+   */ 
+  GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1,
+
+  /** 
+   * Message 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.
+   */ 
+  GNUNET_MULTICAST_REC_PAST_HEAD = 2,
+
+  /** 
+   * Internal error (i.e. database error).  Try some other peer.
+   */ 
+  GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3
+
+};
+
+
+/** 
+ * Replay a message from the multicast group.
+ *
+ * @param rh Replay handle identifying which replay operation was requested.
+ * @param msg Replayed message, NULL if unknown/error.
+ * @param ec Error code.
+ */
+void
+GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
+                        const struct GNUNET_MULTICAST_MessageHeader *msg,
+                        enum GNUNET_MULTICAST_ReplayErrorCode ec);
+
+
+/** 
+ * Handle to pass back for the answer of a ping.
+ */
+struct GNUNET_MULTICAST_PingHandle;
+
+
+/** 
+ * A response to a @e ping.
+ *
+ * @param ph Handle that was given for the ping.
+ * @param message_id Latest message ID seen by this peer for this group.
+ */
+void
+GNUNET_MULTICAST_pong (struct GNUNET_MULTICAST_ReplayHandle *rh,
+                       uint64_t message_id);
+
+
+/** 
+ * Method called whenever a @e ping is received from another member.
+ *
+ * A @e ping is sent after a period of inactivity to check if the member has 
not
+ * missed any messages.  A ping contains the latest message ID a member has
+ * seen.  If the latest message ID on the receiving member is higher, the
+ * missing messages must be replayed to the requesting member using
+ * GNUNET_MULTICAST_replay(), otherwise GNUNET_MULTICAST_pong() must be called 
with
+ * the same message ID, indicating no newer messages was seen by this peer.
+ *
+ * @param cls Closure.
+ * @param peer Identity of the peer who sent the ping.
+ * @param latest_message_id Latest message ID seen by the requesting member.
+ * @param rh Handle to pass back to GNUNET_MULTICAST_pong() or 
GNUNET_MULTICAST_replay().
+ */
+typedef void (*GNUNET_MULTICAST_PingCallback)(void *cls,
+                                              const struct GNUNET_PeerIdentity 
*peer,
+                                              uint64_t latest_messaged_id
+                                              struct 
GNUNET_MULTICAST_ReplayHandle *rh);
+
+
+/** 
  * Start a multicast group.
  *
  * Will advertise the origin in the P2P overlay network under the respective
@@ -404,10 +455,10 @@
  * @param join_policy What is the membership policy of the group?
  * @param replay_cb Function that can be called to replay a message.
  * @param test_cb Function multicast can use to test group membership.
- * @param join_cb Function called to approve / disapprove joining of a peer,
- *                and to inform about a leaving member.
- * @param leave_cb Function called to inform about a leaving member.
- * @param response_cb Function called with messages from group members.
+ * @param ping_cb Function called to answer a ping.
+ * @param join_cb Function called to approve / disapprove joining of a peer.
+ * @param leave_cb Function called when a member wants to leave the group.
+ * @param request_cb Function called with messages from group members.
  * @return Handle for the origin, NULL on error.
  */
 struct GNUNET_MULTICAST_Origin *
@@ -417,8 +468,10 @@
                               enum GNUNET_MULTICAST_JoinPolicy join_policy,
                               GNUNET_MULITCAST_ReplayCallback replay_cb,
                               GNUNET_MULITCAST_MembershipTestCallback test_cb,
-                              GNUNET_MULTICAST_MembershipChangeCallback 
join_cb,
-                              GNUNET_MULTICAST_ResponseCallback response_cb);
+                              GNUNET_MULITCAST_PingCallback ping_cb,
+                              GNUNET_MULTICAST_JoinCallback join_cb,
+                              GNUNET_MULTICAST_LeaveCallback leave_cb,
+                              GNUNET_MULTICAST_RequestCallback request_cb);
 
 
 /** 

Modified: gnunet/src/include/gnunet_protocols.h
===================================================================
--- gnunet/src/include/gnunet_protocols.h       2013-06-27 10:01:34 UTC (rev 
27646)
+++ gnunet/src/include/gnunet_protocols.h       2013-06-27 10:05:03 UTC (rev 
27647)
@@ -1922,40 +1922,68 @@
  
******************************************************************************/
 
 /**
- * Multicast message, from origin to all members
+ * Multicast message from the origin to all members.
  */
 #define GNUNET_MESSAGE_TYPE_MULTICAST_MESSAGE
 
 /**
- * A peer joined the group.
+ * A unicast message from a group member to the origin.
  */
-#define GNUNET_MESSAGE_TYPE_MULTICAST_JOIN
+#define GNUNET_MESSAGE_TYPE_MULTICAST_REQUEST
 
+
 /**
- * A peer left the group.
+ * A peer wants to join the group.
+ *
+ * Unicast message to a group member.
  */
-#define GNUNET_MESSAGE_TYPE_MULTICAST_LEAVE
+#define GNUNET_MESSAGE_TYPE_MULTICAST_REQUEST_JOIN
 
 /**
- * Message from a peer to origin.
+ * A join request was rejected.
+ *
+ * Unicast response to a join request.
  */
-#define GNUNET_MESSAGE_TYPE_MULTICAST_PEER_MESSAGE
+#define GNUNET_MESSAGE_TYPE_MULTICAST_REJECT_JOIN
 
 /**
- * A peer wants to join the group.
+ * A peer joined the group.
+ *
+ * Sent to all members by the origin.
  */
-#define GNUNET_MESSAGE_TYPE_MULTICAST_PEER_JOIN
+#define GNUNET_MESSAGE_TYPE_MULTICAST_NOTICE_JOIN
 
 /**
  * A peer wants to leave the group.
  */
-#define GNUNET_MESSAGE_TYPE_MULTICAST_PEER_LEAVE
+#define GNUNET_MESSAGE_TYPE_MULTICAST_REQUEST_LEAVE
 
 /**
+ * A peer left the group.
+ */
+#define GNUNET_MESSAGE_TYPE_MULTICAST_NOTICE_LEAVE
+
+/**
+ * Ping request from a peer.
+ *
+ * A ping is sent after a period of inactivity and contains the last received
+ * message ID.
+ */
+#define GNUNET_MESSAGE_TYPE_MULTICAST_PEER_PING
+
+/**
+ * Response to a ping.
+ *
+ * Contains the last received message ID.
+ */
+#define GNUNET_MESSAGE_TYPE_MULTICAST_PEER_PONG
+
+/**
  * Group terminated.
  */
 #define GNUNET_MESSAGE_TYPE_MULTICAST_GROUP_END
 
+
 
/*******************************************************************************
  * PSYC message types
  
******************************************************************************/