convering more services to new core MQ API

[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 7bcaa7efcaa2b89d550636c676ebeecf8b30228b..35313263ddb56560ee2ceb281cf80e31cd01a482 100644 (file)
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -106,7 +106,7 @@
 
 
 /**
- * Implementation of the GNUNET_MQ_extract_nexted_mh macro.
+ * Implementation of the #GNUNET_MQ_extract_nexted_mh macro.
  *
  * @param mh message header to extract nested message header from
  * @param base_size size of the message before the nested message's header appears
@@ -117,6 +117,12 @@ GNUNET_MQ_extract_nested_mh_ (const struct GNUNET_MessageHeader *mh,
                               uint16_t base_size);
 
 
+/**
+ * Opaque handle to an envelope.
+ */
+struct GNUNET_MQ_Envelope;
+
+
 /**
  * Implementation of the #GNUNET_MQ_msg_nested_mh macro.
  *
@@ -138,11 +144,6 @@ GNUNET_MQ_msg_nested_mh_ (struct GNUNET_MessageHeader **mhp,
  */
 struct GNUNET_MQ_Handle;
 
-/**
- * Opaque handle to an envelope.
- */
-struct GNUNET_MQ_Envelope;
-
 
 /**
  * Error codes for the queue.
@@ -304,7 +305,7 @@ struct GNUNET_MQ_MessageHandler
 /**
  * End-marker for the handlers array
  */
-#define GNUNET_MQ_handler_end() {NULL, NULL, NULL, 0, 0}
+#define GNUNET_MQ_handler_end() { NULL, NULL, NULL, 0, 0 }
 
 
 /**
@@ -433,7 +434,68 @@ GNUNET_MQ_discard (struct GNUNET_MQ_Envelope *mqm);
 
 
 /**
- * Send a message with the give message queue.
+ * Function to obtain the current envelope from
+ * within #GNUNET_MQ_SendImpl implementations.
+ *
+ * @param mq message queue to interrogate
+ * @return the current envelope
+ */
+struct GNUNET_MQ_Envelope *
+GNUNET_MQ_get_current_envelope (struct GNUNET_MQ_Handle *mq);
+
+
+/**
+ * Set application-specific options for this envelope.
+ * Overrides the options set for the queue with
+ * #GNUNET_MQ_set_options() for this message only.
+ *
+ * @param env message to set options for
+ * @param flags flags to use (meaning is queue-specific)
+ * @param extra additional buffer for further data (also queue-specific)
+ */
+void
+GNUNET_MQ_env_set_options (struct GNUNET_MQ_Envelope *env,
+                          uint64_t flags,
+                          const void *extra);
+
+
+/**
+ * Get application-specific options for this envelope.
+ *
+ * @param env message to set options for
+ * @param[out] flags set to flags to use (meaning is queue-specific)
+ * @return extra additional buffer for further data (also queue-specific)
+ */
+const void *
+GNUNET_MQ_env_get_options (struct GNUNET_MQ_Envelope *env,
+                          uint64_t *flags);
+
+
+/**
+ * Set application-specific options for this queue.
+ *
+ * @param mq message queue to set options for
+ * @param flags flags to use (meaning is queue-specific)
+ * @param extra additional buffer for further data (also queue-specific)
+ */
+void
+GNUNET_MQ_set_options (struct GNUNET_MQ_Handle *mq,
+                      uint64_t flags,
+                      const void *extra);
+
+
+/**
+ * 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 given message queue.
  * May only be called once per message.
  *
  * @param mq message queue
@@ -444,6 +506,18 @@ GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
                struct GNUNET_MQ_Envelope *ev);
 
 
+/**
+ * Send a copy of a message with the given 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
@@ -512,6 +586,18 @@ GNUNET_MQ_queue_for_callbacks (GNUNET_MQ_SendImpl send,
                                void *cls);
 
 
+/**
+ * Change the closure argument in all of the `handlers` of the
+ * @a mq.
+ *
+ * @param mq to modify
+ * @param handlers_cls new closure to use
+ */
+void
+GNUNET_MQ_set_handlers_closure (struct GNUNET_MQ_Handle *mq,
+                                void *handlers_cls);
+
+
 /**
  * Call a callback once the envelope has been sent, that is,
  * sending it can not be canceled anymore.