* 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
* 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
*/
/**
- * 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
* @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,
uint16_t base_size);
+/**
+ * Opaque handle to an envelope.
+ */
+struct GNUNET_MQ_Envelope;
+
+
/**
* Implementation of the #GNUNET_MQ_msg_nested_mh macro.
*
*/
struct GNUNET_MQ_Handle;
-/**
- * Opaque handle to an envelope.
- */
-struct GNUNET_MQ_Envelope;
-
/**
* Error codes for the queue.
* 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
};
* 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
/**
* 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 }
/**
* 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_hd_fixed_size(test_message,
+ * GNUNET_MESSAGE_TYPE_TEST,
+ * struct GNUNET_MessageTest,
+ * "context"),
* GNUNET_MQ_handler_end()
* };
*
* @param name unique basename for the functions
* @param code message type constant
* @param str type of the message (a struct)
+ * @param ctx context for the callbacks
*/
-#define GNUNET_MQ_hd_fixed_size(name,code,str) \
- struct GNUNET_MQ_MessageHandler \
- make_##name##_handler (void *cls) { \
- void (*cb)(void *cls, const str *msg) = &handle_##name; \
- struct GNUNET_MQ_MessageHandler mh = { \
- NULL, (GNUNET_MQ_MessageCallback) cb, \
- cls, code, sizeof (str) }; \
- return mh; \
- }
+#define GNUNET_MQ_hd_fixed_size(name,code,str,ctx) \
+ ({ \
+ void (*_cb)(void *cls, const str *msg) = &handle_##name; \
+ ((struct GNUNET_MQ_MessageHandler) { \
+ NULL, (GNUNET_MQ_MessageCallback) _cb, \
+ (ctx), (code), sizeof (str) }); \
+ })
/**
* 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,
- * struct GNUNET_MessageTest);
* static int
* check_test (void *cls,
* const struct GNUNET_MessageTest *msg)
* }
*
* struct GNUNET_MQ_MessageHandler handlers[] = {
- * make_test_message_handler ("context"),
+ * GNUNET_MQ_hd_var_size(test_message,
+ * GNUNET_MESSAGE_TYPE_TEST,
+ * struct GNUNET_MessageTest,
+ * "context"),
* GNUNET_MQ_handler_end()
* };
*
* @param name unique basename for the functions
* @param code message type constant
* @param str type of the message (a struct)
+ * @param ctx context for the callbacks
*/
-#define GNUNET_MQ_hd_var_size(name,code,str) \
- struct GNUNET_MQ_MessageHandler \
- make_##name##_handler (void *ctx) { \
- int (*mv)(void *cls, const str *msg) = &check_##name; \
- void (*cb)(void *cls, const str *msg) = &handle_##name;\
- struct GNUNET_MQ_MessageHandler mh = \
- { (GNUNET_MQ_MessageValidationCallback) mv, \
- (GNUNET_MQ_MessageCallback) cb, \
- ctx, code, sizeof (str) }; \
- return mh; \
- }
+#define GNUNET_MQ_hd_var_size(name,code,str,ctx) \
+ ({ \
+ int (*_mv)(void *cls, const str *msg) = &check_##name; \
+ void (*_cb)(void *cls, const str *msg) = &handle_##name; \
+ ((struct GNUNET_MQ_MessageHandler) \
+ { (GNUNET_MQ_MessageValidationCallback) _mv, \
+ (GNUNET_MQ_MessageCallback) _cb, \
+ (ctx), (code), sizeof (str) }); \
+ })
/**
*/
struct GNUNET_MQ_Envelope *
GNUNET_MQ_msg_ (struct GNUNET_MessageHeader **mhp,
+
uint16_t size,
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
/**
- * 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);
+
+
+/**
+ * Function to obtain the last envelope in the queue.
+ *
+ * @param mq message queue to interrogate
+ * @return the last envelope in the queue
+ */
+struct GNUNET_MQ_Envelope *
+GNUNET_MQ_get_last_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
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
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.
*
* @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);
/**
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.
/**
* 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.
*
/**
- * 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);
/**
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 */