/*
This file is part of GNUnet.
- (C) 2012 Christian Grothoff (and other contributing authors)
+ (C) 2012-2013 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 2, or (at your
+ by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
* @author Florian Dold
* @file include/gnunet_mq_lib.h
* @brief general purpose message queue
+ * @defgroup mq general purpose message queue
+ * @{
*/
#ifndef GNUNET_MQ_H
#define GNUNET_MQ_H
-#include "gnunet_common.h"
-
/**
* Allocate an envelope, with extra space allocated after the space needed
* @param var pointer to a message struct, the type of the expression determines the base size,
* the space after the base size is the nested message
* @return a 'struct GNUNET_MessageHeader *' that points at the nested message of the given message,
- * or NULL if the given message in 'var' does not have any space after the message struct
+ * or NULL if the given message in @a var does not have any space after the message struct
*/
#define GNUNET_MQ_extract_nested_mh(var) GNUNET_MQ_extract_nested_mh_ ((struct GNUNET_MessageHeader *) (var), sizeof (*(var)))
*/
struct GNUNET_MQ_Envelope;
+
+/**
+ * Error codes for the queue.
+ */
enum GNUNET_MQ_Error
{
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_READ = 1,
+
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_WRITE = 2,
+
+ /**
+ * FIXME: document!
+ */
GNUNET_MQ_ERROR_TIMEOUT = 4
};
/**
* Signature of functions implementing the
* destruction of a message queue.
- * Implementations must not free 'mq', but should
- * take care of 'impl_state'.
- *
+ * Implementations must not free @a mq, but should
+ * take care of @a impl_state.
+ *
* @param mq the message queue to destroy
* @param impl_state state of the implementation
*/
/**
* Implementation function that cancels the currently sent message.
- *
+ *
* @param mq message queue
* @param impl_state state specific to the implementation
*/
struct GNUNET_MQ_MessageHandler
{
/**
- * Callback, called every time a new message of
+ * Callback, called every time a new message of
* the specified type has been receied.
*/
GNUNET_MQ_MessageCallback cb;
-
/**
* Type of the message this handler covers.
*/
/**
* Create a new envelope.
- *
+ *
* @param mhp message header to store the allocated message header in, can be NULL
* @param size size of the message to allocate
* @param type type of the message, will be set in the allocated message
/**
* Send a message with the give message queue.
* May only be called once per message.
- *
+ *
* @param mq message queue
* @param ev the envelope with the message to send.
*/
void
-GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev);
+GNUNET_MQ_send (struct GNUNET_MQ_Handle *mq,
+ 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 callback has been called
+ * Cancel sending the message. Message must have been sent with
+ * #GNUNET_MQ_send before. May not be called after the notify sent
+ * callback has been called
*
* @param ev queued envelope to cancel
*/
*
* @param connection the client connection
* @param handlers handlers for receiving messages
+ * @param error_handler error handler
* @param cls closure for the handlers
* @return the message queue
*/
struct GNUNET_MQ_Handle *
GNUNET_MQ_queue_for_connection_client (struct GNUNET_CLIENT_Connection *connection,
const struct GNUNET_MQ_MessageHandler *handlers,
+ GNUNET_MQ_ErrorHandler error_handler,
void *cls);
/**
- * Create a message queue for a GNUNET_STREAM_Socket.
+ * Create a message queue for a GNUNET_SERVER_Client.
*
* @param client the client
* @return the message queue
* @param send function the implements sending messages
* @param destroy function that implements destroying the queue
* @param cancel function that implements canceling a message
- * @param impl_state for the queue, passed to 'send' and 'destroy'
+ * @param impl_state for the queue, passed to @a send, @a destroy and @a cancel
* @param handlers array of message handlers
* @param error_handler handler for read and write errors
* @param cls closure for message handlers and error handler
const struct GNUNET_MQ_MessageHandler *handlers,
GNUNET_MQ_ErrorHandler error_handler,
void *cls);
-
+
/**
- * Replace the handlers of a message queue with new handlers.
- * Takes effect immediately, even for messages that already have been received, but for
- * with the handler has not been called.
+ * Replace the handlers of a message queue with new handlers. Takes
+ * effect immediately, even for messages that already have been
+ * received, but for with the handler has not been called.
*
* If the message queue does not support receiving messages,
* this function has no effect.
/**
* 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.
*
- * @param mq message queue with the current message
+ * @param mq message queue with the current message, only valid
+ * until #GNUNET_MQ_impl_send_continue is called
* @return message to send, never NULL
*/
const struct GNUNET_MessageHeader *
GNUNET_MQ_impl_state (struct GNUNET_MQ_Handle *mq);
-/**
- * Mark the current message as irrevocably sent, but do not
- * proceed with sending the next message.
- * Will call the appropriate GNUNET_MQ_NotifyCallback, if any.
- *
- * @param mq message queue
- */
-void
-GNUNET_MQ_impl_send_commit (struct GNUNET_MQ_Handle *mq);
+/** @} */ /* end of group mq */
#endif
projects / oweals / gnunet.git / blobdiff