You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2015/07/16 07:33:16 UTC
[2/2] qpid-proton git commit: PROTON-865: C++ binding API
documentation and cleanup.
PROTON-865: C++ binding API documentation and cleanup.
- API doc comments on most of API, some TODO notes left in headers.
- Use proton::url consistently rather than std::string in API where appropriate.
- Fix some const issues.
- Clean up messaging_event enum names, add event_type constants to proton_event.
- Consistent option parsing for examples, python compatible.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/58c57e79
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/58c57e79
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/58c57e79
Branch: refs/heads/cjansen-cpp-client
Commit: 58c57e79034d4abfacd03415740bdb2e0a0b2cc2
Parents: cdad4dd
Author: Alan Conway <ac...@redhat.com>
Authored: Tue Jul 14 18:53:11 2015 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Thu Jul 16 01:32:54 2015 -0400
----------------------------------------------------------------------
examples/cpp/broker.cpp | 13 +-
examples/cpp/direct_recv.cpp | 55 +----
examples/cpp/direct_send.cpp | 54 +----
examples/cpp/encode_decode.cpp | 3 +-
examples/cpp/example_test.py | 2 +-
examples/cpp/helloworld.cpp | 15 +-
examples/cpp/helloworld_blocking.cpp | 23 +-
examples/cpp/helloworld_direct.cpp | 20 +-
examples/cpp/options.hpp | 173 +++++++++++++
examples/cpp/simple_recv.cpp | 55 ++---
examples/cpp/simple_send.cpp | 54 +----
proton-c/bindings/cpp/README.md | 8 +-
proton-c/bindings/cpp/docs/tutorial.md | 38 +--
.../bindings/cpp/include/proton/acceptor.hpp | 3 +
proton-c/bindings/cpp/include/proton/acking.hpp | 9 +
.../cpp/include/proton/blocking_connection.hpp | 9 +-
.../cpp/include/proton/blocking_link.hpp | 1 +
.../cpp/include/proton/blocking_sender.hpp | 1 +
proton-c/bindings/cpp/include/proton/config.hpp | 30 +++
.../bindings/cpp/include/proton/connection.hpp | 26 +-
.../bindings/cpp/include/proton/container.hpp | 49 +++-
proton-c/bindings/cpp/include/proton/data.hpp | 2 +-
.../bindings/cpp/include/proton/decoder.hpp | 10 +-
.../bindings/cpp/include/proton/delivery.hpp | 21 +-
.../bindings/cpp/include/proton/duration.hpp | 12 +-
.../bindings/cpp/include/proton/encoder.hpp | 5 +-
.../bindings/cpp/include/proton/endpoint.hpp | 35 ++-
proton-c/bindings/cpp/include/proton/error.hpp | 7 +-
proton-c/bindings/cpp/include/proton/event.hpp | 20 +-
proton-c/bindings/cpp/include/proton/export.hpp | 2 +
proton-c/bindings/cpp/include/proton/handle.hpp | 4 +-
.../bindings/cpp/include/proton/handler.hpp | 7 +-
proton-c/bindings/cpp/include/proton/link.hpp | 27 ++-
.../bindings/cpp/include/proton/message.hpp | 32 ++-
.../cpp/include/proton/messaging_adapter.hpp | 4 +-
.../cpp/include/proton/messaging_event.hpp | 95 ++++----
.../cpp/include/proton/messaging_handler.hpp | 19 +-
.../cpp/include/proton/proton_event.hpp | 242 ++++++++++++++++++-
.../cpp/include/proton/proton_handle.hpp | 2 +
.../cpp/include/proton/proton_handler.hpp | 7 +-
.../bindings/cpp/include/proton/receiver.hpp | 1 +
proton-c/bindings/cpp/include/proton/sender.hpp | 4 +-
.../bindings/cpp/include/proton/session.hpp | 29 ++-
.../bindings/cpp/include/proton/terminus.hpp | 8 +-
.../bindings/cpp/include/proton/transport.hpp | 3 +
.../bindings/cpp/include/proton/type_traits.hpp | 19 +-
proton-c/bindings/cpp/include/proton/types.hpp | 86 +++----
proton-c/bindings/cpp/include/proton/url.hpp | 28 ++-
.../cpp/include/proton/wait_condition.hpp | 3 +
.../bindings/cpp/src/blocking_connection.cpp | 5 +-
.../cpp/src/blocking_connection_impl.cpp | 3 +-
proton-c/bindings/cpp/src/connection.cpp | 2 +-
proton-c/bindings/cpp/src/connection_impl.cpp | 2 +-
proton-c/bindings/cpp/src/connection_impl.hpp | 2 +-
proton-c/bindings/cpp/src/container.cpp | 6 +-
proton-c/bindings/cpp/src/container_impl.cpp | 12 +-
proton-c/bindings/cpp/src/container_impl.hpp | 4 +-
proton-c/bindings/cpp/src/decoder.cpp | 1 -
proton-c/bindings/cpp/src/endpoint.cpp | 10 +
proton-c/bindings/cpp/src/error.cpp | 2 +
proton-c/bindings/cpp/src/link.cpp | 2 +-
proton-c/bindings/cpp/src/message.cpp | 11 +-
proton-c/bindings/cpp/src/messaging_adapter.cpp | 54 ++---
proton-c/bindings/cpp/src/messaging_event.cpp | 83 ++++---
proton-c/bindings/cpp/src/proton_event.cpp | 144 +++++++----
proton-c/bindings/cpp/src/session.cpp | 4 +-
proton-c/bindings/cpp/src/url.cpp | 21 ++
proton-c/include/proton/message.h | 2 +-
68 files changed, 1200 insertions(+), 545 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/broker.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/broker.cpp b/examples/cpp/broker.cpp
index 86f5b89..a57fff9 100644
--- a/examples/cpp/broker.cpp
+++ b/examples/cpp/broker.cpp
@@ -19,6 +19,8 @@
*
*/
+#include "options.hpp"
+
#include "proton/container.hpp"
#include "proton/messaging_handler.hpp"
#include "proton/url.hpp"
@@ -196,12 +198,19 @@ class broker : public proton::messaging_handler {
};
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 {
- std::string url(argc > 1 ? argv[1] : "0.0.0.0");
+ opts.parse();
broker broker(url);
proton::container(broker).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;
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/direct_recv.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/direct_recv.cpp b/examples/cpp/direct_recv.cpp
index 5c8c808..9eead92 100644
--- a/examples/cpp/direct_recv.cpp
+++ b/examples/cpp/direct_recv.cpp
@@ -19,6 +19,8 @@
*
*/
+#include "options.hpp"
+
#include "proton/container.hpp"
#include "proton/messaging_handler.hpp"
#include "proton/link.hpp"
@@ -30,8 +32,6 @@
#include <stdio.h>
#include <string.h>
-
-
class direct_recv : public proton::messaging_handler {
private:
proton::url url;
@@ -66,52 +66,23 @@ class direct_recv : public proton::messaging_handler {
}
};
-static void parse_options(int argc, char **argv, int &count, std::string &addr);
-
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 {
- int message_count = 100;
- std::string address("127.0.0.1:5672/examples");
- parse_options(argc, argv, message_count, address);
+ 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;
}
+ return 1;
}
-
-static void usage() {
- std::cout << "Usage: direct_recv -m message_count -a address:" << std::endl;
- exit (1);
-}
-
-
-static void parse_options(int argc, char **argv, int &count, std::string &addr) {
- int c, i;
- for (i = 1; i < argc; i++) {
- if (strlen(argv[i]) == 2 && argv[i][0] == '-') {
- c = argv[i][1];
- const char *nextarg = i < argc ? argv[i+1] : NULL;
-
- switch (c) {
- case 'a':
- if (!nextarg) usage();
- addr = nextarg;
- i++;
- break;
- case 'm':
- if (!nextarg) usage();
- unsigned newc;
- if (sscanf( nextarg, "%d", &newc) != 1) usage();
- count = newc;
- i++;
- break;
- default:
- usage();
- }
- }
- else usage();
- }
-}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/direct_send.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/direct_send.cpp b/examples/cpp/direct_send.cpp
index 9ffa28a..a4e572c 100644
--- a/examples/cpp/direct_send.cpp
+++ b/examples/cpp/direct_send.cpp
@@ -19,6 +19,8 @@
*
*/
+#include "options.hpp"
+
#include "proton/container.hpp"
#include "proton/messaging_handler.hpp"
#include "proton/connection.hpp"
@@ -74,52 +76,22 @@ class simple_send : public proton::messaging_handler {
}
};
-static void parse_options(int argc, char **argv, int &count, std::string &addr);
-
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 {
- int message_count = 100;
- std::string address("127.0.0.1:5672/examples");
- parse_options(argc, argv, message_count, address);
+ 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;
- }
-}
-
-
-static void usage() {
- std::cout << "Usage: simple_send -m message_count -a address:" << std::endl;
- exit (1);
-}
-
-
-static void parse_options(int argc, char **argv, int &count, std::string &addr) {
- int c, i;
- for (i = 1; i < argc; i++) {
- if (strlen(argv[i]) == 2 && argv[i][0] == '-') {
- c = argv[i][1];
- const char *nextarg = i < argc ? argv[i+1] : NULL;
-
- switch (c) {
- case 'a':
- if (!nextarg) usage();
- addr = nextarg;
- i++;
- break;
- case 'm':
- if (!nextarg) usage();
- unsigned newc;
- if (sscanf( nextarg, "%d", &newc) != 1) usage();
- count = newc;
- i++;
- break;
- default:
- usage();
- }
- }
- else usage();
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/encode_decode.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/encode_decode.cpp b/examples/cpp/encode_decode.cpp
index df9ad15..ea0f471 100644
--- a/examples/cpp/encode_decode.cpp
+++ b/examples/cpp/encode_decode.cpp
@@ -175,10 +175,11 @@ int main(int, char**) {
insert_extract_containers();
mixed_containers();
insert_extract_stream_operators();
+ return 0;
} catch (const exception& e) {
cerr << endl << "error: " << e.what() << endl;
- return 1;
}
+ return 1;
}
// print_next prints the next value from values by recursively descending into complex values.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/example_test.py
----------------------------------------------------------------------
diff --git a/examples/cpp/example_test.py b/examples/cpp/example_test.py
index b2110f6..8dd4341 100644
--- a/examples/cpp/example_test.py
+++ b/examples/cpp/example_test.py
@@ -94,7 +94,7 @@ class Broker(object):
def __init__(self):
self.addr = pick_addr()
- cmd = [exe_name("broker"), self.addr]
+ cmd = [exe_name("broker"), "-a", self.addr]
try:
self.process = Popen(cmd, stdout=NULL, stderr=NULL)
wait_addr(self.addr)
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/helloworld.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/helloworld.cpp b/examples/cpp/helloworld.cpp
index 13bdbc7..34e5076 100644
--- a/examples/cpp/helloworld.cpp
+++ b/examples/cpp/helloworld.cpp
@@ -27,16 +27,16 @@
class hello_world : public proton::messaging_handler {
private:
- proton::url server;
- std::string address;
+ proton::url url;
+
public:
- hello_world(const proton::url &url) : server(url), address(url.path()) {}
+ hello_world(const proton::url& u) : url(u) {}
void on_start(proton::event &e) {
- proton::connection conn = e.container().connect(server);
- e.container().create_receiver(conn, address);
- e.container().create_sender(conn, address);
+ proton::connection conn = e.container().connect(url);
+ e.container().create_receiver(conn, url.path());
+ e.container().create_sender(conn, url.path());
}
void on_sendable(proton::event &e) {
@@ -58,8 +58,9 @@ int main(int argc, char **argv) {
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;
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/helloworld_blocking.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/helloworld_blocking.cpp b/examples/cpp/helloworld_blocking.cpp
index ff14320..2b6b4db 100644
--- a/examples/cpp/helloworld_blocking.cpp
+++ b/examples/cpp/helloworld_blocking.cpp
@@ -27,15 +27,15 @@
class hello_world_blocking : public proton::messaging_handler {
private:
- std::string server;
- std::string address;
+ proton::url url;
+
public:
- hello_world_blocking(const std::string &s, const std::string &addr) : server(s), address(addr) {}
+ hello_world_blocking(const proton::url& u) : url(u) {}
void on_start(proton::event &e) {
- proton::connection conn = e.container().connect(server);
- e.container().create_receiver(conn, address);
+ proton::connection conn = e.container().connect(url);
+ e.container().create_receiver(conn, url.path());
}
void on_message(proton::event &e) {
@@ -47,20 +47,21 @@ class hello_world_blocking : public proton::messaging_handler {
int main(int argc, char **argv) {
try {
- std::string server = argc > 1 ? argv[1] : ":5672";
- std::string addr = argc > 2 ? argv[2] : "examples";
- proton::blocking_connection conn(server);
- proton::blocking_sender sender = conn.create_sender(addr);
+ proton::url url(argc > 1 ? argv[1] : "127.0.0.1:5672/examples");
+
+ proton::blocking_connection conn(url);
+ proton::blocking_sender sender = conn.create_sender(url.path());
proton::message m;
m.body("Hello World!");
sender.send(m);
conn.close();
// TODO Temporary hack until blocking receiver available
- hello_world_blocking hw(server, addr);
+ hello_world_blocking hw(url);
proton::container(hw).run();
+ return 0;
} catch (const std::exception& e) {
std::cerr << e.what() << std::endl;
- return 1;
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/helloworld_direct.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/helloworld_direct.cpp b/examples/cpp/helloworld_direct.cpp
index d81d2b7..2c7792e 100644
--- a/examples/cpp/helloworld_direct.cpp
+++ b/examples/cpp/helloworld_direct.cpp
@@ -27,15 +27,15 @@
class hello_world_direct : public proton::messaging_handler {
private:
- proton::url url_;
- proton::acceptor acceptor_;
+ proton::url url;
+ proton::acceptor acceptor;
public:
- hello_world_direct(const std::string &u) : url_(u) {}
+ hello_world_direct(const proton::url& u) : url(u) {}
void on_start(proton::event &e) {
- acceptor_ = e.container().listen(url_);
- e.container().create_sender(url_);
+ acceptor = e.container().listen(url);
+ e.container().create_sender(url);
}
void on_sendable(proton::event &e) {
@@ -54,18 +54,20 @@ class hello_world_direct : public proton::messaging_handler {
}
void on_connection_closed(proton::event &e) {
- acceptor_.close();
+ acceptor.close();
}
-
};
int main(int argc, char **argv) {
try {
- std::string url = argc > 1 ? argv[1] : ":8888/examples";
+ // 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;
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/options.hpp
----------------------------------------------------------------------
diff --git a/examples/cpp/options.hpp b/examples/cpp/options.hpp
new file mode 100644
index 0000000..5378507
--- /dev/null
+++ b/examples/cpp/options.hpp
@@ -0,0 +1,173 @@
+#ifndef OPTIONS_HPP
+#define OPTIONS_HPP
+/*
+ * 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
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include <string>
+#include <sstream>
+#include <ostream>
+#include <vector>
+#include <stdexcept>
+
+/** bad_option is thrown for option parsing errors */
+struct bad_option : public std::runtime_error {
+ bad_option(const std::string& s) : std::runtime_error(s) {}
+};
+
+/** Simple command-line option parser for example programs */
+class options {
+ public:
+
+ options(int argc, char const * const * argv) : argc_(argc), argv_(argv), prog_(argv[0]), help_() {
+ size_t slash = prog_.find_last_of("/\\");
+ if (slash != std::string::npos)
+ prog_ = prog_.substr(slash+1); // Extract prog name from path
+ add_flag(help_, 'h', "help", "Print the help message");
+ }
+
+ ~options() {
+ for (opts::iterator i = opts_.begin(); i != opts_.end(); ++i)
+ delete *i;
+ }
+
+ /** Updates value when parse() is called if option is present with a value. */
+ template<class T>
+ void add_value(T& value, char short_name, const std::string& long_name, const std::string& description, const std::string var) {
+ opts_.push_back(new option_value<T>(value, short_name, long_name, description, var));
+ }
+
+ /** Sets flag when parse() is called if option is present. */
+ void add_flag(bool& flag, char short_name, const std::string& long_name, const std::string& description) {
+ opts_.push_back(new option_flag(flag, short_name, long_name, description));
+ }
+
+ /** Parse the command line, return the index of the first non-option argument.
+ *@throws bad_option if there is a parsing error or unknown option.
+ */
+ int parse() {
+ int arg = 1;
+ for (; arg < argc_ && argv_[arg][0] == '-'; ++arg) {
+ opts::iterator i = opts_.begin();
+ while (i != opts_.end() && !(*i)->parse(argc_, argv_, arg))
+ ++i;
+ if (i == opts_.end())
+ throw bad_option(std::string("unknown option ") + argv_[arg]);
+ }
+ if (help_) throw bad_option("");
+ return arg;
+ }
+
+ /** Print a usage message */
+ friend std::ostream& operator<<(std::ostream& os, const options& op) {
+ os << std::endl << "usage: " << op.prog_ << " [options]" << std::endl;
+ os << std::endl << "options:" << std::endl;
+ for (opts::const_iterator i = op.opts_.begin(); i < op.opts_.end(); ++i)
+ os << **i << std::endl;
+ return os;
+ }
+
+ private:
+ class option {
+ public:
+ option(char s, const std::string& l, const std::string& d, const std::string v) :
+ short_(std::string("-") + s), long_("--" + l), desc_(d), var_(v) {}
+ virtual ~option() {}
+
+ virtual bool parse(int argc, char const * const * argv, int &i) = 0;
+ virtual void print_default(std::ostream&) const {};
+
+ friend std::ostream& operator<<(std::ostream& os, const option& op) {
+ os << " " << op.short_;
+ if (!op.var_.empty()) os << " " << op.var_;
+ os << ", " << op.long_;
+ if (!op.var_.empty()) os << "=" << op.var_;
+ os << std::endl << " " << op.desc_;
+ op.print_default(os);
+ return os;
+ }
+
+ protected:
+ std::string short_, long_, desc_, var_;
+ };
+
+ template <class T>
+ class option_value : public option {
+ public:
+ option_value(T& value, char s, const std::string& l, const std::string& d, const std::string& v) :
+ option(s, l, d, v), value_(value) {}
+
+ bool parse(int argc, char const * const * argv, int &i) {
+ std::string arg(argv[i]);
+ if (arg == short_ || arg == long_) {
+ if (i < argc-1) {
+ set_value(arg, argv[++i]);
+ return true;
+ } else {
+ throw bad_option("missing value for " + arg);
+ }
+ }
+ if (arg.compare(0, long_.size(), long_) == 0 && arg[long_.size()] == '=' ) {
+ set_value(long_, arg.substr(long_.size()+1));
+ return true;
+ }
+ return false;
+ }
+
+ virtual void print_default(std::ostream& os) const { os << " (default " << value_ << ")"; }
+
+ void set_value(const std::string& opt, const std::string& s) {
+ std::istringstream is(s);
+ is >> value_;
+ if (is.fail() || is.bad())
+ throw bad_option("bad value for " + opt + ": " + s);
+ }
+
+ private:
+ T& value_;
+ };
+
+ class option_flag: public option {
+ public:
+ option_flag(bool& flag, const char s, const std::string& l, const std::string& d) :
+ option(s, l, d, ""), flag_(flag)
+ { flag_ = false; }
+
+ bool parse(int /*argc*/, char const * const * argv, int &i) {
+ if (argv[i] == short_ || argv[i] == long_) {
+ flag_ = true;
+ return true;
+ } else {
+ return false;
+ }
+ }
+
+ private:
+ bool &flag_;
+ };
+
+ typedef std::vector<option*> opts;
+
+ int argc_;
+ char const * const * argv_;
+ std::string prog_;
+ opts opts_;
+ bool help_;
+};
+
+#endif // OPTIONS_HPP
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/simple_recv.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/simple_recv.cpp b/examples/cpp/simple_recv.cpp
index 8cc8bc4..b2cec63 100644
--- a/examples/cpp/simple_recv.cpp
+++ b/examples/cpp/simple_recv.cpp
@@ -19,6 +19,8 @@
*
*/
+#include "options.hpp"
+
#include "proton/container.hpp"
#include "proton/messaging_handler.hpp"
#include "proton/link.hpp"
@@ -63,52 +65,23 @@ class simple_recv : public proton::messaging_handler {
}
};
-static void parse_options(int argc, char **argv, int &count, std::string &addr);
-
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 {
- int message_count = 100;
- std::string address("127.0.0.1:5672/examples");
- parse_options(argc, argv, message_count, address);
+ 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;
- }
-}
-
-
-static void usage() {
- std::cout << "Usage: simple_recv -m message_count -a address:" << std::endl;
- exit (1);
-}
-
-
-static void parse_options(int argc, char **argv, int &count, std::string &addr) {
- int c, i;
- for (i = 1; i < argc; i++) {
- if (strlen(argv[i]) == 2 && argv[i][0] == '-') {
- c = argv[i][1];
- const char *nextarg = i < argc ? argv[i+1] : NULL;
-
- switch (c) {
- case 'a':
- if (!nextarg) usage();
- addr = nextarg;
- i++;
- break;
- case 'm':
- if (!nextarg) usage();
- unsigned newc;
- if (sscanf( nextarg, "%d", &newc) != 1) usage();
- count = newc;
- i++;
- break;
- default:
- usage();
- }
- }
- else usage();
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/examples/cpp/simple_send.cpp
----------------------------------------------------------------------
diff --git a/examples/cpp/simple_send.cpp b/examples/cpp/simple_send.cpp
index 0cf4cd3..0bac49b 100644
--- a/examples/cpp/simple_send.cpp
+++ b/examples/cpp/simple_send.cpp
@@ -19,6 +19,8 @@
*
*/
+#include "options.hpp"
+
#include "proton/container.hpp"
#include "proton/messaging_handler.hpp"
#include "proton/connection.hpp"
@@ -71,52 +73,22 @@ class simple_send : public proton::messaging_handler {
}
};
-static void parse_options(int argc, char **argv, int &count, std::string &addr);
-
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", "receive COUNT messages", "COUNT");
try {
- int message_count = 100;
- std::string address("127.0.0.1:5672/examples");
- parse_options(argc, argv, message_count, address);
+ 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;
- }
-}
-
-
-static void usage() {
- std::cout << "Usage: simple_send -m message_count -a address:" << std::endl;
- exit (1);
-}
-
-
-static void parse_options(int argc, char **argv, int &count, std::string &addr) {
- int c, i;
- for (i = 1; i < argc; i++) {
- if (strlen(argv[i]) == 2 && argv[i][0] == '-') {
- c = argv[i][1];
- const char *nextarg = i < argc ? argv[i+1] : NULL;
-
- switch (c) {
- case 'a':
- if (!nextarg) usage();
- addr = nextarg;
- i++;
- break;
- case 'm':
- if (!nextarg) usage();
- unsigned newc;
- if (sscanf( nextarg, "%d", &newc) != 1) usage();
- count = newc;
- i++;
- break;
- default:
- usage();
- }
- }
- else usage();
}
+ return 1;
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/README.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/README.md b/proton-c/bindings/cpp/README.md
index b6640e5..28eabbe 100644
--- a/proton-c/bindings/cpp/README.md
+++ b/proton-c/bindings/cpp/README.md
@@ -8,10 +8,8 @@ API documentation in doxygen format.
# TO DO
Doc & examples
-- Example set with tutorial documentation. Follow pyton examples + C++ encode/decode example.
- - Consistent option parsing for examples, like other languages.
- - Auto tests for all examples validating all statements & code in tutorial.
-- API documentation, fill out & organize for readable doxygen HTML.
+- Finish example set and tutorial documentation, following pyton examples.
+- Auto tests for all examples validating all statements & code in tutorial.
- C++ section on website.
Bugs
@@ -19,7 +17,7 @@ Bugs
- Drop PIMPL pattern in API: pn_foo pointer is already hiding the impl.
- Proper ownership of pn_objects created by user, e.g. Message. Let user choose pointer style?
- Error handling, examples crash on error e.g. queue not found.
-- FIXME and TODO notes in code.
+- TODO notes in code.
Tests
- Interop/type testing for full AMQP type coverage.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/docs/tutorial.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/tutorial.md b/proton-c/bindings/cpp/docs/tutorial.md
index 91c3c91..e695aaf 100644
--- a/proton-c/bindings/cpp/docs/tutorial.md
+++ b/proton-c/bindings/cpp/docs/tutorial.md
@@ -5,23 +5,18 @@ This is a brief tutorial that will walk you through the fundamentals of building
messaging applications in incremental steps. There are further examples, in
addition the ones mentioned in the tutorial.
-Note on Brokers and URLs
-------------------------
+Some of the examples require an AMQP *broker* that can receive, store and send
+messages. \ref broker.cpp is a simple example broker which you can use. When run
+without arguments it listens on `0.0.0.0:5672`, the standard AMQP port on all
+network interfaces. To use a different port or network interface:
-Some of the examples require an AMQP *broker* that can receive, store and send messages.
-
-There is a very simple broker included as an example (\ref broker.cpp) which you can use.
-Run it like this:
-
- broker [URL]
-
-The default URL is "0.0.0.0:5672" which listens on the standard AMQP port on all
-network interfaces.
+ broker -a <host>:<port>
Instead of the example broker, you can use any AMQP 1.0 compliant broker. You
must configure your broker to have a queue (or topic) named "examples".
-Most of the examples take an optional URL argument, the simplest form is:
+Most of the examples take an optional URL argument or `-a URL` option the
+URL looks like:
HOST:PORT/ADDRESS
@@ -140,6 +135,11 @@ event loop exits, and the run() method will return.
So now we have our example working without a broker involved!
+Note that for this example we paick an "unusual" port 8888 since we are talking
+to ourselves rather than a broker.
+
+\skipline url =
+
Asynchronous Send and Receive
-----------------------------
@@ -212,7 +212,7 @@ got to.
\dontinclude simple_recv.cpp
-Now let's look at the corresponding receiver \ref simple_recv.cpp:
+Now let's look at the corresponding receiver \ref simple_recv.cpp
This time we'll use an `expected` member variable for for the number of messages we expecct and
a `received` variable to count how many we have received so far.send.
@@ -295,7 +295,7 @@ as a simple broker for testing purposes is an example of this).
Request/Response
----------------
-\todo FIXME missing example in C++
+\todo TODO missing example in C++
A common pattern is to send a request message and expect a response message in
return. AMQP has special support for this pattern. Let's have a look at a simple
@@ -303,7 +303,7 @@ example. We'll start with \ref server.cpp, the program that will process the
request and send the response. Note that we are still using a broker in this
example.
-\todo FIXME insert server snips
+\todo TODO insert server snips
Our server will provide a very simple service: it will respond with the
body of the request converted to uppercase.
@@ -316,7 +316,7 @@ reply\_to.
Now let's create a simple \ref client.cpp to test this service out.
-\todo FIXME insert client snips
+\todo TODO insert client snips
As well as sending requests, we need to be able to get back the
responses. We create a receiver for that (see line 14), but we don't
@@ -335,7 +335,7 @@ Again, we could avoid having any intermediary process here if we wished.
The following code implementas a server to which the client above could
connect directly without any need for a broker or similar.
-\todo FIXME missing server_direct.cpp
+\todo TODO missing server_direct.cpp
Though this requires some more extensive changes than the simple sending
and receiving examples, the essence of the program is still the same.
@@ -349,7 +349,7 @@ 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:
-\todo FIXME selected_recv.cpp
+\todo TODO selected_recv.cpp
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
@@ -359,4 +359,4 @@ 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:
-\todo FIXME queue_browser.cpp
+\todo TODO queue_browser.cpp
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/acceptor.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/acceptor.hpp b/proton-c/bindings/cpp/include/proton/acceptor.hpp
index 0df9589..bc9edbc 100644
--- a/proton-c/bindings/cpp/include/proton/acceptor.hpp
+++ b/proton-c/bindings/cpp/include/proton/acceptor.hpp
@@ -30,6 +30,7 @@ struct pn_connection_t;
namespace proton {
+/** acceptor accepts connections. @see container::listen */
class acceptor : public proton_handle<pn_acceptor_t>
{
public:
@@ -39,7 +40,9 @@ class acceptor : public proton_handle<pn_acceptor_t>
PN_CPP_EXTERN acceptor& operator=(const acceptor&);
PN_CPP_EXTERN ~acceptor();
+ /** close the acceptor */
PN_CPP_EXTERN void close();
+
private:
friend class proton_impl_ref<acceptor>;
};
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/acking.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/acking.hpp b/proton-c/bindings/cpp/include/proton/acking.hpp
index edc2d81..0001a4d 100644
--- a/proton-c/bindings/cpp/include/proton/acking.hpp
+++ b/proton-c/bindings/cpp/include/proton/acking.hpp
@@ -28,12 +28,19 @@
namespace proton {
+/** acking provides simple functions to acknowledge, or settle, a delivery */
class acking
{
public:
+ /** accept a delivery */
PN_CPP_EXTERN virtual void accept(delivery &d);
+ /** reject a delivery */
PN_CPP_EXTERN virtual void reject(delivery &d);
+ /** release a delivery. Mark it delivery::MODIFIED if it has already been delivered,
+ * delivery::RELEASED otherwise.
+ */
PN_CPP_EXTERN virtual void release(delivery &d, bool delivered=true);
+ /** settle a delivery with the given delivery::state */
PN_CPP_EXTERN virtual void settle(delivery &d, delivery::state s = delivery::REJECTED);
};
@@ -41,3 +48,5 @@ class acking
}
#endif /*!PROTON_CPP_ACKING_H*/
+
+
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/blocking_connection.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/blocking_connection.hpp b/proton-c/bindings/cpp/include/proton/blocking_connection.hpp
index 27d7cdd..9aa456f 100644
--- a/proton-c/bindings/cpp/include/proton/blocking_connection.hpp
+++ b/proton-c/bindings/cpp/include/proton/blocking_connection.hpp
@@ -33,13 +33,14 @@
struct pn_connection_t;
namespace proton {
-
+class url;
class container;
class blocking_connection_impl;
class ssl_domain;
class blocking_sender;
class wait_condition;
+// TODO documentation
class blocking_connection : public handle<blocking_connection_impl>
{
public:
@@ -48,11 +49,11 @@ class blocking_connection : public handle<blocking_connection_impl>
PN_CPP_EXTERN blocking_connection& operator=(const blocking_connection& c);
PN_CPP_EXTERN ~blocking_connection();
- PN_CPP_EXTERN blocking_connection(std::string &url, duration = duration::FOREVER,
- ssl_domain *ssld=0, container *c=0);
+ PN_CPP_EXTERN blocking_connection(const proton::url &url, duration = duration::FOREVER,
+ ssl_domain *ssld=0, container *c=0);
PN_CPP_EXTERN void close();
- PN_CPP_EXTERN blocking_sender create_sender(std::string &address, handler *h=0);
+ PN_CPP_EXTERN blocking_sender create_sender(const std::string &address, handler *h=0);
PN_CPP_EXTERN void wait(wait_condition &condition);
PN_CPP_EXTERN void wait(wait_condition &condition, std::string &msg, duration timeout=duration::FOREVER);
PN_CPP_EXTERN duration timeout();
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/blocking_link.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/blocking_link.hpp b/proton-c/bindings/cpp/include/proton/blocking_link.hpp
index c1872a4..0fe5e9a 100644
--- a/proton-c/bindings/cpp/include/proton/blocking_link.hpp
+++ b/proton-c/bindings/cpp/include/proton/blocking_link.hpp
@@ -35,6 +35,7 @@ namespace proton {
class blocking_connection;
+// TODO documentation
class blocking_link
{
public:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/blocking_sender.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/blocking_sender.hpp b/proton-c/bindings/cpp/include/proton/blocking_sender.hpp
index 0df5a9c..0fa89d9 100644
--- a/proton-c/bindings/cpp/include/proton/blocking_sender.hpp
+++ b/proton-c/bindings/cpp/include/proton/blocking_sender.hpp
@@ -37,6 +37,7 @@ namespace proton {
class blocking_connection;
class blocking_link;
+// TODO documentation
class blocking_sender : public blocking_link
{
public:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/config.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/config.hpp b/proton-c/bindings/cpp/include/proton/config.hpp
new file mode 100644
index 0000000..70260b7
--- /dev/null
+++ b/proton-c/bindings/cpp/include/proton/config.hpp
@@ -0,0 +1,30 @@
+#ifndef CONFIG_HPP
+#define CONFIG_HPP
+/*
+ * 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
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**@file
+ * @internal
+ */
+
+#if (defined(__cplusplus) && __cplusplus >= 201100) || (defined(_MSC_FULL_VER) && _MSC_FULL_VER >= 150030729)
+#define USE_CPP11
+#endif
+
+#endif // CONFIG_HPP
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/connection.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/connection.hpp b/proton-c/bindings/cpp/include/proton/connection.hpp
index 9998a0a..af3c585 100644
--- a/proton-c/bindings/cpp/include/proton/connection.hpp
+++ b/proton-c/bindings/cpp/include/proton/connection.hpp
@@ -36,6 +36,7 @@ class handler;
class transport;
class connection_impl;
+/** connection is the local end of a connectoin to a remote AMQP peer. */
class connection : public endpoint, public handle<connection_impl>
{
public:
@@ -47,15 +48,32 @@ class connection : public endpoint, public handle<connection_impl>
PN_CPP_EXTERN connection& operator=(const connection& c);
+ ///@name getters @{
PN_CPP_EXTERN class transport& transport();
PN_CPP_EXTERN handler *override();
- PN_CPP_EXTERN void override(handler *h);
- PN_CPP_EXTERN void open();
- PN_CPP_EXTERN void close();
PN_CPP_EXTERN pn_connection_t *pn_connection();
PN_CPP_EXTERN class container &container();
PN_CPP_EXTERN std::string hostname();
- PN_CPP_EXTERN link link_head(endpoint::State mask);
+ ///@}
+
+ /** override the handler for this connection */
+ PN_CPP_EXTERN void override(handler *h);
+
+ /** Initiate local open, not complete till messaging_handler::on_connection_opened()
+ * or proton_handler::on_connection_remote_open()
+ */
+ PN_CPP_EXTERN void open();
+
+ /** Initiate local close, not complete till messaging_handler::on_connection_closed()
+ * or proton_handler::on_connection_remote_close()
+ */
+ PN_CPP_EXTERN void close();
+
+ /** Get the first link on this connection matching the state mask.
+ * @see link::next, endpoint::state
+ */
+ PN_CPP_EXTERN link link_head(endpoint::state mask);
+
private:
friend class private_impl_ref<connection>;
friend class connector;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/container.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/container.hpp b/proton-c/bindings/cpp/include/proton/container.hpp
index 2aaa289..ec55167 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -40,35 +40,70 @@ class messaging_handler;
class sender;
class receiver;
class link;
- class handler;
+class handler;
+/** Top level container for connections and other objects, runs the event loop */
class container : public handle<container_impl>
{
public:
+ ///@name internal @internal @{
PN_CPP_EXTERN container(container_impl *);
PN_CPP_EXTERN container(const container& c);
PN_CPP_EXTERN container& operator=(const container& c);
PN_CPP_EXTERN ~container();
+ ///@}
+ /** Create a container */
PN_CPP_EXTERN container();
+
+ /** Create a container and set the top-level messaging_handler */
PN_CPP_EXTERN container(messaging_handler &mhandler);
+
+ /** Locally open a connection @see connection::open */
PN_CPP_EXTERN connection connect(const proton::url&, handler *h=0);
+
+ /** Run the event loop, return when all connections and acceptors are closed. */
PN_CPP_EXTERN void run();
+
+ /** Start the reactor, you must call process() to process events */
PN_CPP_EXTERN void start();
+
+ /** Process events, return true if there are more events to process. */
PN_CPP_EXTERN bool process();
+
+ /** Stop the reactor, causes run() to return and process() to return false. */
PN_CPP_EXTERN void stop();
- PN_CPP_EXTERN void wakeup();
- PN_CPP_EXTERN bool is_quiesced();
- PN_CPP_EXTERN pn_reactor_t *reactor();
- PN_CPP_EXTERN sender create_sender(connection &connection, std::string &addr, handler *h=0);
+
+ /** Create a sender on connection with target=addr and optional handler h */
+ PN_CPP_EXTERN sender create_sender(connection &connection, const std::string &addr, handler *h=0);
+
+ /** Open a connection to url and create a sender with target=url.path() */
PN_CPP_EXTERN sender create_sender(const proton::url &);
- PN_CPP_EXTERN receiver create_receiver(connection &connection, std::string &addr);
+
+ /** Create a receiver on connection with target=addr and optional handler h */
+ PN_CPP_EXTERN receiver create_receiver(connection &connection, const std::string &addr, handler *h=0);
+
+ /** Create a receiver on connection with source=addr and optional handler h */
PN_CPP_EXTERN receiver create_receiver(const url &);
+
+ /** Open a connection to url and create a receiver with source=url.path() */
PN_CPP_EXTERN acceptor listen(const proton::url &);
+
+ /// Identifier for the container
PN_CPP_EXTERN std::string container_id();
+
+ /// Get timeout, process() will return if there is no activity within the timeout.
PN_CPP_EXTERN duration timeout();
+
+ /// Set timeout, process() will return if there is no activity within the timeout.
PN_CPP_EXTERN void timeout(duration timeout);
- private:
+
+ /// Get the reactor
+ PN_CPP_EXTERN pn_reactor_t *reactor();
+
+ PN_CPP_EXTERN void wakeup();
+ PN_CPP_EXTERN bool is_quiesced();
+private:
friend class private_impl_ref<container>;
};
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/data.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/data.hpp b/proton-c/bindings/cpp/include/proton/data.hpp
index c0d3e8c..638315a 100644
--- a/proton-c/bindings/cpp/include/proton/data.hpp
+++ b/proton-c/bindings/cpp/include/proton/data.hpp
@@ -26,7 +26,7 @@ struct pn_data_t;
namespace proton {
-/** Base for classes that hold AMQP data. */
+/** Base for classes that hold AMQP data, not for direct use. @see value, encoder, decoder. */
class data {
public:
PN_CPP_EXTERN explicit data();
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/decoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/decoder.hpp b/proton-c/bindings/cpp/include/proton/decoder.hpp
index 22effe3..6761653 100644
--- a/proton-c/bindings/cpp/include/proton/decoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/decoder.hpp
@@ -29,13 +29,13 @@ namespace proton {
class value;
-/** Raised by decoder operations on error. @ingroup cpp*/
+/** Raised by decoder operations on error.*/
struct decode_error : public error { PN_CPP_EXTERN explicit decode_error(const std::string&) throw(); };
-/** Skips a value with `decoder >> skip()`. @ingroup cpp */
+/** Skips a value with `decoder >> skip()`. */
struct skip{};
-/** Rewind the decoder with `decoder >> rewind()`. @ingroup cpp */
+/** Rewind the decoder with `decoder >> rewind()`. */
struct rewind{};
/**
@@ -64,7 +64,7 @@ struct rewind{};
* extracting AMQP maps.
*
* You can also extract container values element-by-element, see decoder::operator>>(decoder&, start&)
- * @ingroup cpp
+ *
*/
class decoder : public virtual data {
public:
@@ -126,7 +126,7 @@ class decoder : public virtual data {
template <class T, type_id A> T get_as() { T value; *this >> as<A>(value); return value; }
/** Call decoder::start() in constructor, decoder::finish in destructor().
- * @ingroup cpp
+ *
*/
struct scope : public start {
decoder& decoder_;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/delivery.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/delivery.hpp b/proton-c/bindings/cpp/include/proton/delivery.hpp
index 0dc80da..3f4dafc 100644
--- a/proton-c/bindings/cpp/include/proton/delivery.hpp
+++ b/proton-c/bindings/cpp/include/proton/delivery.hpp
@@ -29,17 +29,19 @@
namespace proton {
+/** delivery status of a message */
class delivery : public proton_handle<pn_delivery_t>
{
public:
+ /** Delivery state of a message */
enum state {
- NONE = 0,
- RECEIVED = PN_RECEIVED,
- ACCEPTED = PN_ACCEPTED,
- REJECTED = PN_REJECTED,
- RELEASED = PN_RELEASED,
- MODIFIED = PN_MODIFIED
+ 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
PN_CPP_EXTERN delivery(pn_delivery_t *d);
@@ -47,8 +49,15 @@ class delivery : public proton_handle<pn_delivery_t>
PN_CPP_EXTERN ~delivery();
PN_CPP_EXTERN delivery(const delivery&);
PN_CPP_EXTERN delivery& operator=(const delivery&);
+
+ /** Return true if the delivery has been settled. */
PN_CPP_EXTERN bool settled();
+
+ /** Settle the delivery, informs the remote end. */
PN_CPP_EXTERN void settle();
+
+ // TODO aconway 2015-07-15: add update() here?
+
PN_CPP_EXTERN pn_delivery_t *pn_delivery();
private:
friend class proton_impl_ref<delivery>;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/duration.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/duration.hpp b/proton-c/bindings/cpp/include/proton/duration.hpp
index b5bd59b..8b7d1ad 100644
--- a/proton-c/bindings/cpp/include/proton/duration.hpp
+++ b/proton-c/bindings/cpp/include/proton/duration.hpp
@@ -27,9 +27,7 @@
namespace proton {
-/** @ingroup cpp
- * A duration is a time in milliseconds.
- */
+/** Duration in milliseconds. */
class duration : public comparable<duration>
{
public:
@@ -39,10 +37,10 @@ class duration : public comparable<duration>
bool operator<(duration d) { return milliseconds < d.milliseconds; }
bool operator==(duration d) { return milliseconds == d.milliseconds; }
- PN_CPP_EXTERN static const duration FOREVER;
- PN_CPP_EXTERN static const duration IMMEDIATE;
- PN_CPP_EXTERN static const duration SECOND;
- PN_CPP_EXTERN static const duration MINUTE;
+ 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
};
inline duration operator*(duration d, std::uint64_t n) { return duration(d.milliseconds*n); }
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/encoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/encoder.hpp b/proton-c/bindings/cpp/include/proton/encoder.hpp
index 57f3c45..b3e2ab4 100644
--- a/proton-c/bindings/cpp/include/proton/encoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/encoder.hpp
@@ -25,8 +25,6 @@
#include "proton/type_traits.hpp"
#include <iosfwd>
-#include <iostream> // FIXME aconway 2015-06-18:
-
struct pn_data_t;
namespace proton {
@@ -60,7 +58,6 @@ struct encode_error : public error { PN_CPP_EXTERN explicit encode_error(const s
* You can also insert containers element-by-element, see operator<<(encoder&, const start&)
*
*@throw decoder::error if the curent value is not a container type.
- *@ingroup cpp
*/
class encoder : public virtual data {
public:
@@ -137,7 +134,7 @@ class encoder : public virtual data {
template <class T> friend encoder& operator<<(encoder&, cref<T, ARRAY>);
template <class T> friend encoder& operator<<(encoder&, cref<T, LIST>);
template <class T> friend encoder& operator<<(encoder&, cref<T, MAP>);
- // TODO aconway 2015-06-16: DESCRIBED.
+ // TODO aconway 2015-06-16: described values.
///@}
/** Copy data from a raw pn_data_t */
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/endpoint.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/endpoint.hpp b/proton-c/bindings/cpp/include/proton/endpoint.hpp
index 89904ba..11970c7 100644
--- a/proton-c/bindings/cpp/include/proton/endpoint.hpp
+++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp
@@ -30,21 +30,36 @@ class handler;
class connection;
class transport;
+/** endpoint is a base class for session, connection and link */
class endpoint
{
public:
- enum {
- LOCAL_UNINIT = PN_LOCAL_UNINIT,
- REMOTE_UNINIT = PN_REMOTE_UNINIT,
- LOCAL_ACTIVE = PN_LOCAL_ACTIVE,
- REMOTE_ACTIVE = PN_REMOTE_ACTIVE,
- LOCAL_CLOSED = PN_LOCAL_CLOSED,
- REMOTE_CLOSED = PN_REMOTE_CLOSED
- };
- typedef int State;
+ /** 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::link_head, connection::session_head, link::next, session::next
+ */
+ typedef int state;
+
+ /// endpoint state bit values @{
+ static const int LOCAL_UNINIT; ///< Local endpoint is un-initialized
+ static const int REMOTE_UNINIT; ///< Remote endpoint is un-initialized
+ static const int LOCAL_ACTIVE; ///< Local endpoint is active
+ static const int REMOTE_ACTIVE; ///< Remote endpoint is active
+ static const int LOCAL_CLOSED; ///< Local endpoint has been closed
+ static const int REMOTE_CLOSED; ///< Remote endpoint has been closed
+ static const int LOCAL_MASK; ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED)
+ static const int REMOTE_MASK; ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED)
+ ///@}
// TODO: condition, remote_condition, update_condition, get/handler
-protected:
+
+ protected:
PN_CPP_EXTERN endpoint();
PN_CPP_EXTERN ~endpoint();
};
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/error.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/error.hpp b/proton-c/bindings/cpp/include/proton/error.hpp
index 2e2ac17..6432b71 100644
--- a/proton-c/bindings/cpp/include/proton/error.hpp
+++ b/proton-c/bindings/cpp/include/proton/error.hpp
@@ -27,11 +27,12 @@
namespace proton {
-/** @ingroup cpp
- * Functions in the proton namespace throw a subclass of proton::error on error.
- */
+/** 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&) throw(); };
+/** Raised if timeout expires */
+struct timeout_error : public error { PN_CPP_EXTERN explicit timeout_error(const std::string&) throw(); };
+
/** Raised if a message is rejected */
struct message_reject : public error { PN_CPP_EXTERN explicit message_reject(const std::string&) throw(); };
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/event.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/event.hpp b/proton-c/bindings/cpp/include/proton/event.hpp
index 2feff2b..c4c5d7c 100644
--- a/proton-c/bindings/cpp/include/proton/event.hpp
+++ b/proton-c/bindings/cpp/include/proton/event.hpp
@@ -34,20 +34,32 @@ class handler;
class container;
class connection;
-class event
-{
+/** Context information about a proton event */
+class event {
public:
+ virtual PN_CPP_EXTERN ~event();
+
+ /// Dispatch this event to a handler.
virtual PN_CPP_EXTERN void dispatch(handler &h) = 0;
+
+ /// Get container.
virtual PN_CPP_EXTERN class container &container();
+ /// Get connection.
virtual PN_CPP_EXTERN class connection &connection();
+ /// Get sender @throws error if no sender.
virtual PN_CPP_EXTERN class sender sender();
+ /// Get receiver @throws error if no receiver.
virtual PN_CPP_EXTERN class receiver receiver();
+ /// Get link @throws error if no link.
virtual PN_CPP_EXTERN class link link();
+ /// Get message @throws error if no message.
virtual PN_CPP_EXTERN class message message();
- virtual PN_CPP_EXTERN void message(class message &);
- virtual PN_CPP_EXTERN ~event();
+ /// Get message @throws error if no message.
+ virtual PN_CPP_EXTERN void message(class message&);
+
protected:
PN_CPP_EXTERN event();
+
private:
event(const event&);
event& operator=(const event&);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/export.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/export.hpp b/proton-c/bindings/cpp/include/proton/export.hpp
index 0be5187..bb211ae 100644
--- a/proton-c/bindings/cpp/include/proton/export.hpp
+++ b/proton-c/bindings/cpp/include/proton/export.hpp
@@ -22,6 +22,7 @@
*
*/
+/// Internal: import/export macros @cond INTERNAL
#if defined(WIN32) && !defined(PN_CPP_DECLARE_STATIC)
//
// Import and Export definitions for Windows:
@@ -42,5 +43,6 @@
#else
# define PN_CPP_EXTERN PN_CPP_IMPORT
#endif
+///@endcond
#endif /*!PN_CPP_IMPORTEXPORT_H*/
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/handle.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/handle.hpp b/proton-c/bindings/cpp/include/proton/handle.hpp
index 0a23b01..e0542ef 100644
--- a/proton-c/bindings/cpp/include/proton/handle.hpp
+++ b/proton-c/bindings/cpp/include/proton/handle.hpp
@@ -26,10 +26,10 @@
namespace proton {
+///@cond INTERNAL
template <class> class private_impl_ref;
template <class> class proton_impl_ref;
-
-// FIXME aconway 2015-06-09: don't need handle, get rid of it.
+///@endcond INTERNAL
/**
* A handle is like a pointer: refers to an underlying implementation object.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/handler.hpp b/proton-c/bindings/cpp/include/proton/handler.hpp
index eb019e3..cb4ff81 100644
--- a/proton-c/bindings/cpp/include/proton/handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/handler.hpp
@@ -28,14 +28,19 @@
namespace proton {
+/// Base class for event handlers.
+/// Handlers form a tree, a handler is a vector of pointers to child handlers.
class handler : public std::vector<handler*> {
public:
PN_CPP_EXTERN handler();
PN_CPP_EXTERN virtual ~handler();
+ /// Called if a handler function is not over-ridden to handle an event.
PN_CPP_EXTERN virtual void on_unhandled(event &e);
- PN_CPP_EXTERN virtual void add_child_handler(handler &e);
+ /// Add a child handler, equivalent to this->push_back(&h)
+ /// h must not be deleted before this handler.
+ PN_CPP_EXTERN virtual void add_child_handler(handler &h);
};
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/link.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/link.hpp b/proton-c/bindings/cpp/include/proton/link.hpp
index ba17584..feabfec 100644
--- a/proton-c/bindings/cpp/include/proton/link.hpp
+++ b/proton-c/bindings/cpp/include/proton/link.hpp
@@ -32,6 +32,7 @@ struct pn_connection_t;
namespace proton {
+/** Messages are transferred across a link. Base class for sender, receiver. */
class link : public endpoint, public proton_handle<pn_link_t>
{
public:
@@ -40,20 +41,42 @@ class link : public endpoint, public proton_handle<pn_link_t>
PN_CPP_EXTERN ~link();
PN_CPP_EXTERN link(const link&);
PN_CPP_EXTERN link& operator=(const link&);
+
+ /** Locally open the link, not complete till messaging_handler::on_link_opened or
+ * proton_handler::link_remote_open
+ */
PN_CPP_EXTERN void open();
+
+ /** Locally close the link, not complete till messaging_handler::on_link_closeed or
+ * proton_handler::link_remote_close
+ */
PN_CPP_EXTERN void close();
+
+ /** True if link is a sender */
PN_CPP_EXTERN bool is_sender();
+ /** True if link is a receiver */
PN_CPP_EXTERN bool is_receiver();
+ /** Credit available on the link */
PN_CPP_EXTERN int credit();
+ /** Local source of the link */
PN_CPP_EXTERN terminus source();
+ /** Local target of the link */
PN_CPP_EXTERN terminus target();
+ /** Remote source of the link */
PN_CPP_EXTERN terminus remote_source();
+ /** Remote source of the link */
PN_CPP_EXTERN terminus remote_target();
+ /** Link name */
PN_CPP_EXTERN std::string name();
- PN_CPP_EXTERN pn_link_t *pn_link() const;
- PN_CPP_EXTERN link next(endpoint::State mask);
+
+ /** Next link that matches state mask. @see endpoint::state */
+ PN_CPP_EXTERN link next(endpoint::state mask);
+
+ /** Connection of the link */
PN_CPP_EXTERN class connection &connection();
+ PN_CPP_EXTERN pn_link_t *pn_link() const;
+
protected:
PN_CPP_EXTERN virtual void verify_type(pn_link_t *l);
private:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/message.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp
index 0667337..528088b 100644
--- a/proton-c/bindings/cpp/include/proton/message.hpp
+++ b/proton-c/bindings/cpp/include/proton/message.hpp
@@ -32,7 +32,7 @@ struct pn_data_t;
namespace proton {
-// FIXME aconway 2015-06-17: documentation of properties.
+/// An AMQP message.
class message : public proton_handle<pn_message_t>
{
public:
@@ -44,7 +44,15 @@ class message : public proton_handle<pn_message_t>
PN_CPP_EXTERN pn_message_t *pn_message() const;
+ /** Clear the message content */
+ PN_CPP_EXTERN void clear();
+
+ ///@name Message properties
+ ///@{
+
+ /// Globally unique identifier, can be an a string, an unsigned long, a uuid or a binary value.
PN_CPP_EXTERN void id(const value& id);
+ /// Globally unique identifier, can be an a string, an unsigned long, a uuid or a binary value.
PN_CPP_EXTERN value id() const;
PN_CPP_EXTERN void user(const std::string &user);
@@ -59,7 +67,9 @@ class message : public proton_handle<pn_message_t>
PN_CPP_EXTERN void reply_to(const std::string &s);
PN_CPP_EXTERN std::string reply_to() const;
+ /// Correlation identifier, can be an a string, an unsigned long, a uuid or a binary value.
PN_CPP_EXTERN void correlation_id(const value&);
+ /// Correlation identifier, can be an a string, an unsigned long, a uuid or a binary value.
PN_CPP_EXTERN value correlation_id() const;
PN_CPP_EXTERN void content_type(const std::string &s);
@@ -77,29 +87,35 @@ class message : public proton_handle<pn_message_t>
PN_CPP_EXTERN void group_id(const std::string &s);
PN_CPP_EXTERN std::string group_id() const;
- PN_CPP_EXTERN void reply_togroup_id(const std::string &s);
- PN_CPP_EXTERN std::string reply_togroup_id() const;
+ PN_CPP_EXTERN void reply_to_group_id(const std::string &s);
+ PN_CPP_EXTERN std::string reply_to_group_id() const;
+ ///@}
- /** Set the body to an AMQP value. */
+ /** Set the body to a proton::value. */
PN_CPP_EXTERN void body(const value&);
- /** Template to convert any type to a value and set as the body */
+ /** Set the body to any type T that can be converted to a proton::value */
template <class T> void body(const T& v) { body(value(v)); }
- /** Set the body to a sequence of sections containing AMQP values. */
+ /** Set the body to a sequence of values, each value is encoded as an AMQP section. */
PN_CPP_EXTERN void body(const values&);
+ /** Get the body values, there may be more than one. */
PN_CPP_EXTERN const values& body() const;
- PN_CPP_EXTERN values& body(); ///< Allows in-place modification of body sections.
+ /** Get a reference to the body, can be modified in-place. */
+ PN_CPP_EXTERN values& body();
- // FIXME aconway 2015-06-17: consistent and flexible treatment of buffers.
+ // TODO aconway 2015-06-17: consistent and flexible treatment of buffers.
// Allow convenient std::string encoding/decoding (with re-use of existing
// string capacity) but also need to allow encoding/decoding of non-string
// buffers. Introduce a buffer type with begin/end pointers?
+ /** Encode the message into string data */
PN_CPP_EXTERN void encode(std::string &data);
+ /** Retrun encoded message as a string */
PN_CPP_EXTERN std::string encode();
+ /** Decode from string data into the message. */
PN_CPP_EXTERN void decode(const std::string &data);
private:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/messaging_adapter.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/messaging_adapter.hpp b/proton-c/bindings/cpp/include/proton/messaging_adapter.hpp
index 3486b97..8744c95 100644
--- a/proton-c/bindings/cpp/include/proton/messaging_adapter.hpp
+++ b/proton-c/bindings/cpp/include/proton/messaging_adapter.hpp
@@ -29,6 +29,8 @@
#include "proton/event.h"
#include "proton/reactor.h"
+///@cond INTERNAL
+
namespace proton {
// Combine's Python's: endpoint_state_handler, incoming_message_handler, outgoing_message_handler
@@ -72,5 +74,5 @@ class messaging_adapter : public messaging_handler
};
}
-
+///@endcond INTERNAL
#endif /*!PROTON_CPP_MESSAGING_ADAPTER_H*/
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/messaging_event.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/messaging_event.hpp b/proton-c/bindings/cpp/include/proton/messaging_event.hpp
index 62f0160..950c389 100644
--- a/proton-c/bindings/cpp/include/proton/messaging_event.hpp
+++ b/proton-c/bindings/cpp/include/proton/messaging_event.hpp
@@ -30,54 +30,59 @@ class handler;
class container;
class connection;
-typedef enum {
- PN_MESSAGING_PROTON = 0, // Wrapped pn_event_t
- // Covenience events for C++ messaging_handlers
- PN_MESSAGING_ABORT,
- PN_MESSAGING_ACCEPTED,
- PN_MESSAGING_COMMIT,
- PN_MESSAGING_CONNECTION_CLOSED,
- PN_MESSAGING_CONNECTION_CLOSING,
- PN_MESSAGING_CONNECTION_ERROR,
- PN_MESSAGING_CONNECTION_OPENED,
- PN_MESSAGING_CONNECTION_OPENING,
- PN_MESSAGING_DISCONNECTED,
- PN_MESSAGING_FETCH,
- PN_MESSAGING_Id_LOADED,
- PN_MESSAGING_LINK_CLOSED,
- PN_MESSAGING_LINK_CLOSING,
- PN_MESSAGING_LINK_OPENED,
- PN_MESSAGING_LINK_OPENING,
- PN_MESSAGING_LINK_ERROR,
- PN_MESSAGING_MESSAGE,
- PN_MESSAGING_QUIT,
- PN_MESSAGING_RECORD_INSERTED,
- PN_MESSAGING_RECORDS_LOADED,
- PN_MESSAGING_REJECTED,
- PN_MESSAGING_RELEASED,
- PN_MESSAGING_REQUEST,
- PN_MESSAGING_RESPONSE,
- PN_MESSAGING_SENDABLE,
- PN_MESSAGING_SESSION_CLOSED,
- PN_MESSAGING_SESSION_CLOSING,
- PN_MESSAGING_SESSION_OPENED,
- PN_MESSAGING_SESSION_OPENING,
- PN_MESSAGING_SESSION_ERROR,
- PN_MESSAGING_SETTLED,
- PN_MESSAGING_START,
- PN_MESSAGING_TIMER,
- PN_MESSAGING_TRANSACTION_ABORTED,
- PN_MESSAGING_TRANSACTION_COMMITTED,
- PN_MESSAGING_TRANSACTION_DECLARED,
- PN_MESSAGING_TRANSPORT_CLOSED
-} messaging_event_type_t;
-
+/** An event for the proton::messaging_handler */
class messaging_event : public proton_event
{
public:
+
+ // TODO aconway 2015-07-16: document meaning of each event type.
+
+ /** Event types for a messaging_handler */
+ enum event_type {
+ PROTON = 0, // Wrapped pn_event_t
+ ABORT,
+ ACCEPTED,
+ COMMIT,
+ CONNECTION_CLOSED,
+ CONNECTION_CLOSING,
+ CONNECTION_ERROR,
+ CONNECTION_OPENED,
+ CONNECTION_OPENING,
+ DISCONNECTED,
+ FETCH,
+ ID_LOADED,
+ LINK_CLOSED,
+ LINK_CLOSING,
+ LINK_OPENED,
+ LINK_OPENING,
+ LINK_ERROR,
+ MESSAGE,
+ QUIT,
+ RECORD_INSERTED,
+ RECORDS_LOADED,
+ REJECTED,
+ RELEASED,
+ REQUEST,
+ RESPONSE,
+ SENDABLE,
+ SESSION_CLOSED,
+ SESSION_CLOSING,
+ SESSION_OPENED,
+ SESSION_OPENING,
+ SESSION_ERROR,
+ SETTLED,
+ START,
+ TIMER,
+ TRANSACTION_ABORTED,
+ TRANSACTION_COMMITTED,
+ TRANSACTION_DECLARED,
+ TRANSPORT_CLOSED
+ };
+
messaging_event(pn_event_t *ce, pn_event_type_t t, class container &c);
- messaging_event(messaging_event_type_t t, proton_event &parent);
+ messaging_event(event_type t, proton_event &parent);
~messaging_event();
+
virtual PN_CPP_EXTERN void dispatch(handler &h);
virtual PN_CPP_EXTERN class connection &connection();
virtual PN_CPP_EXTERN class sender sender();
@@ -85,8 +90,10 @@ class messaging_event : public proton_event
virtual PN_CPP_EXTERN class link link();
virtual PN_CPP_EXTERN class message message();
virtual PN_CPP_EXTERN void message(class message &);
+ PN_CPP_EXTERN event_type type() const;
+
private:
- messaging_event_type_t messaging_type_;
+ event_type type_;
proton_event *parent_event_;
class message *message_;
messaging_event operator=(const messaging_event&);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
index 946b9b5..7de6ebd 100644
--- a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
@@ -31,13 +31,27 @@ namespace proton {
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.
+ */
class messaging_handler : public proton_handler , public acking
{
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 messaging_handler(int prefetch=10, bool auto_accept=true, bool auto_settle=true,
- bool peer_close_is_error=false);
+ bool peer_close_is_error=false);
+
PN_CPP_EXTERN virtual ~messaging_handler();
+ ///@name Over-ride these member functions to handle events
+ ///@{
PN_CPP_EXTERN virtual void on_abort(event &e);
PN_CPP_EXTERN virtual void on_accepted(event &e);
PN_CPP_EXTERN virtual void on_commit(event &e);
@@ -75,8 +89,9 @@ class messaging_handler : public proton_handler , public acking
PN_CPP_EXTERN virtual void on_transaction_committed(event &e);
PN_CPP_EXTERN virtual void on_transaction_declared(event &e);
PN_CPP_EXTERN virtual void on_transport_closed(event &e);
+ ///@}
- private:
+ private:
int prefetch_;
bool auto_accept_;
bool auto_settle_;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/proton_event.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/proton_event.hpp b/proton-c/bindings/cpp/include/proton/proton_event.hpp
index c4bd5e8..d811ae5 100644
--- a/proton-c/bindings/cpp/include/proton/proton_event.hpp
+++ b/proton-c/bindings/cpp/include/proton/proton_event.hpp
@@ -31,22 +31,260 @@ class container;
class connection;
class container;
+/** Event information for a proton::proton_handler */
class proton_event : public event
{
public:
+
+ ///@name Event types
+ ///@{
+
+ /// The type of an event
+ typedef int event_type;
+
+ /**
+ * Defined as a programming convenience. No event of this type will
+ * ever be generated.
+ */
+ PN_CPP_EXTERN static const event_type EVENT_NONE;
+
+ /**
+ * A reactor has been started. Events of this type point to the reactor.
+ */
+ PN_CPP_EXTERN static const event_type REACTOR_INIT;
+
+ /**
+ * A reactor has no more events to process. Events of this type
+ * point to the reactor.
+ */
+ PN_CPP_EXTERN static const event_type REACTOR_QUIESCED;
+
+ /**
+ * A reactor has been stopped. Events of this type point to the reactor.
+ */
+ PN_CPP_EXTERN static const event_type REACTOR_FINAL;
+
+ /**
+ * A timer event has occurred.
+ */
+ PN_CPP_EXTERN static const event_type TIMER_TASK;
+
+ /**
+ * The connection has been created. This is the first event that
+ * will ever be issued for a connection. Events of this type point
+ * to the relevant connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_INIT;
+
+ /**
+ * The connection has been bound to a transport. This event is
+ * issued when the transport::bind() is called.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_BOUND;
+
+ /**
+ * The connection has been unbound from its transport. This event is
+ * issued when transport::unbind() is called.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_UNBOUND;
+
+ /**
+ * The local connection endpoint has been closed. Events of this
+ * type point to the relevant connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_LOCAL_OPEN;
+
+ /**
+ * The remote endpoint has opened the connection. Events of this
+ * type point to the relevant connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_REMOTE_OPEN;
+
+ /**
+ * The local connection endpoint has been closed. Events of this
+ * type point to the relevant connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_LOCAL_CLOSE;
+
+ /**
+ * The remote endpoint has closed the connection. Events of this
+ * type point to the relevant connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_REMOTE_CLOSE;
+
+ /**
+ * The connection has been freed and any outstanding processing has
+ * been completed. This is the final event that will ever be issued
+ * for a connection.
+ */
+ PN_CPP_EXTERN static const event_type CONNECTION_FINAL;
+
+ /**
+ * The session has been created. This is the first event that will
+ * ever be issued for a session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_INIT;
+
+ /**
+ * The local session endpoint has been opened. Events of this type
+ * point ot the relevant session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_LOCAL_OPEN;
+
+ /**
+ * The remote endpoint has opened the session. Events of this type
+ * point to the relevant session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_REMOTE_OPEN;
+
+ /**
+ * The local session endpoint has been closed. Events of this type
+ * point ot the relevant session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_LOCAL_CLOSE;
+
+ /**
+ * The remote endpoint has closed the session. Events of this type
+ * point to the relevant session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_REMOTE_CLOSE;
+
+ /**
+ * The session has been freed and any outstanding processing has
+ * been completed. This is the final event that will ever be issued
+ * for a session.
+ */
+ PN_CPP_EXTERN static const event_type SESSION_FINAL;
+
+ /**
+ * The link has been created. This is the first event that will ever
+ * be issued for a link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_INIT;
+
+ /**
+ * The local link endpoint has been opened. Events of this type
+ * point ot the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_LOCAL_OPEN;
+
+ /**
+ * The remote endpoint has opened the link. Events of this type
+ * point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_REMOTE_OPEN;
+
+ /**
+ * The local link endpoint has been closed. Events of this type
+ * point ot the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_LOCAL_CLOSE;
+
+ /**
+ * The remote endpoint has closed the link. Events of this type
+ * point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_REMOTE_CLOSE;
+
+ /**
+ * The local link endpoint has been detached. Events of this type
+ * point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_LOCAL_DETACH;
+
+ /**
+ * The remote endpoint has detached the link. Events of this type
+ * point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_REMOTE_DETACH;
+
+ /**
+ * The flow control state for a link has changed. Events of this
+ * type point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_FLOW;
+
+ /**
+ * The link has been freed and any outstanding processing has been
+ * completed. This is the final event that will ever be issued for a
+ * link. Events of this type point to the relevant link.
+ */
+ PN_CPP_EXTERN static const event_type LINK_FINAL;
+
+ /**
+ * A delivery has been created or updated. Events of this type point
+ * to the relevant delivery.
+ */
+ PN_CPP_EXTERN static const event_type DELIVERY;
+
+ /**
+ * The transport has new data to read and/or write. Events of this
+ * type point to the relevant transport.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT;
+
+ /**
+ * The transport has authenticated, if this is received by a server
+ * the associated transport has authenticated an incoming connection
+ * and transport::user() can be used to obtain the authenticated
+ * user.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT_AUTHENTICATED;
+
+ /**
+ * Indicates that a transport error has occurred. Use
+ * transport::condition() to access the details of the error
+ * from the associated transport.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT_ERROR;
+
+ /**
+ * Indicates that the head of the transport has been closed. This
+ * means the transport will never produce more bytes for output to
+ * the network. Events of this type point to the relevant transport.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT_HEAD_CLOSED;
+
+ /**
+ * Indicates that the tail of the transport has been closed. This
+ * means the transport will never be able to process more bytes from
+ * the network. Events of this type point to the relevant transport.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT_TAIL_CLOSED;
+
+ /**
+ * Indicates that the both the head and tail of the transport are
+ * closed. Events of this type point to the relevant transport.
+ */
+ PN_CPP_EXTERN static const event_type TRANSPORT_CLOSED;
+
+ PN_CPP_EXTERN static const event_type SELECTABLE_INIT;
+ PN_CPP_EXTERN static const event_type SELECTABLE_UPDATED;
+ PN_CPP_EXTERN static const event_type SELECTABLE_READABLE;
+ PN_CPP_EXTERN static const event_type SELECTABLE_WRITABLE;
+ PN_CPP_EXTERN static const event_type SELECTABLE_ERROR;
+ PN_CPP_EXTERN static const event_type SELECTABLE_EXPIRED;
+ PN_CPP_EXTERN static const event_type SELECTABLE_FINAL;
+
+ ///@}
+
virtual PN_CPP_EXTERN void dispatch(handler &h);
virtual PN_CPP_EXTERN class container &container();
virtual PN_CPP_EXTERN class connection &connection();
virtual PN_CPP_EXTERN class sender sender();
virtual PN_CPP_EXTERN class receiver receiver();
virtual PN_CPP_EXTERN class link link();
- PN_CPP_EXTERN int type();
+
+ /** Get type of event */
+ PN_CPP_EXTERN event_type type();
+
PN_CPP_EXTERN pn_event_t* pn_event();
+
protected:
PN_CPP_EXTERN proton_event(pn_event_t *ce, pn_event_type_t t, class container &c);
private:
pn_event_t *pn_event_;
- int type_;
+ event_type type_;
class container &container_;
};
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/proton_handle.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/proton_handle.hpp b/proton-c/bindings/cpp/include/proton/proton_handle.hpp
index 5799bf6..6fc9211 100644
--- a/proton-c/bindings/cpp/include/proton/proton_handle.hpp
+++ b/proton-c/bindings/cpp/include/proton/proton_handle.hpp
@@ -26,7 +26,9 @@
namespace proton {
+///@cond INTERNAL
template <class> class proton_impl_ref;
+///@endcond INTERNAL
/**
* See handle.h. Similar but for lightly wrapped Proton pn_object_t targets.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/proton_handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/proton_handler.hpp b/proton-c/bindings/cpp/include/proton/proton_handler.hpp
index 24384a8..2738f71 100644
--- a/proton-c/bindings/cpp/include/proton/proton_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/proton_handler.hpp
@@ -28,10 +28,15 @@ namespace proton {
class event;
class proton_event;
+/// Handler base class, subclass and over-ride event handling member functions.
+/// @see proton::proton_event for meaning of events.
class proton_handler : public handler
{
public:
PN_CPP_EXTERN proton_handler();
+
+ ///@name Over-ride these member functions to handle events
+ ///@{
PN_CPP_EXTERN virtual void on_reactor_init(event &e);
PN_CPP_EXTERN virtual void on_reactor_quiesced(event &e);
PN_CPP_EXTERN virtual void on_reactor_final(event &e);
@@ -72,8 +77,8 @@ class proton_handler : public handler
PN_CPP_EXTERN virtual void on_selectable_expired(event &e);
PN_CPP_EXTERN virtual void on_selectable_error(event &e);
PN_CPP_EXTERN virtual void on_selectable_final(event &e);
-
PN_CPP_EXTERN virtual void on_unhandled(event &e);
+ ///@}
};
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/receiver.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/receiver.hpp b/proton-c/bindings/cpp/include/proton/receiver.hpp
index be19358..4f2df0f 100644
--- a/proton-c/bindings/cpp/include/proton/receiver.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver.hpp
@@ -31,6 +31,7 @@ struct pn_connection_t;
namespace proton {
+/// A receiving link
class receiver : public link
{
public:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/sender.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/sender.hpp b/proton-c/bindings/cpp/include/proton/sender.hpp
index 1d35c42..3573a90 100644
--- a/proton-c/bindings/cpp/include/proton/sender.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender.hpp
@@ -33,12 +33,14 @@ struct pn_connection_t;
namespace proton {
-
+/// A sending link
class sender : public link
{
public:
PN_CPP_EXTERN sender(pn_link_t *lnk=0);
PN_CPP_EXTERN sender(const link& c);
+
+ /// Send a message on the link.
PN_CPP_EXTERN delivery send(message &m);
protected:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/58c57e79/proton-c/bindings/cpp/include/proton/session.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/session.hpp b/proton-c/bindings/cpp/include/proton/session.hpp
index b0117c0..7f670b8 100644
--- a/proton-c/bindings/cpp/include/proton/session.hpp
+++ b/proton-c/bindings/cpp/include/proton/session.hpp
@@ -37,22 +37,37 @@ class container;
class handler;
class transport;
- class session : public endpoint, public proton_handle<pn_session_t>
+/** A session is a collection of links */
+class session : public endpoint, public proton_handle<pn_session_t>
{
public:
PN_CPP_EXTERN session(pn_session_t *s);
PN_CPP_EXTERN session();
- PN_CPP_EXTERN ~session();
- PN_CPP_EXTERN void open();
PN_CPP_EXTERN session(const session&);
+ PN_CPP_EXTERN ~session();
PN_CPP_EXTERN session& operator=(const session&);
+
+ /** Initiate local open, not complete till messaging_handler::on_session_opened()
+ * or proton_handler::on_session_remote_open()
+ */
+ PN_CPP_EXTERN void open();
+
+ /** Initiate local close, not complete till messaging_handler::on_session_closed()
+ * or proton_handler::on_session_remote_close()
+ */
PN_CPP_EXTERN void close();
- PN_CPP_EXTERN pn_session_t *pn_session();
+
+ /// Get connection
PN_CPP_EXTERN virtual class connection &connection();
- PN_CPP_EXTERN receiver create_receiver(std::string name);
- PN_CPP_EXTERN sender create_sender(std::string name);
+ /// Create a receiver link
+ PN_CPP_EXTERN receiver create_receiver(const std::string& name);
+ /// Create a sender link
+ PN_CPP_EXTERN sender create_sender(const std::string& name);
+
+ PN_CPP_EXTERN pn_session_t *pn_session();
+
private:
- friend class proton_impl_ref<session>;
+ friend class proton_impl_ref<session>;
};
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org