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

[gnunet]

Author: grothoff
Date: 2013-06-11 15:14:16 +0200 (Tue, 11 Jun 2013)
New Revision: 27412

Modified:
   gnunet/src/include/gnunet_multicast_service.h
   gnunet/src/include/gnunet_psyc_service.h
Log:
-further refinements to the APIs for PSYC/multicast

Modified: gnunet/src/include/gnunet_multicast_service.h
===================================================================
--- gnunet/src/include/gnunet_multicast_service.h       2013-06-11 11:44:41 UTC 
(rev 27411)
+++ gnunet/src/include/gnunet_multicast_service.h       2013-06-11 13:14:16 UTC 
(rev 27412)
@@ -205,6 +205,10 @@
    * thereby starting a new chain.  The origin will then have to
    * re-create the full state with state update messages following the
    * state reset message.
+   *
+   * Open question: needed in multicast, or just have this in PSYC;
+   * still might be useful for selective fetching of messages.
+   * Still, that again should that not be done by PSYC?
    */
   uint64_t state_delta GNUNET_PACKED;
 
@@ -287,27 +291,27 @@
  * @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 int (*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_MembershipChangeCallback)(void *cls,
+                                                         const struct 
GNUNET_PeerIdentity *peer,
+                                                         const struct 
GNUNET_MessageHeader *join_req,
+                                                         int is_joining,
+                                                         struct 
GNUNET_MULTICAST_JoinHandle *jh);
 
 
 /**
  * Method called to test if a member was in the group at a particular time.
  *
+ * FIXME: maybe allow reply to be asynchronous
+ *
  * @param cls closure
  * @param peer identity of the peer that we want to test
  * @param message_id message ID for which we want to do the test
- * @param group_generation the generation of the group for which we want to do 
the test
  * @return GNUNET_YES if peer was a member, GNUNET_NO if peer was not a member,
  *         GNUNET_SYSERR if we cannot answer the membership test
  */
 typedef int (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls,
                                                       const struct 
GNUNET_PeerIdentity *peer,
-                                                      uint64_t message_id,
-                                                      uint64_t 
group_generation);
+                                                      uint64_t message_id);
 
 
 /**
@@ -333,13 +337,14 @@
  * 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 message_id unique number of the message, 0 for response to join 
request,
+ *        normal message IDs in either direction start at 1.
  * @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);
+typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls,
+                                                          uint64_t message_id,
+                                                          const struct 
GNUNET_MULTICAST_MessageHeader *msg);
 
 
 /**
@@ -463,7 +468,7 @@
                              uint64_t max_known_state_message_id,
                              GNUNET_MULTICAST_ReplayCallback replay_cb,
                              GNUNET_MULITCAST_MembershipTestCallback test_cb,
-                             GNUNET_MULTICAST_MessageCallback message_cb,
+                             GNUNET_MULTICAST_MulticastMessageCallback 
message_cb,
                              const struct GNUNET_MessageHeader *join_req);
 
 
@@ -487,7 +492,7 @@
 struct GNUNET_MULTICAST_ReplayRequest *
 GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
                                        uint64_t message_id,
-                                       GNUNET_MULTICAST_MessageCallback 
message_cb,
+                                       
GNUNET_MULTICAST_MulticastMessageCallback message_cb,
                                        void *message_cb_cls);
 
 

Modified: gnunet/src/include/gnunet_psyc_service.h
===================================================================
--- gnunet/src/include/gnunet_psyc_service.h    2013-06-11 11:44:41 UTC (rev 
27411)
+++ gnunet/src/include/gnunet_psyc_service.h    2013-06-11 13:14:16 UTC (rev 
27412)
@@ -95,6 +95,28 @@
 
 
 /**
+ * Information flags for data fragments set via PSYC.
+ */
+enum GNUNET_PSYC_FragmentStatus
+{
+  /**
+   * This is the first part of data for the given method call.
+   */
+  GNUNET_PSYC_FS_FIRST = 1,
+  
+  /**
+   * This is the last part of data for the given method call.
+   */
+  GNUNET_PSYC_FS_LAST = 2,
+
+  /**
+   * OR'ed flags if payload is not fragmented.
+   */
+  GNUNET_PSYC_FS_NOT_FRAGMENTED = (GNUNET_PSYC_FS_FIRST | GNUNET_PSYC_FS_LAST)
+};
+
+
+/**
  * Method called from PSYC upon receiving a message indicating a call
  * to a 'method'.  
  *
@@ -107,18 +129,22 @@
  *                   (unique only in combination with the given sender for
  *                    this channel)
  * @param group_generation group generation counter for this message
- *                   (always zero for messages from members to channel owner)
- * @param data_size number of bytes in 'data'
+ *                   (always zero for messages from members to channel owner); 
FIXME: needed?
+ * @param data_off byte offset of 'data' in the overall data of the method
+ * @param data_size number of bytes in 'data'; 
  * @param data data stream given to the method (might not be zero-terminated 
  *             if data is binary)
+ * @param frag fragmentation status for the data
  */
 typedef int (*GNUNET_PSYC_Method)(void *cls,
                                  const char *full_method_name,
                                  const struct GNUNET_PeerIdentity *sender,
                                  uint64_t message_id,
                                  uint64_t group_generation,
+                                 uint64_t data_off,
                                  size_t data_size,
-                                 const void *data);
+                                 const void *data,
+                                 enum GNUNET_PSYC_FragmentStatus frag);
 
 
 /**
@@ -140,10 +166,9 @@
  * events.
  *
  * @param cfg configuration to use (to connect to PSYC service)
- * @param name name of the channel, only important if this is a subchannel
- * @param method_count number of methods in 'methods' array
- * @param methods functions to invoke on messages received from members,
+ * @param method functions to invoke on messages received from members,
  *                typcially at least contains functions for 'join' and 'leave'.
+ * @param method_cls closure for 'method'
  * @param priv_key ECC key that will be used to sign messages for this
  *                 PSYC session; public key is used to identify the
  *                 PSYC group; FIXME: we'll likely want to use
@@ -158,9 +183,8 @@
  */
 struct GNUNET_PSYC_Channel *
 GNUNET_PSYC_channel_start (const struct GNUNET_CONFIGURATION_Handle *cfg, 
-                          const char *name,
-                          unsigned int method_count,
-                          const struct GNUNET_PSYC_Method *methods,
+                          GNUNET_PSYC_Method method,
+                          void *method_cls,
                           const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
                           enum GNUNET_MULTICAST_JoinPolicy join_policy);
 
@@ -219,11 +243,11 @@
  *        (i.e. state too large)
  */
 int
-GNUNET_PSYC_channel_update (struct GNUNET_PSYC_Channel *channel,
-                           const char *full_state_name,
-                           enum GNUNET_PSYC_Operator type,
-                           size_t data_size,
-                           const void *data);
+GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel,
+                                 const char *full_state_name,
+                                 enum GNUNET_PSYC_Operator type,
+                                 size_t data_size,
+                                 const void *data);
 
 
 /**
@@ -243,7 +267,7 @@
  * @return GNUNET_SYSERR on error (fatal, aborts transmission)
  *         GNUNET_NO on success, if more data is to be transmitted later 
  *         (should be used if 'data_size' was not big enough to take all the 
data)
- *         GNUNET_OK if this completes the transmission (all data supplied)
+ *         GNUNET_YES if this completes the transmission (all data supplied)
  */
 typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls,
                                              uint64_t message_id,
@@ -429,9 +453,9 @@
  *
  * @param cfg configuration to use
  * @param pub_key ECC key that identifies the channel we wish to join
- * @param method_count number of methods in 'methods' array
- * @param methods functions to invoke on messages received from the channel,
+ * @param method function to invoke on messages received from the channel,
  *                typcially at least contains functions for 'join' and 'leave'.
+ * @param method_cls closure for 'method'
  * @param state_count number of state handlers
  * @param state_handlers array of state event handlers
  * @return handle for the member, NULL on error 
@@ -439,8 +463,8 @@
 struct GNUNET_PSYC_Member *
 GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, 
                         const struct GNUNET_CRYPTO_EccPublicKey *pub_key,
-                        unsigned int method_count,
-                        const struct GNUNET_PSYC_Method *methods,
+                        GNUNET_PSYC_Method method,
+                        void *method_cls,
                         unsigned int state_count,
                         struct GNUNET_PSYC_StateHandler *state_handlers);
 
@@ -469,17 +493,17 @@
  *        function must copy at most '*data_size' bytes to 'data'.
  * @return GNUNET_SYSERR on error (fatal, aborts transmission)
  *         GNUNET_NO on success, if more data is to be transmitted later
- *         GNUNET_OK if this completes the transmission (all data supplied)
+ *         GNUNET_YES if this completes the transmission (all data supplied)
  */
-typedef int (*GNUNET_PSYC_HostReadyNotify)(void *cls,
-                                          size_t *data_size,
-                                          char *data);
+typedef int (*GNUNET_PSYC_OriginReadyNotify)(void *cls,
+                                            size_t *data_size,
+                                            char *data);
 
 
 /**
  * Handle for a pending PSYC transmission operation.
  */
-struct GNUNET_PSYC_HostTransmitHandle;
+struct GNUNET_PSYC_OriginTransmitHandle;
 
 
 /**
@@ -491,11 +515,11 @@
  * @param notify_cls closure for 'notify'
  * @return transmission handle, NULL on error (i.e. more than one request 
queued)
  */
-struct GNUNET_PSYC_HostTransmitHandle *
-GNUNET_PSYC_member_send_to_host (struct GNUNET_PSYC_Member *member,
-                                const char *method_name,
-                                GNUNET_PSYC_HostReadyNotify notify,
-                                void *notify_cls);
+struct GNUNET_PSYC_OriginTransmitHandle *
+GNUNET_PSYC_member_send_to_origin (struct GNUNET_PSYC_Member *member,
+                                  const char *method_name,
+                                  GNUNET_PSYC_OriginReadyNotify notify,
+                                  void *notify_cls);
 
 
 /**
@@ -511,19 +535,19 @@
  * @param value_size number of bytes in 'value'
  */
 uint64_t
-GNUNET_PSYC_member_host_variable_set (struct GNUNET_PSYC_Member *member,
-                                     const char *variable_name,
-                                     const void *value,
-                                     size_t value_size);
+GNUNET_PSYC_member_origin_variable_set (struct GNUNET_PSYC_Member *member,
+                                       const char *variable_name,
+                                       const void *value,
+                                       size_t value_size);
 
 
 /**
- * Abort transmission request to host.
+ * Abort transmission request to origin.
  *
  * @param th handle of the request that is being aborted
  */
 void
-GNUNET_PSYC_member_send_to_host_cancel (struct GNUNET_PSYC_HostTransmitHandle 
*th);
+GNUNET_PSYC_member_send_to_origin_cancel (struct 
GNUNET_PSYC_OriginTransmitHandle *th);
 
 
 /**
@@ -541,6 +565,8 @@
  * @param member which channel should be replayed?
  * @param start earliest interesting point in history
  * @param end last (exclusive) interesting point in history
+ * @param method function to invoke on messages received from the story
+ * @param method_cls closure for 'method'
  * @param finish_cb function to call when the requested story has been fully 
  *        told (counting message IDs might not suffice, as some messages
  *        might be secret and thus the listener would not know the story is 
@@ -554,6 +580,8 @@
 GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member,
                               uint64_t start,
                               uint64_t end,
+                              GNUNET_PSYC_Method method,
+                              void *method_cls,
                               void (*finish_cb)(void *),
                               void *finish_cb_cls);