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/qpid@1076625 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 64 insertions, 24 deletions

diff --git a/cpp/include/qmf/AgentSession.h b/cpp/include/qmf/AgentSession.h
index 9e29d6b54b..39d921a8ec 100644
--- a/cpp/include/qmf/AgentSession.h
+++ b/cpp/include/qmf/AgentSession.h
@@ -72,14 +72,14 @@ 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 AgentSession(qpid::messaging::Connection&, const std::string& options="");
+        QMF_EXTERN AgentSession(qpid::messaging::Connection& conn, const std::string& options="");
 
         /**
          * setDomain - Change the QMF domain that this agent 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 agent session.
          */
-        QMF_EXTERN void setDomain(const std::string&);
+        QMF_EXTERN void setDomain(const std::string& domain);
 
         /**
          * Set identifying attributes of this agent.
@@ -88,16 +88,16 @@ namespace qmf {
          * setInstance - Set the unique instance name (if not set, a UUID will be assigned)
          * These must be called prior to opening the agent session.
          */
-        QMF_EXTERN void setVendor(const std::string&);
-        QMF_EXTERN void setProduct(const std::string&);
-        QMF_EXTERN void setInstance(const std::string&);
+        QMF_EXTERN void setVendor(const std::string& vendor);
+        QMF_EXTERN void setProduct(const std::string& product);
+        QMF_EXTERN void setInstance(const std::string& instance);
 
         /**
          * setAttribute - Set an arbitrary attribute for this agent.  The attributes are not used
          * to uniquely identify the agent but can be used as a search criteria when looking for agents.
          * This must be called prior to opening the agent session.
          */
-        QMF_EXTERN void setAttribute(const std::string&, const qpid::types::Variant&);
+        QMF_EXTERN void setAttribute(const std::string& key, const qpid::types::Variant& value);
 
         /**
          * Get the identifying name of the agent.
@@ -119,13 +119,19 @@ namespace qmf {
          * Get the next event from the agent session.  Events represent actions that must be acted upon by the
          * agent 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 agent application's main execution loop.
+         * If the timeout is set to Duration::IMMEDIATE, the call will not block.
          */
-        QMF_EXTERN bool nextEvent(AgentEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER);
+        QMF_EXTERN bool nextEvent(AgentEvent& 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;
 
         /**
          * Register a schema to be exposed by this agent.
          */
-        QMF_EXTERN void registerSchema(Schema&);
+        QMF_EXTERN void registerSchema(Schema& schema);
 
         /**
          * Add data to be managed internally by the agent.  If the option external:True is selected, this call
@@ -138,12 +144,12 @@ namespace qmf {
          *                     across different sessions.  If persistent, it is the agent application's
          *                     responsibility to ensure the name is the same each time it is added.
          */
-        QMF_EXTERN DataAddr addData(Data&, const std::string& name="", bool persistent=false);
+        QMF_EXTERN DataAddr addData(Data& data, const std::string& name="", bool persistent=false);
 
         /**
          * Delete data from internal agent management.
          */
-        QMF_EXTERN void delData(const DataAddr&);
+        QMF_EXTERN void delData(const DataAddr& dataAddr);
 
         /**
          * The following methods are used to respond to events received in nextEvent.
@@ -155,13 +161,13 @@ namespace qmf {
          * complete - Indicate that the response to a query is complete (external:True only)
          * methodSuccess - Indicate the successful completion of a method call.
          */
-        QMF_EXTERN void authAccept(AgentEvent&);
-        QMF_EXTERN void authReject(AgentEvent&, const std::string& diag="");
-        QMF_EXTERN void raiseException(AgentEvent&, const std::string&);
-        QMF_EXTERN void raiseException(AgentEvent&, const Data&);
-        QMF_EXTERN void response(AgentEvent&, const Data&);
-        QMF_EXTERN void complete(AgentEvent&);
-        QMF_EXTERN void methodSuccess(AgentEvent&);
+        QMF_EXTERN void authAccept(AgentEvent& event);
+        QMF_EXTERN void authReject(AgentEvent& event, const std::string& diag="");
+        QMF_EXTERN void raiseException(AgentEvent& event, const std::string& errorText);
+        QMF_EXTERN void raiseException(AgentEvent& event, const Data& errorData);
+        QMF_EXTERN void response(AgentEvent& event, const Data& responseData);
+        QMF_EXTERN void complete(AgentEvent& event);
+        QMF_EXTERN void methodSuccess(AgentEvent& event);
 
         /**
          * Raise an event to be sent into the QMF network.
diff --git a/cpp/include/qmf/ConsoleSession.h b/cpp/include/qmf/ConsoleSession.h
index 0c73e7a6db..896f8ffda7 100644
--- a/cpp/include/qmf/ConsoleSession.h
+++ b/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: