From 72b5f95323cd316011b0aa6dce27a51ebffd85e9 Mon Sep 17 00:00:00 2001 From: Justin Ross Date: Mon, 25 Jan 2016 21:16:10 -0800 Subject: [PATCH] PROTON-1109: Improve C++ binding documentation - Update the overview and tutorial; this is Alan's work - Add lots of new API documentation - Correct broken links - Hide elements of the API that are not yet settled - Configure doxygen for less cluttered output - Clean up the header files (all one style) - Adjust the formatting of some of the examples --- examples/cpp/README.hpp | 129 ++++++-- examples/cpp/broker.cpp | 7 +- examples/cpp/broker.hpp | 70 +++-- examples/cpp/client.cpp | 10 +- examples/cpp/direct_recv.cpp | 16 +- examples/cpp/direct_send.cpp | 17 +- examples/cpp/engine/helloworld.cpp | 4 +- examples/cpp/helloworld.cpp | 4 +- examples/cpp/helloworld_direct.cpp | 7 +- examples/cpp/queue_browser.cpp | 8 +- examples/cpp/selected_recv.cpp | 4 +- examples/cpp/server.cpp | 17 +- examples/cpp/server_direct.cpp | 15 +- examples/cpp/simple_recv.cpp | 18 +- examples/cpp/simple_send.cpp | 16 +- proton-c/CMakeLists.txt | 1 + proton-c/bindings/cpp/docs/mainpage.md | 234 ++++++++------- proton-c/bindings/cpp/docs/tutorial.hpp | 72 +++-- proton-c/bindings/cpp/docs/user.doxygen.in | 58 ++-- .../bindings/cpp/include/proton/acceptor.hpp | 21 +- .../cpp/include/proton/annotation_key.hpp | 38 ++- .../bindings/cpp/include/proton/condition.hpp | 26 +- .../bindings/cpp/include/proton/config.hpp | 21 +- .../cpp/include/proton/connection.hpp | 88 ++++-- .../cpp/include/proton/connection_engine.hpp | 85 +++--- .../cpp/include/proton/connection_options.hpp | 101 +++++-- .../bindings/cpp/include/proton/container.hpp | 98 +++--- proton-c/bindings/cpp/include/proton/data.hpp | 13 +- .../bindings/cpp/include/proton/decoder.hpp | 6 +- .../bindings/cpp/include/proton/delivery.hpp | 101 +++---- .../bindings/cpp/include/proton/duration.hpp | 19 +- .../bindings/cpp/include/proton/encoder.hpp | 12 +- .../bindings/cpp/include/proton/endpoint.hpp | 55 ++-- .../bindings/cpp/include/proton/error.hpp | 54 +++- .../bindings/cpp/include/proton/event.hpp | 40 ++- .../bindings/cpp/include/proton/export.hpp | 6 +- .../bindings/cpp/include/proton/handler.hpp | 82 ++++- proton-c/bindings/cpp/include/proton/io.hpp | 52 ++-- proton-c/bindings/cpp/include/proton/link.hpp | 87 ++++-- .../cpp/include/proton/link_options.hpp | 137 ++++++--- .../bindings/cpp/include/proton/message.hpp | 283 ++++++++++-------- .../cpp/include/proton/message_id.hpp | 41 ++- .../bindings/cpp/include/proton/object.hpp | 25 +- .../cpp/include/proton/pn_unique_ptr.hpp | 24 +- .../bindings/cpp/include/proton/reactor.hpp | 7 + .../bindings/cpp/include/proton/receiver.hpp | 10 +- .../cpp/include/proton/reconnect_timer.hpp | 8 +- proton-c/bindings/cpp/include/proton/sasl.hpp | 35 ++- .../bindings/cpp/include/proton/scalar.hpp | 82 +++-- .../bindings/cpp/include/proton/sender.hpp | 20 +- .../bindings/cpp/include/proton/session.hpp | 69 +++-- proton-c/bindings/cpp/include/proton/ssl.hpp | 106 +++++-- proton-c/bindings/cpp/include/proton/task.hpp | 12 +- .../bindings/cpp/include/proton/terminus.hpp | 69 ++++- .../bindings/cpp/include/proton/transport.hpp | 27 +- .../cpp/include/proton/type_traits.hpp | 20 +- .../bindings/cpp/include/proton/types.hpp | 126 ++++---- proton-c/bindings/cpp/include/proton/url.hpp | 136 +++++---- .../bindings/cpp/include/proton/value.hpp | 91 ++++-- proton-c/include/proton/ssl.h | 8 +- 60 files changed, 1974 insertions(+), 1074 deletions(-) diff --git a/examples/cpp/README.hpp b/examples/cpp/README.hpp index de65d6e94d..c03982b98d 100644 --- a/examples/cpp/README.hpp +++ b/examples/cpp/README.hpp @@ -1,35 +1,34 @@ // Examples overview. // // For a better overview, see the tutorial in the generated documentation. +// // In your build directory do: +// // make docs-cpp -// then open proton-c/bindings/cpp/docs/html/tutorial.html in your browser. // +// then open proton-c/bindings/cpp/docs/html/tutorial.html in your browser. // DEVELOPER NOTE: if you are adding or modifying examples you should keep this // file and ../proton-c/bindings/cpp/docs/tutorial.hpp up to date. -/** \example helloworld.cpp +/** @example helloworld.cpp -Basic example that connects to an intermediary on 127.0.0.1:5672, -establishes a subscription from the 'examples' nodeu on that -intermediary, then creates a sending link to the same node and sends -one message. On receving the message back via the subcription, the -connection is closed. +Connects to a broker on 127.0.0.1:5672, establishes a subscription +from the 'examples' node, and creates a sending link to the same +node. Sends one message and receives it back. */ -/** \example helloworld_direct.cpp +/** @example helloworld_direct.cpp -A variant of the basic helloworld example, that does not use an -intermediary, but listens for incoming connections itself. It -establishes a connection to itself with a link over which a single -message is sent. This demonstrates the ease with which a simple daemon -can be built using the API. +Variation of helloworld that does not use a broker, but listens for +incoming connections itself. It establishes a connection to itself +with a link over which a single message is sent. This demonstrates the +ease with which a simple daemon an be built using the API. */ -/** \example simple_send.cpp +/** @example simple_send.cpp An example of sending a fixed number of messages and tracking their (asynchronous) acknowledgement. Messages are sent through the 'examples' node on @@ -37,14 +36,14 @@ an intermediary accessible on 127.0.0.1:5672. */ -/** \example simple_recv.cpp +/** @example simple_recv.cpp Subscribes to the 'examples' node on an intermediary accessible on 127.0.0.1:5672. Simply prints out the body of received messages. */ -/** \example direct_send.cpp +/** @example direct_send.cpp Accepts an incoming connection and then sends like `simple_send`. You can connect directly to `direct_send` *without* a broker using \ref simple_recv.cpp. @@ -52,7 +51,7 @@ Make sure to stop the broker first or use a different port for `direct_send`. */ -/** \example direct_recv.cpp +/** @example direct_recv.cpp Accepts an incoming connection and then receives like `simple_recv`. You can connect directly to `direct_recv` *without* a broker using \ref simple_send.cpp. @@ -60,13 +59,16 @@ Make sure to stop the broker first or use a different port for `direct_recv`. */ -/** \example encode_decode.cpp +/// @cond INTERNAL +/// XXX change namespaces +/** @example encode_decode.cpp Shows how C++ data types can be converted to and from AMQP types. */ +/// @endcond -/** \example client.cpp +/** @example client.cpp The client part of a request-response example. Sends requests and prints out responses. Requires an intermediary that supports the AMQP @@ -75,7 +77,7 @@ are sent through the 'examples' node. */ -/** \example server.cpp +/** @example server.cpp The server part of a request-response example, that receives requests via the examples node, converts the body to uppercase and sends the @@ -83,9 +85,9 @@ result back to the indicated reply address. */ -/** \example server_direct.cpp +/** @example server_direct.cpp -A variant of the server part of a request-response example, that +A variant of the server part of a request-response example that accepts incoming connections and does not need an intermediary. Much like the original server, it receives incoming requests, converts the body to uppercase and sends the result back to the indicated reply @@ -94,23 +96,98 @@ alternatives. */ -/** \example broker.hpp +/** @example broker.hpp Common logic for a simple "mini broker" that creates creates queues automatically when a client tries to send or subscribe. This file contains the `queue` class that queues messages and the `broker_handler` class that manages queues and links and transfers messages to/from clients. -There are several broker programs all using the same logic but illustrating -different ways to run a server application. +Examples \ref broker.cpp and \ref engine/broker.cpp use this same +broker logic but show different ways to run it in a server application. + +*/ + +/** @example broker.cpp + +A simple, single-threaded broker using the `proton::container`. You can use this +to run other examples that reqiure an intermediary, or you can use any AMQP 1.0 +broker. This broker creates queues automatically when a client tries to send or +subscribe. + +Uses the broker logic from \ref broker.hpp, the same logic as the +`proton::connection_engine` broker example \ref engine/broker.cpp. + +*/ + +//////////////// connection_engine examples. + +/** \example engine/helloworld.cpp + +`proton::connection_engine` example to send a "Hello World" message to +itself. Compare with the corresponding `proton::container` example \ref +helloworld.cpp. + +*/ + +/** \example engine/simple_send.cpp + +`proton::connection_engine` example of sending a fixed number of messages and +tracking their (asynchronous) acknowledgement. Messages are sent through the +'examples' node on an intermediary accessible on 127.0.0.1:5672. */ -/** \example broker.cpp +/** \example engine/simple_recv.cpp + +`proton::connection_engine` example that subscribes to the 'examples' node and prints + the body of received messages. + +*/ + +/** \example engine/direct_send.cpp + +`proton::connection_engine` example accepts an incoming connection and then +sends like `simple_send`. You can connect directly to `direct_send` *without* a +broker using \ref simple_recv.cpp. Make sure to stop the broker first or use a +different port for `direct_send`. + +*/ + +/** \example engine/direct_recv.cpp + +`proton::connection_engine` example accepts an incoming connection and then +receives like `simple_recv`. You can connect directly to `direct_recv` +*without* a broker using \ref simple_send.cpp. Make sure to stop the broker +first or use a different port for `direct_recv`. + +*/ + +/** \example engine/client.cpp + +`proton::connection_engine` client for request-response example. Sends requests and +prints out responses. Requires an intermediary that supports the AMQP 1.0 +dynamic nodes on which the responses are received. The requests are sent through +the 'examples' node. + +*/ + +/** \example engine/server.cpp + +`proton::connection_engine` server for request-response example, that receives +requests via the examples node, converts the body to uppercase and sends the +result back to the indicated reply address. + +*/ + +/** \example engine/broker.cpp A simple, single-threaded broker using the `proton::container`. You can use this to run other examples that reqiure an intermediary, or you can use any AMQP 1.0 broker. This broker creates queues automatically when a client tries to send or subscribe. +Uses the broker logic from \ref broker.hpp, the same logic as the +proton::container` broker example \ref broker.cpp. + */ diff --git a/examples/cpp/broker.cpp b/examples/cpp/broker.cpp index 097a612330..48efa932f0 100644 --- a/examples/cpp/broker.cpp +++ b/examples/cpp/broker.cpp @@ -39,7 +39,6 @@ class broker { proton::handler& handler() { return handler_; } private: - class my_handler : public broker_handler { public: my_handler(const proton::url& u, queues& qs) : broker_handler(qs), url_(u) {} @@ -59,19 +58,23 @@ class broker { }; int main(int argc, char **argv) { - // Command line options proton::url url("0.0.0.0"); options opts(argc, argv); + opts.add_value(url, 'a', "address", "listen on URL", "URL"); + try { opts.parse(); + broker b(url); proton::container(b.handler()).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/broker.hpp b/examples/cpp/broker.hpp index 1c13ae4750..c7fd0df691 100644 --- a/examples/cpp/broker.hpp +++ b/examples/cpp/broker.hpp @@ -1,5 +1,6 @@ #ifndef BROKER_HPP #define BROKER_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,13 +20,12 @@ * under the License. */ -/**@file - * - * Common code used by different broker examples. - * - * The examples add functionality as needed, this helps to make it easier to see - * the important differences between the examples. - */ +/// @file +/// +/// Common code used by different broker examples. +/// +/// The examples add functionality as needed, this helps to make it +/// easier to see the important differences between the examples. #include "proton/event.hpp" #include "proton/message.hpp" @@ -39,7 +39,7 @@ #include #include -/** A simple implementation of a queue. */ +/// A simple implementation of a queue. class queue { public: queue(const std::string &name, bool dynamic = false) : name_(name), dynamic_(dynamic) {} @@ -66,26 +66,34 @@ class queue { } bool deliver_to(proton::sender *s) { - // deliver to single sender if supplied, else all consumers + // Deliver to single sender if supplied, else all consumers int count = s ? 1 : consumers_.size(); + if (!count) return false; + bool result = false; sender_list::iterator it = consumers_.begin(); - if (!s && count) - s = &*it; + if (!s && count) { + s = &*it; + } + while (messages_.size()) { if (s->credit()) { const proton::message& m = messages_.front(); + s->send(m); messages_.pop_front(); result = true; } - if (--count) + + if (--count) { it++; - else + } else { return result; + } } + return false; } @@ -99,17 +107,21 @@ class queue { sender_list consumers_; }; -/** A collection of queues and queue factory, used by a broker */ +/// A collection of queues and queue factory, used by a broker. class queues { public: queues() : next_id_(0) {} // Get or create a queue. virtual queue &get(const std::string &address = std::string()) { - if (address.empty()) + if (address.empty()) { throw std::runtime_error("empty queue name"); + } + queue*& q = queues_[address]; + if (!q) q = new queue(address); + return *q; } @@ -118,6 +130,7 @@ class queues { std::ostringstream os; os << "q" << next_id_++; queue *q = queues_[os.str()] = new queue(os.str(), true); + return *q; } @@ -130,7 +143,7 @@ class queues { protected: typedef std::map queue_map; queue_map queues_; - uint64_t next_id_; // Use to generate unique queue IDs. + uint64_t next_id_; // Use to generate unique queue IDs. }; @@ -141,15 +154,17 @@ class broker_handler : public proton::handler { void on_link_open(proton::event &e) { proton::link lnk = e.link(); + if (!!lnk.sender()) { proton::terminus remote_source(lnk.remote_source()); queue &q = remote_source.dynamic() ? queues_.dynamic() : queues_.get(remote_source.address()); lnk.local_source().address(q.name()); + q.subscribe(lnk.sender()); std::cout << "broker outgoing link from " << q.name() << std::endl; - } - else { // Receiver + } else { + // Receiver std::string address = lnk.remote_target().address(); if (!address.empty()) { lnk.local_target().address(address); @@ -158,16 +173,20 @@ class broker_handler : public proton::handler { } } - void unsubscribe (proton::sender lnk) { + void unsubscribe(proton::sender lnk) { std::string address = lnk.local_source().address(); - if (queues_.get(address).unsubscribe(lnk)) + + if (queues_.get(address).unsubscribe(lnk)) { queues_.erase(address); + } } void on_link_close(proton::event &e) { proton::link lnk = e.link(); - if (!!lnk.sender()) + + if (!!lnk.sender()) { unsubscribe(lnk.sender()); + } } void on_connection_close(proton::event &e) { @@ -179,10 +198,12 @@ class broker_handler : public proton::handler { } void remove_stale_consumers(proton::connection connection) { - proton::link_range r = connection.find_links(proton::endpoint::REMOTE_ACTIVE); + proton::link_range r = connection.find_links(proton::endpoint::REMOTE_ACTIVE); + for (proton::link_iterator l = r.begin(); l != r.end(); ++l) { - if (!!l->sender()) + if (!!l->sender()) { unsubscribe(l->sender()); + } } } @@ -190,11 +211,13 @@ class broker_handler : public proton::handler { proton::link lnk = e.link(); std::string address = lnk.local_source().address(); proton::sender s = lnk.sender(); + queues_.get(address).dispatch(&s); } void on_message(proton::event &e) { std::string address = e.link().local_target().address(); + queues_.get(address).publish(e.message(), e.link().receiver()); } @@ -202,5 +225,4 @@ class broker_handler : public proton::handler { queues& queues_; }; - #endif // BROKER_HPP diff --git a/examples/cpp/client.cpp b/examples/cpp/client.cpp index 60eb13b88d..43ccb3c201 100644 --- a/examples/cpp/client.cpp +++ b/examples/cpp/client.cpp @@ -48,19 +48,24 @@ class client : public proton::handler { proton::message req; req.body(requests.front()); req.reply_to(receiver.remote_source().address()); + sender.send(req); } void on_link_open(proton::event &e) { - if (e.link() == receiver) + if (e.link() == receiver) { send_request(); + } } void on_message(proton::event &e) { if (requests.empty()) return; // Spurious extra message! + proton::message& response = e.message(); + std::cout << requests.front() << " => " << response.body() << std::endl; requests.erase(requests.begin()); + if (!requests.empty()) { send_request(); } else { @@ -70,9 +75,9 @@ class client : public proton::handler { }; int main(int argc, char **argv) { - // Command line options proton::url url("127.0.0.1:5672/examples"); options opts(argc, argv); + opts.add_value(url, 'a', "address", "connect and send to URL", "URL"); try { @@ -93,5 +98,6 @@ int main(int argc, char **argv) { } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/direct_recv.cpp b/examples/cpp/direct_recv.cpp index 56fa1e28a0..ffb2f03cf4 100644 --- a/examples/cpp/direct_recv.cpp +++ b/examples/cpp/direct_recv.cpp @@ -49,37 +49,45 @@ class direct_recv : public proton::handler { void on_message(proton::event &e) { proton::message& msg = e.message(); - if (msg.id().get() < received) - return; // ignore duplicate + + if (msg.id().get() < received) { + return; // Ignore duplicate + } + if (expected == 0 || received < expected) { std::cout << msg.body() << std::endl; received++; } + if (received == expected) { e.receiver().close(); e.connection().close(); + if (!!acceptor) acceptor.close(); } } }; int main(int argc, char **argv) { - // Command line options std::string address("127.0.0.1:5672/examples"); int message_count = 100; options opts(argc, argv); + opts.add_value(address, 'a', "address", "listen and receive on URL", "URL"); opts.add_value(message_count, 'm', "messages", "receive COUNT messages", "COUNT"); + try { opts.parse(); + direct_recv recv(address, message_count); proton::container(recv).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } - diff --git a/examples/cpp/direct_send.cpp b/examples/cpp/direct_send.cpp index d171175d8a..edd71028aa 100644 --- a/examples/cpp/direct_send.cpp +++ b/examples/cpp/direct_send.cpp @@ -38,8 +38,8 @@ class simple_send : public proton::handler { int confirmed; int total; proton::acceptor acceptor; - public: + public: simple_send(const std::string &s, int c) : url(s), sent(0), confirmed(0), total(c) {} void on_start(proton::event &e) { @@ -49,12 +49,15 @@ class simple_send : public proton::handler { void on_sendable(proton::event &e) { proton::sender sender = e.sender(); + while (sender.credit() && sent < total) { proton::message msg; - msg.id(sent + 1); std::map m; - m["sequence"] = sent+1; + m["sequence"] = sent + 1; + + msg.id(sent + 1); msg.body(m); + sender.send(msg); sent++; } @@ -62,8 +65,10 @@ class simple_send : public proton::handler { void on_delivery_accept(proton::event &e) { confirmed++; + if (confirmed == total) { std::cout << "all messages confirmed" << std::endl; + e.connection().close(); acceptor.close(); } @@ -75,21 +80,25 @@ class simple_send : public proton::handler { }; int main(int argc, char **argv) { - // Command line options std::string address("127.0.0.1:5672/examples"); int message_count = 100; options opts(argc, argv); + opts.add_value(address, 'a', "address", "listen and send on URL", "URL"); opts.add_value(message_count, 'm', "messages", "send COUNT messages", "COUNT"); + try { opts.parse(); + simple_send send(address, message_count); proton::container(send).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/engine/helloworld.cpp b/examples/cpp/engine/helloworld.cpp index 72be78eae7..4440e4d6ae 100644 --- a/examples/cpp/engine/helloworld.cpp +++ b/examples/cpp/engine/helloworld.cpp @@ -31,7 +31,6 @@ class hello_world : public proton::handler { std::string address_; public: - hello_world(const std::string& address) : address_(address) {} void on_start(proton::event &e) { @@ -55,11 +54,14 @@ class hello_world : public proton::handler { int main(int argc, char **argv) { try { proton::url url(argc > 1 ? argv[1] : "127.0.0.1:5672/examples"); + hello_world hw(url.path()); proton::io::socket_engine(url, hw).run(); + return 0; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/helloworld.cpp b/examples/cpp/helloworld.cpp index b8f8b61353..a969f27bad 100644 --- a/examples/cpp/helloworld.cpp +++ b/examples/cpp/helloworld.cpp @@ -31,7 +31,6 @@ class hello_world : public proton::handler { proton::url url; public: - hello_world(const proton::url& u) : url(u) {} void on_start(proton::event &e) { @@ -55,11 +54,14 @@ class hello_world : public proton::handler { int main(int argc, char **argv) { try { std::string url = argc > 1 ? argv[1] : "127.0.0.1:5672/examples"; + hello_world hw(url); proton::container(hw).run(); + return 0; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/helloworld_direct.cpp b/examples/cpp/helloworld_direct.cpp index 8b4af5ba54..05ae8a2769 100644 --- a/examples/cpp/helloworld_direct.cpp +++ b/examples/cpp/helloworld_direct.cpp @@ -30,8 +30,8 @@ class hello_world_direct : public proton::handler { private: proton::url url; proton::acceptor acceptor; - public: + public: hello_world_direct(const proton::url& u) : url(u) {} void on_start(proton::event &e) { @@ -60,14 +60,17 @@ class hello_world_direct : public proton::handler { int main(int argc, char **argv) { try { - // Pick an "unusual" port since we are going to be talking to ourselves, not a broker. + // Pick an "unusual" port since we are going to be talking to + // ourselves, not a broker. std::string url = argc > 1 ? argv[1] : "127.0.0.1:8888/examples"; hello_world_direct hwd(url); proton::container(hwd).run(); + return 0; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/queue_browser.cpp b/examples/cpp/queue_browser.cpp index 015e6adac9..02c0b30eda 100644 --- a/examples/cpp/queue_browser.cpp +++ b/examples/cpp/queue_browser.cpp @@ -32,7 +32,6 @@ class browser : public proton::handler { proton::url url; public: - browser(const proton::url& u) : url(u) {} void on_start(proton::event &e) { @@ -42,19 +41,24 @@ class browser : public proton::handler { void on_message(proton::event &e) { std::cout << e.message().body() << std::endl; - if (e.receiver().queued() == 0 && e.receiver().drained() > 0) + + if (e.receiver().queued() == 0 && e.receiver().drained() > 0) { e.connection().close(); + } } }; int main(int argc, char **argv) { try { std::string url = argc > 1 ? argv[1] : "127.0.0.1:5672/examples"; + browser b(url); proton::container(b).run(); + return 0; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/selected_recv.cpp b/examples/cpp/selected_recv.cpp index ad010c07c5..a07d9a51ab 100644 --- a/examples/cpp/selected_recv.cpp +++ b/examples/cpp/selected_recv.cpp @@ -32,7 +32,6 @@ class selected_recv : public proton::handler { proton::url url; public: - selected_recv(const proton::url& u) : url(u) {} void on_start(proton::event &e) { @@ -48,11 +47,14 @@ class selected_recv : public proton::handler { int main(int argc, char **argv) { try { std::string url = argc > 1 ? argv[1] : "127.0.0.1:5672/examples"; + selected_recv recv(url); proton::container(recv).run(); + return 0; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/server.cpp b/examples/cpp/server.cpp index 7711f0e9d6..d913ee147d 100644 --- a/examples/cpp/server.cpp +++ b/examples/cpp/server.cpp @@ -40,49 +40,60 @@ class server : public proton::handler { sender_map senders; public: - server(const std::string &u) : url(u) {} void on_start(proton::event &e) { connection = e.container().connect(url); connection.open_receiver(url.path()); + std::cout << "server connected to " << url << std::endl; } std::string to_upper(const std::string &s) { std::string uc(s); size_t l = uc.size(); + for (size_t i=0; i())); reply.correlation_id(e.message().correlation_id()); - if (!senders[reply_to]) + + if (!senders[reply_to]) { senders[reply_to] = connection.open_sender(reply_to); + } + senders[reply_to].send(reply); } }; int main(int argc, char **argv) { - // Command line options std::string address("amqp://0.0.0.0:5672/examples"); options opts(argc, argv); + opts.add_value(address, 'a', "address", "listen on URL", "URL"); + try { opts.parse(); + server srv(address); proton::container(srv).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/server_direct.cpp b/examples/cpp/server_direct.cpp index abc49c0a46..9d3b79c953 100644 --- a/examples/cpp/server_direct.cpp +++ b/examples/cpp/server_direct.cpp @@ -41,7 +41,6 @@ class server : public proton::handler { int address_counter; public: - server(const std::string &u) : url(u), address_counter(0) {} void on_start(proton::event &e) { @@ -52,18 +51,22 @@ class server : public proton::handler { std::string to_upper(const std::string &s) { std::string uc(s); size_t l = uc.size(); + for (size_t i=0; isecond; proton::message reply; + reply.address(reply_to); reply.body(to_upper(e.message().body().get())); reply.correlation_id(e.message().correlation_id()); + sender.send(reply); } } }; int main(int argc, char **argv) { - // Command line options std::string address("amqp://127.0.0.1:5672/examples"); options opts(argc, argv); + opts.add_value(address, 'a', "address", "listen on URL", "URL"); + try { opts.parse(); + server srv(address); proton::container(srv).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/simple_recv.cpp b/examples/cpp/simple_recv.cpp index c3df4770d3..22d603efdc 100644 --- a/examples/cpp/simple_recv.cpp +++ b/examples/cpp/simple_recv.cpp @@ -31,16 +31,14 @@ #include #include - - class simple_recv : public proton::handler { private: proton::url url; proton::receiver receiver; uint64_t expected; uint64_t received; - public: + public: simple_recv(const std::string &s, int c) : url(s), expected(c), received(0) {} void on_start(proton::event &e) { @@ -50,11 +48,15 @@ class simple_recv : public proton::handler { void on_message(proton::event &e) { proton::message& msg = e.message(); - if (msg.id().get() < received) - return; // ignore duplicate + + if (msg.id().get() < received) { + return; // Ignore duplicate + } + if (expected == 0 || received < expected) { std::cout << msg.body() << std::endl; received++; + if (received == expected) { e.receiver().close(); e.connection().close(); @@ -64,22 +66,26 @@ class simple_recv : public proton::handler { }; int main(int argc, char **argv) { - // Command line options std::string address("127.0.0.1:5672/examples"); + int message_count = 100; options opts(argc, argv); + opts.add_value(address, 'a', "address", "connect to and receive from URL", "URL"); opts.add_value(message_count, 'm', "messages", "receive COUNT messages", "COUNT"); try { opts.parse(); + simple_recv recv(address, message_count); proton::container(recv).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/examples/cpp/simple_send.cpp b/examples/cpp/simple_send.cpp index cfec153a9e..8598fe0e7b 100644 --- a/examples/cpp/simple_send.cpp +++ b/examples/cpp/simple_send.cpp @@ -37,8 +37,8 @@ class simple_send : public proton::handler { int sent; int confirmed; int total; - public: + public: simple_send(const std::string &s, int c) : url(s), sent(0), confirmed(0), total(c) {} void on_start(proton::event &e) { @@ -47,12 +47,15 @@ class simple_send : public proton::handler { void on_sendable(proton::event &e) { proton::sender sender = e.sender(); + while (sender.credit() && sent < total) { proton::message msg; - msg.id(sent + 1); std::map m; - m["sequence"] = sent+1; + m["sequence"] = sent + 1; + + msg.id(sent + 1); msg.body(m); + sender.send(msg); sent++; } @@ -60,6 +63,7 @@ class simple_send : public proton::handler { void on_delivery_accept(proton::event &e) { confirmed++; + if (confirmed == total) { std::cout << "all messages confirmed" << std::endl; e.connection().close(); @@ -72,21 +76,25 @@ class simple_send : public proton::handler { }; int main(int argc, char **argv) { - // Command line options std::string address("127.0.0.1:5672/examples"); int message_count = 100; options opts(argc, argv); + opts.add_value(address, 'a', "address", "connect and send to URL", "URL"); opts.add_value(message_count, 'm', "messages", "send COUNT messages", "COUNT"); + try { opts.parse(); + simple_send send(address, message_count); proton::container(send).run(); + return 0; } catch (const bad_option& e) { std::cout << opts << std::endl << e.what() << std::endl; } catch (const std::exception& e) { std::cerr << e.what() << std::endl; } + return 1; } diff --git a/proton-c/CMakeLists.txt b/proton-c/CMakeLists.txt index 9d973485b3..c3f92947f1 100644 --- a/proton-c/CMakeLists.txt +++ b/proton-c/CMakeLists.txt @@ -43,6 +43,7 @@ else() set (OPTIONAL_ARG OPTIONAL) add_custom_target(docs) endif() +add_custom_target(doc DEPENDS docs) # Set the default SSL/TLS implementation find_package(OpenSSL) diff --git a/proton-c/bindings/cpp/docs/mainpage.md b/proton-c/bindings/cpp/docs/mainpage.md index 3f7e35cb88..f20d9573f2 100644 --- a/proton-c/bindings/cpp/docs/mainpage.md +++ b/proton-c/bindings/cpp/docs/mainpage.md @@ -1,112 +1,136 @@ -Introduction {#mainpage} -============ +# Introduction {#mainpage} -This is the C++ API for the proton AMQP protocol engine. It allows you to write -client and server applications that send and receive AMQP messages. +This is the C++ API for the Proton AMQP protocol engine. It allows you +to write client and server applications that send and receive AMQP +messages. The best way to start is with the \ref tutorial "tutorial". -An overview of the model ------------------------- - -Messages are transferred between connected peers over 'links'. At the sending -peer the link is called a sender. At the receiving peer it is called a -receiver. Messages are sent by senders and received by receivers. Links may have -named 'source' and 'target' addresses (see "sources and targets" below.) - -Links are established over sessions. Sessions are established over -connections. Connections are (generally) established between two uniquely -identified containers. Though a connection can have multiple sessions, often -this is not needed. The container API allows you to ignore sessions unless you -actually require them. - -The sending of a message over a link is called a delivery. The message -is the content sent, including all meta-data such as headers and -annotations. The delivery is the protocol exchange associated with the -transfer of that content. - -To indicate that a delivery is complete, either the sender or the -receiver 'settles' it. When the other side learns that it has been -settled, they will no longer communicate about that delivery. The -receiver can also indicate whether they accept or reject the -message. - -Three different delivery levels or 'guarantees' can be achieved: at-most-once, -at-least-once or exactly-once. See below for details. - -### Sources and targets ### - -Every link has two addresses, *source* and *target*. The most common pattern for -using these addresses is as follows: - -When a client creates a *receiver* link, it sets the *source* address. This -means "I want to receive messages from this source." This is often referred to -as "subscribing" to the source. When a client creates a *sender* link, it sets -the *target* address. This means "I want to send to this target." - -In the case of a broker, the source or target usually refers to a queue or -topic. In general they can refer to any AMQP-capable node. - -In the *request-response* pattern, a request message carries a *reply-to* -address for the response message. This can be any AMQP address, but it is often -useful to create a temporary address for just the response message. - -The most common approach is for the client to create a *receiver* for the -response with the *dynamic* flag set. This asks the server to generate a unique -*source* address automatically and discard it when the link closes. The client -uses this "dynamic" source address as the reply-to when it sends the request, -and the response is delivered to the client's dynamic receiver. - -In the case of a broker a dynamic address usually corresponds to a temporary -queue but any AMQP request-response server can use this technique. The \ref -server_direct.cpp example illustrates how to implement a queueless -request-response server. - -Commonly used classes ---------------------- - -A brief summary of some of the key classes follows. - -The `proton::container` class is the main entry point into the API, allowing -connections and links to be established. Applications are structured as one or -more event handlers. - -The easiest way to implement a handler is to define a subclass of -`proton::messaging_handler` and over-ride the event handling member functions -that interest you. - -To send messages, call `proton::container::create_sender()` to create a -`proton::sender` and then call `proton::sender::send()`. This is typically done -when the sender is *sendable*, a condition indicated by the -`proton::messaging_handler::on_sendable()` event, to avoid execessive build up -of messages. - -To receive messages, call `proton::container::create_receiver()` to create a -`proton::receiver`. When messages are recieved the -`proton::messaging_handler::on_message()` event handler function will be called. - -Other key classes: - -- proton::message represents an AMQP message, which has a body, headers and other properties. -- proton::connection represents a connection to a remote AMQP endpoint. -- proton::delivery holds the delivery status of a message. -- proton::event carries details of an event. - -The library provides intuitive default conversions between AMQP and C++ types -for message data q, but also allows detailed examination and construction of -complex AMQP types. For details on converting between AMQP and C++ data types -see the \ref encode_decode.cpp example and classes `proton::encoder`, -`proton::decoder` and `proton::value`. - -`proton::connection_engine` provides fewer facilities that `proton::container` -but makes fewer (no) assumptions about application threading and IO. It may be -easier to integrate with an existing IO framework, for multi-threaded -applications or for non-socket IO. See the \ref select_broker.cpp example. The -main application and AMQP logic is implemented the same way using the `connection_engine` or -the container. - -Delivery Guarantees -------------------- +## An overview of the AMQP model + +Messages are transferred between connected peers over *links*. The +sending end of a link is a `proton::sender`, and the receiving end is +a `proton::receiver`. Links have named 'source' and 'target' +addresses. See "Sources and Targets" below for more information. + +Links are grouped in a `proton::session`. Messages for links in the +same session are sent sequentially. Messages on different sessions +can be interleaved, so a large message being sent on one session does +not block messages being sent on other sessions. + +Sessions are created over a `proton::connection`, which represents the +network connection. You can create links directly on a connection +using its default session if you don't need multiple sessions. + +`proton::message` represents the message: the body (content), headers, +annotations, and so on. A `proton::delivery` represents the act of +transferring a message over a link. The receiver acknowledges the +delivery by accepting or rejecting it. The delivery is *settled* when +both ends are done with it. Different settlement methods give +different levels of reliability: *at-most-once*, *at-least-once*, and +*exactly-once*. See "Delivery Guarantees" below for details. + +## Sources and targets + +Every link has two addresses, *source* and *target*. The most common +pattern for using these addresses is as follows: + +When a client creates a *receiver* link, it sets the *source* +address. This means "I want to receive messages from this source." +This is often referred to as "subscribing" to the source. When a +client creates a *sender* link, it sets the *target* address. This +means "I want to send to this target." + +In the case of a broker, the source or target usually refers to a +queue or topic. In general they can refer to any AMQP-capable node. + +In the *request-response* pattern, a request message carries a +*reply-to* address for the response message. This can be any AMQP +address, but it is often useful to create a temporary address for just +the response message. + +The most common approach is for the client to create a *receiver* for +the response with the *dynamic* flag set. This asks the server to +generate a unique *source* address automatically and discard it when +the link closes. The client uses this "dynamic" source address as the +reply-to when it sends the request, and the response is delivered to +the client's dynamic receiver. + +In the case of a broker, a dynamic address usually corresponds to a +temporary queue, but any AMQP request-response server can use this +technique. The \ref server_direct.cpp example illustrates how to +implement a queueless request-response server. + +## Anatomy of a Proton application + +To send AMQP commands, call methods on classes like +`proton::connection`, `proton::sender`, `proton::receiver`, or +`proton::delivery`. To handle incoming commands, implement the +`proton::handler` interface. The handler receives calls like +`on_message` (a message is received), `on_link_open` (a link is +opened), and `on_sendable` (a link is ready to send messages). + +Messages are represented by `proton::message`. AMQP defines a type +encoding that you can use for interoperability, but you can also use +any encoding you wish and pass binary data as the +`proton::message::body`. `proton::value` and `proton::scalar` provide +conversion between AMQP and C++ data types. + + + +There are two alternative ways to manage handlers and AMQP objects, +the `proton::container` and the `proton::connection_engine`. You can +code your application so that it can be run with either. Say you find +the `proton::container` easier to get started but later need more +flexibility. You can switch to the `proton::connection_engine` with +little or no change to your handlers. + +### %proton::container + +`proton::container` is a *reactor* framework that manages multiple +connections and dispatches events to handlers. You implement +`proton::handler` with your logic to react to events, and register it +with the container. The container lets you open multiple connections +and links, receive incoming connections and links, and send, receive, +and acknowledge messages. + +The reactor handles IO for multiple connections using sockets and +`poll`. It dispatches events to your handlers in a single thread, +where you call `proton::container::run`. The container is not +thread-safe: once it is running you can only operate on Proton objects +from your handler methods. + +### %proton::connection_engine + +`proton::connection_engine` dispatches events for a *single +connection*. The subclass `proton::io::socket_engine` does +socket-based IO. An application with a single connection is just like +using `proton::container` except you attach your handler to a +`proton::io::socket_engine` instead. You can compare examples, such as +\ref helloworld.cpp and \ref engine/helloworld.cpp. + +Now consider multiple connections. `proton::container` is easy to use +but restricted to a single thread. `proton::connection_engine` is not +thread-safe either, but *each engine is independent*. You can process +different connections in different threads, or use a thread pool to +process a dynamic set of connections. + +The engine does not provide built-in polling and listening like the +`proton::container`, but you can drive engines using any polling or +threading strategy and any IO library (for example, epoll, kqueue, +solaris completion ports, IOCP proactor, boost::asio, libevent, etc.) +This can be important for optimizing performance or supporting diverse +platforms. The example \ref engine/broker.cpp shows a broker using +sockets and poll, but you can see how the code could be adapted. + +`proton::connection_engine` also does not dictate the IO mechanism, +but it is an abstract class. `proton::socket_engine` provides +ready-made socket-based IO, but you can write your own subclass with +any IO code. Just override the `io_read`, `io_write` and `io_close` +methods. For example, the proton test suite implements an in-memory +connection using `std::deque` for test purposes. + +## Delivery guarantees For *at-most-once*, the sender settles the message as soon as it sends it. If the connection is lost before the message is received by the diff --git a/proton-c/bindings/cpp/docs/tutorial.hpp b/proton-c/bindings/cpp/docs/tutorial.hpp index 81ca7c95a2..dcfbe057d1 100644 --- a/proton-c/bindings/cpp/docs/tutorial.hpp +++ b/proton-c/bindings/cpp/docs/tutorial.hpp @@ -3,7 +3,7 @@ // that shows messed-up line numbers in \skip \until code extracts so this file // is markdown wrapped in a C++ comment - which works. -/*! \page tutorial Tutorial +/**\page tutorial Tutorial This is a brief tutorial that will walk you through the fundamentals of building messaging applications in incremental steps. There are further examples, in @@ -28,6 +28,10 @@ It usually defaults to `127.0.0.1:5672/examples`, but you can change this if your broker is on a different host or port, or you want to use a different queue or topic name (the ADDRESS part of the URL). URL details are at `proton::url` +The first part of the tutorial uses the `proton::container`, later we will +show some of the same examples implemented using the `proton::connection_engine`. +Most of the code is the same for either approach. + Hello World! ------------ @@ -39,14 +43,14 @@ receiving. In a realistic system the sender and receiver would normally be in different processes. The complete example is \ref helloworld.cpp We will include the following classes: `proton::container` runs an event loop -which dispatches events to a `proton::messaging_handler`. This allows a *reactive* +which dispatches events to a `proton::handler`. This allows a *reactive* style of programming which is well suited to messaging applications. `proton::url` is a simple parser for the URL format mentioned above. \skip proton/container \until proton/url We will define a class `hello_world` which is a subclass of -`proton::messaging_handler` and over-rides functions to handle the events +`proton::handler` and over-rides functions to handle the events of interest in sending and receiving a message. \skip class hello_world @@ -121,18 +125,18 @@ as before. However we also handle two new events. We now close the connection from the senders side once the message has been accepted. The acceptance of the message is an indication of successful transfer to the -peer. We are notified of that event through the `on_accepted()` +peer. We are notified of that event through the `on_delivery_accept()` callback. -\skip on_accepted +\skip on_delivery_accept \until } Then, once the connection has been closed, of which we are -notified through the `on_closed()` callback, we stop accepting incoming +notified through the `on_connection_close()` callback, we stop accepting incoming connections at which point there is no work to be done and the event loop exits, and the run() method will return. -\skip on_closed +\skip on_connection_close \until } So now we have our example working without a broker involved! @@ -193,7 +197,7 @@ to track the confirmation of the messages we have sent. We only close the connection and exit when the receiver has received all the messages we wanted to send. -\skip on_accepted +\skip on_delivery_accept \until } \until } @@ -209,7 +213,7 @@ library will automatically try to reconnect for us, and when our sender is sendable again, we can restart from the point we know the receiver got to. -\skip on_disconnected +\skip on_disconnect \until } \dontinclude simple_recv.cpp @@ -283,7 +287,7 @@ link, we listen for incoming connections. When we have received confirmation of all the messages we sent, we can close the acceptor in order to exit. -\skip on_accepted +\skip on_delivery_accept \until } \until } @@ -340,11 +344,11 @@ reply_to address to be the dynamically assigned address of our receiver. We need to use the address assigned by the broker as the `reply_to` address of our requests, so we can't send them until our receiver has been set up. To do -that, we add an `on_link_opened()` method to our handler class, and if the link +that, we add an `on_link_open()` method to our handler class, and if the link associated with event is the receiver, we use that as the trigger to send our first request. -\skip on_link_opened +\skip on_link_open \until } When we receive a reply, we send the next request. @@ -374,7 +378,7 @@ Next we need to handle incoming requests for links with dynamic addresses from the client. We give the link a unique address and record it in our `senders` map. -\skip on_link_opening +\skip on_link_open \until } Note we are interested in *sender* links above because we are implementing the @@ -388,21 +392,37 @@ Finally when we receive a message we look up its `reply_to` in our senders map a \until } \until } -/* TODO selector and browser +Connection Engine +----------------- + +The `proton::connection_engine` is an alternative to the container. For simple +applications with a single connection, its use is about the same as the the +`proton::container`, but it allows more flexibility for multi-threaded +applications or applications with unusual IO requirements. + +\dontinclude engine/helloworld.cpp + +We'll look at the \ref engine/helloworld.cpp example step-by-step to see how it differs +from the container \ref helloworld.cpp version. -Many brokers offer the ability to consume messages based on a 'selector' -that defines which messages are of interest based on particular values -of the headers. The following example shows how that can be achieved: +First we include the `proton::io::socket_engine` class, which is a `proton::connection_engine` +that uses socket IO. -\todo TODO selected_recv.cpp +\skipline proton/io.hpp -When creating the receiver, we specify a Selector object as an option. -The options argument can take a single object or a list. Another option -that is sometimes of interest when using a broker is the ability to -'browse' the messages on a queue, rather than consuming them. This is -done in AMQP by specifying a distribution mode of 'copy' (instead of -'move' which is the expected default for queues). An example of that is -shown next: +Our `hello_world` class differs only in the `on_start()` method. Instead of +calling `container.connect()`, we simply call `proton::connection::open` to open the +engine's' connection: + +\skip on_start +\until } + +Our `main` function only differs in that it creates and runs a `socket_engine` +instead of a `container`. + +\skip main +\until } +\until } +\until } -\todo TODO queue_browser.cpp */ diff --git a/proton-c/bindings/cpp/docs/user.doxygen.in b/proton-c/bindings/cpp/docs/user.doxygen.in index fa4a9f2c7d..e76337a57a 100644 --- a/proton-c/bindings/cpp/docs/user.doxygen.in +++ b/proton-c/bindings/cpp/docs/user.doxygen.in @@ -1,4 +1,4 @@ -# +## ## Licensed to the Apache Software Foundation (ASF) under one ## or more contributor license agreements. See the NOTICE file ## distributed with this work for additional information @@ -19,31 +19,38 @@ # Project options -PROJECT_NAME = proton-cpp -PROJECT_NUMBER = @PN_VERSION_MAJOR@.@PN_VERSION_MINOR@ -PROJECT_BRIEF = "Proton C++ API" -OUTPUT_DIRECTORY = . -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -INLINE_INHERITED_MEMB = YES -JAVADOC_AUTOBRIEF = YES -MULTILINE_CPP_IS_BRIEF = NO -INHERIT_DOCS = YES -BUILTIN_STL_SUPPORT = YES -INLINE_SIMPLE_STRUCTS = YES +PROJECT_NAME = "Qpid Proton C++" +PROJECT_NUMBER = @PN_VERSION_MAJOR@.@PN_VERSION_MINOR@.@PN_VERSION_POINT@ +OUTPUT_DIRECTORY = . +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +INLINE_INHERITED_MEMB = YES +JAVADOC_AUTOBRIEF = YES +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +BUILTIN_STL_SUPPORT = YES +INLINE_SIMPLE_STRUCTS = YES +EXTRACT_LOCAL_CLASSES = NO +HIDE_UNDOC_CLASSES = YES +HIDE_COMPOUND_REFERENCE = YES +HIDE_SCOPE_NAMES = YES +MAX_INITIALIZER_LINES = 0 +ALPHABETICAL_INDEX = NO -# Build related configuration options +# Redefine protected as private and strip out the PN_CPP_EXTERN macro -EXTRACT_ALL = YES -INTERNAL_DOCS = NO +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = protected=private PN_CPP_EXTERN= -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages QUIET = YES WARNINGS = YES -# configuration options related to the input files +# Configuration options related to the input files INPUT = @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/docs @CMAKE_SOURCE_DIR@/examples/cpp/README.hpp FILE_PATTERNS = *.hpp *.md @@ -53,17 +60,14 @@ EXAMPLE_RECURSIVE = YES # View and list options -GENERATE_TREEVIEW = YES -GENERATE_TODOLIST = NO -GENERATE_TESTLIST = NO -GENERATE_BUGLIST = NO -GENERATE_DEPRECATEDLIST= YES - +GENERATE_TODOLIST = NO +GENERATE_TESTLIST = NO +GENERATE_BUGLIST = NO +GENERATE_DEPRECATEDLIST = YES -# configuration options related to the HTML output +# Configuration options related to the output format GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION = .html - GENERATE_LATEX = NO diff --git a/proton-c/bindings/cpp/include/proton/acceptor.hpp b/proton-c/bindings/cpp/include/proton/acceptor.hpp index 4edcc11fdd..ebca8ba0cf 100644 --- a/proton-c/bindings/cpp/include/proton/acceptor.hpp +++ b/proton-c/bindings/cpp/include/proton/acceptor.hpp @@ -30,23 +30,28 @@ struct pn_connection_t; namespace proton { -/** acceptor accepts connections. @see container::listen */ +/// A context for accepting inbound connections. +/// +/// @see container::listen class acceptor : public object { public: + /// @cond INTERNAL + /// XXX important to expose? acceptor(pn_acceptor_t* a=0) : object(a) {} + /// @endcond - /** close the acceptor */ + /// Close the acceptor. PN_CPP_EXTERN void close(); - /** Return the current set of connection options applied to inbound connectons by the acceptor. - * - * Note that changes made to the connection options only affect connections accepted after this - * call returns. - */ + /// Return the current set of connection options applied to + /// inbound connectons by the acceptor. + /// + /// Note that changes made to the connection options only affect + /// connections accepted after this call returns. PN_CPP_EXTERN class connection_options &connection_options(); }; } -#endif /*!PROTON_CPP_ACCEPTOR_H*/ +#endif // PROTON_CPP_ACCEPTOR_H diff --git a/proton-c/bindings/cpp/include/proton/annotation_key.hpp b/proton-c/bindings/cpp/include/proton/annotation_key.hpp index edd63b131c..69138ca89e 100644 --- a/proton-c/bindings/cpp/include/proton/annotation_key.hpp +++ b/proton-c/bindings/cpp/include/proton/annotation_key.hpp @@ -1,5 +1,6 @@ #ifndef ANNOTATION_KEY_HPP #define ANNOTATION_KEY_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -23,36 +24,53 @@ #include "proton/scalar.hpp" namespace proton { + class encoder; class decoder; -/** An annotation_key can contain one of the following types: uint64_t or amqp_symbol. */ +/// A key for use with AMQP annotation maps. +/// +/// An annotation_key can contain either a uint64_t or a +/// proton::amqp::amqp_symbol. class annotation_key : public restricted_scalar { public: + /// Create an empty key. annotation_key() { scalar_ = uint64_t(0); } - ///@name Assign a C++ value, deduce the AMQP type() - ///@{ + /// @name Assignment operators + /// + /// Assign a C++ value, deducing the AMQP type(). + /// + /// @{ annotation_key& operator=(uint64_t x) { scalar_ = x; return *this; } annotation_key& operator=(const amqp_symbol& x) { scalar_ = x; return *this; } - /// std::string is encoded as amqp_symbol + /// `std::string` is encoded as proton::amqp::amqp_symbol. annotation_key& operator=(const std::string& x) { scalar_ = amqp_symbol(x); return *this; } - /// char* is encoded as amqp_symbol + /// `char*` is encoded as proton::amqp::amqp_symbol. annotation_key& operator=(const char *x) { scalar_ = amqp_symbol(x); return *this; } - ///@} + /// @} - /// Converting constructor from any type that we can assign from. + /// A constructor that converts from any type that we can assign + /// from. template annotation_key(T x) { *this = x; } + /// @name Get methods + /// + /// @{ void get(uint64_t& x) const { scalar_.get(x); } void get(amqp_symbol& x) const { scalar_.get(x); } + /// @} + /// Return the value as type T. template T get() const { T x; get(x); return x; } - friend PN_CPP_EXTERN encoder operator<<(encoder, const annotation_key&); - friend PN_CPP_EXTERN decoder operator>>(decoder, annotation_key&); - friend class message; + /// @cond INTERNAL + friend PN_CPP_EXTERN encoder operator<<(encoder, const annotation_key&); + friend PN_CPP_EXTERN decoder operator>>(decoder, annotation_key&); + friend class message; + /// @endcond }; } + #endif // ANNOTATION_KEY_HPP diff --git a/proton-c/bindings/cpp/include/proton/condition.hpp b/proton-c/bindings/cpp/include/proton/condition.hpp index 46d6e7510b..426e3749f2 100644 --- a/proton-c/bindings/cpp/include/proton/condition.hpp +++ b/proton-c/bindings/cpp/include/proton/condition.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/value.hpp" @@ -30,22 +31,29 @@ struct pn_condition_t; namespace proton { -/** condition allows access to error or other special circumstance information */ -class condition -{ +/// Describes an endpoint error state. +class condition { public: + /// @cond INTERNAL condition(pn_condition_t* c) : condition_(c) {} + /// @endcond - /** Assert no condition set */ + /// @cond INTERNAL + /// XXX want to discuss + /// Assert no condition set. bool operator!() const; - /** Condition name */ + /// @endcond + + /// Condition name. std::string name() const; - /** Descriptive string for condition */ + + /// Descriptive string for condition. std::string description() const; - /** Extra information for condition n*/ + + /// Extra information for condition n*/ value info() const; - /** Simple printable string for condition */ + /// Simple printable string for condition. std::string str() const; private: @@ -54,4 +62,4 @@ class condition } -#endif /*!PROTON_CPP_CONDITION_H*/ +#endif // PROTON_CPP_CONDITION_H diff --git a/proton-c/bindings/cpp/include/proton/config.hpp b/proton-c/bindings/cpp/include/proton/config.hpp index 4d3dff923d..dea4c9e9a4 100644 --- a/proton-c/bindings/cpp/include/proton/config.hpp +++ b/proton-c/bindings/cpp/include/proton/config.hpp @@ -1,5 +1,6 @@ #ifndef CONFIG_HPP #define CONFIG_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,13 +20,17 @@ * under the License. */ -/**@file - * - * Configuration macros, can be set via -D compiler options or in code. - * - * On a C++11 compliant compiler, all C++11 features are enabled by default. - * Otherwise they can be enabled or disabled separately with -D on the compile line. - */ +/// @cond INTERNAL +/// XXX discuss + +/// @file +/// +/// Configuration macros. They can be set via -D compiler options or +/// in code. +/// +/// On a C++11 compliant compiler, all C++11 features are enabled by +/// default. Otherwise they can be enabled or disabled separately +/// with -D on the compile line. #ifndef PN_HAS_CPP11 #if (defined(__cplusplus) && __cplusplus >= 201100) @@ -48,3 +53,5 @@ #endif #endif // CONFIG_HPP + +/// @endcond diff --git a/proton-c/bindings/cpp/include/proton/connection.hpp b/proton-c/bindings/cpp/include/proton/connection.hpp index ec86bd78df..410f7f6f4a 100644 --- a/proton-c/bindings/cpp/include/proton/connection.hpp +++ b/proton-c/bindings/cpp/include/proton/connection.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/endpoint.hpp" #include "proton/link.hpp" @@ -37,20 +38,23 @@ namespace proton { class handler; class engine; -/** connection to a remote AMQP peer. */ -class connection : public object, public endpoint -{ +/// A connection to a remote AMQP peer. +class connection : public object, public endpoint { public: + /// @cond INTERNAL connection(pn_connection_t* c=0) : object(c) {} + /// @endcond - /* Endpoint behaviours */ - + /// Get the state of this connection. PN_CPP_EXTERN endpoint::state state() const; + PN_CPP_EXTERN condition local_condition() const; PN_CPP_EXTERN condition remote_condition() const; - /// Get the container, throw an exception if this connection is not managed - /// by a container. + /// Get the container. + /// + /// @throw proton::error if this connection is not managed by a + /// container PN_CPP_EXTERN class container &container() const; /// Get the transport for the connection. @@ -59,59 +63,77 @@ class connection : public object, public endpoint /// Return the AMQP host name for the connection. PN_CPP_EXTERN std::string host() const; + /// @cond INTERNAL + /// XXX this should be a connection option, right? /// Set the AMQP host name for the connection PN_CPP_EXTERN void host(const std::string& h); + /// @endcond - /// Return the container-ID for the connection. + /// Return the container ID for the connection. PN_CPP_EXTERN std::string container_id() const; - /** Initiate local open, not complete till messaging_handler::on_connection_opened() - * or proton_handler::on_connection_remote_open() - */ + /// @cond INTERNAL + /// XXX connection options + /// Initiate local open. The operation is not complete till + /// handler::on_connection_open(). PN_CPP_EXTERN void open(); + /// @endcond - /** Initiate local close, not complete till messaging_handler::on_connection_closed() - * or proton_handler::on_connection_remote_close() - */ + /// Initiate local close. The operation is not complete till + /// handler::on_connection_close(). PN_CPP_EXTERN void close(); - /** Release link and session resources of this connection - */ + /// @cond INTERNAL + /// XXX undiscussed + /// Release link and session resources of this connection. PN_CPP_EXTERN void release(); + /// @endcond - /** Create a new session */ + /// Open a new session. PN_CPP_EXTERN session open_session(); - /** Default session is created on first call and re-used for the lifetime of the connection */ + /// Get the default session. A default session is created on the + /// first call and reused for the lifetime of the connection. PN_CPP_EXTERN session default_session(); - /** Create a sender on default_session() with target=addr and link options=opts */ - PN_CPP_EXTERN sender open_sender(const std::string &addr, const link_options &opts = link_options()); + /// Open a sender for `addr` on default_session(). + PN_CPP_EXTERN sender open_sender(const std::string &addr, + const link_options &opts = link_options()); - /** Create a receiver on default_session() with target=addr and optional link options opts */ - PN_CPP_EXTERN receiver open_receiver(const std::string &addr, const link_options &opts = link_options()); + /// Open a receiver for `addr` on default_session(). + PN_CPP_EXTERN receiver open_receiver(const std::string &addr, + const link_options &opts = link_options()); - /** Return links on this connection matching the state mask. */ + /// Return links on this connection matching the state mask. PN_CPP_EXTERN link_range find_links(endpoint::state mask) const; - /** Return sessions on this connection matching the state mask. */ + /// Return sessions on this connection matching the state mask. PN_CPP_EXTERN session_range find_sessions(endpoint::state mask) const; - /// True if the connection is fully closed, i.e. local and remote ends are closed. - bool closed() const { return (state()&LOCAL_CLOSED) && (state()&REMOTE_CLOSED); } + /// @cond INTERNAL + /// + /// XXX not yet discussed, why this convenience but not others? + /// opened? should this not be on endpoint? + /// + /// True if the connection is fully closed, i.e. local and remote + /// ends are closed. + bool closed() const { return (state() & LOCAL_CLOSED) && (state() & REMOTE_CLOSED); } + /// @endcond private: PN_CPP_EXTERN void user(const std::string &); PN_CPP_EXTERN void password(const std::string &); - friend class connection_context; - friend class connection_engine; - friend class connection_options; - friend class connector; - friend class transport; - friend class container_impl; + /// @cond INTERNAL + friend class connection_context; + friend class connection_engine; + friend class connection_options; + friend class connector; + friend class transport; + friend class container_impl; + /// @endcond }; } -#endif /*!PROTON_CPP_CONNECTION_H*/ +#endif // PROTON_CPP_CONNECTION_H diff --git a/proton-c/bindings/cpp/include/proton/connection_engine.hpp b/proton-c/bindings/cpp/include/proton/connection_engine.hpp index 83839e827a..4565f33956 100644 --- a/proton-c/bindings/cpp/include/proton/connection_engine.hpp +++ b/proton-c/bindings/cpp/include/proton/connection_engine.hpp @@ -1,5 +1,6 @@ #ifndef CONNECTION_ENGINE_HPP #define CONNECTION_ENGINE_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -33,41 +34,40 @@ namespace proton { class connection_engine_context; - class handler; class connection; // TODO aconway 2016-01-23: doc contrast with container. -/** - * A connection_engine manages a single AMQP connection. It is useful for - * integrating AMQP into an existing IO framework. - * - * The engine provides a simple "bytes-in/bytes-out" interface. Incoming AMQP - * bytes from any kind of data connection are fed into the engine and processed - * to dispatch events to a proton::handler. The resulting AMQP output data is - * available from the engine and can sent back over the connection. - * - * The engine does no IO of its own. It assumes a two-way flow of bytes over - * some externally-managed "connection". The "connection" could be a socket - * managed by select, poll, epoll or some other mechanism, or it could be - * something else such as an RDMA connection, a shared-memory buffer or a Unix - * pipe. - * - * The application is coded the same way for engine or container: you implement - * proton::handler. Handlers attached to an engine will receive transport, - * connection, session, link and message events. They will not receive reactor, - * selectable or timer events, the engine assumes those are managed externally. - * - * THREAD SAFETY: A single engine instance cannot be called concurrently, but - * different engine instances can be processed concurrently in separate threads. - */ +/// An interface for connection-oriented IO integration. A +/// connection_engine manages a single AMQP connection. It is useful +/// for integrating AMQP into an existing IO framework. +/// +/// The engine provides a simple "bytes-in/bytes-out" interface. Incoming AMQP +/// bytes from any kind of data connection are fed into the engine and processed +/// to dispatch events to a proton::handler. The resulting AMQP output data is +/// available from the engine and can sent back over the connection. +/// +/// The engine does no IO of its own. It assumes a two-way flow of bytes over +/// some externally-managed "connection". The "connection" could be a socket +/// managed by select, poll, epoll or some other mechanism, or it could be +/// something else such as an RDMA connection, a shared-memory buffer or a Unix +/// pipe. +/// +/// The application is coded the same way for engine or container: you implement +/// proton::handler. Handlers attached to an engine will receive transport, +/// connection, session, link and message events. They will not receive reactor, +/// selectable or timer events, the engine assumes those are managed externally. +/// +/// THREAD SAFETY: A single engine instance cannot be called concurrently, but +/// different engine instances can be processed concurrently in separate threads. class connection_engine { public: // FIXME aconway 2016-01-23: DOC class container { public: - /// Create a container with id, default to random UUID if id == "". + /// Create a container with id. Default to random UUID if id + /// == "". PN_CPP_EXTERN container(const std::string &id = ""); /// Return the container-id @@ -90,7 +90,7 @@ class connection_engine { connection_options options_; }; - /** Create a connection engine that dispatches to handler. */ + /// Create a connection engine that dispatches to handler. PN_CPP_EXTERN connection_engine(handler&, const connection_options& = no_opts); PN_CPP_EXTERN virtual ~connection_engine(); @@ -117,29 +117,33 @@ class connection_engine { /// @return true if process should be called again, i.e. !closed() PN_CPP_EXTERN bool process(int io_flags=READ|WRITE); - /// Non-throwing version of process. - /// Use closed() and error_str() to check the status of the engine. + /// Non-throwing version of process. Use closed() and error_str() + /// to check the status of the engine. PN_CPP_EXTERN bool process_nothrow(int io_flags=READ|WRITE); - /** - * True if the engine is closed, meaning there are no further - * events to process and close_io has been called. - * Call error_str() to get an error description. - */ + /// True if the engine is closed, meaning there are no further + /// events to process and close_io has been called. Call + /// error_str() to get an error description. PN_CPP_EXTERN bool closed() const; - /** If the engine was closed by an error, return a pointer */ + /// If the engine was closed by an error, return a pointer. PN_CPP_EXTERN std::string error_str() const; - /** Get the AMQP connection associated with this connection_engine. */ + /// Get the AMQP connection associated with this connection_engine. PN_CPP_EXTERN class connection connection() const; - /** Get the transport object connection associated with this connection_engine. */ + /// Get the transport associated with this connection_engine. PN_CPP_EXTERN class transport transport() const; - /** Disconnect the engine. Calls io::close and dispatches final events to - * the handler. Neither the handler nor the io will be used after this call. - */ + /// Disconnect the engine. + /// + /// @internal + /// + /// XXX calls io::close? + /// + /// Calls io::close and dispatches final events to the + /// handler. Neither the handler nor the io will be used after + /// this call. PN_CPP_EXTERN void disconnect(); protected: @@ -166,7 +170,6 @@ class connection_engine { PN_CPP_EXTERN static const connection_options no_opts; private: - connection_engine(const connection_engine&); connection_engine& operator=(const connection_engine&); @@ -178,6 +181,6 @@ class connection_engine { connection_engine_context* ctx_; }; - } + #endif // CONNECTION_ENGINE_HPP diff --git a/proton-c/bindings/cpp/include/proton/connection_options.hpp b/proton-c/bindings/cpp/include/proton/connection_options.hpp index e72ac13f3d..cea1900e37 100644 --- a/proton-c/bindings/cpp/include/proton/connection_options.hpp +++ b/proton-c/bindings/cpp/include/proton/connection_options.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/config.hpp" #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -35,50 +36,102 @@ namespace proton { class proton_handler; class connection; -/** Options for creating a connection. - * - * Options can be "chained" like this: - * - * c = container.connect(url, connection_options().handler(h).max_frame_size(1234)); - * - * You can also create an options object with common settings and use it as a base - * for different connections that have mostly the same settings: - * - * connection_options opts; - * opts.idle_timeout(1000).max_frame_size(10000); - * c1 = container.connect(url1, opts.handler(h1)); - * c2 = container.connect(url2, opts.handler(h2)); - * - * Normal value semantics, copy or assign creates a separate copy of the options. - */ +/// Options for creating a connection. +/// +/// Options can be "chained" like this: +/// +/// @code +/// c = container.connect(url, connection_options().handler(h).max_frame_size(1234)); +/// @endcode +/// +/// You can also create an options object with common settings and use +/// it as a base for different connections that have mostly the same +/// settings: +/// +/// @code +/// connection_options opts; +/// opts.idle_timeout(1000).max_frame_size(10000); +/// c1 = container.connect(url1, opts.handler(h1)); +/// c2 = container.connect(url2, opts.handler(h2)); +/// @endcode +/// +/// Normal value semantics: copy or assign creates a separate copy of +/// the options. class connection_options { public: + /// Create an empty set of options. PN_CPP_EXTERN connection_options(); + + /// Copy options. PN_CPP_EXTERN connection_options(const connection_options&); + PN_CPP_EXTERN ~connection_options(); + + /// Copy options. PN_CPP_EXTERN connection_options& operator=(const connection_options&); /// Override with options from other. PN_CPP_EXTERN void override(const connection_options& other); - // TODO: Document options - + /// Set a handler for the connection. PN_CPP_EXTERN connection_options& handler(class handler *); + + /// Set the maximum frame size. PN_CPP_EXTERN connection_options& max_frame_size(uint32_t max); + + /// Set the maximum channels. PN_CPP_EXTERN connection_options& max_channels(uint16_t max); + + /// Set the idle timeout. PN_CPP_EXTERN connection_options& idle_timeout(duration); + + /// @cond INTERNAL + /// XXX remove PN_CPP_EXTERN connection_options& heartbeat(duration); + /// @endcond + + /// Set the container ID. PN_CPP_EXTERN connection_options& container_id(const std::string &id); + + /// @cond INTERNAL + + /// XXX more discussion PN_CPP_EXTERN connection_options& link_prefix(const std::string &id); + + /// XXX settle questions about reconnect_timer PN_CPP_EXTERN connection_options& reconnect(const reconnect_timer &); + + /// @endcond + + /// Set SSL client options. PN_CPP_EXTERN connection_options& ssl_client_options(const class ssl_client_options &); + + /// Set SSL server options. PN_CPP_EXTERN connection_options& ssl_server_options(const class ssl_server_options &); + + /// @cond INTERNAL + + /// XXX remove PN_CPP_EXTERN connection_options& peer_hostname(const std::string &name); + + /// XXX ssl_ prefix PN_CPP_EXTERN connection_options& resume_id(const std::string &id); + + /// @endcond + + /// Enable or disable SASL. PN_CPP_EXTERN connection_options& sasl_enabled(bool); + + /// @cond INTERNAL + /// XXX sasl_ prefix PN_CPP_EXTERN connection_options& allow_insecure_mechs(bool); PN_CPP_EXTERN connection_options& allowed_mechs(const std::string &); + /// @endcond + + /// Set the SASL configuration name. PN_CPP_EXTERN connection_options& sasl_config_name(const std::string &); + + /// Set the SASL configuration path. PN_CPP_EXTERN connection_options& sasl_config_path(const std::string &); private: @@ -91,11 +144,13 @@ class connection_options { class impl; pn_unique_ptr impl_; - friend class container_impl; - friend class connector; - friend class connection_engine; + /// @cond INTERNAL + friend class container_impl; + friend class connector; + friend class connection_engine; + /// @endcond }; -} // namespace +} -#endif /*!PROTON_CPP_CONNECTION_OPTIONS_H*/ +#endif // PROTON_CPP_CONNECTION_OPTIONS_H diff --git a/proton-c/bindings/cpp/include/proton/container.hpp b/proton-c/bindings/cpp/include/proton/container.hpp index 8e907b7e56..8b33ca413d 100644 --- a/proton-c/bindings/cpp/include/proton/container.hpp +++ b/proton-c/bindings/cpp/include/proton/container.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/duration.hpp" #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -43,76 +44,99 @@ class handler; class task; class container_impl; -/** - * Top level container for connections and other objects, runs the event loop. - * - * Note that by default, links belonging to the container have generated link-names - * of the form - */ +/// A top-level container of connections, sessions, and links. +/// +/// A container gives a unique identity to each communicating peer. It +/// is often a process-level object. + +/// It serves as an entry point to the API, allowing connections and +/// links to be established. It can be supplied with an event handler +/// in order to intercept important messaging events, such as newly +/// received messages or newly issued link credit for sending +/// messages. class container { public: - /// Container ID should be unique within your system. - /// By default a random ID is generated. + /// Create a container. + /// + /// Container ID should be unique within your system. By default a + /// random ID is generated. PN_CPP_EXTERN container(const std::string& id=""); - /// Container ID should be unique within your system. By default a random ID is generated. + /// Create a container with an event handler. + /// + /// Container ID should be unique within your system. By default a + /// random ID is generated. PN_CPP_EXTERN container(handler& mhandler, const std::string& id=std::string()); PN_CPP_EXTERN ~container(); - /** Locally open a connection @see connection::open */ - PN_CPP_EXTERN connection connect(const proton::url&, const connection_options &opts = connection_options()); + /// Open a connection to `url`. + PN_CPP_EXTERN connection connect(const proton::url&, + const connection_options &opts = connection_options()); - /** Listen on url host and port for incoming connections. */ - PN_CPP_EXTERN acceptor listen(const proton::url&, const connection_options &opts = connection_options()); + /// Listen on `url` for incoming connections. + PN_CPP_EXTERN acceptor listen(const proton::url&, + const connection_options &opts = connection_options()); - /** Run the event loop, return when all connections and acceptors are closed. */ + /// Start processing events. It returns when all connections and + /// acceptors are closed. PN_CPP_EXTERN void run(); - /** Open a new connection to url and create a sender with target=url.path(). - Any supplied link or connection options will override the container's - template options. */ - PN_CPP_EXTERN sender open_sender(const proton::url &, const proton::link_options &l = proton::link_options(), + /// Open a connection to `url` and open a sender for `url.path()`. + /// Any supplied link or connection options will override the + /// container's template options. + PN_CPP_EXTERN sender open_sender(const proton::url &, + const proton::link_options &l = proton::link_options(), const connection_options &c = connection_options()); - /** Create a receiver on a new connection with source=url.path(). Any - supplied link or connection options will override the container's - template options. */ - PN_CPP_EXTERN receiver open_receiver(const url &, const proton::link_options &l = proton::link_options(), + /// Open a connection to `url` and open a receiver for + /// `url.path()`. Any supplied link or connection options will + /// override the container's template options. + PN_CPP_EXTERN receiver open_receiver(const url &, + const proton::link_options &l = proton::link_options(), const connection_options &c = connection_options()); - /// Identifier for the container + /// A unique identifier for the container. PN_CPP_EXTERN std::string id() const; + /// @cond INTERNAL + + /// XXX remove /// The reactor associated with this container. PN_CPP_EXTERN class reactor reactor() const; - // Schedule a timer task event in delay milliseconds. + /// XXX settle some API questions + /// Schedule a timer task event in delay milliseconds. PN_CPP_EXTERN task schedule(int delay, handler *h = 0); - /** Copy the connection options to a template which will be - applied to subsequent outgoing connections. These are applied first - and overriden by additional connection options provided in - other methods */ + /// @endcond + + /// Copy the connection options to a template which will be + /// applied to subsequent outgoing connections. These are applied + /// first and overriden by additional connection options provided + /// in other methods. PN_CPP_EXTERN void client_connection_options(const connection_options &); - /** Copy the connection options to a template which will be - applied to incoming connections. These are applied before the - first open event on the connection. */ + /// Copy the connection options to a template which will be + /// applied to incoming connections. These are applied before the + /// first open event on the connection. PN_CPP_EXTERN void server_connection_options(const connection_options &); - /** Copy the link options to a template applied to new links created and - opened by this container. They are applied before the open event on the - link and may be overriden by link options in other methods. */ + /// Copy the link options to a template applied to new links + /// created and opened by this container. They are applied before + /// the open event on the link and may be overriden by link + /// options in other methods. PN_CPP_EXTERN void link_options(const link_options &); - private: pn_unique_ptr impl_; + + /// @cond INTERNAL friend class connector; - friend class link; + friend class link; + /// @endcond }; } -#endif /*!PROTON_CPP_CONTAINER_H*/ +#endif // PROTON_CPP_CONTAINER_H diff --git a/proton-c/bindings/cpp/include/proton/data.hpp b/proton-c/bindings/cpp/include/proton/data.hpp index c9f0a08f21..09cca58f6a 100644 --- a/proton-c/bindings/cpp/include/proton/data.hpp +++ b/proton-c/bindings/cpp/include/proton/data.hpp @@ -1,5 +1,6 @@ #ifndef DATA_H #define DATA_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,7 +20,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX remove #include "proton/decoder.hpp" #include "proton/encoder.hpp" @@ -34,10 +36,9 @@ namespace proton { class data; -/**@internal - * Holds a sequence of AMQP values, allows inserting and extracting via encoder() and decoder(). - * Cannot be directly instantiated, use `value` - */ +/// Holds a sequence of AMQP values, allows inserting and extracting +/// via encoder() and decoder(). Cannot be directly instantiated, use +/// `value`. class data : public object { public: data(pn_data_t* d=0) : object(d) {} @@ -98,6 +99,6 @@ class data : public object { } -///@endcond +/// @endcond #endif // DATA_H diff --git a/proton-c/bindings/cpp/include/proton/decoder.hpp b/proton-c/bindings/cpp/include/proton/decoder.hpp index fdd2f223a6..3dab9c94f4 100644 --- a/proton-c/bindings/cpp/include/proton/decoder.hpp +++ b/proton-c/bindings/cpp/include/proton/decoder.hpp @@ -19,7 +19,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX change namespace, review better #include "proton/error.hpp" #include "proton/type_traits.hpp" @@ -396,6 +397,7 @@ template decoder operator>>(decoder d, std: #endif // PN_NO_CONTAINER_CONVERT } -///@endcond + +/// @endcond #endif // DECODER_H diff --git a/proton-c/bindings/cpp/include/proton/delivery.hpp b/proton-c/bindings/cpp/include/proton/delivery.hpp index a05347bfa0..c4e6243d01 100644 --- a/proton-c/bindings/cpp/include/proton/delivery.hpp +++ b/proton-c/bindings/cpp/include/proton/delivery.hpp @@ -1,4 +1,3 @@ - #ifndef PROTON_CPP_DELIVERY_H #define PROTON_CPP_DELIVERY_H @@ -22,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/object.hpp" @@ -30,94 +30,95 @@ namespace proton { -/** delivery status of a message */ +/// A message transfer. Every delivery exists within the context of a +/// proton::link. A delivery attempt can fail. As a result, a +/// particular message may correspond to multiple deliveries. class delivery : public object { public: + /// @cond INTERNAL delivery(pn_delivery_t* d=0) : object(d) {} + /// @endcond - /** Delivery state of a message */ + /// Delivery state values. enum state { - NONE = 0, ///< Unknown state + NONE = 0, ///< Unknown state RECEIVED = PN_RECEIVED, ///< Received but not yet settled ACCEPTED = PN_ACCEPTED, ///< Settled as accepted REJECTED = PN_REJECTED, ///< Settled as rejected RELEASED = PN_RELEASED, ///< Settled as released MODIFIED = PN_MODIFIED ///< Settled as modified - }; // AMQP spec 3.4 delivery State + }; // AMQP spec 3.4 delivery State - /** Return true if the delivery has been settled. */ + /// @cond INTERNAL + /// XXX settle how much of this we need to expose + + /// Return true if the delivery has been settled. PN_CPP_EXTERN bool settled() const; - /** Settle the delivery, informs the remote end. */ + /// Settle the delivery; informs the remote end. PN_CPP_EXTERN void settle(); - /** Set the local state of the delivery. */ + /// Set the local state of the delivery. PN_CPP_EXTERN void update(delivery::state state); - /** update and settle a delivery with the given delivery::state */ + /// Update and settle a delivery with the given delivery::state PN_CPP_EXTERN void settle(delivery::state s); - /** settle with ACCEPTED state */ + /// @endcond + + /// Settle with ACCEPTED state PN_CPP_EXTERN void accept() { settle(ACCEPTED); } - /** settle with REJECTED state */ + /// Settle with REJECTED state PN_CPP_EXTERN void reject() { settle(REJECTED); } - /** settle with REJECTED state */ + /// Settle with RELEASED state PN_CPP_EXTERN void release() { settle(RELEASED); } - /** settle with MODIFIED state */ + /// Settle with MODIFIED state PN_CPP_EXTERN void modify() { settle(MODIFIED); } - /** - * Check if a delivery is readable. - * - * A delivery is considered readable if it is the current delivery on - * an incoming link. - */ + /// @cond INTERNAL + /// XXX who needs this? + + /// Check if a delivery is readable. + /// + /// A delivery is considered readable if it is the current delivery on + /// an incoming link. PN_CPP_EXTERN bool partial() const; - /** - * Check if a delivery is writable. - * - * A delivery is considered writable if it is the current delivery on - * an outgoing link, and the link has positive credit. - */ + /// Check if a delivery is writable. + /// + /// A delivery is considered writable if it is the current delivery on + /// an outgoing link, and the link has positive credit. PN_CPP_EXTERN bool writable() const; - /** - * Check if a delivery is readable. - * - * A delivery is considered readable if it is the current delivery on - * an incoming link. - */ + /// Check if a delivery is readable. + /// + /// A delivery is considered readable if it is the current + /// delivery on an incoming link. PN_CPP_EXTERN bool readable() const; - /** - * Check if a delivery is updated. - * - * A delivery is considered updated whenever the peer communicates a - * new disposition for the delivery. Once a delivery becomes updated, - * it will remain so until clear() is called. - */ + /// Check if a delivery is updated. + /// + /// A delivery is considered updated whenever the peer + /// communicates a new disposition for the delivery. Once a + /// delivery becomes updated, it will remain so until clear() is + /// called. PN_CPP_EXTERN bool updated() const; - /** - * Clear the updated flag for a delivery. - */ + /// Clear the updated flag for a delivery. PN_CPP_EXTERN void clear(); - /** - * Get the remote disposition state for a delivery. - */ - PN_CPP_EXTERN state remote_state() const; - - /** - * Get the size of the current delivery - */ + /// Get the size of the current delivery. PN_CPP_EXTERN size_t pending() const; + + /// @endcond + + /// Get the remote state for a delivery. + PN_CPP_EXTERN state remote_state() const; }; } -#endif /*!PROTON_CPP_DELIVERY_H*/ +#endif // PROTON_CPP_DELIVERY_H diff --git a/proton-c/bindings/cpp/include/proton/duration.hpp b/proton-c/bindings/cpp/include/proton/duration.hpp index 1726701022..200064dccc 100644 --- a/proton-c/bindings/cpp/include/proton/duration.hpp +++ b/proton-c/bindings/cpp/include/proton/duration.hpp @@ -28,17 +28,21 @@ namespace proton { -/** Duration in milliseconds. */ -class duration : public comparable -{ +/// A span of time in milliseconds. +class duration : public comparable { public: + /// @cond INTERNAL + /// XXX public and mutable? uint64_t milliseconds; + /// @endcond + + /// Create a duration. explicit duration(uint64_t ms = 0) : milliseconds(ms) {} - PN_CPP_EXTERN static const duration FOREVER; ///< Wait for ever + PN_CPP_EXTERN static const duration FOREVER; ///< Wait for ever PN_CPP_EXTERN static const duration IMMEDIATE; ///< Don't wait at all - PN_CPP_EXTERN static const duration SECOND; ///< One second - PN_CPP_EXTERN static const duration MINUTE; ///< One minute + PN_CPP_EXTERN static const duration SECOND; ///< One second + PN_CPP_EXTERN static const duration MINUTE; ///< One minute }; inline bool operator<(duration x, duration y) { return x.milliseconds < y.milliseconds; } @@ -49,6 +53,7 @@ inline duration operator*(amqp_ulong n, duration d) { return d * n; } inline amqp_timestamp operator+(amqp_timestamp ts, duration d) { return amqp_timestamp(ts.milliseconds+d.milliseconds); } inline amqp_timestamp operator+(duration d, amqp_timestamp ts) { return ts + d; } + } -#endif /*!PROTON_CPP_DURATION_H*/ +#endif // PROTON_CPP_DURATION_H diff --git a/proton-c/bindings/cpp/include/proton/encoder.hpp b/proton-c/bindings/cpp/include/proton/encoder.hpp index c2d683e1d0..187641237d 100644 --- a/proton-c/bindings/cpp/include/proton/encoder.hpp +++ b/proton-c/bindings/cpp/include/proton/encoder.hpp @@ -1,5 +1,6 @@ #ifndef ENCODER_H #define ENCODER_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,7 +20,8 @@ * under the License. */ -///@cond INTERNAL +/// @cond INTERNAL +/// XXX change namespace, review better #include "proton/error.hpp" #include "proton/types.hpp" @@ -42,8 +44,8 @@ #endif // PN_NO_CONTAINER_CONVERT -///@file -///@internal +/// @file +/// @internal struct pn_data_t; @@ -62,6 +64,7 @@ template struct cref { cref(const T& v) : value(v) {} const T& value; }; + template const type_id cref::type = A; /** @@ -264,8 +267,9 @@ template encoder operator<<(encoder e, cons #endif // PN_HAS_CPP11 #endif // PN_NO_CONTAINER_CONVERT + } -///@endcond +/// @endcond #endif // ENCODER_H diff --git a/proton-c/bindings/cpp/include/proton/endpoint.hpp b/proton-c/bindings/cpp/include/proton/endpoint.hpp index 832548a42e..fd698b05b8 100644 --- a/proton-c/bindings/cpp/include/proton/endpoint.hpp +++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp @@ -27,42 +27,42 @@ namespace proton { -/** endpoint is a base class for session, connection and link */ -class endpoint -{ +/// The base class for session, connection, and link. +class endpoint { public: - /** state is a bit mask of state_bit values. - * - * A state mask is matched against an endpoint as follows: If the state mask - * contains both local and remote flags, then an exact match against those - * flags is performed. If state contains only local or only remote flags, - * then a match occurs if any of the local or remote flags are set - * respectively. - * - * @see connection::links, connection::sessions - */ + /// A bit mask of state bit values. + /// + /// A state mask is matched against an endpoint as follows: If the + /// state mask contains both local and remote flags, then an exact + /// match against those flags is performed. If state contains only + /// local or only remote flags, then a match occurs if any of the + /// local or remote flags are set respectively. + /// + /// @see connection::find_links, connection::find_sessions typedef int state; - /// endpoint state bit values @{ - PN_CPP_EXTERN static const state LOCAL_UNINIT; ///< Local endpoint is un-initialized - PN_CPP_EXTERN static const state REMOTE_UNINIT; ///< Remote endpoint is un-initialized - PN_CPP_EXTERN static const state LOCAL_ACTIVE; ///< Local endpoint is active - PN_CPP_EXTERN static const state REMOTE_ACTIVE; ///< Remote endpoint is active - PN_CPP_EXTERN static const state LOCAL_CLOSED; ///< Local endpoint has been closed - PN_CPP_EXTERN static const state REMOTE_CLOSED; ///< Remote endpoint has been closed - PN_CPP_EXTERN static const state LOCAL_MASK; ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED) - PN_CPP_EXTERN static const state REMOTE_MASK; ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED) - ///@} + PN_CPP_EXTERN static const state LOCAL_UNINIT; ///< Local endpoint is uninitialized + PN_CPP_EXTERN static const state REMOTE_UNINIT; ///< Remote endpoint is uninitialized + PN_CPP_EXTERN static const state LOCAL_ACTIVE; ///< Local endpoint is active + PN_CPP_EXTERN static const state REMOTE_ACTIVE; ///< Remote endpoint is active + PN_CPP_EXTERN static const state LOCAL_CLOSED; ///< Local endpoint has been closed + PN_CPP_EXTERN static const state REMOTE_CLOSED; ///< Remote endpoint has been closed + PN_CPP_EXTERN static const state LOCAL_MASK; ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED) + PN_CPP_EXTERN static const state REMOTE_MASK; ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED) + /// Get the local error condition. virtual condition local_condition() const = 0; + + /// Get the error condition of the remote endpoint. virtual condition remote_condition() const = 0; virtual ~endpoint() {} }; -///@cond INTERNAL - +/// @cond INTERNAL +/// XXX important to expose? + template class iter_base : public comparable > { public: typedef T value_type; @@ -79,7 +79,6 @@ template class iter_base : public comparable > { T ptr_; endpoint::state state_; }; -///@endcond INTERNAL /// An iterator range. template class range { @@ -92,7 +91,9 @@ template class range { private: I begin_, end_; }; + +/// @endcond } -#endif /*!PROTON_CPP_H*/ +#endif // PROTON_CPP_H diff --git a/proton-c/bindings/cpp/include/proton/error.hpp b/proton-c/bindings/cpp/include/proton/error.hpp index 30834060f3..d4d56224e5 100644 --- a/proton-c/bindings/cpp/include/proton/error.hpp +++ b/proton-c/bindings/cpp/include/proton/error.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/config.hpp" #include "proton/export.hpp" @@ -29,26 +30,55 @@ namespace proton { -/** Functions in the proton namespace throw a subclass of proton::error on error. */ -struct error : public std::runtime_error { PN_CPP_EXTERN explicit error(const std::string&); }; +/// The base proton error. +/// +/// All exceptions thrown from functions in the proton namespace are +/// subclasses of proton::error. +struct error : public std::runtime_error { + /// @cond INTERNAL + /// XXX do we intend users to construct these (and subclasses)? + PN_CPP_EXTERN explicit error(const std::string&); + /// @endcond +}; -/** Raised if timeout expires */ -struct timeout_error : public error { PN_CPP_EXTERN explicit timeout_error(const std::string&); }; +/// Raised if a timeout expires. +struct timeout_error : public error { + /// @cond INTERNAL + PN_CPP_EXTERN explicit timeout_error(const std::string&); + /// @endcond +}; -/** Raised if there is an error decoding AMQP data as a C++ value. */ -struct decode_error : public error { PN_CPP_EXTERN explicit decode_error(const std::string&); }; +/// @cond INTERNAL +/// XXX change namespace + +/// Raised if there is an error decoding AMQP data as a C++ value. +struct decode_error : public error { + PN_CPP_EXTERN explicit decode_error(const std::string&); +}; -/** Raised if there is an error encoding a C++ value as AMQP data. */ -struct encode_error : public error { PN_CPP_EXTERN explicit encode_error(const std::string&); }; +/// Raised if there is an error encoding a C++ value as AMQP data. +struct encode_error : public error { + PN_CPP_EXTERN explicit encode_error(const std::string&); +}; -/** Error reading or writing external IO. */ -struct io_error : public error { PN_CPP_EXTERN explicit io_error(const std::string&); }; +/// @endcond -/** Attempt to use a closed resource (connnection, session or link). */ +/// @cond INTERNAL +/// XXX need to discuss + +/// Error reading or writing external IO. +struct io_error : public error { + PN_CPP_EXTERN explicit io_error(const std::string&); +}; + +/// Attempt to use a closed resource (connnection, session, or link). struct closed_error : public io_error { PN_CPP_EXTERN explicit closed_error(const std::string& = default_msg); static const std::string default_msg; }; +/// @endcond + } -#endif /*!PROTON_CPP_EXCEPTIONS_H*/ + +#endif // PROTON_CPP_EXCEPTIONS_H diff --git a/proton-c/bindings/cpp/include/proton/event.hpp b/proton-c/bindings/cpp/include/proton/event.hpp index 641d5534d3..844fcaba14 100644 --- a/proton-c/bindings/cpp/include/proton/event.hpp +++ b/proton-c/bindings/cpp/include/proton/event.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/link.hpp" #include "proton/connection.hpp" @@ -34,15 +35,20 @@ class handler; class container; class connection; -/** Context information about a proton event */ +/// A context for a proton event. +/// +/// @see proton::handler class event { public: virtual PN_CPP_EXTERN ~event(); - /// Return the name of the event type + /// Return the name of the event type. virtual PN_CPP_EXTERN std::string name() const = 0; - /// Get the container, throw an exception this event was not generated by a container. + /// Get the container. + /// + /// @throw proton::error if this event was not generated by a + /// container virtual PN_CPP_EXTERN class container& container() const; /// Get transport @@ -51,15 +57,30 @@ class event { virtual PN_CPP_EXTERN class connection connection() const; /// Get session. virtual PN_CPP_EXTERN class session session() const; - /// Get sender @throws error if no sender. + + /// Get sender. + /// + /// @throw proton::error if no sender virtual PN_CPP_EXTERN class sender sender() const; - /// Get receiver @throws error if no receiver. + + /// Get receiver. + /// + /// @throw proton::error if no receiver virtual PN_CPP_EXTERN class receiver receiver() const; - /// Get link @throws error if no link. + + /// Get link. + /// + /// @throw proton::error if no link virtual PN_CPP_EXTERN class link link() const; - /// Get delivery @throws error if no delivery. + + /// Get delivery. + /// + /// @throw proton::error if no delivery virtual PN_CPP_EXTERN class delivery delivery() const; - /** Get message @throws error if no message. */ + + /// Get message. + /// + /// @throw proton::error if no message virtual PN_CPP_EXTERN class message &message() const; protected: @@ -70,7 +91,6 @@ class event { event& operator=(const event&); }; - } -#endif /*!PROTON_CPP_EVENT_H*/ +#endif // PROTON_CPP_EVENT_H diff --git a/proton-c/bindings/cpp/include/proton/export.hpp b/proton-c/bindings/cpp/include/proton/export.hpp index fdebc6f952..2eb330c95b 100644 --- a/proton-c/bindings/cpp/include/proton/export.hpp +++ b/proton-c/bindings/cpp/include/proton/export.hpp @@ -23,6 +23,7 @@ */ /// @cond INTERNAL + /// import/export macros #if defined(WIN32) && !defined(PN_CPP_DECLARE_STATIC) // @@ -44,6 +45,7 @@ #else # define PN_CPP_EXTERN PN_CPP_IMPORT #endif -///@endcond -#endif /*!PN_CPP_IMPORTEXPORT_H*/ +/// @endcond + +#endif // PN_CPP_IMPORTEXPORT_H diff --git a/proton-c/bindings/cpp/include/proton/handler.hpp b/proton-c/bindings/cpp/include/proton/handler.hpp index a681cffb86..44fad03024 100644 --- a/proton-c/bindings/cpp/include/proton/handler.hpp +++ b/proton-c/bindings/cpp/include/proton/handler.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -31,69 +32,118 @@ class condition; class event; class messaging_adapter; -/** messaging_handler base class. Provides a simpler set of events than - * proton::proton_handler and automates some common tasks. Subclass and - * over-ride event handling member functions. - * @see proton::messaging_event for meaning of events. - */ +/// Callback functions for handling proton events. +/// +/// Subclass and override event-handling member functions. +/// +/// @see proton::event class handler { public: - /** Create a messaging_handler - *@param prefetch set flow control to automatically pre-fetch this many messages - *@param auto_accept automatically accept received messages after on_message() - *@param auto_settle automatically settle on receipt of delivery for sent messages. - *@param peer_close_is_error treat orderly remote connection close as error. - */ - PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true, bool auto_settle=true, + /// @cond INTERNAL + /// XXX move configuration to connection or container + + /// Create a handler. + /// + /// @param prefetch set flow control to automatically pre-fetch + /// this many messages + /// + /// @param auto_accept automatically accept received messages + /// after on_message() + /// + /// @param auto_settle automatically settle on receipt of delivery + /// for sent messages + /// + /// @param peer_close_is_error treat orderly remote connection + /// close as error + PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true, + bool auto_settle=true, bool peer_close_is_error=false); + /// @endcond + PN_CPP_EXTERN virtual ~handler(); - ///@name Over-ride these member functions to handle events - ///@{ + /// @name Event callbacks + /// + /// Override these member functions to handle events. + /// + /// @{ + + /// The event loop is starting. PN_CPP_EXTERN virtual void on_start(event &e); + /// A message is received. PN_CPP_EXTERN virtual void on_message(event &e); + /// A message can be sent. PN_CPP_EXTERN virtual void on_sendable(event &e); + /// The underlying network transport has closed. PN_CPP_EXTERN virtual void on_transport_close(event &e); + /// The underlying network transport has closed with an error + /// condition. PN_CPP_EXTERN virtual void on_transport_error(event &e); + /// The remote peer opened the connection. PN_CPP_EXTERN virtual void on_connection_open(event &e); + /// The remote peer closed the connection. PN_CPP_EXTERN virtual void on_connection_close(event &e); + /// The remote peer closed the connection with an error condition. PN_CPP_EXTERN virtual void on_connection_error(event &e); + /// The remote peer opened the session. PN_CPP_EXTERN virtual void on_session_open(event &e); + /// The remote peer closed the session. PN_CPP_EXTERN virtual void on_session_close(event &e); + /// The remote peer closed the session with an error condition. PN_CPP_EXTERN virtual void on_session_error(event &e); + /// The remote peer opened the link. PN_CPP_EXTERN virtual void on_link_open(event &e); + /// The remote peer closed the link. PN_CPP_EXTERN virtual void on_link_close(event &e); + /// The remote peer closed the link with an error condition. PN_CPP_EXTERN virtual void on_link_error(event &e); + /// The remote peer accepted an outgoing message. PN_CPP_EXTERN virtual void on_delivery_accept(event &e); + /// The remote peer rejected an outgoing message. PN_CPP_EXTERN virtual void on_delivery_reject(event &e); + /// The remote peer released an outgoing message. PN_CPP_EXTERN virtual void on_delivery_release(event &e); + /// The remote peer settled an outgoing message. PN_CPP_EXTERN virtual void on_delivery_settle(event &e); + /// The remote peer declared a transaction. PN_CPP_EXTERN virtual void on_transaction_declare(event &e); + /// The remote peer committed a transaction. PN_CPP_EXTERN virtual void on_transaction_commit(event &e); + /// The remote peer aborted a transaction. PN_CPP_EXTERN virtual void on_transaction_abort(event &e); + /// @cond INTERNAL + /// XXX settle API questions around task + /// A timer fired. PN_CPP_EXTERN virtual void on_timer(event &e); + /// @endcond + /// Fallback event handling. PN_CPP_EXTERN virtual void on_unhandled(event &e); + /// Fallback error handling. PN_CPP_EXTERN virtual void on_unhandled_error(event &e, const condition &c); - ///@} + + /// @} private: pn_unique_ptr messaging_adapter_; + + /// @cond INTERNAL friend class container; friend class connection_engine; friend class connection_options; friend class link_options; + /// @endcond }; } -#endif /*!PROTON_CPP_MESSAGING_HANDLER_H*/ +#endif // PROTON_CPP_MESSAGING_HANDLER_H diff --git a/proton-c/bindings/cpp/include/proton/io.hpp b/proton-c/bindings/cpp/include/proton/io.hpp index c4a3aa4d78..cf97f3b546 100644 --- a/proton-c/bindings/cpp/include/proton/io.hpp +++ b/proton-c/bindings/cpp/include/proton/io.hpp @@ -1,6 +1,6 @@ - #ifndef SOCKET_IO_HPP #define SOCKET_IO_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -24,42 +24,52 @@ namespace proton { -/** IO using sockets, file descriptors or handles. - * - * Note that you can use proton::connection_engine to communicate using AMQP - * over your own IO implementation or to integrate an existing IO framework of - * your choice. - */ +/// IO using sockets, file descriptors, or handles. + +/// Note that you can use proton::connection_engine to communicate +/// using AMQP over your own IO implementation or to integrate an +/// existing IO framework of your choice. + namespace io { -///@name Setup and tear-down IO functionality. -/// -/// Call proton::io::initialize before using any functions in the proton::io namespace. -/// Call proton::io::finalize when you are done. +/// @name Setup and teardown /// -/// You can call initialize/finalize more than once as long as they are in -/// matching pairs. Use proton::io::guard to call initialize/finalize around a scope. +/// Call proton::io::initialize before using any functions in the +/// proton::io namespace. Call proton::io::finalize when you are +/// done. /// -/// Note on POSIX systems these are no-ops, but they are required for Windows. +/// You can call initialize/finalize more than once as long as they +/// are in matching pairs. Use proton::io::guard to call +/// initialize/finalize around a scope. /// -///@{ +/// Note that on POSIX systems these are no-ops, but they are required +/// for Windows. /// -/// Initialize the proton::io subsystem +/// @{ + +/// Initialize the proton::io subsystem. PN_CPP_EXTERN void initialize(); -/// Finalize the proton::io subsystem -PN_CPP_EXTERN void finalize(); //nothrow +/// Finalize the proton::io subsystem. +PN_CPP_EXTERN void finalize(); // nothrow + +/// Use to call io::initialize and io::finalize around a scope. struct guard { guard() { initialize(); } ~guard() { finalize(); } }; -///@} +/// @} + +/// An IO resource. typedef int64_t descriptor; +/// @cond INTERNAL +/// don't know what it is PN_CPP_EXTERN extern const descriptor INVALID_DESCRIPTOR; +/// @endcond -// Return the string describing the most recent IO error. +/// Return a string describing the most recent IO error. PN_CPP_EXTERN std::string error_str(); /// Open a TCP connection to the host:port (port can be a service name or number) from a proton::url. @@ -90,6 +100,7 @@ class listener { descriptor socket_; }; +/// A connection_engine for socket-based IO. class socket_engine : public connection_engine { public: /// Wrap an open socket. Sets non-blocking mode. @@ -101,6 +112,7 @@ class socket_engine : public connection_engine { /// Get the socket descriptor. descriptor socket() const { return socket_; } + /// Start the engine. PN_CPP_EXTERN void run(); protected: diff --git a/proton-c/bindings/cpp/include/proton/link.hpp b/proton-c/bindings/cpp/include/proton/link.hpp index f3c62ef940..1852c61582 100644 --- a/proton-c/bindings/cpp/include/proton/link.hpp +++ b/proton-c/bindings/cpp/include/proton/link.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/endpoint.hpp" #include "proton/export.hpp" #include "proton/message.hpp" @@ -37,81 +38,104 @@ class sender; class receiver; class condition; -/** Messages are transferred across a link. Base class for sender, receiver. */ -class link : public object , public endpoint -{ +/// A named channel for sending or receiving messages. It is the base +/// class for sender and receiver. +class link : public object , public endpoint { public: + /// @cond INTERNAL link(pn_link_t* l=0) : object(l) {} + /// @endcond - /* Endpoint behaviours */ + // Endpoint behaviours + /// Get the state of this link. PN_CPP_EXTERN endpoint::state state() const; + PN_CPP_EXTERN condition local_condition() const; PN_CPP_EXTERN condition remote_condition() const; - /** Locally open the link, not complete till messaging_handler::on_link_opened or - * proton_handler::link_remote_open - */ + /// Locally open the link. The operation is not complete till + /// handler::on_link_open. PN_CPP_EXTERN void open(const link_options &opts = link_options()); - /** Locally close the link, not complete till messaging_handler::on_link_closed or - * proton_handler::link_remote_close - */ + /// Locally close the link. The operation is not complete till + /// handler::on_link_close. PN_CPP_EXTERN void close(); - /** Return sender if this link is a sender, 0 if not. */ + /// Return sender if this link is a sender, 0 if not. PN_CPP_EXTERN class sender sender(); + + /// Return sender if this link is a sender, 0 if not. PN_CPP_EXTERN const class sender sender() const; - /** Return receiver if this link is a receiver, 0 if not. */ + /// Return receiver if this link is a receiver, 0 if not. PN_CPP_EXTERN class receiver receiver(); + + /// Return receiver if this link is a receiver, 0 if not. PN_CPP_EXTERN const class receiver receiver() const; - /** Credit available on the link */ + /// Credit available on the link. PN_CPP_EXTERN int credit() const; - /** The number of queued deliveries for the link */ + /// The number of deliveries queued on the link. PN_CPP_EXTERN int queued(); - /** The number of unsettled deliveries on the link */ + /// @cond INTERNAL + /// XXX ask about when this is used + /// The number of unsettled deliveries on the link. PN_CPP_EXTERN int unsettled(); + /// @endcond - /** The count of credit returned. */ + /// @cond INTERNAL + /// XXX revisit mind-melting API inherited from C PN_CPP_EXTERN int drained(); + /// @endcond - /** Local source of the link. */ + /// Local source of the link. PN_CPP_EXTERN terminus local_source() const; - /** Local target of the link. */ + + /// Local target of the link. PN_CPP_EXTERN terminus local_target() const; - /** Remote source of the link. */ + + /// Remote source of the link. PN_CPP_EXTERN terminus remote_source() const; - /** Remote target of the link. */ + + /// Remote target of the link. PN_CPP_EXTERN terminus remote_target() const; - /** Link name */ + /// Get the link name. PN_CPP_EXTERN std::string name() const; - /** Connection that owns this link */ + /// Connection that owns this link. PN_CPP_EXTERN class connection connection() const; - /** Session that owns this link */ + /// Session that owns this link. PN_CPP_EXTERN class session session() const; - /** Set a custom handler for this link. */ + /// @cond INTERNAL + /// XXX settle open questions + + /// Set a custom handler for this link. PN_CPP_EXTERN void handler(proton_handler &); - /** Unset any custom handler */ + /// Unset any custom handler. PN_CPP_EXTERN void detach_handler(); - /** Get message data from current delivery on link */ + /// @cond INTERNAL + + /// XXX ask about use case, revisit names + /// Get message data from current delivery on link. PN_CPP_EXTERN ssize_t recv(char* buffer, size_t size); - /** Advance the link one delivery */ + /// XXX ask about use case, revisit names + /// Advance the link one delivery. PN_CPP_EXTERN bool advance(); - /** Navigate the links in a connection - get next link with state */ + /// XXX remove + /// Navigate the links in a connection - get next link with state. PN_CPP_EXTERN link next(endpoint::state) const; + /// XXX local versus remote, mutability PN_CPP_EXTERN link_options::sender_settle_mode sender_settle_mode(); PN_CPP_EXTERN void sender_settle_mode(link_options::sender_settle_mode); PN_CPP_EXTERN link_options::receiver_settle_mode receiver_settle_mode(); @@ -119,8 +143,11 @@ class link : public object , public endpoint PN_CPP_EXTERN link_options::sender_settle_mode remote_sender_settle_mode(); PN_CPP_EXTERN link_options::receiver_settle_mode remote_receiver_settle_mode(); + /// @endcond }; +/// @cond INTERNAL +/// XXX important to expose? /// An iterator for links. class link_iterator : public iter_base { public: @@ -134,12 +161,14 @@ class link_iterator : public iter_base { private: const session* session_; }; +/// @endcond /// A range of links. typedef range link_range; + } #include "proton/sender.hpp" #include "proton/receiver.hpp" -#endif /*!PROTON_CPP_LINK_H*/ +#endif // PROTON_CPP_LINK_H diff --git a/proton-c/bindings/cpp/include/proton/link_options.hpp b/proton-c/bindings/cpp/include/proton/link_options.hpp index 085d512be2..932e8b39be 100644 --- a/proton-c/bindings/cpp/include/proton/link_options.hpp +++ b/proton-c/bindings/cpp/include/proton/link_options.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/config.hpp" #include "proton/export.hpp" #include "proton/pn_unique_ptr.hpp" @@ -35,106 +36,146 @@ namespace proton { class proton_handler; class link; -/** Options for creating a link. - * - * Options can be "chained" like this: - * - * l = container.create_sender(url, link_options().handler(h).browsing(true)); - * - * You can also create an options object with common settings and use it as a base - * for different connections that have mostly the same settings: - * - * link_options opts; - * opts.browsing(true); - * l1 = container.open_sender(url1, opts.handler(h1)); - * c2 = container.open_receiver(url2, opts.handler(h2)); - * - * Normal value semantics, copy or assign creates a separate copy of the options. - */ +/// Options for creating a link. +/// +/// Options can be "chained" like this: +/// +/// @code +/// l = container.create_sender(url, link_options().handler(h).browsing(true)); +/// @endcode +/// +/// You can also create an options object with common settings and use +/// it as a base for different connections that have mostly the same +/// settings: +/// +/// @code +/// link_options opts; +/// opts.browsing(true); +/// l1 = container.open_sender(url1, opts.handler(h1)); +/// c2 = container.open_receiver(url2, opts.handler(h2)); +/// @endcode +/// +/// Normal value semantics: copy or assign creates a separate copy of +/// the options. class link_options { public: - /** The message delivery policy to establish when opening a link. */ + /// The message delivery policy to establish when opening a link. enum delivery_mode { - // No set policy. The application must settle messages itself according to its own policy. + // No set policy. The application must settle messages itself + // according to its own policy. DELIVERY_MODE_NONE = 0, - // Outgoing messages are settled immediately by the link. There are no duplicates. + // Outgoing messages are settled immediately by the link. + // There are no duplicates. AT_MOST_ONCE, - // The receiver settles the delivery first with an accept/reject/release disposition. - // The sender waits to settle until after the disposition notification is received. + // The receiver settles the delivery first with an + // accept/reject/release disposition. The sender waits to + // settle until after the disposition notification is + // received. AT_LEAST_ONCE }; - /// Sender settlement behaviour for a link + /// Sender settlement behaviour for a link. enum sender_settle_mode { UNSETTLED = PN_SND_UNSETTLED, SETTLED = PN_SND_SETTLED, MIXED = PN_SND_MIXED }; - /// Receiver settlement behaviour for a link + /// @cond INTERNAL + /// XXX discuss the names + /// Receiver settlement behaviour for a link. enum receiver_settle_mode { SETTLE_ALWAYS = PN_RCV_FIRST, SETTLE_SECOND= PN_RCV_SECOND }; + /// @endcond - /** The lifetime of dynamically created nodes. */ + /// The lifetime of dynamically created nodes. enum lifetime_policy { // The policy is unspecified. LIFETIME_UNSPECIFIED = 0, - // The lifetime of the dynamic node is scoped to lifetime of the creating link. + // The lifetime of the dynamic node is scoped to lifetime of + // the creating link. DELETE_ON_CLOSE = 0x2B, - // The node will be deleted when it is neither the source nor the target of any link. + // The node will be deleted when it is neither the source nor + // the target of any link. DELETE_ON_NO_LINKS = 0x2C, - // The node will be deleted when the creating link no longer exists and no messages remain at the node. + // The node will be deleted when the creating link no longer + // exists and no messages remain at the node. DELETE_ON_NO_MESSAGES = 0x2D, - // The node will be deleted when there are no links which have this node as - // their source or target, and there remain no messages at the node. + // The node will be deleted when there are no links which have + // this node as their source or target, and there remain no + // messages at the node. DELETE_ON_NO_LINKS_OR_MESSAGES = 0x2E }; - + /// Create an empty set of options. PN_CPP_EXTERN link_options(); + + /// Copy options. PN_CPP_EXTERN link_options(const link_options&); + PN_CPP_EXTERN ~link_options(); + + /// Copy options. PN_CPP_EXTERN link_options& operator=(const link_options&); /// Override with options from other. PN_CPP_EXTERN void override(const link_options& other); - /** Set a handler for events scoped to the link. If NULL, link-scoped events on the link are discarded. */ + /// Set a handler for events scoped to the link. If NULL, + /// link-scoped events on the link are discarded. PN_CPP_EXTERN link_options& handler(class handler *); - /** Receiver-only option to specify whether messages are browsed or - consumed. Setting browsing to true is Equivalent to setting - distribution_mode(COPY). Setting browsing to false is equivalent to - setting distribution_mode(MOVE). */ + + /// Receiver-only option to specify whether messages are browsed + /// or consumed. Setting browsing to true is equivalent to + /// setting distribution_mode(COPY). Setting browsing to false is + /// equivalent to setting distribution_mode(MOVE). PN_CPP_EXTERN link_options& browsing(bool); - /** Set the distribution mode for message transfer. See terminus::distribution_mode. */ + + /// Set the distribution mode for message transfer. PN_CPP_EXTERN link_options& distribution_mode(enum terminus::distribution_mode); - /* Receiver-only option to create a durable subsription on the receiver. - Equivalent to setting the terminus durability to termins::DELIVERIES and - the expiry policy to terminus::EXPIRE_NEVER. */ + + /// Receiver-only option to create a durable subsription on the + /// receiver. Equivalent to setting the terminus durability to + /// terminus::DELIVERIES and the expiry policy to + /// terminus::EXPIRE_NEVER. PN_CPP_EXTERN link_options& durable_subscription(bool); - /* Set the delivery mode on the link. */ + + /// Set the delivery mode on the link. PN_CPP_EXTERN link_options& delivery_mode(delivery_mode); - /* Request a dynamically generated node at the peer. */ + + /// Request a dynamically generated node at the peer. PN_CPP_EXTERN link_options& dynamic_address(bool); - /* Set the lifetime policy for a receiver to a dynamically created node. */ + + /// Set the lifetime policy for a receiver to a dynamically + /// created node. PN_CPP_EXTERN link_options& lifetime_policy(lifetime_policy); - /* Set the local address for the link. */ + + /// Set the local address for the link. PN_CPP_EXTERN link_options& local_address(const std::string &addr); - /* Set a selector on the receiver to str. This sets a single registered filter on the link of - type apache.org:selector-filter with value str. */ + + /// @cond INTERNAL + /// XXX need to discuss spec issues, jms versus amqp filters + /// + /// Set a selector on the receiver to str. This sets a single + /// registered filter on the link of type + /// apache.org:selector-filter with value str. PN_CPP_EXTERN link_options& selector(const std::string &str); + /// @endcond private: - friend class link; void apply(link&) const; proton_handler* handler() const; class impl; pn_unique_ptr impl_; + + /// @cond INTERNAL + friend class link; + /// @endcond }; -} // namespace +} -#endif /*!PROTON_CPP_LINK_OPTIONS_H*/ +#endif // PROTON_CPP_LINK_OPTIONS_H diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp index aeabbcb46c..645da861ff 100644 --- a/proton-c/bindings/cpp/include/proton/message.hpp +++ b/proton-c/bindings/cpp/include/proton/message.hpp @@ -42,198 +42,222 @@ class delivery; class message_id; class annotation_key; -/** An AMQP message. Value semantics, can be copied or assigned to make a new message. */ -class message -{ +/// An AMQP message. +/// +/// Value semantics: can be copied or assigned to make a new message. +class message { public: + /// A map of string keys and AMQP scalar values. typedef std::map property_map; + + /// A map of AMQP annotation keys and AMQP values. typedef std::map annotation_map; + /// Create an empty message. PN_CPP_EXTERN message(); + + /// Copy a message. PN_CPP_EXTERN message(const message&); + #if PN_HAS_CPP11 PN_CPP_EXTERN message(message&&); #endif - /// Construct a message from any value that can be assigned to a proton::value - template message(const T& x) : pn_msg_(0) { body() = x; } + /// Create a message with its body set from any value that can be + /// assigned to a proton::value. + template message(const T& x) : pn_msg_(0) { body() = x; } PN_CPP_EXTERN ~message(); + /// Copy a message. PN_CPP_EXTERN message& operator=(const message&); - /** Clear the message content and properties. */ - PN_CPP_EXTERN void clear(); + /// @name Basic properties and methods + /// @{ - ///@name Standard AMQP message properties - ///@{ + /// Clear the message content and properties. + PN_CPP_EXTERN void clear(); PN_CPP_EXTERN void id(const message_id& id); PN_CPP_EXTERN message_id id() const; + /// @cond INTERNAL + /// XXX consider just user, in order to be consistent with similar + /// fields elsewhere in the API PN_CPP_EXTERN void user_id(const std::string &user); PN_CPP_EXTERN std::string user_id() const; + /// @endcond - PN_CPP_EXTERN void address(const std::string &addr); - PN_CPP_EXTERN std::string address() const; - - PN_CPP_EXTERN void subject(const std::string &s); - PN_CPP_EXTERN std::string subject() const; + /// Encode entire message into a byte vector, growing it if + /// necessary. + PN_CPP_EXTERN void encode(std::vector &bytes) const; - PN_CPP_EXTERN void reply_to(const std::string &s); - PN_CPP_EXTERN std::string reply_to() const; + /// Return encoded message as a byte vector. + PN_CPP_EXTERN std::vector encode() const; - PN_CPP_EXTERN void correlation_id(const message_id&); - PN_CPP_EXTERN message_id correlation_id() const; + /// Decode from string data into the message. + PN_CPP_EXTERN void decode(const std::vector &bytes); - PN_CPP_EXTERN void content_type(const std::string &s); - PN_CPP_EXTERN std::string content_type() const; + /// @cond INTERNAL + /// XXX should a delivery know its own link already? + /// + /// Decode the message corresponding to a delivery from a link. + PN_CPP_EXTERN void decode(proton::link, proton::delivery); + /// @endcond - PN_CPP_EXTERN void content_encoding(const std::string &s); - PN_CPP_EXTERN std::string content_encoding() const; + /// @} - PN_CPP_EXTERN void expiry_time(amqp_timestamp t); - PN_CPP_EXTERN amqp_timestamp expiry_time() const; + /// @name Routing + /// @{ - PN_CPP_EXTERN void creation_time(amqp_timestamp t); - PN_CPP_EXTERN amqp_timestamp creation_time() const; + PN_CPP_EXTERN void address(const std::string &addr); + PN_CPP_EXTERN std::string address() const; + + PN_CPP_EXTERN void reply_to(const std::string &addr); + PN_CPP_EXTERN std::string reply_to() const; - PN_CPP_EXTERN void group_id(const std::string &s); - PN_CPP_EXTERN std::string group_id() const; + PN_CPP_EXTERN void correlation_id(const message_id&); + PN_CPP_EXTERN message_id correlation_id() const; - PN_CPP_EXTERN void reply_to_group_id(const std::string &s); - PN_CPP_EXTERN std::string reply_to_group_id() const; + /// @} - ///@} + /// @name Content + /// @{ - /** Set the body, equivalent to body() = v */ + /// Set the body, equivalent to body() = v template void body(const T& v) { body() = v; } - /** Get the body. */ + /// Get the body. PN_CPP_EXTERN const value& body() const; - /** Get a reference to the body that can be modified in-place. */ + /// Get a reference to the body that can be modified in-place. PN_CPP_EXTERN value& body(); - /** Application properties map, can be modified in place. */ - PN_CPP_EXTERN property_map& application_properties(); - PN_CPP_EXTERN const property_map& application_properties() const; - - /** Message annotations map, can be modified in place. */ - PN_CPP_EXTERN annotation_map& message_annotations(); - PN_CPP_EXTERN const annotation_map& message_annotations() const; - - /** Delivery annotations map, can be modified in place. */ - PN_CPP_EXTERN annotation_map& delivery_annotations(); - PN_CPP_EXTERN const annotation_map& delivery_annotations() const; + PN_CPP_EXTERN void subject(const std::string &s); + PN_CPP_EXTERN std::string subject() const; - /** Encode entire message into a byte vector, growing it if necessary. */ - PN_CPP_EXTERN void encode(std::vector &bytes) const; + PN_CPP_EXTERN void content_type(const std::string &s); + PN_CPP_EXTERN std::string content_type() const; - /** Return encoded message as a byte vector */ - PN_CPP_EXTERN std::vector encode() const; + PN_CPP_EXTERN void content_encoding(const std::string &s); + PN_CPP_EXTERN std::string content_encoding() const; - /** Decode from string data into the message. */ - PN_CPP_EXTERN void decode(const std::vector &bytes); + PN_CPP_EXTERN void expiry_time(amqp_timestamp t); + PN_CPP_EXTERN amqp_timestamp expiry_time() const; - /** Decode the message corresponding to a delivery from a link. */ - PN_CPP_EXTERN void decode(proton::link, proton::delivery); + PN_CPP_EXTERN void creation_time(amqp_timestamp t); + PN_CPP_EXTERN amqp_timestamp creation_time() const; - /** - * Get the inferred flag for a message. - * - * The inferred flag for a message indicates how the message content - * is encoded into AMQP sections. If inferred is true then binary and - * list values in the body of the message will be encoded as AMQP DATA - * and AMQP SEQUENCE sections, respectively. If inferred is false, - * then all values in the body of the message will be encoded as AMQP - * VALUE sections regardless of their type. - */ + /// Get the inferred flag for a message. + /// + /// The inferred flag for a message indicates how the message + /// content is encoded into AMQP sections. If inferred is true + /// then binary and list values in the body of the message will be + /// encoded as AMQP DATA and AMQP SEQUENCE sections, + /// respectively. If inferred is false, then all values in the + /// body of the message will be encoded as AMQP VALUE sections + /// regardless of their type. PN_CPP_EXTERN bool inferred() const; - /** Get the inferred flag for a message. */ + /// Set the inferred flag for a message. PN_CPP_EXTERN void inferred(bool); - /** - * Get the durable flag for a message. - * - * The durable flag indicates that any parties taking responsibility - * for the message must durably store the content. - * - * @return the value of the durable flag - */ + /// @} + + /// @name Transfer headers + /// @{ + + /// Get the durable flag for a message. + /// + /// The durable flag indicates that any parties taking + /// responsibility for the message must durably store the content. + /// + /// @return the value of the durable flag PN_CPP_EXTERN bool durable() const; - /** Set the durable flag for a message. */ + /// Set the durable flag for a message. PN_CPP_EXTERN void durable(bool); - /** - * Get the ttl for a message. - * - * The ttl for a message determines how long a message is considered - * live. When a message is held for retransmit, the ttl is - * decremented. Once the ttl reaches zero, the message is considered - * dead. Once a message is considered dead it may be dropped. - * - * @return the ttl in milliseconds - */ + /// Get the TTL for a message. + /// + /// The TTL (time to live) for a message determines how long a + /// message is considered live. When a message is held for + /// retransmit, the TTL is decremented. Once the TTL reaches zero, + /// the message is considered dead. Once a message is considered + /// dead it may be dropped. PN_CPP_EXTERN duration ttl() const; - /** Set the ttl for a message */ + + /// Set the TTL for a message. PN_CPP_EXTERN void ttl(duration); - /** - * Get the priority for a message. - * - * The priority of a message impacts ordering guarantees. Within a - * given ordered context, higher priority messages may jump ahead of - * lower priority messages. - * - * @return the message priority - */ + /// Get the priority for a message. + /// + /// The priority of a message impacts ordering guarantees. Within + /// a given ordered context, higher priority messages may jump + /// ahead of lower priority messages. PN_CPP_EXTERN uint8_t priority() const; - /** Set the priority for a message. */ + + /// Set the priority for a message. PN_CPP_EXTERN void priority(uint8_t); - /** - * Get the first acquirer flag for a message. - * - * When set to true, the first acquirer flag for a message indicates - * that the recipient of the message is the first recipient to acquire - * the message, i.e. there have been no failed delivery attempts to - * other acquirers. Note that this does not mean the message has not - * been delivered to, but not acquired, by other recipients. - * - * @return the first acquirer flag for the message - */ + /// Get the first acquirer flag for a message. + /// + /// When set to true, the first acquirer flag for a message + /// indicates that the recipient of the message is the first + /// recipient to acquire the message, i.e. there have been no + /// failed delivery attempts to other acquirers. Note that this + /// does not mean the message has not been delivered to, but not + /// acquired, by other recipients. PN_CPP_EXTERN bool first_acquirer() const; - /** Set the first acquirer flag for a message. */ + + /// Set the first acquirer flag for a message. PN_CPP_EXTERN void first_acquirer(bool); - /** - * Get the delivery count for a message. - * - * The delivery count field tracks how many attempts have been made to - * delivery a message. - * - * @return the delivery count for the message - */ + /// Get the delivery count for a message. + /// + /// The delivery count field tracks how many attempts have been made to + /// delivery a message. PN_CPP_EXTERN uint32_t delivery_count() const; - /** Get the delivery count for a message. */ + + /// Get the delivery count for a message. PN_CPP_EXTERN void delivery_count(uint32_t); - /** - * Get the group sequence for a message. - * - * The group sequence of a message identifies the relative ordering of - * messages within a group. The default value for the group sequence - * of a message is zero. - * - * @return the group sequence for the message - */ + /// @} + + /// @name Message groups + /// @{ + + PN_CPP_EXTERN void group_id(const std::string &s); + PN_CPP_EXTERN std::string group_id() const; + + PN_CPP_EXTERN void reply_to_group_id(const std::string &s); + PN_CPP_EXTERN std::string reply_to_group_id() const; + + /// Get the group sequence for a message. + /// + /// The group sequence of a message identifies the relative + /// ordering of messages within a group. The default value for the + /// group sequence of a message is zero. PN_CPP_EXTERN int32_t group_sequence() const; - /** Set the group sequence for a message. */ + /// Set the group sequence for a message. PN_CPP_EXTERN void group_sequence(int32_t); + /// @} + + /// @name Extended attributes + /// @{ - friend PN_CPP_EXTERN void swap(message&, message&); + /// Application properties map, can be modified in place. + PN_CPP_EXTERN property_map& application_properties(); + PN_CPP_EXTERN const property_map& application_properties() const; + + /// Message annotations map, can be modified in place. + PN_CPP_EXTERN annotation_map& message_annotations(); + PN_CPP_EXTERN const annotation_map& message_annotations() const; + + /// Delivery annotations map, can be modified in place. + PN_CPP_EXTERN annotation_map& delivery_annotations(); + PN_CPP_EXTERN const annotation_map& delivery_annotations() const; + + /// @} private: pn_message_t *pn_msg() const; @@ -243,8 +267,13 @@ class message mutable property_map application_properties_; mutable annotation_map message_annotations_; mutable annotation_map delivery_annotations_; + + /// @cond INTERNAL + /// XXX settle necessity (there were some other options) + friend PN_CPP_EXTERN void swap(message&, message&); + /// @endcond }; } -#endif /*!PROTON_CPP_MESSAGE_H*/ +#endif // PROTON_CPP_MESSAGE_H diff --git a/proton-c/bindings/cpp/include/proton/message_id.hpp b/proton-c/bindings/cpp/include/proton/message_id.hpp index b08482fdfa..0adef07e45 100644 --- a/proton-c/bindings/cpp/include/proton/message_id.hpp +++ b/proton-c/bindings/cpp/include/proton/message_id.hpp @@ -1,5 +1,6 @@ #ifndef MESSAGE_ID_HPP #define MESSAGE_ID_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -23,18 +24,28 @@ #include "proton/scalar.hpp" namespace proton { + class encoder; class decoder; -/** A message_id can contain one of the following types: - * uint64_t, amqp_uuid, amqp_binary or amqp_string. - */ +/// An AMQP message ID. +/// +/// It can contain one of the following types: +/// +/// - uint64_t +/// - proton::amqp::amqp_uuid +/// - proton::amqp::amqp_binary +/// - proton::amqp::amqp_string class message_id : public restricted_scalar { public: + /// Create an empty (0) message ID. message_id() { scalar_ = uint64_t(0); } - ///@name Assign a C++ value, deduce the AMQP type() - ///@{ + /// @name Assignment operators + /// + /// Assign a C++ value, deduce the AMQP type() + /// + /// @{ message_id& operator=(uint64_t x) { scalar_ = x; return *this; } message_id& operator=(const amqp_uuid& x) { scalar_ = x; return *this; } message_id& operator=(const amqp_binary& x) { scalar_ = x; return *this; } @@ -43,21 +54,31 @@ class message_id : public restricted_scalar { message_id& operator=(const std::string& x) { scalar_ = amqp_string(x); return *this; } /// char* is encoded as amqp_string message_id& operator=(const char *x) { scalar_ = amqp_string(x); return *this; } - ///@} + /// @} - /// Converting constructor from any type that we can assign from. + /// Create a message ID from any type that we can assign from. template message_id(T x) { *this = x; } + /// @name Get methods + /// + /// get(T&) extracts the value if the types match exactly and + /// throws type_error otherwise. + /// + /// @{ void get(uint64_t& x) const { scalar_.get(x); } void get(amqp_uuid& x) const { scalar_.get(x); } void get(amqp_binary& x) const { scalar_.get(x); } void get(amqp_string& x) const { scalar_.get(x); } + /// @} + /// Return the value as type T. template T get() const { T x; get(x); return x; } - friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&); - friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&); - friend class message; + /// @cond INTERNAL + friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&); + friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&); + friend class message; + /// @endcond }; } diff --git a/proton-c/bindings/cpp/include/proton/object.hpp b/proton-c/bindings/cpp/include/proton/object.hpp index cc2bd31a7c..4e12e6fe9c 100644 --- a/proton-c/bindings/cpp/include/proton/object.hpp +++ b/proton-c/bindings/cpp/include/proton/object.hpp @@ -1,5 +1,6 @@ #ifndef OBJECT_HPP #define OBJECT_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,6 +20,8 @@ * under the License. */ +/// @cond INTERNAL + #include "proton/config.hpp" #include "proton/export.hpp" #include "proton/comparable.hpp" @@ -26,7 +29,6 @@ namespace proton { -///@cond INTERNAL class pn_ptr_base { protected: PN_CPP_EXTERN static void incref(void* p); @@ -51,9 +53,6 @@ template class pn_ptr : private pn_ptr_base, public comparable(p, true); } private: @@ -62,29 +61,31 @@ template class pn_ptr : private pn_ptr_base, public comparable pn_ptr take_ownership(T* p) { return pn_ptr::take_ownership(p); } -///@endcond INTERNAL - -/** - * Base class for proton object types - */ +/// Base class for proton object types. template class object : public comparable > { public: bool operator!() const { return !object_; } - friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; } - friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; } - protected: object(pn_ptr o) : object_(o) {} T* pn_object() const { return object_.get(); } private: pn_ptr object_; + + friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; } + friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; } }; } + +/// @endcond + #endif // OBJECT_HPP diff --git a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp index 6533b0bfb5..12636eb425 100644 --- a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp +++ b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp @@ -19,21 +19,22 @@ * under the License. */ +/// @cond INTERNAL +/// XXX discuss where this gets exposed + #include "proton/config.hpp" #include namespace proton { -/** - * A simple unique ownership pointer, used as a return value from functions that - * transfer ownership to the caller. - * - * pn_unique_ptr return values should be converted immediately to - * std::unique_ptr if that is available or std::auto_ptr (by calling release()) - * for older C++. You should not use pn_unique_ptr in your own code, it is a - * limited pointer class designed only to work around differences between C++11 - * and C++03. - */ +/// A simple unique ownership pointer, used as a return value from +/// functions that transfer ownership to the caller. +/// +/// pn_unique_ptr return values should be converted immediately to +/// std::unique_ptr if that is available or std::auto_ptr (by calling +/// release()) for older C++. You should not use pn_unique_ptr in your +/// own code. It is a limited pointer class designed only to work +/// around differences between C++11 and C++03. template class pn_unique_ptr { public: pn_unique_ptr(T* p=0) : ptr_(p) {} @@ -59,5 +60,8 @@ template class pn_unique_ptr { T* ptr_; }; +/// @endcond + } + #endif // UNIQUE_PTR_HPP diff --git a/proton-c/bindings/cpp/include/proton/reactor.hpp b/proton-c/bindings/cpp/include/proton/reactor.hpp index 7592a148b2..82514058cc 100644 --- a/proton-c/bindings/cpp/include/proton/reactor.hpp +++ b/proton-c/bindings/cpp/include/proton/reactor.hpp @@ -1,5 +1,6 @@ #ifndef REACTOR_HPP #define REACTOR_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,6 +20,9 @@ * under the License. */ +/// @cond INTERNAL +/// XXX remove + #include "proton/object.hpp" #include "proton/duration.hpp" @@ -91,4 +95,7 @@ class reactor : public object { }; } + +/// @endcond + #endif // REACTOR_HPP diff --git a/proton-c/bindings/cpp/include/proton/receiver.hpp b/proton-c/bindings/cpp/include/proton/receiver.hpp index d0df703db6..11569e4267 100644 --- a/proton-c/bindings/cpp/include/proton/receiver.hpp +++ b/proton-c/bindings/cpp/include/proton/receiver.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/endpoint.hpp" #include "proton/link.hpp" @@ -31,11 +32,12 @@ struct pn_connection_t; namespace proton { -/// A receiving link -class receiver : public link -{ +/// A link for receiving messages. +class receiver : public link { public: + /// @cond INTERNAL receiver(pn_link_t* r=0) : link(r) {} + /// @endcond /// Add credit to the link PN_CPP_EXTERN void flow(int count); @@ -43,4 +45,4 @@ class receiver : public link } -#endif /*!PROTON_CPP_RECEIVER_H*/ +#endif // PROTON_CPP_RECEIVER_H diff --git a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp index f89f47e137..d7b720f99c 100644 --- a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp +++ b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp @@ -22,6 +22,9 @@ * */ +/// @cond INTERNAL +/// XXX more discussion + #include "proton/export.hpp" #include "proton/types.hpp" #include "proton/reactor.hpp" @@ -55,9 +58,12 @@ class reconnect_timer int32_t next_delay_; pn_timestamp_t timeout_deadline_; reactor reactor_; + friend class connector; }; +/// @endcond + } -#endif /*!PROTON_CPP_RECONNECT_H*/ +#endif // PROTON_CPP_RECONNECT_H diff --git a/proton-c/bindings/cpp/include/proton/sasl.hpp b/proton-c/bindings/cpp/include/proton/sasl.hpp index 98cfea7960..53052d72d6 100644 --- a/proton-c/bindings/cpp/include/proton/sasl.hpp +++ b/proton-c/bindings/cpp/include/proton/sasl.hpp @@ -21,40 +21,59 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/sasl.h" #include namespace proton { +/// SASL information. class sasl { public: - /** The result of the SASL negotiation */ + /// The result of the SASL negotiation. enum outcome { - NONE = PN_SASL_NONE, /** negotiation not completed */ - OK = PN_SASL_OK, /** authentication succeeded */ - AUTH = PN_SASL_AUTH, /** failed due to bad credentials */ - SYS = PN_SASL_SYS, /** failed due to a system error */ - PERM = PN_SASL_PERM, /** failed due to unrecoverable error */ - TEMP = PN_SASL_TEMP /** failed due to transient error */ + NONE = PN_SASL_NONE, ///< Negotiation not completed + OK = PN_SASL_OK, ///< Authentication succeeded + AUTH = PN_SASL_AUTH, ///< Failed due to bad credentials + SYS = PN_SASL_SYS, ///< Failed due to a system error + PERM = PN_SASL_PERM, ///< Failed due to unrecoverable error + TEMP = PN_SASL_TEMP ///< Failed due to transient error }; + /// @cond INTERNAL + /// XXX need to discuss sasl(pn_sasl_t* s) : object_(s) {} PN_CPP_EXTERN static bool extended(); PN_CPP_EXTERN void done(enum outcome); + /// @endcond + + /// Get the outcome. PN_CPP_EXTERN enum outcome outcome() const; + + /// Get the user name. PN_CPP_EXTERN std::string user() const; + + /// Get the mechanism. PN_CPP_EXTERN std::string mech() const; + /// @cond INTERNAL PN_CPP_EXTERN void allow_insecure_mechs(bool); + /// @endcond + + /// True if insecure mechanisms are permitted. PN_CPP_EXTERN bool allow_insecure_mechs(); + + /// @cond INTERNAL + /// XXX setters? versus connection options PN_CPP_EXTERN void allowed_mechs(const std::string &); PN_CPP_EXTERN void config_name(const std::string&); PN_CPP_EXTERN void config_path(const std::string&); + /// @endcond private: pn_sasl_t* object_; }; } -#endif /*!PROTON_CPP_SASL_H*/ +#endif // PROTON_CPP_SASL_H diff --git a/proton-c/bindings/cpp/include/proton/scalar.hpp b/proton-c/bindings/cpp/include/proton/scalar.hpp index c06a67523a..3975301e8b 100644 --- a/proton-c/bindings/cpp/include/proton/scalar.hpp +++ b/proton-c/bindings/cpp/include/proton/scalar.hpp @@ -1,5 +1,6 @@ #ifndef SCALAR_HPP #define SCALAR_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -30,11 +31,16 @@ namespace proton { class encoder; class decoder; -/** scalar holds an instance of any scalar AMQP type. */ +/// A holder for an instance of any scalar AMQP type. class scalar : public comparable { public: + /// Create an empty scalar. PN_CPP_EXTERN scalar(); + + /// Copy a scalar. PN_CPP_EXTERN scalar(const scalar&); + + /// Copy a scalar. PN_CPP_EXTERN scalar& operator=(const scalar&); /// Type for the value in the scalar, NULL_TYPE if empty() @@ -43,8 +49,11 @@ class scalar : public comparable { /// True if the scalar is empty. PN_CPP_EXTERN bool empty() const; - ///@name Assign a C++ value, deduce the AMQP type() - ///@{ + /// @name Assignment operators + /// + /// Assign a C++ value and deduce the AMQP type(). + /// + /// @{ PN_CPP_EXTERN scalar& operator=(bool); PN_CPP_EXTERN scalar& operator=(uint8_t); PN_CPP_EXTERN scalar& operator=(int8_t); @@ -67,13 +76,17 @@ class scalar : public comparable { PN_CPP_EXTERN scalar& operator=(const amqp_binary&); PN_CPP_EXTERN scalar& operator=(const std::string& s); ///< Treated as an AMQP string PN_CPP_EXTERN scalar& operator=(const char* s); ///< Treated as an AMQP string - ///@} + /// @} - /// Construct from any type that we can assign from. + /// Create a scalar from any type that we can assign from. template explicit scalar(T x) { *this = x; } - ///@name get(T&) extracts the value if the types match exactly, throws type_error otherwise. - ///@{ + /// @name Get methods + /// + /// get(T&) extracts the value if the types match exactly and + /// throws type_error otherwise. + /// + /// @{ PN_CPP_EXTERN void get(bool&) const; PN_CPP_EXTERN void get(uint8_t&) const; PN_CPP_EXTERN void get(int8_t&) const; @@ -95,25 +108,30 @@ class scalar : public comparable { PN_CPP_EXTERN void get(amqp_symbol&) const; PN_CPP_EXTERN void get(amqp_binary&) const; PN_CPP_EXTERN void get(std::string&) const; ///< Treated as an AMQP string - ///@} + /// @} - ///@ get() is like get(T&) but returns the value.. + /// get() is like get(T&) but returns the value. template T get() const { T x; get(x); return x; } - ///@name as_ methods do "loose" conversion, they will convert the scalar's - ///value to the requested type if possible, else throw type_error - ///@{ - PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN double as_double() const; ///< Allowed if type_id_is_floating_point(type()) + /// @name As methods + /// + /// As methods do "loose" conversion. They will convert the + /// scalar's value to the requested type if possible, else throw + /// type_error. + /// + /// @{ + PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if type_id_is_integral(type()) + PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if type_id_is_integral(type()) + PN_CPP_EXTERN double as_double() const; ///< Allowed if type_id_is_floating_point(type()) PN_CPP_EXTERN std::string as_string() const; ///< Allowed if type_id_is_string_like(type()) - ///@} + /// @} + /// @cond INTERNAL + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const scalar&); friend PN_CPP_EXTERN encoder operator<<(encoder, const scalar&); friend PN_CPP_EXTERN decoder operator>>(decoder, scalar&); - /// Scalars with different type() are considered unequal even if the values /// are equal as numbers or strings. friend PN_CPP_EXTERN bool operator==(const scalar& x, const scalar& y); @@ -121,6 +139,8 @@ class scalar : public comparable { /// For scalars of different type(), operator< sorts by order of type(). friend PN_CPP_EXTERN bool operator<(const scalar& x, const scalar& y); + /// @endcond + private: void ok(pn_type_t) const; void set(const std::string&, pn_type_t); @@ -131,29 +151,39 @@ class scalar : public comparable { friend class message; }; -///@internal base for restricted scalar types +/// @cond INTERNAL +/// XXX should it be public? + +/// Base class for restricted scalar types. class restricted_scalar : public comparable { public: operator const scalar&() const { return scalar_; } type_id type() const { return scalar_.type(); } - ///@name as_ methods do "loose" conversion, they will convert the scalar's - ///value to the requested type if possible, else throw type_error - ///@{ + /// @name As methods + /// + /// As methods do "loose" conversion. They will convert the + /// scalar's value to the requested type if possible, else throw + /// type_error. + /// + /// @{ int64_t as_int() const { return scalar_.as_int(); } uint64_t as_uint() const { return scalar_.as_uint(); } double as_double() const { return scalar_.as_double(); } std::string as_string() const { return scalar_.as_string(); } - ///@} - - friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x) { return o << x.scalar_; } - friend bool operator<(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ < y.scalar_; } - friend bool operator==(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ == y.scalar_; } + /// @} protected: restricted_scalar() {} scalar scalar_; + + friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x) { return o << x.scalar_; } + friend bool operator<(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ < y.scalar_; } + friend bool operator==(const restricted_scalar& x, const restricted_scalar& y) { return x.scalar_ == y.scalar_; } }; +/// @endcond + } + #endif // SCALAR_HPP diff --git a/proton-c/bindings/cpp/include/proton/sender.hpp b/proton-c/bindings/cpp/include/proton/sender.hpp index a5835fdda6..178497708a 100644 --- a/proton-c/bindings/cpp/include/proton/sender.hpp +++ b/proton-c/bindings/cpp/include/proton/sender.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/delivery.hpp" #include "proton/link.hpp" @@ -33,26 +34,31 @@ struct pn_connection_t; namespace proton { -/// A sending link +/// A link for sending messages. class sender : public link { public: + /// @cond INTERNAL sender(pn_link_t* s=0) : link(s) {} + /// @endcond /// Send a message on the link. PN_CPP_EXTERN delivery send(const message &m); - /** The number of deliveries that might be able to be sent if sufficient credit were - issued on the link. See sender::offered(). Maintained by the application. */ + /// @cond INTERNAL + /// XXX undiscussed + + /// The number of deliveries that might be able to be sent if + /// sufficient credit were issued on the link. See + /// sender::offered(). Maintained by the application. PN_CPP_EXTERN int available(); - /** Set the availability of deliveries for a sender. */ + /// Set the availability of deliveries for a sender. PN_CPP_EXTERN void offered(int c); - + /// @endcond }; - } -#endif /*!PROTON_CPP_SENDER_H*/ +#endif // PROTON_CPP_SENDER_H diff --git a/proton-c/bindings/cpp/include/proton/session.hpp b/proton-c/bindings/cpp/include/proton/session.hpp index e88273efba..a16fbe3fa4 100644 --- a/proton-c/bindings/cpp/include/proton/session.hpp +++ b/proton-c/bindings/cpp/include/proton/session.hpp @@ -21,6 +21,7 @@ * under the License. * */ + #include "proton/export.hpp" #include "proton/endpoint.hpp" #include "proton/link.hpp" @@ -37,58 +38,73 @@ namespace proton { class container; class handler; -/** A session is a collection of links */ +/// A container of links. class session : public object, public endpoint { public: + /// @cond INTERNAL session(pn_session_t* s=0) : object(s) {} + /// @endcond - /* Endpoint behaviours */ + // Endpoint behaviours + /// Get the state of this session. PN_CPP_EXTERN endpoint::state state() const; + PN_CPP_EXTERN condition local_condition() const; PN_CPP_EXTERN condition remote_condition() const; - /** Initiate local open, not complete till messaging_handler::on_session_opened() - * or proton_handler::on_session_remote_open() - */ + /// @cond INTERNAL + /// XXX needs to take connection options + /// Initiate local open. The operation is not complete till + /// handler::on_session_open(). PN_CPP_EXTERN void open(); - - /** Initiate local close, not complete till messaging_handler::on_session_closed() - * or proton_handler::on_session_remote_close() - */ + /// @endcond + + /// Initiate local close. The operation is not complete till + /// handler::on_session_close(). PN_CPP_EXTERN void close(); - /// Get connection + /// Get the connection this session belongs to. PN_CPP_EXTERN class connection connection() const; - /** An un-opened receiver link, you can set link properties before calling open(). - * - *@param name if specified must be unique, by default the container generates a name - * of the form: + "@" + container.id() - */ + /// @cond INTERNAL + /// XXX consider removing + + /// An unopened receiver link, you can set link properties before calling open(). + /// + /// @param name if specified must be unique, by default the + /// container generates a name of the form: + "@" + + /// container.id() PN_CPP_EXTERN receiver create_receiver(const std::string& name=""); - /** An un-opened sender link, you can set link properties before calling open(). - * - *@param name if specified must be unique, by default the container generates a name - * of the form: + "@" + container.id() - */ + /// An unopened sender link, you can set link properties before calling open(). + /// + /// @param name if specified must be unique, by default the + /// container generates a name of the form: + "@" + + /// container.id() PN_CPP_EXTERN sender create_sender(const std::string& name=""); - /** Create and open a sender with target=addr and optional link options opts*/ + /// @endcond + + /// Open a sender for `addr`. PN_CPP_EXTERN sender open_sender(const std::string &addr, const link_options &opts = link_options()); - /** Create and open a receiver with target=addr and optional link options opts */ + /// Open a receiver for `addr`. PN_CPP_EXTERN receiver open_receiver(const std::string &addr, const link_options &opts = link_options()); - /** Navigate the sessions in a connection - get next session with endpoint state*/ + /// @cond INTERNAL + /// XXX is this or should this be obviated by find functions? + /// Navigate the sessions in a connection - get next session with endpoint state PN_CPP_EXTERN session next(endpoint::state) const; + /// @endcond - /** Return the links on this session matching the state mask. */ + /// Return the links on this session matching the state mask. PN_CPP_EXTERN link_range find_links(endpoint::state mask) const; }; +/// @cond INTERNAL +/// XXX should be exposed? /// An iterator for sessions. class session_iterator : public iter_base { public: @@ -97,10 +113,11 @@ class session_iterator : public iter_base { PN_CPP_EXTERN session_iterator operator++(); session_iterator operator++(int) { session_iterator x(*this); ++(*this); return x; } }; - +/// @endcond + /// A range of sessions. typedef range session_range; } -#endif /*!PROTON_CPP_SESSION_H*/ +#endif // PROTON_CPP_SESSION_H diff --git a/proton-c/bindings/cpp/include/proton/ssl.hpp b/proton-c/bindings/cpp/include/proton/ssl.hpp index 11ac0a9139..d2111c99f8 100644 --- a/proton-c/bindings/cpp/include/proton/ssl.hpp +++ b/proton-c/bindings/cpp/include/proton/ssl.hpp @@ -21,60 +21,98 @@ * under the License. * */ + #include "proton/export.hpp" -#include "proton/ssl.h" +#include "proton/ssl.h" #include namespace proton { class connection_options; +/// SSL information. class ssl { public: + /// Determines the level of peer validation. enum verify_mode { + /// Require peer to provide a valid identifying certificate VERIFY_PEER = PN_SSL_VERIFY_PEER, + /// Do not require a certificate or cipher authorization ANONYMOUS_PEER = PN_SSL_ANONYMOUS_PEER, + /// Require valid certificate and matching name VERIFY_PEER_NAME = PN_SSL_VERIFY_PEER_NAME }; - /// Outcome specifier for an attempted session resume + + /// Outcome specifier for an attempted session resume. enum resume_status { - UNKNOWN = PN_SSL_RESUME_UNKNOWN, /**< Session resume state unknown/not supported */ - NEW = PN_SSL_RESUME_NEW, /**< Session renegotiated - not resumed */ - REUSED = PN_SSL_RESUME_REUSED /**< Session resumed from previous session. */ + UNKNOWN = PN_SSL_RESUME_UNKNOWN, ///< Session resume state unknown or not supported + NEW = PN_SSL_RESUME_NEW, ///< Session renegotiated, not resumed + REUSED = PN_SSL_RESUME_REUSED ///< Session resumed from previous session }; + + /// @cond INTERNAL ssl(pn_ssl_t* s) : object_(s) {} + /// @endcond + + /// @cond INTERNAL + + /// XXX C API uses cipher_name + /// Get the cipher name. PN_CPP_EXTERN std::string cipher() const; + + /// XXX C API uses protocol_name + /// Get the protocol name. PN_CPP_EXTERN std::string protocol() const; + + /// Get the security strength factor. PN_CPP_EXTERN int ssf() const; + + /// XXX remove PN_CPP_EXTERN void peer_hostname(const std::string &); PN_CPP_EXTERN std::string peer_hostname() const; + + /// XXX discuss, what's the meaning of "remote" here? PN_CPP_EXTERN std::string remote_subject() const; + + /// XXX setters? versus connection options PN_CPP_EXTERN void resume_session_id(const std::string& session_id); + PN_CPP_EXTERN enum resume_status resume_status() const; -private: + /// @endcond + + private: pn_ssl_t* object_; }; - class ssl_certificate { public: + /// Create an SSL certificate. PN_CPP_EXTERN ssl_certificate(const std::string &certdb_main, const std::string &certdb_extra = std::string()); + + /// Create an SSL certificate. + /// + /// @internal + /// XXX what is the difference between these? PN_CPP_EXTERN ssl_certificate(const std::string &certdb_main, const std::string &certdb_extra, const std::string &passwd); + private: std::string certdb_main_; std::string certdb_extra_; std::string passwd_; bool pw_set_; + + /// @cond INTERNAL friend class ssl_client_options; friend class ssl_server_options; + /// @endcond }; - class ssl_domain_impl; namespace internal { + // Base class for SSL configuration class ssl_domain { public: @@ -89,42 +127,64 @@ class ssl_domain { private: ssl_domain_impl *impl_; }; -} +} -/** SSL/TLS configuration for inbound connections created from a listener */ +/// SSL configuration for inbound connections. class ssl_server_options : private internal::ssl_domain { public: - /** SSL options for servers based on the supplied X509 certificate specifier. */ + /// Server SSL options based on the supplied X.509 certificate + /// specifier. PN_CPP_EXTERN ssl_server_options(ssl_certificate &cert); - /** SSL options for servers requiring connecting clients to provide a client certificate. */ + + /// Server SSL options requiring connecting clients to provide a + /// client certificate. PN_CPP_EXTERN ssl_server_options(ssl_certificate &cert, const std::string &trust_db, - const std::string &advertise_db = std::string(), - enum ssl::verify_mode mode = ssl::VERIFY_PEER); - /** SSL options for servers restricted to available anonymous cipher suites on the platform. */ + const std::string &advertise_db = std::string(), + enum ssl::verify_mode mode = ssl::VERIFY_PEER); + + /// Server SSL options restricted to available anonymous cipher + /// suites on the platform. PN_CPP_EXTERN ssl_server_options(); private: - // Bring pn_domain into scope and allow connection_options to use it + // Bring pn_domain into scope and allow connection_options to use + // it. using internal::ssl_domain::pn_domain; + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; - -/** SSL/TLS configuration for outgoing connections */ +/// SSL configuration for outbound connections. class ssl_client_options : private internal::ssl_domain { public: - PN_CPP_EXTERN ssl_client_options(const std::string &trust_db, enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); - PN_CPP_EXTERN ssl_client_options(ssl_certificate&, const std::string &trust_db, enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); - /** A client domain restricted to available anonymous cipher suites on the platform. */ + /// Create SSL client options. + PN_CPP_EXTERN ssl_client_options(const std::string &trust_db, + enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); + + /// Create SSL client options. + /// + /// @internal + /// XXX how is this distinct? + PN_CPP_EXTERN ssl_client_options(ssl_certificate&, const std::string &trust_db, + enum ssl::verify_mode = ssl::VERIFY_PEER_NAME); + + /// Server SSL options restricted to available anonymous cipher + /// suites on the platform. PN_CPP_EXTERN ssl_client_options(); private: - // Bring pn_domain into scope and allow connection_options to use it + // Bring pn_domain into scope and allow connection_options to use + // it. using internal::ssl_domain::pn_domain; + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; } -#endif /*!PROTON_CPP_SSL_H*/ +#endif // PROTON_CPP_SSL_H diff --git a/proton-c/bindings/cpp/include/proton/task.hpp b/proton-c/bindings/cpp/include/proton/task.hpp index ffa0b11c31..07b7a5de54 100644 --- a/proton-c/bindings/cpp/include/proton/task.hpp +++ b/proton-c/bindings/cpp/include/proton/task.hpp @@ -21,6 +21,10 @@ * under the License. * */ + +/// @cond INTERNAL +/// XXX needs more discussion + #include "proton/export.hpp" #include "proton/object.hpp" @@ -28,15 +32,17 @@ namespace proton { -/** A task for timer events */ +/// A task for timer events. class task : public object { public: task(pn_task_t* t) : object(t) {} - /** Cancel the scheduled task. */ + /// Cancel the scheduled task. PN_CPP_EXTERN void cancel(); }; } -#endif /*!PROTON_CPP_TASK_H*/ +/// @endcond + +#endif // PROTON_CPP_TASK_H diff --git a/proton-c/bindings/cpp/include/proton/terminus.hpp b/proton-c/bindings/cpp/include/proton/terminus.hpp index ce52360689..a10ff9be41 100644 --- a/proton-c/bindings/cpp/include/proton/terminus.hpp +++ b/proton-c/bindings/cpp/include/proton/terminus.hpp @@ -21,31 +21,36 @@ * under the License. * */ -#include "proton/export.hpp" -#include "proton/link.h" +#include "proton/export.hpp" #include "proton/object.hpp" #include "proton/value.hpp" + +#include "proton/link.h" #include namespace proton { class link; -/** A terminus represents one end of a link. - * The source terminus is where messages originate, the target terminus is where they go. - */ -class terminus -{ +/// One end of a link, either a source or a target. +/// +/// The source terminus is where messages originate; the target +/// terminus is where they go. +/// +/// @see proton::link +class terminus { public: + /// @cond INTERNAL terminus(pn_terminus_t* t); + /// @endcond /// Type of terminus - enum type{ + enum type { TYPE_UNSPECIFIED = PN_UNSPECIFIED, SOURCE = PN_SOURCE, TARGET = PN_TARGET, - COORDINATOR = PN_COORDINATOR ///< Transaction co-ordinator + COORDINATOR = PN_COORDINATOR ///< Transaction coordinator }; /// Durability @@ -70,37 +75,69 @@ class terminus MOVE = PN_DIST_MODE_MOVE }; + /// Get the terminus type. PN_CPP_EXTERN enum type type() const; + + /// Set the terminus type. PN_CPP_EXTERN void type(enum type); + + /// Get the expiration policy. PN_CPP_EXTERN enum expiry_policy expiry_policy() const; + + /// Set the expiration policy. PN_CPP_EXTERN void expiry_policy(enum expiry_policy); + + /// @cond INTERNAL + /// XXX use duration PN_CPP_EXTERN uint32_t timeout() const; PN_CPP_EXTERN void timeout(uint32_t seconds); + /// @endcond + + /// Get the distribution mode. PN_CPP_EXTERN enum distribution_mode distribution_mode() const; + + /// Set the distribution mode. PN_CPP_EXTERN void distribution_mode(enum distribution_mode); + + /// Get the durability flag. PN_CPP_EXTERN enum durability durability(); + + /// Set the durability flag. PN_CPP_EXTERN void durability(enum durability); + + /// Get the source or target address. PN_CPP_EXTERN std::string address() const; + + /// Set the source or target address. PN_CPP_EXTERN void address(const std::string &); + + /// True if the remote node is created dynamically. PN_CPP_EXTERN bool dynamic() const; + + /// Enable or disable dynamic creation of the remote node. PN_CPP_EXTERN void dynamic(bool); - /** Obtain a reference to the AMQP dynamic node properties for the terminus. - * See also link_options::lifetime_policy. */ + /// Obtain a reference to the AMQP dynamic node properties for the + /// terminus. See also link_options::lifetime_policy. PN_CPP_EXTERN value& node_properties(); + + /// Obtain a reference to the AMQP dynamic node properties for the + /// terminus. See also link_options::lifetime_policy. PN_CPP_EXTERN const value& node_properties() const; - /** Obtain a reference to the AMQP filter set for the terminus. - * See also link_options::selector. */ + /// Obtain a reference to the AMQP filter set for the terminus. + /// See also link_options::selector. PN_CPP_EXTERN value& filter(); + + /// Obtain a reference to the AMQP filter set for the terminus. + /// See also link_options::selector. PN_CPP_EXTERN const value& filter() const; -private: + private: pn_terminus_t* object_; value properties_, filter_; }; - } -#endif /*!PROTON_CPP_TERMINUS_H*/ +#endif // PROTON_CPP_TERMINUS_H diff --git a/proton-c/bindings/cpp/include/proton/transport.hpp b/proton-c/bindings/cpp/include/proton/transport.hpp index b3a9c6d267..2d84f3d59a 100644 --- a/proton-c/bindings/cpp/include/proton/transport.hpp +++ b/proton-c/bindings/cpp/include/proton/transport.hpp @@ -34,16 +34,30 @@ class connection; class condition; class sasl; -/** Represents a connection transport */ -class transport : public object -{ +/// A network layer supporting an AMQP connection. +class transport : public object { public: + /// @cond INTERNAL transport(pn_transport_t* t) : object(t) {} + /// @endcond + /// @cond INTERNAL + /// XXX what if a transport is associated with multiple connections? + /// Get the connection associated with this transport. PN_CPP_EXTERN class connection connection() const; + /// @endcond + + /// Get SSL information. PN_CPP_EXTERN class ssl ssl() const; + + /// Get SASL information. PN_CPP_EXTERN class sasl sasl() const; + + /// Get the error condition. PN_CPP_EXTERN class condition condition() const; + + /// @cond INTERNAL + /// XXX need to discuss, local versus remote PN_CPP_EXTERN void unbind(); PN_CPP_EXTERN void bind(class connection &); PN_CPP_EXTERN uint32_t max_frame_size() const; @@ -52,10 +66,13 @@ class transport : public object PN_CPP_EXTERN uint16_t remote_max_channels() const; PN_CPP_EXTERN uint32_t idle_timeout() const; PN_CPP_EXTERN uint32_t remote_idle_timeout() const; + /// @endcond + + /// @cond INTERNAL friend class connection_options; + /// @endcond }; - } -#endif /*!PROTON_CPP_TRANSPORT_H*/ +#endif // PROTON_CPP_TRANSPORT_H diff --git a/proton-c/bindings/cpp/include/proton/type_traits.hpp b/proton-c/bindings/cpp/include/proton/type_traits.hpp index 8f502a364e..56f503ce37 100644 --- a/proton-c/bindings/cpp/include/proton/type_traits.hpp +++ b/proton-c/bindings/cpp/include/proton/type_traits.hpp @@ -1,5 +1,6 @@ #ifndef TYPE_TRAITS_HPP #define TYPE_TRAITS_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,17 +20,20 @@ * under the License. */ -/**@file - * Internal: Type traits for mapping between AMQP and C++ types. - * - * Also provides workarounds for missing type_traits classes on older C++ compilers. - * @cond INTERNAL - */ +/// @cond INTERNAL + +/// @file +/// +/// Internal: Type traits for mapping between AMQP and C++ types. +/// +/// Also provides workarounds for missing type_traits classes on older +/// C++ compilers. #include "proton/config.hpp" #include "proton/types.hpp" namespace proton { + class value; template struct enable_if {}; @@ -121,8 +125,8 @@ template struct is_unknown_integer { static const bool value = !has_type_id::value && is_integral::value; }; - } -///@endcond + +/// @endcond #endif // TYPE_TRAITS_HPP diff --git a/proton-c/bindings/cpp/include/proton/types.hpp b/proton-c/bindings/cpp/include/proton/types.hpp index 32a2fca793..ee93082965 100644 --- a/proton-c/bindings/cpp/include/proton/types.hpp +++ b/proton-c/bindings/cpp/include/proton/types.hpp @@ -1,5 +1,6 @@ #ifndef TYPES_H #define TYPES_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -19,71 +20,71 @@ * under the License. */ -/**@file - * Defines C++ types representing AMQP types. - */ +/// @file +/// +/// Defines C++ types representing AMQP types. #include "proton/comparable.hpp" #include "proton/export.hpp" #include "proton/error.hpp" -#include +#include // XXX everywhere else folks are using "codec.h" #include - #include #include #include #include -#include namespace proton { -/** type_id identifies an AMQP type. */ +/// An identifier for AMQP types. enum type_id { - NULL_TYPE=PN_NULL, ///< The null type, contains no data. - BOOLEAN=PN_BOOL, ///< Boolean true or false. - UBYTE=PN_UBYTE, ///< Unsigned 8 bit integer. - BYTE=PN_BYTE, ///< Signed 8 bit integer. - USHORT=PN_USHORT, ///< Unsigned 16 bit integer. - SHORT=PN_SHORT, ///< Signed 16 bit integer. - UINT=PN_UINT, ///< Unsigned 32 bit integer. - INT=PN_INT, ///< Signed 32 bit integer. - CHAR=PN_CHAR, ///< 32 bit unicode character. - ULONG=PN_ULONG, ///< Unsigned 64 bit integer. - LONG=PN_LONG, ///< Signed 64 bit integer. - TIMESTAMP=PN_TIMESTAMP, ///< Signed 64 bit milliseconds since the epoch. - FLOAT=PN_FLOAT, ///< 32 bit binary floating point. - DOUBLE=PN_DOUBLE, ///< 64 bit binary floating point. - DECIMAL32=PN_DECIMAL32, ///< 32 bit decimal floating point. - DECIMAL64=PN_DECIMAL64, ///< 64 bit decimal floating point. - DECIMAL128=PN_DECIMAL128, ///< 128 bit decimal floating point. - UUID=PN_UUID, ///< 16 byte UUID. - BINARY=PN_BINARY, ///< Variable length sequence of bytes. - STRING=PN_STRING, ///< Variable length utf8-encoded string. - SYMBOL=PN_SYMBOL, ///< Variable length encoded string. - DESCRIBED=PN_DESCRIBED, ///< A descriptor and a value. - ARRAY=PN_ARRAY, ///< A sequence of values of the same type. - LIST=PN_LIST, ///< A sequence of values, may be of mixed types. - MAP=PN_MAP ///< A sequence of key:value pairs, may be of mixed types. + NULL_TYPE = PN_NULL, ///< The null type, contains no data. + BOOLEAN = PN_BOOL, ///< Boolean true or false. + UBYTE = PN_UBYTE, ///< Unsigned 8 bit integer. + BYTE = PN_BYTE, ///< Signed 8 bit integer. + USHORT = PN_USHORT, ///< Unsigned 16 bit integer. + SHORT = PN_SHORT, ///< Signed 16 bit integer. + UINT = PN_UINT, ///< Unsigned 32 bit integer. + INT = PN_INT, ///< Signed 32 bit integer. + CHAR = PN_CHAR, ///< 32 bit unicode character. + ULONG = PN_ULONG, ///< Unsigned 64 bit integer. + LONG = PN_LONG, ///< Signed 64 bit integer. + TIMESTAMP = PN_TIMESTAMP, ///< Signed 64 bit milliseconds since the epoch. + FLOAT = PN_FLOAT, ///< 32 bit binary floating point. + DOUBLE = PN_DOUBLE, ///< 64 bit binary floating point. + DECIMAL32 = PN_DECIMAL32, ///< 32 bit decimal floating point. + DECIMAL64 = PN_DECIMAL64, ///< 64 bit decimal floating point. + DECIMAL128 = PN_DECIMAL128, ///< 128 bit decimal floating point. + UUID = PN_UUID, ///< 16 byte UUID. + BINARY = PN_BINARY, ///< Variable length sequence of bytes. + STRING = PN_STRING, ///< Variable length utf8-encoded string. + SYMBOL = PN_SYMBOL, ///< Variable length encoded string. + DESCRIBED = PN_DESCRIBED, ///< A descriptor and a value. + ARRAY = PN_ARRAY, ///< A sequence of values of the same type. + LIST = PN_LIST, ///< A sequence of values, may be of mixed types. + MAP = PN_MAP ///< A sequence of key:value pairs, may be of mixed types. }; -/// Name of the AMQP type +/// Get the name of the AMQP type. PN_CPP_EXTERN std::string type_name(type_id); -/// Print the type_name +/// Print the type name. PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, type_id); -/// Raised when there is a type mismatch, with the expected and actual type ID. +/// @cond INTERNAL + +/// XXX change namespace +/// Raised when there is a type mismatch, with the expected and actual +/// type ID. struct type_error : public decode_error { PN_CPP_EXTERN explicit type_error(type_id want, type_id got, const std::string& =std::string()); type_id want; ///< Expected type_id type_id got; ///< Actual type_id }; -///@cond INTERNAL PN_CPP_EXTERN pn_bytes_t pn_bytes(const std::string&); PN_CPP_EXTERN std::string str(const pn_bytes_t& b); -///@endcond /// AMQP NULL type. struct amqp_null {}; @@ -133,7 +134,8 @@ struct amqp_binary : public std::string { explicit amqp_binary(const pn_bytes_t& b) : std::string(b.start, b.size) {} }; -/// Template for opaque proton proton types that can be treated as byte arrays. +/// Template for opaque proton proton types that can be treated as +/// byte arrays. template struct opaque : public comparable > { P value; opaque(const P& p=P()) : value(p) {} @@ -154,12 +156,15 @@ template bool operator<(const opaque& x, const opaque& y) { retu /// AMQP 16-byte UUID. typedef opaque amqp_uuid; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_uuid&); + /// AMQP 32-bit decimal floating point (IEEE 854). typedef opaque amqp_decimal32; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal32&); + /// AMQP 64-bit decimal floating point (IEEE 854). typedef opaque amqp_decimal64; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal64&); + /// AMQP 128-bit decimal floating point (IEEE 854). typedef opaque amqp_decimal128; PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_decimal128&); @@ -174,11 +179,18 @@ inline bool operator==(amqp_timestamp x, amqp_timestamp y) { return x.millisecon inline bool operator<(amqp_timestamp x, amqp_timestamp y) { return x.milliseconds < y.milliseconds; } PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const amqp_timestamp&); +/// @endcond + // TODO aconway 2015-06-16: described types. -///@name Attributes of a type_id value, returns same result as the -/// corresponding std::type_traits tests for the corresponding C++ types. -///@{ +/// @name Type test functions +/// +/// Attributes of a type_id value, returns same result as the +/// corresponding std::type_traits tests for the corresponding C++ +/// types. +/// +/// @{ + /// Any scalar type PN_CPP_EXTERN bool type_id_is_scalar(type_id); /// One of the signed integer types: BYTE, SHORT, INT or LONG @@ -197,16 +209,19 @@ PN_CPP_EXTERN bool type_id_is_decimal(type_id); PN_CPP_EXTERN bool type_id_is_string_like(type_id); /// Container types: MAP, LIST, ARRAY or DESCRIBED. PN_CPP_EXTERN bool type_id_is_container(type_id); -///@} -/** Print the name of a type. */ +/// @} + +/// Print the name of a type. PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, type_id); -/** Information needed to start extracting or inserting a container type. - * - * See encoder::operator<<(encoder&, const start&) and decoder::operator>>(decoder&, start&) - * for examples of use. - */ +/// @cond INTERNAL +/// XXX change namespace + +/// Information needed to start extracting or inserting a container type. +/// +/// See encoder::operator<<(encoder&, const start&) and +/// decoder::operator>>(decoder&, start&) for examples of use. struct start { PN_CPP_EXTERN start(type_id type=NULL_TYPE, type_id element=NULL_TYPE, bool described=false, size_t size=0); type_id type; ///< The container type: ARRAY, LIST, MAP or DESCRIBED. @@ -214,19 +229,24 @@ struct start { bool is_described; ///< true if first value is a descriptor. size_t size; ///< the element count excluding the descriptor (if any) - /** Return a start for an array */ + /// Return a start for an array. PN_CPP_EXTERN static start array(type_id element, bool described=false); - /** Return a start for a list */ + + /// Return a start for a list. PN_CPP_EXTERN static start list(); - /** Return a start for a map */ + + /// Return a start for a map. PN_CPP_EXTERN static start map(); - /** Return a start for a described type */ + + /// Return a start for a described type. PN_CPP_EXTERN static start described(); }; -/** Finish inserting or extracting a container value. */ +/// Finish inserting or extracting a container value. struct finish {}; +/// @endcond + } #endif // TYPES_H diff --git a/proton-c/bindings/cpp/include/proton/url.hpp b/proton-c/bindings/cpp/include/proton/url.hpp index c2d273b515..62aa6a0eb7 100644 --- a/proton-c/bindings/cpp/include/proton/url.hpp +++ b/proton-c/bindings/cpp/include/proton/url.hpp @@ -1,5 +1,6 @@ #ifndef URL_HPP #define URL_HPP + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -21,110 +22,133 @@ #include "proton/types.hpp" #include "proton/error.hpp" + #include struct pn_url_t; namespace proton { -/// Thrown if URL parsing fails. +/// Raised if URL parsing fails. struct url_error : public error { + /// @cond INTERNAL PN_CPP_EXTERN explicit url_error(const std::string&); + /// @endcond }; - -/** - * url is a proton URL of the form `://:@:/`. - * scheme can be `amqp` or `amqps`. host is a DNS name or IP address (v4 or v6) - * port can be a number or symbolic service name like `amqp`. path is normally used as - * a link source or target address, on a broker it typically it corresponds to a queue or topic name. - */ +/// A proton URL. +/// +/// Proton URLs take the form +/// `://:@:/`. +/// +/// - Scheme can be `amqp` or `amqps`. Host is a DNS name or IP +/// address (v4 or v6). +/// +/// - Port can be a number or a symbolic service name such as `amqp`. +/// +/// - Path is normally used as a link source or target address. On a +/// broker it typically corresponds to a queue or topic name. class url { public: static const std::string AMQP; ///< "amqp" prefix static const std::string AMQPS; ///< "amqps" prefix - /** Create an empty url */ + /// Create an empty URL PN_CPP_EXTERN url(); - /** Parse url_str as an AMQP URL. If defaults is true, fill in defaults for missing values - * otherwise return an empty string for missing values. - * Note: converts automatically from string. - *@throw url_error if URL is invalid. - */ + /// Parse `url_str` as an AMQP URL. If defaults is true, fill in + /// defaults for missing values otherwise return an empty string + /// for missing values. + /// + /// @note Converts automatically from string. + /// + /// @throw url_error if URL is invalid. PN_CPP_EXTERN url(const std::string& url_str, bool defaults=true); - /** Parse url_str as an AMQP URL. If defaults is true, fill in defaults for missing values - * otherwise return an empty string for missing values. - * Note: converts automatically from string. - *@throw url_error if URL is invalid. - */ + /// Parse `url_str` as an AMQP URL. If defaults is true, fill in + /// defaults for missing values otherwise return an empty string + /// for missing values. + /// + /// @note Converts automatically from string. + /// + /// @throw url_error if URL is invalid. PN_CPP_EXTERN url(const char* url_str, bool defaults=true); + /// Copy a URL. PN_CPP_EXTERN url(const url&); PN_CPP_EXTERN ~url(); + /// Copy a URL. PN_CPP_EXTERN url& operator=(const url&); - /** Parse a string as a URL - *@throws url_error if URL is invalid. - */ + /// Parse a string as a URL. + /// + /// @throws url_error if URL is invalid. PN_CPP_EXTERN void parse(const std::string&); - /** Parse a string as a URL - *@throws url_error if URL is invalid. - */ + /// Parse a string as a URL. + /// + /// @throws url_error if URL is invalid. PN_CPP_EXTERN void parse(const char*); + /// True if the URL is empty. PN_CPP_EXTERN bool empty() const; - /** str returns the URL as a string string */ + /// `str` returns the URL as a string PN_CPP_EXTERN std::string str() const; - /**@name Get parts of the URL - *@{ - */ + /// @name URL fields + /// + /// @{ + PN_CPP_EXTERN std::string scheme() const; + PN_CPP_EXTERN void scheme(const std::string&); + + /// @cond INTERNAL PN_CPP_EXTERN std::string username() const; + PN_CPP_EXTERN void username(const std::string&); + /// @endcond + PN_CPP_EXTERN std::string password() const; + PN_CPP_EXTERN void password(const std::string&); + PN_CPP_EXTERN std::string host() const; - /** port is a string, it can be a number or a symbolic name like "amqp" */ + PN_CPP_EXTERN void host(const std::string&); + /// `port` can be a number or a symbolic name such as "amqp". + PN_CPP_EXTERN void port(const std::string&); PN_CPP_EXTERN std::string port() const; - /** port_int is the numeric value of the port. */ + /// `port_int` is the numeric value of the port. PN_CPP_EXTERN uint16_t port_int() const; - /** path is everything after the final "/" */ - PN_CPP_EXTERN std::string path() const; - //@} - - /** host_port returns just the host:port part of the URL */ + /// host_port returns just the `host:port` part of the URL PN_CPP_EXTERN std::string host_port() const; - /**@name Set parts of the URL - *@{ - */ - PN_CPP_EXTERN void scheme(const std::string&); - PN_CPP_EXTERN void username(const std::string&); - PN_CPP_EXTERN void password(const std::string&); - PN_CPP_EXTERN void host(const std::string&); - /** port is a string, it can be a number or a symbolic name like "amqp" */ - PN_CPP_EXTERN void port(const std::string&); + /// `path` is everything after the final "/". + PN_CPP_EXTERN std::string path() const; PN_CPP_EXTERN void path(const std::string&); - //@} - /** defaults fills in default values for missing parts of the URL */ - PN_CPP_EXTERN void defaults(); + /// @} - friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const url&); - - /** parse url from istream, automatically fills in defaults for missing values. - * - * Note: an invalid url is indicated by setting std::stream::fail() NOT by throwing url_error. - */ - friend PN_CPP_EXTERN std::istream& operator>>(std::istream&, url&); + /// @cond INTERNAL + /// XXX need to discuss + /// defaults fills in default values for missing parts of the URL. + PN_CPP_EXTERN void defaults(); + /// @endcond private: pn_url_t* url_; -}; + /// @cond INTERNAL + + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const url&); + + /// Parse `url` from istream. This automatically fills in + /// defaults for missing values. + /// + /// @note An invalid url is indicated by setting + /// std::stream::fail(), NOT by throwing url_error. + friend PN_CPP_EXTERN std::istream& operator>>(std::istream&, url&); + + /// @endcond +}; } diff --git a/proton-c/bindings/cpp/include/proton/value.hpp b/proton-c/bindings/cpp/include/proton/value.hpp index 732763c280..4076e993ba 100644 --- a/proton-c/bindings/cpp/include/proton/value.hpp +++ b/proton-c/bindings/cpp/include/proton/value.hpp @@ -1,5 +1,6 @@ #ifndef VALUE_H #define VALUE_H + /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file @@ -18,77 +19,103 @@ * specific language governing permissions and limitations * under the License. */ + #include "proton/data.hpp" #include "proton/types.hpp" namespace proton { -/** - * Holder for an AMQP value. - * - * proton::value can hold any AMQP data value, simple or compound. It has - * assignment and conversion operators to convert its contents easily to and - * from native C++ types. - * - */ +/// A holder for an AMQP value. +/// +/// A proton::value can hold any AMQP data value, simple or compound. +/// It has assignment and conversion operators to convert its contents +/// easily to and from native C++ types. class value : public comparable { public: + /// Create an empty value. PN_CPP_EXTERN value(); + + /// Copy a value. PN_CPP_EXTERN value(const value&); + #if PN_HAS_CPP11 PN_CPP_EXTERN value(value&&); #endif + + /// Copy a value. PN_CPP_EXTERN value& operator=(const value&); + /// Create a value from C++ type T. template value(const T& x) : data_(proton::data::create()) { encode() << x; } + + /// Create a value from C++ type T. template value& operator=(const T& x) { encode() << x; return *this; } + /// Remove any contained data. PN_CPP_EXTERN void clear(); + + /// True if the value contains no data. PN_CPP_EXTERN bool empty() const; - /** Type of the current value*/ + /// Get the type of the current value. PN_CPP_EXTERN type_id type() const; + /// @name Get methods + /// + /// Extract the value to type T. + /// + /// @{ + /// Get the value. template void get(T &t) const { decode() >> t; } /// Get an AMQP map as any type T that satisfies the map concept. template void get_map(T& t) const { decode() >> to_map(t); } + /// Get a map as a as any type T that is a sequence pair-like types with first and second. template void get_pairs(T& t) const { decode() >> to_pairs(t); } + /// Get an AMQP array or list as type T that satisfies the sequence concept. */ template void get_sequence(T& t) const { decode() >> to_sequence(t); } + /// @} + /// Get the value as C++ type T. template T get() const { T t; get(t); return t; } - ///@name as_ methods do "loose" conversion, they will convert the scalar - ///value to the requested type if possible, else throw type_error - ///@{ - PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if type_id_is_integral(type()) - PN_CPP_EXTERN double as_double() const; ///< Allowed if type_id_is_floating_point(type()) - PN_CPP_EXTERN std::string as_string() const; ///< Allowed if type_id_is_string_like(type()) - ///@} - - ///@cond INTERNAL - PN_CPP_EXTERN encoder encode(); ///< Clear and return an encoder for this value. - PN_CPP_EXTERN decoder decode() const; ///< Rewind and return an encoder for this value. - PN_CPP_EXTERN class data& data() const; ///< Return a data reference, no clear or rewind. - ///@endcond - - friend PN_CPP_EXTERN void swap(value&, value&); - friend PN_CPP_EXTERN bool operator==(const value& x, const value& y); - friend PN_CPP_EXTERN bool operator<(const value& x, const value& y); - friend PN_CPP_EXTERN class encoder operator<<(class encoder e, const value& dv); - friend PN_CPP_EXTERN class decoder operator>>(class decoder d, value& dv); - friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream& o, const value& dv); + /// @name As methods + /// + /// As methods do "loose" conversion, they will convert the scalar + /// value to the requested type if possible, else throw type_error. + /// + /// @{ + PN_CPP_EXTERN int64_t as_int() const; ///< Allowed if `type_id_is_integral(type())` + PN_CPP_EXTERN uint64_t as_uint() const; ///< Allowed if `type_id_is_integral(type())` + PN_CPP_EXTERN double as_double() const; ///< Allowed if `type_id_is_floating_point(type())` + PN_CPP_EXTERN std::string as_string() const; ///< Allowed if `type_id_is_string_like(type())` + /// @} + + /// @cond INTERNAL + /// XXX undiscussed + PN_CPP_EXTERN encoder encode(); ///< Clear and return an encoder for this value. + PN_CPP_EXTERN decoder decode() const; ///< Rewind and return an encoder for this value. + PN_CPP_EXTERN class data& data() const; ///< Return a data reference, no clear or rewind. + /// @endcond private: mutable class data data_; - friend class message; -}; + /// @cond INTERNAL + friend PN_CPP_EXTERN void swap(value&, value&); + friend PN_CPP_EXTERN bool operator==(const value& x, const value& y); + friend PN_CPP_EXTERN bool operator<(const value& x, const value& y); + friend PN_CPP_EXTERN class encoder operator<<(class encoder e, const value& dv); + friend PN_CPP_EXTERN class decoder operator>>(class decoder d, value& dv); + friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream& o, const value& dv); + friend class message; + /// @endcond +}; } + #endif // VALUE_H diff --git a/proton-c/include/proton/ssl.h b/proton-c/include/proton/ssl.h index 6c22014200..8fdae0869a 100644 --- a/proton-c/include/proton/ssl.h +++ b/proton-c/include/proton/ssl.h @@ -364,12 +364,12 @@ typedef enum { * Get the fingerprint of the certificate. The certificate fingerprint (as displayed in the Fingerprints section when * looking at a certificate with say the Firefox browser) is the hexadecimal hash of the entire certificate. * The fingerprint is not part of the certificate, rather it is computed from the certificate and can be used to uniquely identify a certificate. - * @param[in] ssl the ssl client/server to query + * @param[in] ssl0 the ssl client/server to query * @param[in] fingerprint char pointer. The certificate fingerprint (in hex format) will be populated in this array. * If sha1 is the digest name, the fingerprint is 41 characters long (40 + 1 '\0' character), 65 characters long for * sha256 and 129 characters long for sha512 and 33 characters for md5. * @param[in] fingerprint_length - Must be at >= 33 for md5, >= 41 for sha1, >= 65 for sha256 and >=129 for sha512. - * @param[in] the hash algorithm to use. Must be of type pn_ssl_hash_alg (currently supports sha1, sha256, sha512 and md5) + * @param[in] hash_alg the hash algorithm to use. Must be of type pn_ssl_hash_alg (currently supports sha1, sha256, sha512 and md5) * @return error code - Returns 0 on success. Return a value less than zero if there were any errors. Upon execution of this function, * char *fingerprint will contain the appropriate null terminated hex fingerprint */ @@ -386,8 +386,8 @@ PN_EXTERN int pn_ssl_get_cert_fingerprint(pn_ssl_t *ssl0, * O = Organization - Company Name * OU = Organization Unit - division or unit * CN = CommonName - * @param[in] ssl the ssl client/server to query - * @param[in] The enumeration pn_ssl_cert_subject_subfield representing the required sub field. + * @param[in] ssl0 the ssl client/server to query + * @param[in] field The enumeration pn_ssl_cert_subject_subfield representing the required sub field. * @return A null terminated string which contains the requested sub field value which is valid until the ssl object is destroyed. */ PN_EXTERN const char* pn_ssl_get_remote_subject_subfield(pn_ssl_t *ssl0, pn_ssl_cert_subject_subfield field);