使用 AMQ C++ 客户端

Red Hat AMQ Clients 2.11

用于 AMQ Clients 2.11

摘要

本指南论述了如何安装和配置客户端，运行实践示例，并将您的客户端与其他 AMQ 组件一起使用。

使开源包含更多
复制链接

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。

表 1.1. API 术语
实体	描述
Container	连接的顶级容器。
连接	网络上两个对等点间的通信的频道。它包含会话。
会话	发送和接收消息的上下文。它包含发送者和接收器。
sender	将信息发送到目标的频道。它有一个目标。
receiver	从源接收消息的频道。它有一个源。
源	用于消息的命名源点。
目标	消息的命名目的地。
消息	特定于应用程序的信息片段。
交付	消息传输。

第 2 章安装
复制链接

本章介绍了在您的环境中安装 AMQ C++ 的步骤。

2.1. 先决条件
复制链接

您必须具有访问 AMQ 发行文件和软件仓库的订阅。
要在 Red Hat Enterprise Linux 上安装软件包，您必须注册您的系统。

要在 Red Hat Enterprise Linux 上使用 AMQ C++ 构建程序，您必须安装 gcc-c++、 cmake，并 制作 软件包。
要在 Microsoft Windows 上使用 AMQ C++ 构建程序，您必须安装 Visual Studio。

2.2. 在 Red Hat Enterprise Linux 上安装
复制链接

流程

使用 subscription-manager 命令订阅所需的软件包存储库。将 <version > 替换为主发行流的 2，或将 2.11 替换用于长期支持发行流。如有必要，将 < variant> 替换为您的 Red Hat Enterprise Linux 变体的值（如 server 或 workstation）。
Red Hat Enterprise Linux 7
```
sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-7-<variant>-rpms
```
```
$ sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-7-<variant>-rpms
```
Copy to Clipboard Toggle word wrap
Red Hat Enterprise Linux 8
```
sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-8-x86_64-rpms
```
```
$ sudo subscription-manager repos --enable=amq-clients-<version>-for-rhel-8-x86_64-rpms
```
Copy to Clipboard Toggle word wrap
使用 yum 命令安装 qpid-proton-cpp-devel 和 qpid-proton-cpp-docs 软件包。
```
sudo yum install qpid-proton-cpp-devel qpid-proton-cpp-docs
```
```
$ sudo yum install qpid-proton-cpp-devel qpid-proton-cpp-docs
```
Copy to Clipboard Toggle word wrap

有关使用软件包的详情请参考附录 B, 使用 Red Hat Enterprise Linux 软件包。

2.3. 在 Microsoft Windows 上安装
复制链接

流程

打开浏览器并登录红帽客户门户网站 产品下载页面，网址为 access.redhat.com/downloads。
找到 INTEGRATION AND AUTOMATION 类别中的 Red Hat AMQ Clients 条目。
点 Red Hat AMQ Clients。此时会打开 Software Downloads 页面。
下载 AMQ Clients 2.11.0 C++ .zip 文件。
将文件内容提取到您选择的目录中，方法是右键单击 zip 文件并选择 Extract All。

当您提取 .zip 文件的内容时，会创建一个名为 amq-clients-2.11.0-cpp-win 的目录。这是安装的顶级目录，在整个文档中被称为 < install-dir& gt;。

第 3 章开始使用
复制链接

本章介绍了设置环境并运行简单的消息传递程序的步骤。

3.1. 先决条件
复制链接

您必须为您的环境完成安装过程。
您必须有一个 AMQP 1.0 消息代理侦听接口 localhost 和端口 5672 上的连接。它必须启用匿名访问权限。如需更多信息，请参阅启动代理。
您必须有一个名为 example 的队列。如需更多信息，请参阅创建队列。

3.2. 在 Red Hat Enterprise Linux 上运行 Hello World
复制链接

Hello World 示例创建了一个与代理的连接，发送一条消息，其中包含到 示例 队列的问候消息，然后接收它。成功时，它会将收到的消息输出到控制台。

流程

将示例复制到您选择的位置。

cp -r /usr/share/proton/examples/cpp cpp-examples

$ cp -r /usr/share/proton/examples/cpp cpp-examples

Copy to Clipboard

Toggle word wrap

创建构建目录并更改到该目录：
```
mkdir cpp-examples/bld
cd cpp-examples/bld
```
```
$ mkdir cpp-examples/bld
$ cd cpp-examples/bld
```
Copy to Clipboard Toggle word wrap
使用 cmake 配置构建，并使用 make 编译示例。
```
cmake ..
make
```
```
$ cmake ..
$ make
```
Copy to Clipboard Toggle word wrap
运行 helloworld 程序。
```
./helloworld
```
```
$ ./helloworld
Hello World!
```
Copy to Clipboard Toggle word wrap

第 5 章使用 API
复制链接

如需更多信息，请参阅 AMQ C++ API 参考和 AMQ C++ 示例套件。

5.1. 处理消息传递事件
复制链接

AMQ C++ 是一个异步事件驱动的 API。为了定义应用如何处理事件，用户在 messaging_handler 类上实施回调方法。然后，这些方法被称为网络活动或计时器触发新事件。

示例：处理消息传递事件

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";
    }
};

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";
    }
};

Copy to Clipboard

Toggle word wrap

这些只是几个常见情况事件。完整集合记录在 API 参考中。

5.3. 设置容器身份
复制链接

每个容器实例具有唯一的身份，称为容器 ID。当 AMQ C++ 进行连接时，它会将容器 ID 发送到远程对等点。要设置容器 ID，请将其传递给 proton::container 构造器。

示例：设置容器身份

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

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

Copy to Clipboard

Toggle word wrap

如果用户未设置 ID，则当容器被决定时，库会生成一个 UUID。

第 6 章网络连接
复制链接

6.2. 创建出站连接
复制链接

要连接到远程服务器，请使用连接 URL 调用 container::connect （） 方法。这通常在 messaging_handler::on_container_start （） 方法内完成。

示例：创建传出连接

class example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        cont.connect("amqp://example.com");
    }

    void on_connection_open(proton::connection& conn) override {
        std::cout << "The connection is open\n";
    }
};

class example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        cont.connect("amqp://example.com");
    }

    void on_connection_open(proton::connection& conn) override {
        std::cout << "The connection is open\n";
    }
};

Copy to Clipboard

Toggle word wrap

有关创建安全连接的详情，请参考第 7 章 安全性。

6.5. 接受进入的连接
复制链接

AMQ C++ 可以接受入站网络连接，使您能够构建自定义消息传递服务器。

要开始侦听连接，请使用 proton::container::listen （） 方法，以及包含要侦听的本地主机地址和端口的 URL。

示例：接受传入的连接

class example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        cont.listen("0.0.0.0");
    }

    void on_connection_open(proton::connection& conn) override {
        std::cout << "New incoming connection\n";
    }
};

class example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        cont.listen("0.0.0.0");
    }

    void on_connection_open(proton::connection& conn) override {
        std::cout << "New incoming connection\n";
    }
};

Copy to Clipboard

Toggle word wrap

特殊的 IP 地址 0.0.0.0 侦听所有可用的 IPv4 接口。要侦听所有 IPv6 接口，请使用 [::0]。

如需更多信息，请参阅服务器 receive.cpp 示例。

第 7 章安全性
复制链接

7.4. 使用 Kerberos 进行身份验证
复制链接

Kerberos 是一种网络协议，用于根据加密票据的交换集中管理身份验证。如需更多信息，请参阅使用 Kerberos。

在您的操作系统中配置 Kerberos。请参阅配置 Kerberos 在 Red Hat Enterprise Linux 中设置 Kerberos。

在客户端应用程序中启用 GSSAPI SASL 机制。

proton::connection_options opts {};

opts.sasl_allowed_mechs("GSSAPI");

container.connect("amqps://example.com", opts);

proton::connection_options opts {};

opts.sasl_allowed_mechs("GSSAPI");

container.connect("amqps://example.com", opts);

Copy to Clipboard

Toggle word wrap

使用 kinit 命令验证您的用户凭证并存储生成的 Kerberos 票据。
```
kinit USER@REALM
```
```
$ kinit USER@REALM
```
Copy to Clipboard Toggle word wrap
运行客户端程序。

第 8 章发件人和接收器
复制链接

客户端使用发送方和接收器链接来代表传递消息的频道。发件人和接收器是单向的，消息来源的源结尾和消息目的地的目标结尾。

源和目标通常指向消息代理上的队列或主题。源也用于代表订阅。

8.1. 根据需要创建队列和主题
复制链接

有些消息服务器支持按需创建队列和主题。附加发送方或接收器时，服务器使用发送者目标地址或接收器源地址来创建名称与地址匹配的队列或主题。

邮件服务器通常默认为创建队列（用于一对一消息发送）或主题（用于一对多消息发送）。客户端可以通过在源或目标上设置 队列或主题 功能来指示首选情况。

要选择队列或主题语义，请按照以下步骤执行：

配置您的消息服务器，以自动创建队列和主题。这通常是默认配置。
在发送者目标或接收器源上设置 队列或主题 功能，如下例所示。

示例：发送到按需创建的队列

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::sender_options opts {};
    proton::target_options topts {};

    topts.capabilities(std::vector<proton::symbol> { "queue" });
    opts.target(topts);

    conn.open_sender("jobs", opts);
}

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::sender_options opts {};
    proton::target_options topts {};

    topts.capabilities(std::vector<proton::symbol> { "queue" });
    opts.target(topts);

    conn.open_sender("jobs", opts);
}

Copy to Clipboard

Toggle word wrap

示例：从按需创建的主题接收

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    sopts.capabilities(std::vector<proton::symbol> { "topic" });
    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    sopts.capabilities(std::vector<proton::symbol> { "topic" });
    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

Copy to Clipboard

Toggle word wrap

如需了解更多详细信息，请参阅以下示例：

8.2. 创建持久订阅
复制链接

持久化订阅是远程服务器上的一个状态，代表一个消息接收器。通常，当客户端关闭时，消息接收方会被丢弃。但是，由于持久订阅是持久的，客户端可以从它们分离，之后再重新连接。当客户端重新附加时，任何在分离时收到的消息都可用。

持久化订阅通过组合客户端容器 ID 和接收器名称来组成订阅 ID 来唯一标识。它们必须具有稳定的值，以便可以恢复订阅。

要创建持久订阅，请按照以下步骤执行：

将连接容器 ID 设置为 stable 值，如 client-1 ：
```
proton::container cont {handler, "client-1"};
```
```
proton::container cont {handler, "client-1"};
```
Copy to Clipboard Toggle word wrap

使用稳定名称（如 sub-1 ）创建一个接收器，并通过设置 persistence _mode 和 expiry_policy 选项来为持久性 配置接收器源：

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    opts.name("sub-1");
    sopts.durability_mode(proton::source::UNSETTLED_STATE);
    sopts.expiry_policy(proton::source::NEVER);

    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    opts.name("sub-1");
    sopts.durability_mode(proton::source::UNSETTLED_STATE);
    sopts.expiry_policy(proton::source::NEVER);

    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

Copy to Clipboard

Toggle word wrap

要从订阅分离，请使用 proton::receiver::detach （） 方法。要终止订阅，请使用 proton::receiver::close （） 方法。

如需更多信息，请参阅 durable-subscribe.cpp 示例。

8.3. 创建共享订阅
复制链接

共享订阅是远程服务器中代表一个或多个消息接收器的状态。由于它是共享的，多个客户端可以从同一消息流使用。

客户端通过在接收器源上设置 共享功能来配置共享 订阅。

共享订阅通过组合客户端容器 ID 和接收器名称来组成订阅 ID 来唯一标识。它们必须具有稳定的值，以便多个客户端进程可以找到相同的订阅。如果除了 共享 外设置了 全局 功能，则仅接收方名称用于标识订阅。

要创建持久订阅，请按照以下步骤执行：

将连接容器 ID 设置为 stable 值，如 client-1 ：
```
proton::container cont {handler, "client-1"};
```
```
proton::container cont {handler, "client-1"};
```
Copy to Clipboard Toggle word wrap

使用稳定名称（如 sub-1 ）创建一个接收器，并通过设置共享功能来配置用于 共享的 接收器源：

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    opts.name("sub-1");
    sopts.capabilities(std::vector<proton::symbol> { "shared" });

    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

void on_container_start(proton::container& cont) override {
    proton::connection conn = cont.connect("amqp://example.com");
    proton::receiver_options opts {};
    proton::source_options sopts {};

    opts.name("sub-1");
    sopts.capabilities(std::vector<proton::symbol> { "shared" });

    opts.source(sopts);

    conn.open_receiver("notifications", opts);
}

Copy to Clipboard

Toggle word wrap

要从订阅分离，请使用 proton::receiver::detach （） 方法。要终止订阅，请使用 proton::receiver::close （） 方法。

如需更多信息，请参阅 shared-subscribe.cpp 示例。

第 9 章消息交付
复制链接

9.2. 跟踪发送的消息
复制链接

发送消息后，发件人可以保留对代表传输的 tracker 对象的引用。接收器接受或拒绝发送的每个消息。发件人会通知每个跟踪发送的结果。

要监控发送的消息的结果，请覆盖 on_tracker_accept 和 on_tracker_reject 事件处理程序，并将交付状态更新映射到从 send （） 返回的 tracker。

示例：跟踪发送的消息

void on_sendable(proton::sender& snd) override {
    proton::message msg {"job-1"};
    proton::tracker trk = snd.send(msg);
}

void on_tracker_accept(proton::tracker& trk) override {
    std::cout << "Delivery for " << trk << " is accepted\n";
}

void on_tracker_reject(proton::tracker& trk) override {
    std::cout << "Delivery for " << trk << " is rejected\n";
}

void on_sendable(proton::sender& snd) override {
    proton::message msg {"job-1"};
    proton::tracker trk = snd.send(msg);
}

void on_tracker_accept(proton::tracker& trk) override {
    std::cout << "Delivery for " << trk << " is accepted\n";
}

void on_tracker_reject(proton::tracker& trk) override {
    std::cout << "Delivery for " << trk << " is rejected\n";
}

Copy to Clipboard

Toggle word wrap

tracker 对象具有一个 tag （） 方法，用于访问每个发送的唯一标识符。delivery 标签可用于存储在连接失败后重新发送的消息。

9.3. 接收信息
复制链接

要接收消息，请创建一个接收器并覆盖 on_message 事件处理程序。

示例：接收信息

struct example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        proton::connection conn = cont.connect("amqp://example.com");
        conn.open_receiver("jobs");
    }

    void on_message(proton::delivery& dlv, proton::message& msg) override {
        std::cout << "Received message '" << msg.body() << "'\n";
    }
};

struct example_handler : public proton::messaging_handler {
    void on_container_start(proton::container& cont) override {
        proton::connection conn = cont.connect("amqp://example.com");
        conn.open_receiver("jobs");
    }

    void on_message(proton::delivery& dlv, proton::message& msg) override {
        std::cout << "Received message '" << msg.body() << "'\n";
    }
};

Copy to Clipboard

Toggle word wrap

delivery 对象具有一个 tag （） 方法，用于访问每个发送的唯一标识符。

9.4. 确认收到的消息
复制链接

要显式接受或拒绝发送，请使用 on_message 事件处理程序中的 delivery::accept （） 或 delivery::reject （） 方法。

示例：确认收到的信息

void on_message(proton::delivery& dlv, proton::message& msg) override {
    try {
        process_message(msg);
        dlv.accept();
    } catch (std::exception& e) {
        dlv.reject();
    }
}

void on_message(proton::delivery& dlv, proton::message& msg) override {
    try {
        process_message(msg);
        dlv.accept();
    } catch (std::exception& e) {
        dlv.reject();
    }
}

Copy to Clipboard

Toggle word wrap

默认情况下，如果您没有明确确认发送，则库会在 on_message 返回后接受它。要禁用此行为，将 auto_accept receiver 选项设置为 false。

第 10 章错误处理
复制链接

AMQ C++ 中的错误可以通过两种不同的方式处理：

捕获例外
覆盖事件处理功能以截获 AMQP 协议或连接错误

捕获例外是最基本但最精细的方法来处理错误。如果没有在处理程序函数中使用覆盖处理错误，则会抛出异常。

10.1. 捕获例外
复制链接

如果没有在事件处理函数中使用覆盖处理错误，则 容器运行 方法会抛出异常。

AMQ C++ 丢弃从 proton::error 类继承的所有例外，后者又从 std::runtime_error 和 std::exception 类继承。

以下示例演示了如何捕获 AMQ C++ 中抛出的异常：

示例：特定于 API 的异常处理

try {
    // Something that might throw an exception
} catch (proton::error& e) {
    // Handle Proton-specific problems here
} catch (std::exception& e) {
    // Handle more general problems here
}

try {
    // Something that might throw an exception
} catch (proton::error& e) {
    // Handle Proton-specific problems here
} catch (std::exception& e) {
    // Handle more general problems here
}

Copy to Clipboard

Toggle word wrap

如果您不需要特定于 API 的异常处理，您只需要捕获 std::exception，因为 proton::error 会继承它。

10.2. 处理连接和协议错误
复制链接

您可以通过覆盖以下 messaging_handler 方法来处理协议级错误：

on_transport_error(proton::transport&)
on_connection_error(proton::connection&)
on_session_error(proton::session&)
on_receiver_error(proton::receiver&)
on_sender_error(proton::sender&)

每当事件发生特定对象时，这些事件处理例程都会调用。在调用错误处理程序后，也会调用相应的关闭处理程序。

如果没有覆盖多个更具体的错误处理程序，则调用默认错误处理程序：

on_error(proton::error_condition&)

注意

由于在出现任何错误时调用关闭处理程序，因此仅需要在错误处理程序中处理错误本身。资源清理可以通过关闭的处理程序来管理。如果没有特定于特定对象的错误处理，则通常使用常规 on_error 处理程序，且没有更具体的处理程序。

注意

当启用重新连接并且远程服务器关闭具有 amqp:connection:forced 条件的连接时，客户端不会将其视为错误，因此不会触发 on_connection_error 处理程序。相反，客户端会开始重新连接过程。

第 11 章日志记录
复制链接

11.1. 启用协议日志记录
复制链接

客户端可以将 AMQP 协议帧记录到控制台。诊断问题时，这些数据通常至关重要。

要启用协议日志记录，请将 PN_TRACE_FRM 环境变量设置为 1：

示例：启用协议日志记录

export PN_TRACE_FRM=1
<your-client-program>

$ export PN_TRACE_FRM=1
$ <your-client-program>

Copy to Clipboard

Toggle word wrap

要禁用协议日志记录，请取消设置 PN_TRACE_FRM 环境变量。

第 12 章线程和调度
复制链接

AMQ C++ 支持使用 C++11 及之后的版本的完整多线程。旧版本 C++ 可能会有有限的多线程。请参阅第 12.6 节 “使用旧版本的 C++”。

12.1. 线程模型
复制链接

容器 对象可以同时处理多个连接。当 AMQP 事件在连接上发生时，容器会调用 messaging_handler 回调函数。任何一个连接的回调都会按顺序化（不同时调用），但不同连接的回调可以安全地并行执行。

您可以使用 handler connection 选项，将处理程序分配给 container::connect （） 或 listen_handler::on_accept （） 中的连接。建议为每个连接创建一个单独的处理程序，以便处理程序不需要锁定或其他同步来保护它不受库线程的并发使用。如果有任何非library 线程同时使用处理程序，则需要同步。

12.2. thread-safety 规则
复制链接

连接、会话、发送者、接收器、跟踪器 和交付 对象不是线程安全状态，受以下规则约束：

您必须只使用它们来自 messaging_handler 回调或 work_queue 函数。
对于另一个连接，不要使用属于来自回调的一个连接的对象。
您可以在成员变量中存储 AMQ C++ 对象，以便在后续回调中使用，只要您遵守规则 2。

message 对象是一个值类型，其线程限制与标准 C++ 内置类型相同。它不能同时修改。

12.3. 工作队列
复制链接

work_queue 接口提供了一种安全的方法，可在不同的连接处理程序之间或非library 线程和连接处理程序之间进行通信。

每个连接都有一个关联的 work_queue。
工作队列是 thread-safe (C++11 或更高版本)。任何线程都可以添加工作。
work 项是一个 std::function，绑定参数则称为事件回调。

当库调用工作函数时，它被安全序列化，以便您可以像事件回调一样对待工作功能，并安全地访问其中存储的处理器和 AMQ C++ 对象。

12.4. wake primitive
复制链接

connection::wake （） 方法通过触发 on_connection_wake （） 回调，允许任何线程在连接上提示活动。这是 连接 上唯一的 thread-safe 方法。

wake （） 是一个轻量级、低级别的原语，用于在线程之间进行信号。

它不执行任何代码或数据，这与 work_queue 不同。
对 wake （） 的多个调用可能会合并到一个 on_connection_wake （） 中。
可能会出现对 on_connection_wake （） 的调用，而无需任何应用程序调用 wake （），因为库在内部使用 wake （）。

wake （） 的语义与 std::condition_variable::notify_one （） 类似。会有一个唤醒，但必须有一些共享应用程序状态来确定发生唤醒的原因，以及要对其执行什么操作。

工作队列在很多实例中更易于使用，但是如果您已经拥有自己的外部线程安全队列，并且需要高效的方法来唤醒连接来检查它们的数据，则 wake （） 可能很有用。

12.5. 调度延迟工作
复制链接

AMQ C++ 能够延迟后执行代码。您可以使用它来实现应用程序中的基于时间的行为，如定期调度的工作或超时。

要延迟固定时间的工作，请使用 schedule 方法设置延迟并注册定义工作的功能。

示例：在延迟后发送消息

void on_sender_open(proton::sender& snd) override {
    proton::duration interval {5 * proton::duration::SECOND};
    snd.work_queue().schedule(interval, [=] { send(snd); });
}

void send(proton::sender snd) {
    if (snd.credit() > 0) {
        proton::message msg {"hello"};
        snd.send(msg);
    }
}

void on_sender_open(proton::sender& snd) override {
    proton::duration interval {5 * proton::duration::SECOND};
    snd.work_queue().schedule(interval, [=] { send(snd); });
}

void send(proton::sender snd) {
    if (snd.credit() > 0) {
        proton::message msg {"hello"};
        snd.send(msg);
    }
}

Copy to Clipboard

Toggle word wrap

本例在发件人的工作队列中使用 schedule 方法，以将其建立为工作的执行上下文。

12.6. 使用旧版本的 C++
复制链接

在 C++11 之前，在 C++ 中不支持线程。您可以将 AMQ C++ 与线程一起使用，但有以下限制。

容器不创建线程。它仅使用调用 container::run （） 的单个线程。
AMQ C++ 库类都不是 thread-safe，包括 container 和 work_queue。您需要一个外部锁定才能在多个线程中使用 容器。唯一的例外是 connection::wake （）。即使在较旧的 C++ 中，它是线程安全。

container::schedule （） 和 work_queue API 接受 C++11 lambda 函数来定义工作单元。如果您使用不支持 lambda 的 C++ 版本，则必须使用 make_work （） 函数。

第 13 章基于文件的配置
复制链接

AMQ C++ 可以读取用于从名为 connect.json 的本地文件中建立连接的配置选项。这可让您在部署时在应用程序中配置连接。

当应用调用容器连接方法时，库会尝试读取文件，而无需提供任何连接选项。

13.1. 文件位置
复制链接

如果设置，AMQ C++ 将使用 MESSAGING_CONNECT_FILE 环境变量的值来定位配置文件。

如果没有设置 MESSAGING_CONNECT_FILE，AMQ C++ 会在以下位置搜索名为 connect.json 的文件，并按照所示的顺序搜索。它在第一次遇到的匹配项时停止。

对于 Linux：

$PWD/connect.json，其中 $PWD 是客户端进程的当前工作目录
$HOME/.config/messaging/connect.json，其中 $HOME 是当前用户主目录
/etc/messaging/connect.json

在 Windows 上：

%CD%/connect.json，其中 %cd% 是客户端进程的当前工作目录

如果没有找到 connect.json 文件，则库为所有选项使用默认值。

13.3. 配置选项
复制链接

选项键包含一个点(.)，代表嵌套在命名空间内的属性。

Expand

表 13.1. connect.json中的配置选项
键	值类型	默认值	描述
`scheme`	string	`"amqps"`	`"AMQP"` 用于明文或 SSL/TLS `"amqps"`
`主机`	string	`"localhost"`	远程主机的主机名或 IP 地址
`port`	字符串或数字	`"amqps"`	端口号或端口字面
`user`	string	无	进行身份验证的用户名
`密码`	string	无	进行身份验证的密码
`sasl.mechanisms`	list 或 string	none （系统默认设置）	启用 SASL 机制的 JSON 列表。裸机字符串代表一种机制。如果未指定，客户端将使用系统提供的默认机制。
`sasl.allow_insecure`	布尔值	`false`	启用发送明文密码的机制
`tls.cert`	string	无	客户端证书的文件名或数据库 ID
`tls.key`	string	无	客户端证书的私钥的文件名或数据库 ID
`tls.ca`	string	无	CA 证书的文件名、目录或数据库 ID
`tls.verify`	布尔值	`true`	需要具有匹配主机名的有效服务器证书

第 14 章互操作性
复制链接

本章讨论了如何将 AMQ C++ 与其他 AMQ 组件结合使用。有关 AMQ 组件的兼容性概述，请参阅产品简介。

14.1. 与其他 AMQP 客户端交互
复制链接

AMQP 消息使用 AMQP 类型系统组成。这种通用格式是以不同语言的 AMQP 客户端能够相互互操作的原因之一。

发送消息时，AMQ C++ 会自动将语言原生类型转换为 AMQP 编码数据。收到信息时，反向转换就发生。

注意

有关 AMQP 类型的更多信息，请访问由 Apache Qpid 项目维护的交互式类型参考。

Expand

表 14.1. AMQP 类型
AMQP 类型	描述
`null`	一个空值
`布尔值`	true 或 false 值
`char`	单个 Unicode 字符
`string`	一系列 Unicode 字符
`二进制`	一个字节序列
`byte`	签名的 8 位整数
`short`	签名的 16 位整数
`int`	签名的 32 位整数
`long`	签名的 64 位整数
`ubyte`	未签名的 8 位整数
`ushort`	未签名的 16 位整数
`uint`	未签名的 32 位整数
`ulong`	未签名的 64 位整数
`浮点值`	32 位浮点号
`double`	64 位浮点号
`数组`	单个类型的值的序列
`list`	变量类型的序列值
`map`	从不同键到值的映射
`uuid`	通用唯一标识符
`符号`	来自受限域的 7 位 ASCII 字符串
`timestamp`	一个绝对时间点

Expand

表 14.2. 在编码前和解码后 AMQ C++ 类型
AMQP 类型	编码前的 AMQ C++ 类型	解码后 AMQ C++ 类型
`null`	`nullptr`	`nullptr`
`布尔值`	`bool`	`bool`
`char`	`wchar_t`	`wchar_t`
`string`	`std::string`	`std::string`
`二进制`	`proton::binary`	`proton::binary`
`byte`	`int8_t`	`int8_t`
`short`	`int16_t`	`int16_t`
`int`	`int32_t`	`int32_t`
`long`	`int64_t`	`int64_t`
`ubyte`	`uint8_t`	`uint8_t`
`ushort`	`uint16_t`	`uint16_t`
`uint`	`uint32_t`	`uint32_t`
`ulong`	`uint64_t`	`uint64_t`
`浮点值`	`浮点值`	`浮点值`
`double`	`double`	`double`
`list`	`std::vector`	`std::vector`
`map`	`std::map`	`std::map`
`uuid`	`proton::uuid`	`proton::uuid`
`符号`	`proton::symbol`	`proton::symbol`
`timestamp`	`proton::timestamp`	`proton::timestamp`

Expand

表 14.3. AMQ C++ 和其他 AMQ 客户端类型(2 为 1)
编码前的 AMQ C++ 类型	AMQ JavaScript 类型	AMQ .NET 类型
`nullptr`	`null`	`null`
`bool`	`布尔值`	`system.Boolean`
`wchar_t`	`number`	`system.Char`
`std::string`	`string`	`system.String`
`proton::binary`	`string`	`System.Byte[]`
`int8_t`	`number`	`system.SByte`
`int16_t`	`number`	`System.Int16`
`int32_t`	`number`	`System.Int32`
`int64_t`	`number`	`System.Int64`
`uint8_t`	`number`	`system.Byte`
`uint16_t`	`number`	`System.UInt16`
`uint32_t`	`number`	`System.UInt32`
`uint64_t`	`number`	`System.UInt64`
`浮点值`	`number`	`system.Single`
`double`	`number`	`system.Double`
`std::vector`	`Array`	`Amqp.List`
`std::map`	`object`	`Amqp.Map`
`proton::uuid`	`number`	`system.Guid`
`proton::symbol`	`string`	`Amqp.Symbol`
`proton::timestamp`	`number`	`System.DateTime`

Expand

表 14.4. AMQ C++ 和其他 AMQ 客户端类型(2 为 2)
编码前的 AMQ C++ 类型	AMQ Python 类型	AMQ Ruby 类型
`nullptr`	`无`	`nil`
`bool`	`bool`	`true, false`
`wchar_t`	`unicode`	`字符串`
`std::string`	`unicode`	`字符串`
`proton::binary`	`bytes`	`字符串`
`int8_t`	`int`	`整数`
`int16_t`	`int`	`整数`
`int32_t`	`long`	`整数`
`int64_t`	`long`	`整数`
`uint8_t`	`long`	`整数`
`uint16_t`	`long`	`整数`
`uint32_t`	`long`	`整数`
`uint64_t`	`long`	`整数`
`浮点值`	`浮点值`	`浮点值`
`double`	`浮点值`	`浮点值`
`std::vector`	`list`	`Array`
`std::map`	`dict`	`hash`
`proton::uuid`	-	-
`proton::symbol`	`str`	`符号`
`proton::timestamp`	`long`	`Time`

14.2. 使用 AMQ JMS 进行交互
复制链接

AMQP 定义标准映射到 JMS 消息传递模型。本节讨论该映射的各个方面。如需更多信息，请参阅 AMQ JMS Interoperability 章节。

JMS 消息类型

AMQ C++ 提供单个消息类型，其正文类型可能会有所不同。相反，JMS API 使用不同的消息类型来代表不同类型的数据。下表标明特定的正文类型如何映射到 JMS 消息类型。

若要更明确地控制生成的 JMS 消息类型，您可以设置 x-opt-jms-msg-type 消息注释。如需更多信息，请参阅 AMQ JMS Interoperability 章节。

Expand

表 14.5. AMQ C++ 和 JMS 消息类型
AMQ C++ 正文类型	JMS 消息类型
`std::string`	`TextMessage`
`nullptr`	`TextMessage`
`proton::binary`	`BytesMessage`
任何其他类型	`ObjectMessage`

14.3. 连接到 AMQ Broker
复制链接

AMQ Broker 旨在与 AMQP 1.0 客户端互操作。检查以下内容以确保为 AMQP 消息传递配置了代理：

网络防火墙中的端口 5672 将打开。
启用 AMQ Broker AMQP acceptor。请参阅默认接受者设置。
在代理上配置必要的地址。请参阅地址、队列和主题。
代理配置为允许来自您的客户端的访问，客户端被配置为发送所需的凭证。请参阅 Broker 安全。

附录 A. 使用您的订阅
复制链接

AMQ 通过软件订阅提供。要管理您的订阅，请访问红帽客户门户中的帐户。

A.1. 访问您的帐户
复制链接

流程

转至 access.redhat.com。
如果您还没有帐户，请创建一个帐户。
登录到您的帐户。

A.2. 激活订阅
复制链接

流程

转至 access.redhat.com。
导航到 My Subscriptions。
导航到 激活订阅 并输入您的 16 位激活号。

A.3. 下载发行文件
复制链接

要访问 .zip、.tar.gz 和其他发布文件，请使用客户门户查找要下载的相关文件。如果您使用 RPM 软件包或 Red Hat Maven 存储库，则不需要这一步。

流程

打开浏览器并登录红帽客户门户网站 产品下载页面，网址为 access.redhat.com/downloads。
查找 INTEGRATION 目录中的红帽 AMQ 条目。
选择所需的 AMQ 产品。此时会打开 Software Downloads 页面。
单击组件的 Download 链接。

A.4. 为系统注册软件包
复制链接

要在 Red Hat Enterprise Linux 上安装此产品的 RPM 软件包，必须注册您的系统。如果您使用下载的发行文件，则不需要这一步。

流程

转至 access.redhat.com。
进入 Registration Assistant。
选择您的操作系统版本，再继续到下一页。
使用您的系统终端中列出的命令完成注册。

有关注册您的系统的更多信息，请参阅以下资源之一：

附录 B. 使用 Red Hat Enterprise Linux 软件包
复制链接

这部分论述了如何使用作为 Red Hat Enterprise Linux 的 RPM 软件包提供的软件。

要确保此产品的 RPM 软件包可用，您必须首先注册您的系统。

B.1. 概述
复制链接

库或服务器等组件通常关联有多个软件包。您不必安装它们。您只能安装您需要的用户。

主软件包通常具有最简单的名称，而不带有其他限定符。这个软件包提供了在程序运行时使用组件所需的所有接口。

名称以 -devel 结尾的软件包包含 C 和 C++ 库的标头。在编译时，需要它们来构建依赖于此软件包的程序。

名称以 -docs 结尾的软件包包含组件的文档和示例程序。

有关使用 RPM 软件包的更多信息，请参阅以下资源之一：

附录 C. 使用带有示例的 AMQ Broker
复制链接

AMQ C++ 示例需要一个正在运行的消息代理，其中包含名为 example 的队列。使用以下步骤安装和启动代理并定义队列。

C.1. 安装代理
复制链接

按照 AMQ Broker 入门 中的说明来安装代理并创建代理实例。启用匿名访问。

以下流程将代理实例的位置称为 < broker-instance-dir>。

C.3. 创建队列
复制链接

在新终端中，使用 artemis queue 命令创建名为 example 的队列。

<broker-instance-dir>/bin/artemis queue create --name examples --address examples --auto-create-address --anycast

$ <broker-instance-dir>/bin/artemis queue create --name examples --address examples --auto-create-address --anycast

Copy to Clipboard

Toggle word wrap

系统将提示您回答一系列 yes 或没有问题。全部答案为 N。

创建队列后，代理就可以与示例程序一起使用。

C.4. 停止代理
复制链接

运行完示例后，请使用 artemis stop 命令来停止代理。

<broker-instance-dir>/bin/artemis stop

$ <broker-instance-dir>/bin/artemis stop

Copy to Clipboard

Toggle word wrap

更新于 2023-09-26

法律通告
复制链接

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

使用 AMQ C++ 客户端

用于 AMQ Clients 2.11

使开源包含更多复制链接链接已复制到粘贴板!

第 1 章 概述复制链接链接已复制到粘贴板!

1.1. 主要特性复制链接链接已复制到粘贴板!

1.2. 支持的标准和协议复制链接链接已复制到粘贴板!

1.3. 支持的配置复制链接链接已复制到粘贴板!

1.4. 术语和概念复制链接链接已复制到粘贴板!

1.5. 文档惯例复制链接链接已复制到粘贴板!

sudo 命令

文件路径

变量文本

第 2 章 安装复制链接链接已复制到粘贴板!

2.1. 先决条件复制链接链接已复制到粘贴板!

2.2. 在 Red Hat Enterprise Linux 上安装复制链接链接已复制到粘贴板!

2.3. 在 Microsoft Windows 上安装复制链接链接已复制到粘贴板!

第 3 章 开始使用复制链接链接已复制到粘贴板!

3.1. 先决条件复制链接链接已复制到粘贴板!

3.2. 在 Red Hat Enterprise Linux 上运行 Hello World复制链接链接已复制到粘贴板!

第 4 章 例子复制链接链接已复制到粘贴板!

4.1. 发送消息复制链接链接已复制到粘贴板!

运行示例

4.2. 接收信息复制链接链接已复制到粘贴板!

运行示例

第 5 章 使用 API复制链接链接已复制到粘贴板!

5.1. 处理消息传递事件复制链接链接已复制到粘贴板!

5.2. 创建容器复制链接链接已复制到粘贴板!

5.3. 设置容器身份复制链接链接已复制到粘贴板!

第 6 章 网络连接复制链接链接已复制到粘贴板!

6.1. 连接 URL复制链接链接已复制到粘贴板!

6.2. 创建出站连接复制链接链接已复制到粘贴板!

6.3. 配置重新连接复制链接链接已复制到粘贴板!

6.4. 配置故障转移复制链接链接已复制到粘贴板!

6.5. 接受进入的连接复制链接链接已复制到粘贴板!

第 7 章 安全性复制链接链接已复制到粘贴板!

7.1. 使用 SSL/TLS 保护连接复制链接链接已复制到粘贴板!

7.2. 使用用户和密码连接复制链接链接已复制到粘贴板!

7.3. 配置 SASL 身份验证复制链接链接已复制到粘贴板!

7.4. 使用 Kerberos 进行身份验证复制链接链接已复制到粘贴板!

第 8 章 发件人和接收器复制链接链接已复制到粘贴板!

8.1. 根据需要创建队列和主题复制链接链接已复制到粘贴板!

8.2. 创建持久订阅复制链接链接已复制到粘贴板!

8.3. 创建共享订阅复制链接链接已复制到粘贴板!

第 9 章 消息交付复制链接链接已复制到粘贴板!

9.1. 发送消息复制链接链接已复制到粘贴板!

9.2. 跟踪发送的消息复制链接链接已复制到粘贴板!

9.3. 接收信息复制链接链接已复制到粘贴板!

9.4. 确认收到的消息复制链接链接已复制到粘贴板!

第 10 章 错误处理复制链接链接已复制到粘贴板!

10.1. 捕获例外复制链接链接已复制到粘贴板!

10.2. 处理连接和协议错误复制链接链接已复制到粘贴板!

第 11 章 日志记录复制链接链接已复制到粘贴板!

11.1. 启用协议日志记录复制链接链接已复制到粘贴板!

第 12 章 线程和调度复制链接链接已复制到粘贴板!

12.1. 线程模型复制链接链接已复制到粘贴板!

12.2. thread-safety 规则复制链接链接已复制到粘贴板!

12.3. 工作队列复制链接链接已复制到粘贴板!

12.4. wake primitive复制链接链接已复制到粘贴板!

12.5. 调度延迟工作复制链接链接已复制到粘贴板!

12.6. 使用旧版本的 C++复制链接链接已复制到粘贴板!

第 13 章 基于文件的配置复制链接链接已复制到粘贴板!

13.1. 文件位置复制链接链接已复制到粘贴板!

13.2. 文件格式复制链接链接已复制到粘贴板!

13.3. 配置选项复制链接链接已复制到粘贴板!

第 14 章 互操作性复制链接链接已复制到粘贴板!

14.1. 与其他 AMQP 客户端交互复制链接链接已复制到粘贴板!

14.2. 使用 AMQ JMS 进行交互复制链接链接已复制到粘贴板!

JMS 消息类型

14.3. 连接到 AMQ Broker复制链接链接已复制到粘贴板!

附录 A. 使用您的订阅复制链接链接已复制到粘贴板!

A.1. 访问您的帐户复制链接链接已复制到粘贴板!

A.2. 激活订阅复制链接链接已复制到粘贴板!

A.3. 下载发行文件复制链接链接已复制到粘贴板!

A.4. 为系统注册软件包复制链接链接已复制到粘贴板!

附录 B. 使用 Red Hat Enterprise Linux 软件包复制链接链接已复制到粘贴板!

B.1. 概述复制链接链接已复制到粘贴板!

B.2. 搜索软件包复制链接链接已复制到粘贴板!

B.3. 安装软件包复制链接链接已复制到粘贴板!

B.4. 查询软件包信息复制链接链接已复制到粘贴板!

附录 C. 使用带有示例的 AMQ Broker复制链接链接已复制到粘贴板!

使开源包含更多
复制链接

第 1 章概述
复制链接

1.1. 主要特性
复制链接

1.2. 支持的标准和协议
复制链接

1.3. 支持的配置
复制链接

1.4. 术语和概念
复制链接

1.5. 文档惯例
复制链接

第 2 章安装
复制链接

2.1. 先决条件
复制链接

2.2. 在 Red Hat Enterprise Linux 上安装
复制链接

2.3. 在 Microsoft Windows 上安装
复制链接

第 3 章开始使用
复制链接

3.1. 先决条件
复制链接

3.2. 在 Red Hat Enterprise Linux 上运行 Hello World
复制链接

第 4 章例子
复制链接

4.1. 发送消息
复制链接

4.2. 接收信息
复制链接

第 5 章使用 API
复制链接

5.1. 处理消息传递事件
复制链接

5.2. 创建容器
复制链接

5.3. 设置容器身份
复制链接

第 6 章网络连接
复制链接

6.1. 连接 URL
复制链接

6.2. 创建出站连接
复制链接

6.3. 配置重新连接
复制链接

6.4. 配置故障转移
复制链接

6.5. 接受进入的连接
复制链接

第 7 章安全性
复制链接

7.1. 使用 SSL/TLS 保护连接
复制链接

7.2. 使用用户和密码连接
复制链接

7.3. 配置 SASL 身份验证
复制链接

7.4. 使用 Kerberos 进行身份验证
复制链接

第 8 章发件人和接收器
复制链接

8.1. 根据需要创建队列和主题
复制链接

8.2. 创建持久订阅
复制链接

8.3. 创建共享订阅
复制链接

第 9 章消息交付
复制链接

9.1. 发送消息
复制链接

9.2. 跟踪发送的消息
复制链接

9.3. 接收信息
复制链接

9.4. 确认收到的消息
复制链接

第 10 章错误处理
复制链接

10.1. 捕获例外
复制链接

10.2. 处理连接和协议错误
复制链接

第 11 章日志记录
复制链接

11.1. 启用协议日志记录
复制链接

第 12 章线程和调度
复制链接

12.1. 线程模型
复制链接

12.2. thread-safety 规则
复制链接

12.3. 工作队列
复制链接

12.4. wake primitive
复制链接

12.5. 调度延迟工作
复制链接

12.6. 使用旧版本的 C++
复制链接

第 13 章基于文件的配置
复制链接

13.1. 文件位置
复制链接

13.2. 文件格式
复制链接

13.3. 配置选项
复制链接

第 14 章互操作性
复制链接

14.1. 与其他 AMQP 客户端交互
复制链接

14.2. 使用 AMQ JMS 进行交互
复制链接

14.3. 连接到 AMQ Broker
复制链接

附录 A. 使用您的订阅
复制链接

A.1. 访问您的帐户
复制链接

A.2. 激活订阅
复制链接

A.3. 下载发行文件
复制链接

A.4. 为系统注册软件包
复制链接

附录 B. 使用 Red Hat Enterprise Linux 软件包
复制链接

B.1. 概述
复制链接

B.2. 搜索软件包
复制链接

B.3. 安装软件包
复制链接

B.4. 查询软件包信息
复制链接

附录 C. 使用带有示例的 AMQ Broker
复制链接

C.1. 安装代理
复制链接

C.2. 启动代理
复制链接

C.3. 创建队列
复制链接

C.4. 停止代理
复制链接

法律通告
复制链接