QPID-3046 - Updates

 - Additional header comments
 - Added pendingEvents method to ConsoleSession and AgentSession
 - Ensure that nextEvent will not block if timeout is IMMEDIATE (ConsoleSession and AgentSession).


git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1076625 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 41 insertions, 7 deletions

diff --git a/qpid/cpp/include/qmf/ConsoleSession.h b/qpid/cpp/include/qmf/ConsoleSession.h
index 0c73e7a6db..896f8ffda7 100644
--- a/qpid/cpp/include/qmf/ConsoleSession.h
+++ b/qpid/cpp/include/qmf/ConsoleSession.h
@@ -62,14 +62,48 @@ namespace qmf {
          *    strict-security:{True,False}  - If True:  Cooperate with the broker to enforce strict access control to the network
          *                                  - If False: Operate more flexibly with regard to use of messaging facilities [default]
          */
-        QMF_EXTERN ConsoleSession(qpid::messaging::Connection&, const std::string& options="");
-        QMF_EXTERN void setDomain(const std::string&);
-        QMF_EXTERN void setAgentFilter(const std::string&);
+        QMF_EXTERN ConsoleSession(qpid::messaging::Connection& conn, const std::string& options="");
+
+        /**
+         * setDomain - Change the QMF domain that this console will operate in.  If this is not called,
+         * the domain will be "default".  Agents in a domain can be seen only by consoles in the same domain.
+         * This must be called prior to opening the console session.
+         */
+        QMF_EXTERN void setDomain(const std::string& domain);
+        QMF_EXTERN void setAgentFilter(const std::string& filter);
+
+        /**
+         * Open the console session.  After opening the session, the domain cannot be changed.
+         */
         QMF_EXTERN void open();
+
+        /**
+         * Close the session.  Once closed, the session no longer communicates on the messaging network.
+         */
         QMF_EXTERN void close();
-        QMF_EXTERN bool nextEvent(ConsoleEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER);
+
+        /**
+         * Get the next event from the console session.  Events represent actions that must be acted upon by the
+         * console application.  This method blocks for up to the timeout if there are no events to be handled.
+         * This method will typically be the focus of the console application's main execution loop.
+         * If the timeout is set to Duration::IMMEDIATE, the call will not block.
+         */
+        QMF_EXTERN bool nextEvent(ConsoleEvent& outEvent, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER);
+
+        /**
+         * Return the number of events pending for nextEvent.  This method will never block.
+         */
+        QMF_EXTERN int pendingEvents() const;
+
+        /**
+         * getAgentCount, getAgent - Retrieve the set of agents that match the console session's agent filter.
+         */
         QMF_EXTERN uint32_t getAgentCount() const;
-        QMF_EXTERN Agent getAgent(uint32_t) const;
+        QMF_EXTERN Agent getAgent(uint32_t agentIndex) const;
+
+        /**
+         * Get the agent for the connected broker (i.e. the agent embedded in the broker to which we have a connection).
+         */
         QMF_EXTERN Agent getConnectedBrokerAgent() const;
 
         /**
@@ -79,8 +113,8 @@ namespace qmf {
          * will involve all known agents.  If agentFilter is non-empty, it will be applied only to the set of known
          * agents.  A subscription cannot be created that involves an agent not known by the session.
          */
-        QMF_EXTERN Subscription subscribe(const Query&,       const std::string& agentFilter = "", const std::string& options = "");
-        QMF_EXTERN Subscription subscribe(const std::string&, const std::string& agentFilter = "", const std::string& options = "");
+        QMF_EXTERN Subscription subscribe(const Query& query,       const std::string& agentFilter = "", const std::string& options = "");
+        QMF_EXTERN Subscription subscribe(const std::string& query, const std::string& agentFilter = "", const std::string& options = "");
 
 #ifndef SWIG
     private: