diff options
Diffstat (limited to 'qpid/cpp/docs/api/doxygen_mainpage.h')
-rw-r--r-- | qpid/cpp/docs/api/doxygen_mainpage.h | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/qpid/cpp/docs/api/doxygen_mainpage.h b/qpid/cpp/docs/api/doxygen_mainpage.h new file mode 100644 index 0000000000..cb36d7edb0 --- /dev/null +++ b/qpid/cpp/docs/api/doxygen_mainpage.h @@ -0,0 +1,299 @@ +/* + * + * 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. + * + */ + +// This header file is just for doxygen documentation purposes. + +/** \mainpage Qpid C++ API Reference + * + * <h2>Messaging Client API classes</h2> + * <ul> + * <li><p>\ref messaging</p></li> + * <li><p>\ref qmfapi</p></li> + * </ul> + * + * <h2>Code for common tasks</h2> + * + * + * <h3>Includes and Namespaces</h3> + * + * <pre> + * #include <qpid/messaging/Connection.h> + * #include <qpid/messaging/Message.h> + * #include <qpid/messaging/Receiver.h> + * #include <qpid/messaging/Sender.h> + * #include <qpid/messaging/Session.h> + * + * #include <iostream> + * + * using namespace qpid::messaging; + * </pre> + * + * <h3>Opening Sessions and Connections</h3> + * + * <pre> + * int main(int argc, char** argv) { + * std::string broker = argc > 1 ? argv[1] : "localhost:5672"; + * std::string address = argc > 2 ? argv[2] : "amq.topic"; + * Connection connection(broker); + * try { + * connection.open(); + * Session session = connection.createSession(); + * + * // ### Your Code Here ### + * + * connection.close(); + * return 0; + * } catch(const std::exception& error) { + * std::cerr << error.what() << std::endl; + * connection.close(); + * return 1; + * } + * } + * </pre> + * + * <h3>Creating and Sending a Message</h3> + * + * <pre> + * Sender sender = session.createSender(address); + * sender.send(Message("Hello world!")); + * </pre> + * + * <h3>Setting Message Content</h3> + * + * <pre> + * Message message; + * message.setContent("Hello world!"); + * + * // In some applications, you should also set the content type, + * // which is a MIME type + * message.setContentType("text/plain"); + * </pre> + * + * <h3>Receiving a Message</h3> + * + * <pre> + * Receiver receiver = session.createReceiver(address); + * Message message = receiver.fetch(Duration::SECOND * 1); // timeout is optional + * session.acknowledge(); // acknowledge message receipt + * std::cout << message.getContent() << std::endl; + * </pre> + * + * <h3>Receiving Messages from Multiple Sources</h3> + * + * To receive messages from multiple sources, create a receiver for each + * source, and use session.nextReceiver().fetch() to fetch messages. + * session.nextReceiver() is guaranteed to return the receiver + * responsible for the first available message on the session. + * + * <pre> + * Receiver receiver1 = session.createReceiver(address1); + * Receiver receiver2 = session.createReceiver(address2); + * + * Message message = session.nextReceiver().fetch(); + * session.acknowledge(); // acknowledge message receipt + * std::cout << message.getContent() << std::endl; + * </pre> + * + * <h3>Replying to a message:</h3> + * + * <pre> + * // Server creates a service queue and waits for messages + * // If it gets a request, it sends a response to the reply to address + * + * Receiver receiver = session.createReceiver("service_queue; {create: always}"); + * Message request = receiver.fetch(); + * const Address& address = request.getReplyTo(); // Get "reply-to" from request ... + * if (address) { + * Sender sender = session.createSender(address); // ... send response to "reply-to" + * Message response("pong!"); + * sender.send(response); + * session.acknowledge(); + * } + * + * + * // Client creates a private response queue - the # gets converted + * // to a unique string for the response queue name. Client uses the + * // name of this queue as its reply-to. + * + * Sender sender = session.createSender("service_queue"); + * Address responseQueue("#response-queue; {create:always, delete:always}"); + * Receiver receiver = session.createReceiver(responseQueue); + * + * Message request; + * request.setReplyTo(responseQueue); + * request.setContent("ping"); + * sender.send(request); + * Message response = receiver.fetch(); + * std::cout << request.getContent() << " -> " << response.getContent() << std::endl; + * </pre> + * + * + * <h3>Getting and Setting Standard Message Properties</h3> + * + * This shows some of the most commonly used message properties, it is + * not complete. + * + * <pre> + * Message message("Hello world!"); + * message.setContentType("text/plain"); + * message.setSubject("greeting"); + * message.setReplyTo("response-queue"); + * message.setTtl(100); // milliseconds + * message.setDurable(1); + * + * std::cout << "Content: " << message.getContent() << std::endl + * << "Content Type: " << message.getContentType() + * << "Subject: " << message.getSubject() + * << "ReplyTo: " << message.getReplyTo() + * << "Time To Live (in milliseconds) " << message.getTtl() + * << "Durability: " << message.getDurable(); + * </pre> + * + * <h3>Getting and Setting Application-Defined Message Properties</h3> + * + * <pre> + * std::string name = "weekday"; + * std::string value = "Thursday"; + * message.getProperties()[name] = value; + * + * std:string s = message.getProperties()["weekday"]; + * </pre> + * + * <h3>Transparent Failover</h3> + * + * If a connection opened using the reconnect option, it will + * transparently reconnect if the connection is lost. + * + * <pre> + * Connection connection(broker); + * connection.setOption("reconnect", true); + * try { + * connection.open(); + * .... + * </pre> + * + * + * <h3>Maps</h3> + * + * Maps provide a simple way to exchange binary data portably, across + * languages and platforms. Maps can contain simple types, lists, or + * maps. + * + * + * <pre> + * // Sender + * + * Variant::Map content; + * content["id"] = 987654321; + * content["name"] = "Widget"; + * content["probability"] = 0.43; + * Variant::List colours; + * colours.push_back(Variant("red")); + * colours.push_back(Variant("green")); + * colours.push_back(Variant("white")); + * content["colours"] = colours; + * content["uuid"] = Uuid(true); + * + * Message message; + * encode(content, message); + * + * sender.send(message); + * </pre> + * + * <pre> + * // Receiver + * + * Variant::Map content; + * decode(receiver.fetch(), content); + * </pre> + * + * <h3>Guaranteed Delivery</h3> + * + * If a queue is durable, the queue survives a messaging broker crash, as + * well as any durable messages that have been placed on the queue. These + * messages will be delivered when the messaging broker is + * restarted. Delivery is not guaranteed unless both the message and the + * queue are durable. + * + * <pre> + * Sender sender = session.createSender("durable-queue"); + * + * Message message("Hello world!"); + * message.setDurable(1); + * + * sender.send(Message("Hello world!")); + * </pre> + * + * + * <h3>Transactions</h3> + * + * Transactions cover enqueues and dequeues. + * + * When sending messages, a transaction tracks enqueues without actually + * delivering the messages, a commit places messages on their queues, and + * a rollback discards the enqueues. + * + * When receiving messages, a transaction tracks dequeues without + * actually removing acknowledged messages, a commit removes all + * acknowledged messages, and a rollback discards acknowledgements. A + * rollback does not release the message, it must be explicitly released + * to return it to the queue. + * + * <pre> + * Connection connection(broker); + * Session session = connection.createTransactionalSession(); + * ... + * if (looksOk) + * session.commit(); + * else + * session.rollback(); + * </pre> + * + * <h3>Logging</h3> + * + * The Qpidd broker and C++ clients can both use environment variables to + * enable logging. Use QPID_LOG_ENABLE to set the level of logging you + * are interested in (trace, debug, info, notice, warning, error, or + * critical): + * + * <pre> + * export QPID_LOG_ENABLE="warning+" + * </pre> + * + * Use QPID_LOG_OUTPUT to determine where logging output should be + * sent. This is either a file name or the special values stderr, stdout, + * or syslog: + * + * <pre> + * export QPID_LOG_TO_FILE="/tmp/myclient.out" + * </pre> + * + * + */ + +/** + * \defgroup messaging Qpid C++ Client API + * \defgroup qmfapi Qpid Management Framework C++ API + * + */ + + + |