diff options
Diffstat (limited to 'cpp/include/qmf/Agent.h')
| -rw-r--r-- | cpp/include/qmf/Agent.h | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/cpp/include/qmf/Agent.h b/cpp/include/qmf/Agent.h deleted file mode 100644 index e61cd737d0..0000000000 --- a/cpp/include/qmf/Agent.h +++ /dev/null @@ -1,287 +0,0 @@ -#ifndef _QmfAgent_ -#define _QmfAgent_ - -/* - * 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. - */ - -#include "qmf/QmfImportExport.h" - -namespace qmf { - - class AgentImpl; - class Connection; - class ObjectId; - class AgentObject; - class Value; - class Event; - class SchemaObjectClass; - - /** - * AgentListener is used by agents that select the internalStore=false option (see Agent - * constructor) or by agents that wish to provide access control for queries and methods. - * - * \ingroup qmfapi - */ - class AgentListener { - QMF_EXTERN virtual ~AgentListener(); - - /** - * allowQuery is called before a query operation is executed. If true is returned - * by this function, the query will proceed. If false is returned, the query will - * be forbidden. - * - * @param q The query being requested. - * @param userId The authenticated identity of the user requesting the query. - */ - virtual bool allowQuery(const Query& q, const char* userId); - - /** - * allowMethod is called before a method call is executed. If true is returned - * by this function, the method call will proceed. If false is returned, the method - * call will be forbidden. - * - * @param name The name of the method being called. - * @param args A value object (of type "map") that contains both input and output arguments. - * @param oid The objectId that identifies the instance of the object being called. - * @param cls The Schema describing the object being called. - * @param userId The authenticated identity of the requesting user. - */ - virtual bool allowMethod(const char* name, const Value& args, const ObjectId& oid, - const SchemaObjectClass& cls, const char* userId); - - /** - * query is called when the agent receives a query request. The handler must invoke - * Agent::queryResponse zero or more times (using the supplied context) followed by - * a single invocation of Agent::queryComplete. These calls do not need to be made - * synchronously in the context of this function. They may occur before or after this - * function returns. - * - * This function will only be invoked if internalStore=false in the Agent's constructor. - * - * @param context A context value to use in resulting calls to queryResponse and quertComplete. - * @param q The query requested by the console. - * @param userId the authenticated identity of the user requesting the query. - */ - virtual void query(uint32_t context, const Query& q, const char* userId); - - /** - * syncStart is called when a console requests a standing query. This function must - * behave exactly like AgentListener::query (i.e. send zero or more responses followed - * by a queryComplete) except it then remembers the context and the query and makes - * subsequent queryResponse calls whenever appropriate according the the query. - * - * The standing query shall stay in effect until syncStop is called with the same context - * value or until a specified period of time elapses without receiving a syncTouch for the - * context. - * - * This function will only be invoked if internalStore=false in the Agent's constructor. - * - * @param context A context value to use in resulting calls to queryResponse and queryComplete. - * @param q The query requested by the console. - * @param userId the authenticated identity of the user requesting the query. - */ - virtual void syncStart(uint32_t context, const Query& q, const char* userId); - - /** - * syncTouch is called when the console that requested a standing query refreshes its - * interest in the query. The console must periodically "touch" a standing query to keep - * it alive. This prevents standing queries from accumulating when the console disconnects - * before it can stop the query. - * - * This function will only be invoked if internalStore=false in the Agent's constructor. - * - * @param context The context supplied in a previous call to syncStart. - * @param userId The authenticated identity of the requesting user. - */ - virtual void syncTouch(uint32_t context, const char* userId); - - /** - * syncStop is called when the console that requested a standing query no longer wishes to - * receive data associated with that query. The application shall stop processing this - * query and shall remove its record of the context value. - * - * This function will only be invoked if internalStore=false in the Agent's constructor. - * - * @param context The context supplied in a previous call to syncStart. - * @param userId The authenticated identity of the requesting user. - */ - virtual void syncStop(uint32_t context, const char* userId); - - /** - * methodCall is called when a console invokes a method on a QMF object. The application - * must call Agent::methodResponse once in response to this function. The response does - * not need to be called synchronously in the context of this function. It may be called - * before or after this function returns. - * - * This function will only be invoked if internalStore=false in the Agent's constructor. - * - * @param context A context value to use in resulting call to methodResponse. - * @param name The name of the method being called. - * @param args A value object (of type "map") that contains both input and output arguments. - * @param oid The objectId that identifies the instance of the object being called. - * @param cls The Schema describing the object being called. - * @param userId The authenticated identity of the requesting user. - */ - virtual void methodCall(uint32_t context, const char* name, Value& args, - const ObjectId& oid, const SchemaObjectClass& cls, const char* userId); - }; - - /** - * The Agent class is the QMF Agent portal. It should be instantiated once and associated with a - * Connection (setConnection) to connect an agent to the QMF infrastructure. - * - * \ingroup qmfapi - */ - class Agent { - public: - /** - * Create an instance of the Agent class. - * - * @param label An optional string label that can be used to identify the agent. - * - * @param internalStore If true, objects shall be tracked internally by the agent. - * If false, the user of the agent must track the objects. - * If the agent is tracking the objects, queries and syncs are handled by - * the agent. The only involvement the user has is to optionally authorize - * individual operations. If the user is tracking the objects, the user code - * must implement queries and syncs (standing queries). - * - * @param listener A pointer to a class that implements the AgentListener interface. - * This must be supplied if any of the following conditions are true: - * - The agent model contains methods - * - The user wishes to individually authorize query and sync operations. - * - internalStore = false - */ - QMF_EXTERN Agent(char* label="qmfa", bool internalStore=true, AgentListener* listener=0); - - /** - * Destroy an instance of the Agent class. - */ - QMF_EXTERN ~Agent(); - - /** - * Set the persistent store file. This file, if specified, is used to store state information - * about the Agent. For example, if object-ids must be persistent across restarts of the Agent - * program, this file path must be supplied. - * - * @param path Full path to a file that is both writable and readable by the Agent program. - */ - QMF_EXTERN void setStoreDir(const char* path); - - /** - * Provide a connection (to a Qpid broker) over which the agent can communicate. - * - * @param conn Pointer to a Connection object. - */ - QMF_EXTERN void setConnection(Connection* conn); - - /** - * Register a class schema (object or event) with the agent. The agent must have a registered - * schema for an object class or an event class before it can handle objects or events of that - * class. - * - * @param cls Pointer to the schema structure describing the class. - */ - QMF_EXTERN void registerClass(SchemaObjectClass* cls); - QMF_EXTERN void registerClass(SchemaEventClass* cls); - - /** - * Add an object to the agent (for internal storage mode only). - * - * @param obj Reference to the object to be managed by the agent. - * - * @param persistent Iff true, the object ID assigned to the object shall indicate persistence - * (i.e. the object ID shall be the same across restarts of the agent program). - * - * @param oid 64-bit value for the oid (if zero, the agent will assign the value). - * - * @param oidLo 32-bit value for the lower 32-bits of the oid. - * - * @param oidHi 32-bit value for the upper 32-bits of the oid. - */ - QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent=false, uint64_t oid=0); - QMF_EXTERN const ObjectId* addObject(AgentObject& obj, bool persistent, uint32_t oidLo, uint32_t oidHi); - - /** - * Allocate an object ID for an object (for external storage mode only). - * - * @param persistent Iff true, the object ID allocated shall indicate persistence - * (i.e. the object ID shall be the same across restarts of the agent program). - * - * @param oid 64-bit value for the oid (if zero, the agent will assign the value). - * - * @param oidLo 32-bit value for the lower 32-bits of the oid. - * - * @param oidHi 32-bit value for the upper 32-bits of the oid. - */ - QMF_EXTERN const ObjectId* allocObjectId(bool persistent=false, uint64_t oid=0); - QMF_EXTERN const ObjectId* allocObjectId(bool persistent, uint32_t oidLo, uint32_t oidHi); - - /** - * Raise a QMF event. - * - * @param event Reference to an event object to be raised to the QMF infrastructure. - */ - QMF_EXTERN void raiseEvent(Event& event); - - /** - * Provide a response to a query (for external storage mode only). - * - * @param context The context value supplied in the query (via the AgentListener interface). - * - * @param object A reference to the agent that matched the query criteria. - * - * @param prop If true, transmit the property attributes of this object. - * - * @param stat If true, transmit the statistic attributes of this object. - */ - QMF_EXTERN void queryResponse(uint32_t context, AgentObject& object, bool prop = true, bool stat = true); - - /** - * Indicate that a query (or the initial dump of a sync) is complete (for external storage mode only). - * - * @param context The context value supplied in the query/sync (via the AgentListener interface). - */ - QMF_EXTERN void queryComplete(uint32_t context); - - /** - * Provide the response to a method call. - * - * @param context The context value supplied in the method request (via the AgentListener interface). - * - * @param args The argument list from the method call. Must include the output arguments (may include - * the input arguments). - * - * @param status Numerical return status: zero indicates no error, non-zero indicates error. - * - * @param exception Pointer to an exception value. If status is non-zero, the exception value is - * sent to the caller. It is optional (i.e. leave the pointer as 0), or may be - * set to any legal value. A string may be supplied, but an unmanaged object of - * any schema may also be passed. - */ - QMF_EXTERN void methodResponse(uint32_t context, const Value& args, uint32_t status=0, - const Value* exception=0); - - private: - AgentImpl* impl; - }; - -} - -#endif |