path: root/cpp/docs/api/doxygen_mainpage.h

/*
 * 
 * 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&amp; 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
 *
 */