move to new client API: remove old client 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 86144abcaa07b1701b7bae362048b71235118c55..bcf923fcc7943ed23be7439105035ddffc5b3c42 100644 (file)
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -42,7 +42,8 @@
  * The allocated message will already have the type and size field set.
  *
  * @param mvar variable to store the allocated message in;
- *             must have a header field
+ *             must have a header field;
+ *             can be NULL
  * @param esize extra space to allocate after the message
  * @param type type of the message
  * @return the MQ message
@@ -54,7 +55,8 @@
  * The contained message will already have the type and size field set.
  *
  * @param mvar variable to store the allocated message in;
- *             must have a header field
+ *             must have a header field;
+ *             can be NULL
  * @param type type of the message
  * @return the allocated envelope
  */
@@ -111,6 +113,7 @@
  * @param mh message header to extract nested message header from
  * @param base_size size of the message before the nested message's header appears
  * @return pointer to the nested message, does not copy the message
+ *         OR NULL in case of a malformed message.
  */
 const struct GNUNET_MessageHeader *
 GNUNET_MQ_extract_nested_mh_ (const struct GNUNET_MessageHeader *mh,
@@ -171,7 +174,13 @@ enum GNUNET_MQ_Error
    * We received a message that was malformed and thus
    * could not be passed to its handler.
    */
-  GNUNET_MQ_ERROR_MALFORMED = 8
+  GNUNET_MQ_ERROR_MALFORMED = 8,
+
+  /**
+   * We received a message for which we have no matching
+   * handler.
+   */
+  GNUNET_MQ_ERROR_NO_MATCH = 16
 };
 
 
@@ -406,6 +415,7 @@ struct GNUNET_MQ_MessageHandler
  */
 struct GNUNET_MQ_Envelope *
 GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp,
+
                 uint16_t size,
                 uint16_t type);
 
@@ -613,12 +623,12 @@ GNUNET_MQ_set_handlers_closure (struct GNUNET_MQ_Handle *mq,
  *
  * @param ev message to call the notify callback for
  * @param cb the notify callback
- * @param cls closure for the callback
+ * @param cb_cls closure for the callback
  */
 void
 GNUNET_MQ_notify_sent (struct GNUNET_MQ_Envelope *ev,
                        GNUNET_MQ_NotifyCallback cb,
-                       void *cls);
+                       void *cb_cls);
 
 
 /**
@@ -630,6 +640,36 @@ void
 GNUNET_MQ_destroy (struct GNUNET_MQ_Handle *mq);
 
 
+/**
+ * Handle we return for callbacks registered to be
+ * notified when #GNUNET_MQ_destroy() is called on a queue.
+ */
+struct GNUNET_MQ_DestroyNotificationHandle;
+
+
+/**
+ * Register function to be called whenever @a mq is being
+ * destroyed.
+ *
+ * @param mq message queue to watch
+ * @param cb function to call on @a mq destruction
+ * @param cb_cls closure for @a cb
+ * @return handle for #GNUNET_MQ_destroy_notify_cancel().
+ */
+struct GNUNET_MQ_DestroyNotificationHandle *
+GNUNET_MQ_destroy_notify (struct GNUNET_MQ_Handle *mq,
+                         GNUNET_SCHEDULER_TaskCallback cb,
+                         void *cb_cls);
+
+/**
+ * Cancel registration from #GNUNET_MQ_destroy_notify().
+ *
+ * @param dnh handle for registration to cancel
+ */
+void
+GNUNET_MQ_destroy_notify_cancel (struct GNUNET_MQ_DestroyNotificationHandle *dnh);
+
+
 /**
  * Call the message message handler that was registered
  * for the type of the given message in the given message queue.
@@ -662,6 +702,9 @@ GNUNET_MQ_inject_error (struct GNUNET_MQ_Handle *mq,
 
 /**
  * Call the send implementation for the next queued message, if any.
+ * Calls the send notification for the current message unless
+ * #GNUNET_MQ_impl_send_in_flight was called for this envelope.
+ *
  * Only useful for implementing message queues, results in undefined
  * behavior if not used carefully.
  *
@@ -672,18 +715,17 @@ GNUNET_MQ_impl_send_continue (struct GNUNET_MQ_Handle *mq);
 
 
 /**
- * Get the message that should currently be sent.  The returned
- * message is only valid until #GNUNET_MQ_impl_send_continue is
- * called.  Fails if there is no current message.  Only useful for
- * implementing message queues, results in undefined behavior if not
- * used carefully.
+ * Call the send notification for the current message, but do not
+ * try to send the next message until #gnunet_mq_impl_send_continue
+ * is called.
  *
- * @param mq message queue with the current message, only valid
- *        until #GNUNET_MQ_impl_send_continue() is called
- * @return message to send, never NULL
+ * only useful for implementing message queues, results in undefined
+ * behavior if not used carefully.
+ *
+ * @param mq message queue to send the next message with
  */
-const struct GNUNET_MessageHeader *
-GNUNET_MQ_impl_current (struct GNUNET_MQ_Handle *mq);
+void
+GNUNET_MQ_impl_send_in_flight (struct GNUNET_MQ_Handle *mq);
 
 
 /**
@@ -704,6 +746,19 @@ void *
 GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq);
 
 
+/**
+ * Get the message that should currently be sent.
+ * Fails if there is no current message.
+ * Only useful for implementing message queues,
+ * results in undefined behavior if not used carefully.
+ *
+ * @param mq message queue with the current message
+ * @return message to send, never NULL
+ */
+const struct GNUNET_MessageHeader *
+GNUNET_MQ_impl_current (struct GNUNET_MQ_Handle *mq);
+
+
 #endif
 
 /** @} */ /* end of group mq */