diff options
Diffstat (limited to 'cpp')
| -rw-r--r-- | cpp/include/qmf/AgentSession.h | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/cpp/include/qmf/AgentSession.h b/cpp/include/qmf/AgentSession.h index 5259aee360..4ac2b2f3ed 100644 --- a/cpp/include/qmf/AgentSession.h +++ b/cpp/include/qmf/AgentSession.h @@ -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 |