SimpleAmqpClient Documentation

To consume messages, you must first set up a consumer using BasicConsume, which returns a consumer tag. This tag is then used for subsequent operations like receiving messages, setting QoS, or canceling the consumer.

Workflow

1. Start Consumer: Call BasicConsume(queue_name, consumer_properties) to get a consumer_tag.
2. Receive Message: Use BasicConsumeMessage(consumer_tag) to retrieve an Envelope.
3. Acknowledge: Call BasicAck(envelope) to acknowledge the message.
4. Cancel: Call BasicCancel(consumer_tag) to stop consuming.

std::string consumer_tag = channel->BasicConsume("my_queue", "");
Envelope::ptr_t envelope = channel->BasicConsumeMessage(consumer_tag);
// To ack:
channel->BasicAck(envelope);
// To cancel:
channel->BasicCancel(consumer_tag);

SimpleAmqpClient is a CMake-based project. To build it, create a build directory in a sibling directory to the source code and run CMake.

Build Steps

1. Create and enter a build directory:

   mkdir simpleamqpclient-build
   cd simpleamqpclient-build

2. Run CMake:

   cmake ..

3. Use your system's build utility (e.g., make or msbuild) to compile the library.

CMake Targets

• test: Builds and runs the test suite. (Note: Enable the Google-test suite by passing -DENABLE_TESTING=ON to CMake).
• install: Installs headers and the library to the defined CMAKE_INSTALL_PREFIX.
• doc: Generates API documentation using Doxygen (if installed).

Before building, ensure the following dependencies are available:

• boost: Version 1.47.0 or newer (requires chrono and system).
• rabbitmq-c: Version 0.8.0 or better.
• cmake: Version 3.5 or newer.
• Doxygen (Optional): Required only if you wish to generate API documentation.

When handling exceptions, you can determine if an error is recoverable by calling is_soft_error() on an AmqpException object:

• Soft Errors (is_soft_error() == true): These are generally recoverable. The Channel object that originated the error can still be reused. These derive from AmqpClient::ChannelException.
• Hard Errors (is_soft_error() == false): These are non-recoverable. The Channel object is closed and will throw exceptions if used again. These derive from AmqpClient::ConnectionException.

The AmqpClient::BasicMessage::delivery_mode_t enum defines how a message should be handled by durable queues regarding persistence.

• dm_notset (0): No delivery mode specified.
• dm_nonpersistent (1): The message is not persistent.
• dm_persistent (2): The message should be persisted to disk.

msg->DeliveryMode(AmqpClient::BasicMessage::dm_persistent);

In SimpleAmqpClient, AMQP tables (used for arguments in exchanges, queues, etc.) are represented using a Table type, which is a std::map of TableKey (a std::string) to TableValue objects.

TableValue is a variant type that can hold various AMQP-compatible data types. Because RabbitMQ does not support unsigned 64-bit values in tables, TableValue provides a Timestamp type (using std::time_t) to handle such values.

Key types supported by TableValue include:

• Booleans
• Integers (8, 16, 32, and 64-bit signed; 8, 16, and 32-bit unsigned)
• Floating point (float, double)
• Strings
• Arrays (std::vector<TableValue>)
• Tables (AmqpClient::Table)
• Timestamps (std::time_t)

You can use a blocking version of BasicConsumeMessage that accepts a timeout (in milliseconds) to prevent the thread from hanging indefinitely if no message arrives.

Envelope::ptr_t envelope;
channel->BasicConsumeMessage(consumer_tag, envelope, 10); // 10 ms timeout

The AmqpClient::ConsumerCancelledException is thrown when the AMQP server terminates a consumer subscription. This typically occurs in two scenarios:

1. The server ends the subscription because the subscribed queue is being deleted.
2. The client itself issues a basic.cancel request.

You can catch this exception to identify which consumer was affected by calling GetConsumerTag() on the exception object.

try {
    // Code that performs consuming operations
} catch (const AmqpClient::ConsumerCancelledException& e) {
    std::string tag = e.GetConsumerTag();
    // Handle the cancellation for this specific consumer tag
}