Start of Doxygen documentationapi_documentation

1 files changed, 329 insertions, 14 deletions

diff --git a/librabbitmq/amqp.h b/librabbitmq/amqp.h
index 8b91cdc..3d9f7ef 100644
--- a/librabbitmq/amqp.h
+++ b/librabbitmq/amqp.h
@@ -223,6 +223,14 @@ typedef enum amqp_sasl_method_enum_ {
 /* Opaque struct. */
 typedef struct amqp_connection_state_t_ *amqp_connection_state_t;
 
+/**
+ * @brief Gets the version string for the library
+ *
+ * Gets the library version. Format will be of the form vX.Y
+ * where X is the major verion, Y is the minor version.
+ * Memory for the string is owned by the library.
+ *
+ */
 RABBITMQ_EXPORT char const *amqp_version(void);
 
 /* Exported empty data structures */
@@ -236,81 +244,283 @@ RABBITMQ_EXPORT const amqp_array_t amqp_empty_array;
 #define AMQP_EMPTY_TABLE amqp_empty_table
 #define AMQP_EMPTY_ARRAY amqp_empty_array
 
+/**
+ * @brief initializes an \ref amqp_pool_t memory pool
+ *
+ * @param pool a pointer to the amqp_pool_t to be initialized
+ * @param pagesize the minimum allocation size in the pool. Any allocations
+ *        made using amqp_pool_alloc smaller than pagesize will make using
+ *        a page of this size, larger allocations will be made using the size
+ *        of the allocation requested in a 'large page pool'
+ */
 RABBITMQ_EXPORT void init_amqp_pool(amqp_pool_t *pool, size_t pagesize);
+/**
+ * @brief recycles memory associated with an \ref amqp_pool_t memory pool
+ *
+ * Recycles the memory in the amqp_pool_t. Freeing any memory that are considered
+ * 'large pages'
+ * Use of pointers that were returned by amqp_pool_alloc from the pool that
+ * is being recycled, the effects are undefined (the pointers may or may not
+ * be valid).
+ * 
+ * @param pool a pointed to the amqp_pool_t to be recycled
+ */
 RABBITMQ_EXPORT void recycle_amqp_pool(amqp_pool_t *pool);
+/**
+ * @brief frees all memory associated with an \ref amqp_pool_t memory pool
+ *
+ * Frees all memory associated with an \ref amqp_pool_t memory pool
+ *
+ * @param pool the pool to empty
+ */
 RABBITMQ_EXPORT void empty_amqp_pool(amqp_pool_t *pool);
 
+/**
+ * @brief allocates memory from an \ref amqp_pool_t
+ *
+ * @param pool a pointer to the pool to allocate the memory from
+ * @param amount the number of bytes to allocate
+ * @returns a pointer to the allocated memory, NULL on error
+ */
 RABBITMQ_EXPORT void *amqp_pool_alloc(amqp_pool_t *pool, size_t amount);
+/**
+ * @brief allocates memory from an \ref amqp_pool_t and puts it in a \ref amqp_bytes_t structure
+ *
+ * If allocation fails, output.bytes will be NULL
+ * 
+ * @param pool a pointer to the \ref amqp_pool_t memory to allocate from
+ * @param amount the number of bytes to allocate
+ * @param output a amqp_bytes_t structure to store the pointer and length
+ */
 RABBITMQ_EXPORT void amqp_pool_alloc_bytes(amqp_pool_t *pool,
                                           size_t amount, amqp_bytes_t *output);
 
+/**
+ * @brief creates an amqp_bytes_t structure from a c-string
+ *
+ * Creates an amqp_bytes_t structre from a c-string.
+ * output.bytes = cstr
+ * output.len = strlen(cstr)
+ * NOTE: no memory is allocated by this function, the pointer is simply copied
+ *
+ * @param cstr the cstring to assign to the amqp_bytes_t structure
+ * @returns amqp_bytes_t
+ */
 RABBITMQ_EXPORT amqp_bytes_t amqp_cstring_bytes(char const *cstr);
+
+/**
+ * @brief creates a copy of an amqp_bytes_t structure
+ *
+ * Duplicates a amqp_bytes_t structure, duplicating the memory it refers to.
+ * amqp_bytes_t objects created with this function should be freed with
+ * amqp_bytes_free
+ *
+ * @param src the amqp_bytes_t structure to be duplicated
+ * @returns a duplicate of src, output.bytes will be NULL on error
+ */
 RABBITMQ_EXPORT amqp_bytes_t amqp_bytes_malloc_dup(amqp_bytes_t src);
+/**
+ * @brief Allocates a amqp_bytes_t structure with a given size
+ *
+ * Allocates an amqp_bytes_t structure with a given size. amqp_bytes_t 
+ * structures. amqp_bytes_t objects created with this function should be
+ * freed using amqp_bytes_free
+ *
+ * @param amount the size that the amqp_bytes_t structure should point to
+ * @returns amqp_bytes_t, output.bytes will be NULL on error
+ */
 RABBITMQ_EXPORT amqp_bytes_t amqp_bytes_malloc(size_t amount);
+/**
+ * @brief free memory allocated with amqp_bytes_malloc or amqp_bytes_malloc_dup
+ *
+ * @param bytes the amqp_bytes_t to free
+ */
 RABBITMQ_EXPORT void amqp_bytes_free(amqp_bytes_t bytes);
 
+/**
+ * @brief Create and initialize a new amqp_connection_state_t object
+ *
+ * @returns amqp_connection_state_t object, NULL in case of failure
+ */
 RABBITMQ_EXPORT amqp_connection_state_t amqp_new_connection(void);
+
+/**
+ * @brief Get the socket file descriptor associated with a amqp_connection_state_t object
+ *
+ * @param state the amqp_connection_state_t to retrieve the socket from
+ * @returns the socket descriptor associated with the connection, 0 if there isn't one
+ */
 RABBITMQ_EXPORT int amqp_get_sockfd(amqp_connection_state_t state);
+/**
+ * @brief Set the socket file descriptor associated with an amqp_connection_state_t object
+ *
+ * Sets the socket file descriptor associated with an amqp_connection_state_t object,
+ * note that this function will overwrite an existing file descriptor without checking
+ * to see if an existing socket is associated and connected, setting with a connected
+ * socket will lead to undefined behavior
+ *
+ * @param state the amqp_connection_state_t to set the socket for
+ * @param sockfd the socket file descriptor
+ */
 RABBITMQ_EXPORT void amqp_set_sockfd(amqp_connection_state_t state,
 				     int sockfd);
+/**
+ * @brief Sets connection-wide amqp_connection_state_t parameters with the broker
+ *
+ * Sets connection-wide amqp_connection_state_t parameters with the broker.
+ *
+ * @param state
+ * @param channel_max the maximum number of channels, 0 = no limit, 2, is the minimum, 65536 is the maximum
+ * @param frame_max the maximum frame size in bytes. Minimum is 4096, 
+ * @param heartbeat
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_tune_connection(amqp_connection_state_t state,
 					 int channel_max,
 					 int frame_max,
 					 int heartbeat);
+/**
+ * @brief Gets the maximum number of channels supported by this connection
+ *
+ * @param state
+ * @returns the maximum number of channels supported by this connection
+ */
 RABBITMQ_EXPORT int amqp_get_channel_max(amqp_connection_state_t state);
+/**
+ * @brief Destroys a amqp_connection_state_t object created with amqp_new_connection
+ *
+ * @param state
+ * @return
+ */
 RABBITMQ_EXPORT int amqp_destroy_connection(amqp_connection_state_t state);
 
+/**
+ * @brief Given some input handle it handles it an might fill in a frame object
+ *
+ * @param state
+ * @param received_data
+ * @param decoded_frame
+ * @return
+ */
 RABBITMQ_EXPORT int amqp_handle_input(amqp_connection_state_t state,
 				      amqp_bytes_t received_data,
 				      amqp_frame_t *decoded_frame);
 
+/**
+ * @brief Determines whether its ok to release buffers
+ *
+ * @param state
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_boolean_t amqp_release_buffers_ok(
                                                 amqp_connection_state_t state);
 
+/**
+ * @brief Unconditionally recycles the buffers associated with provided connection
+ *
+ * @param state
+ */
 RABBITMQ_EXPORT void amqp_release_buffers(amqp_connection_state_t state);
 
+/**
+ * @brief Recycles the buffers associated with the provided connection if its ok to do so
+ *
+ * @param state
+ */
 RABBITMQ_EXPORT void amqp_maybe_release_buffers(amqp_connection_state_t state);
 
+/**
+ * @brief Sends a frame to the broker
+ *
+ * @param state
+ * @param frame
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_send_frame(amqp_connection_state_t state,
 				    amqp_frame_t const *frame);
 
+/**
+ * @brief Compares two table entries
+ *
+ * @param entry1
+ * @param entry2
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_table_entry_cmp(void const *entry1,
 					 void const *entry2);
 
+/**
+ * @brief Opens a socket to a host on a port
+ *
+ * @param hostname the hostname or IP address to connect to
+ * @param port the port on the hostname to attempt connecting to
+ * @returns a socket file descriptor
+ */
 RABBITMQ_EXPORT int amqp_open_socket(char const *hostname,
 				     int portnumber);
 
+/**
+ * @brief Send a handshake to the broker
+ *
+ * @param state
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_send_header(amqp_connection_state_t state);
 
+/**
+ * @brief Checks to see if there are any inbound frames queued up
+ *
+ * @param state
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_boolean_t amqp_frames_enqueued(
                                                amqp_connection_state_t state);
 
+/**
+ * @brief Does a blocking wait for a single frame from the broker
+ *
+ * @param state
+ * @param decoded_frame
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_simple_wait_frame(amqp_connection_state_t state,
 					   amqp_frame_t *decoded_frame);
 
-RABBITMQ_EXPORT int amqp_simple_wait_method(amqp_connection_state_t state,
-                                          amqp_channel_t expected_channel,
-                                          amqp_method_number_t expected_method,
-                                          amqp_method_t *output);
-
-RABBITMQ_EXPORT int amqp_send_method(amqp_connection_state_t state,
-				     amqp_channel_t channel,
-				     amqp_method_number_t id,
-				     void *decoded);
-
+/**
+ * @brief Sends a method to the broker and waits for a reply
+ *
+ * @param state
+ * @param channel
+ * @param request_id
+ * @param expected_reply_ids
+ * @param decoded_request_method
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_simple_rpc(amqp_connection_state_t state,
                                       amqp_channel_t channel,
                                       amqp_method_number_t request_id,
                                       amqp_method_number_t *expected_reply_ids,
                                       void *decoded_request_method);
 
+/**
+ * @brief Sends a method to the broker and waits for a reply
+ *
+ * @param state
+ * @param channel
+ * @param request_id
+ * @param reply_id
+ * @param decoded_request_method
+ * @returns
+ */
 RABBITMQ_EXPORT void *amqp_simple_rpc_decoded(amqp_connection_state_t state,
 					      amqp_channel_t channel,
 					      amqp_method_number_t request_id,
 					      amqp_method_number_t reply_id,
 					      void *decoded_request_method);
 
-/*
+/**
+ * @brief Checks for the result of the last RPC
+ *
  * The API methods corresponding to most synchronous AMQP methods
  * return a pointer to the decoded method result.  Upon error, they
  * return NULL, and we need some way of discovering what, if anything,
@@ -322,10 +532,24 @@ RABBITMQ_EXPORT void *amqp_simple_rpc_decoded(amqp_connection_state_t state,
  * amqp_rpc_reply_t; operations that do return amqp_rpc_reply_t
  * generally do NOT update this per-connection-global amqp_rpc_reply_t
  * instance.
+ *
+ * @param state
+ * @returns
  */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_get_rpc_reply(
                                                 amqp_connection_state_t state);
 
+/**
+ * @brief Completes the initial handshake with the broker after connecting
+ *
+ * @param state
+ * @param vhost
+ * @param channel_max
+ * @param frame_max
+ * @param heartbeat
+ * @param sasl_method...
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_login(amqp_connection_state_t state,
                                         char const *vhost,
                                         int channel_max,
@@ -334,6 +558,19 @@ RABBITMQ_EXPORT amqp_rpc_reply_t amqp_login(amqp_connection_state_t state,
                                         amqp_sasl_method_enum sasl_method, ...);
 
 struct amqp_basic_properties_t_;
+/**
+ * @brief Publishes a message to the broker
+ *
+ * @param state
+ * @param channel
+ * @param exchange
+ * @param routing_key
+ * @param mandatory
+ * @param immediate
+ * @param properties
+ * @param body
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_basic_publish(amqp_connection_state_t state,
                               amqp_channel_t channel,
                               amqp_bytes_t exchange,
@@ -343,52 +580,117 @@ RABBITMQ_EXPORT int amqp_basic_publish(amqp_connection_state_t state,
                               struct amqp_basic_properties_t_ const *properties,
                               amqp_bytes_t body);
 
+/**
+ * @brief closes a channel
+ *
+ * @param state
+ * @param channel
+ * @param code
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_channel_close(
                                                  amqp_connection_state_t state,
                                                  amqp_channel_t channel,
                                                  int code);
+/**
+ * @brief shuts down the connection to the broker
+ *
+ * @param state
+ * @param code
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_connection_close(
                                                  amqp_connection_state_t state,
                                                  int code);
 
+/**
+ * @brief does a basic.ack for a message
+ *
+ * @param state
+ * @param channel
+ * @param delivery_tag
+ * @param multipl
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_basic_ack(amqp_connection_state_t state,
 				   amqp_channel_t channel,
 				   uint64_t delivery_tag,
 				   amqp_boolean_t multiple);
 
+/**
+ * @brief performs a basic.get for a message
+ *
+ * @param state
+ * @param channel
+ * @param queue
+ * @param no_ack
+ * @returns
+ */
 RABBITMQ_EXPORT amqp_rpc_reply_t amqp_basic_get(amqp_connection_state_t state,
                                                 amqp_channel_t channel,
                                                 amqp_bytes_t queue,
                                                 amqp_boolean_t no_ack);
 
+/**
+ * @brief rejects a received message
+ *
+ * @param state
+ * @param channel
+ * @param delivery_tag
+ * @param requeue
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_basic_reject(amqp_connection_state_t state,
 				      amqp_channel_t channel,
 				      uint64_t delivery_tag,
 				      amqp_boolean_t requeue);
 
-/*
+/**
  * Can be used to see if there is data still in the buffer, if so
  * calling amqp_simple_wait_frame will not immediately enter a
  * blocking read.
  *
  * Possibly amqp_frames_enqueued should be used for this?
+ *
+ * @param state
+ * @returns
  */
 RABBITMQ_EXPORT amqp_boolean_t amqp_data_in_buffer(
                                                 amqp_connection_state_t state);
 
-/*
- * Get the error string for the given error code.
+/**
+ * @briefGet the error string for the given error code.
  *
  * The returned string resides on the heap; the caller is responsible
  * for freeing it.
+ *
+ * @param err
+ * @returns
  */
 RABBITMQ_EXPORT char *amqp_error_string(int err);
 
+/**
+ * @brief decodes a amqp table
+ *
+ * @param encoded
+ * @param pool
+ * @param output
+ * @param offset
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_decode_table(amqp_bytes_t encoded,
                                       amqp_pool_t *pool,
                                       amqp_table_t *output,
                                       size_t *offset);
 
+/**
+ * @brief encodes an amqp table
+ *
+ * @param encoded
+ * @param input
+ * @param offset
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_encode_table(amqp_bytes_t encoded,
                                       amqp_table_t *input,
                                       size_t *offset);
@@ -401,8 +703,21 @@ struct amqp_connection_info {
   int port;
 };
 
+
+/**
+ * @brief Initializes a amqp_connection_info struct to some default values
+ *
+ * @param parsed
+ */
 RABBITMQ_EXPORT void amqp_default_connection_info(
 					  struct amqp_connection_info *parsed);
+/**
+ * @brief Parses an AMQP connection string
+ *
+ * @param url
+ * @param parsed
+ * @returns
+ */
 RABBITMQ_EXPORT int amqp_parse_url(char *url,
 				   struct amqp_connection_info *parsed);