Chapter 5. Using the API

For more information, see the AMQ C++ API reference and AMQ C++ example suite.

5.1. Handling messaging events

AMQ C++ is an asynchronous event-driven API. To define how the application handles events, the user implements callback methods on the messaging_handler class. These methods are then called as network activity or timers trigger new events.

Example: Handling messaging events

struct example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        std::cout << "The container has started\n";

    void on_sendable(proton::sender& snd) override {
        std::cout << "A message can be sent\n";

    void on_message(proton::delivery& dlv, proton::message& msg) override {
        std::cout << "A message is received\n";

These are only a few common-case events. The full set is documented in the API reference.

5.2. Creating a container

The container is the top-level API object. It is the entry point for creating connections, and it is responsible for running the main event loop. It is often constructed with a global event handler.

Example: Creating a container

int main() {
    example_handler handler {};
    proton::container cont {handler};;

5.3. Setting the container identity

Each container instance has a unique identity called the container ID. When AMQ C++ makes a connection, it sends the container ID to the remote peer. To set the container ID, pass it to the proton::container constructor.

Example: Setting the container identity

proton::container cont {handler, "job-processor-3"};

If the user does not set the ID, the library will generate a UUID when the container is constucted.