svn commit: r985074 - /qpid/trunk/qpid/cpp/include/qmf/AgentSession.h

[tr...@apache.org]

Author: tross
Date: Fri Aug 13 02:25:28 2010
New Revision: 985074

URL: http://svn.apache.org/viewvc?rev=985074&view=rev
Log:
QPID-2793 - Added doxygen text

Modified:
    qpid/trunk/qpid/cpp/include/qmf/AgentSession.h

Modified: qpid/trunk/qpid/cpp/include/qmf/AgentSession.h
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/include/qmf/AgentSession.h?rev=985074&r1=985073&r2=985074&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/include/qmf/AgentSession.h (original)
+++ qpid/trunk/qpid/cpp/include/qmf/AgentSession.h Fri Aug 13 02:25:28 2010
@@ -48,6 +48,11 @@ namespace qmf {
         QMF_EXTERN ~AgentSession();
 
         /**
+         * AgentSession
+         *   A session that runs over an AMQP connection for QMF agent operation.
+         *
+         * @param connection - An opened qpid::messaging::Connection
+         * @param options - An optional string containing options
          *
          * The options string is of the form "{key:value,key:value}".  The following keys are supported:
          *
@@ -59,20 +64,88 @@ namespace qmf {
          *                                 If False: generate an AUTH_METHOD event to allow per-method authorization
          */
         QMF_EXTERN AgentSession(qpid::messaging::Connection&, 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&);
+
+        /**
+         * Set identifying attributes of this agent.
+         * setVendor   - Set the vendor string
+         * setProduct  - Set the product name string
+         * 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&);
+
+        /**
+         * 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&);
+
+        /**
+         * Get the identifying name of the agent.
+         */
         QMF_EXTERN const std::string& getName() const;
+
+        /**
+         * Open the agent session.  After opening the session, the domain, identifying strings, and attributes 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();
+
+        /**
+         * 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.
+         */
         QMF_EXTERN bool nextEvent(AgentEvent&, qpid::messaging::Duration timeout=qpid::messaging::Duration::FOREVER);
 
+        /**
+         * Register a schema to be exposed by this agent.
+         */
         QMF_EXTERN void registerSchema(Schema&);
+
+        /**
+         * Add data to be managed internally by the agent.  If the option external:True is selected, this call
+         * should not be used.
+         *
+         * @param data - The data object being managed by the agent.
+         * @param name - A name unique to this object to be used to address the object.
+         *               If left default, a unique name will be assigned by the agent.
+         * @param persistent - Set this to true if the data object is to be considered persistent
+         *                     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);
+
+        /**
+         * Delete data from internal agent management.
+         */
         QMF_EXTERN void delData(const DataAddr&);
 
+        /**
+         * The following methods are used to respond to events received in nextEvent.
+         *
+         * authAccept - Accept an authorization request.
+         * authReject - Reject/forbid an authorization request.
+         * raiseException - indicate failure of an operation (i.e. query or method call).
+         * response - Provide data in response to a query (only for option:  external:True)
+         * 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&);
@@ -80,6 +153,10 @@ namespace qmf {
         QMF_EXTERN void response(AgentEvent&, const Data&);
         QMF_EXTERN void complete(AgentEvent&);
         QMF_EXTERN void methodSuccess(AgentEvent&);
+
+        /**
+         * Raise an event to be sent into the QMF network.
+         */
         QMF_EXTERN void raiseEvent(const Data&);
 
 #ifndef SWIG



---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project:      http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org