add function conv param string

[oweals/gnunet.git] / src / include / gnunet_mq_lib.h

diff --git a/src/include/gnunet_mq_lib.h b/src/include/gnunet_mq_lib.h
index 38ebf6b17c7a45f2a2934aec5fbfb2230908cbb6..08e09d5b51c76c6f18cbdb3fbd7120e38d600300 100644 (file)
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -252,7 +252,7 @@ typedef void
  * the message queue.
  * Not every message queue implementation supports an error handler.
  *
- * @param cls closure, same closure as for the message handlers
+ * @param cls closure
  * @param error error code
  */
 typedef void
@@ -268,12 +268,12 @@ struct GNUNET_MQ_MessageHandler
   /**
    * Callback to validate a message of the specified @e type.
    * The closure given to @e mv will be this struct (not @e ctx).
-   * Using NULL means only size-validation using 
+   * Using NULL means only size-validation using
    * @e expected_size.  In this case, @e expected_size must
    * be non-zero.
    */
   GNUNET_MQ_MessageValidationCallback mv;
-  
+
   /**
    * Callback, called every time a new message of
    * the specified @e type has been receied.
@@ -285,7 +285,7 @@ struct GNUNET_MQ_MessageHandler
    * Closure for @e mv and @e cb.
    */
   void *cls;
-  
+
   /**
    * Type of the message this handler covers, in host byte order.
    */
@@ -317,14 +317,14 @@ struct GNUNET_MQ_MessageHandler
  * The macro is to be used as follows:
  * <code>
  * struct GNUNET_MessageTest { ... }; // must be fixed size
- * GNUNET_MQ_hd_fixed_size(test_message, 
- *                         GNUNET_MESSAGE_TYPE_TEST, 
- *                         struct GNUNET_MessageTest);
  * static void
- * handle_test_message (void *cls, // the struct GNUNET_MQ_MessageHandler
+ * handle_test_message (void *cls,
  *                      const struct GNUNET_MessageTest *msg)
  * { ... }
- * 
+ *
+ * GNUNET_MQ_hd_fixed_size(test_message,
+ *                         GNUNET_MESSAGE_TYPE_TEST,
+ *                         struct GNUNET_MessageTest);
  * struct GNUNET_MQ_MessageHandler handlers[] = {
  *   make_test_message_handler (),
  *   GNUNET_MQ_handler_end()
@@ -355,8 +355,8 @@ struct GNUNET_MQ_MessageHandler
  * The macro is to be used as follows:
  * <code>
  * struct GNUNET_MessageTest { ... }; // can be variable size
- * GNUNET_MQ_hd_var_size(test_message, 
- *                       GNUNET_MESSAGE_TYPE_TEST, 
+ * GNUNET_MQ_hd_var_size(test_message,
+ *                       GNUNET_MESSAGE_TYPE_TEST,
  *                       struct GNUNET_MessageTest);
  * static int
  * check_test (void *cls,
@@ -373,8 +373,8 @@ struct GNUNET_MQ_MessageHandler
  *   const char *ctx = cls;
  *   GNUNET_assert (0 == strcmp ("context", ctx));
  *   // ...
- * } 
- * 
+ * }
+ *
  * struct GNUNET_MQ_MessageHandler handlers[] = {
  *   make_test_message_handler ("context"),
  *   GNUNET_MQ_handler_end()
@@ -411,6 +411,16 @@ GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp,
                 uint16_t type);
 
 
+/**
+ * Create a new envelope by copying an existing message.
+ *
+ * @param hdr header of the message to copy
+ * @return envelope containing @a hdr
+ */
+struct GNUNET_MQ_Envelope *
+GNUNET_MQ_msg_copy (const struct GNUNET_MessageHeader *hdr);
+
+
 /**
  * Discard the message queue message, free all
  * allocated resources. Must be called in the event
@@ -422,6 +432,16 @@ void
 GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *mqm);
 
 
+/**
+ * Obtain the current length of the message queue.
+ *
+ * @param mq queue to inspect
+ * @return number of queued, non-transmitted messages
+ */
+unsigned int
+GNUNET_MQ_get_length (struct GNUNET_MQ_Handle *mq);
+
+
 /**
  * Send a message with the give message queue.
  * May only be called once per message.
@@ -434,6 +454,18 @@ GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
                struct GNUNET_MQ_Envelope *ev);
 
 
+/**
+ * Send a copy of a message with the give message queue.
+ * Can be called repeatedly on the same envelope.
+ *
+ * @param mq message queue
+ * @param ev the envelope with the message to send.
+ */
+void
+GNUNET_MQ_send_copy (struct GNUNET_MQ_Handle *mq,
+                     const struct GNUNET_MQ_Envelope *ev);
+
+
 /**
  * Cancel sending the message. Message must have been sent with
  * #GNUNET_MQ_send before.  May not be called after the notify sent