diff -r 000000000000 -r 2e3d3ce01487 contextframework/cfw/inc/cfscriptengine/CFScript.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/contextframework/cfw/inc/cfscriptengine/CFScript.h Tue Feb 02 10:12:00 2010 +0200 @@ -0,0 +1,409 @@ +/* +* Copyright (c) 2002-2008 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + + +#ifndef C_CFSCRIPT_H +#define C_CFSCRIPT_H + +#include +#include +#include + +#include "cfcontextsubscriptionlistener.h" +#include "cfoperationservices.h" +#include "CFSecurityChecker.h" + +class MCFActionHandler; +class MCFContextInterface; +class CCFContextObject; +class CCFContextSubscriptionImpl; +class CCFScriptSubscription; +class CCFScriptRoot; +class CCFOperationNode; +class CCFScriptEvent; +class CMDXMLNode; +class MCFPlugInOperation; +class MCFPersistentDataInterface; +class CCFPersistentData; +class CCFScriptInfo; +class MCFScriptOwner; + +/** + * Client to ContextManager context object changes; subscribes all + * CCFContextObject needed for the script. When the script's value changes + * from EFalse to ETrue, the callback in CCFScriptHandler is called. + + * @lib CFScriptEngine + * @since Series 60 2.6 + */ +NONSHARABLE_CLASS( CCFScript ): public CBase, +public MCFContextSubscriptionListener, +public MCFOperationServices + { +public: // Constructors and destructor + + /** + * Two-phased constructor. + * @param aStartNode contains XML node where the script starts + * @param aName Script's name, filename or secure id from client thread + * @param aScriptId is id for this script + * @param aActionHandler is MCFActionHandler that is notified when + * notify action fires. + */ + static CCFScript* NewL( CMDXMLNode& aStartNode, + const TDesC& aName, + TInt aScriptId, + const TUid& aOwner, + MCFActionHandler& aActionHandler, + TInt aLength, + MCFExtendedContextInterface& aCF, + MCFSecurityChecker& aSecurityChecker, + MCFPlugInOperation& aPlugInOperation, + RFs& aFs, + MCFScriptOwner* aScriptOwner ); + + /** + * Two-phased constructor that leaves object to the cleanup stack. + * @param aStartNode contains XML node where the script starts + * @param aName Script's name, filename or secure id from client thread + * @param aScriptId is id for this script + * @param aActionHandler is MCFActionHandler that is notified when + * notify action fires. + */ + static CCFScript* NewLC( CMDXMLNode& aStartNode, + const TDesC& aName, + TInt aScriptId, + const TUid& aOwner, + MCFActionHandler& aActionHandler, + TInt aLength, + MCFExtendedContextInterface& aCF, + MCFSecurityChecker& aSecurityChecker, + MCFPlugInOperation& aPlugInOperation, + RFs& aFs, + MCFScriptOwner* aScriptOwner ); + + /** + * Destructor. + */ + ~CCFScript(); + +public: // New functions + + /** + * Activates the script by activating the script root. + */ + void ActivateL(); + + /** + * Check that aOwnerThread has capabilities to do subscriptions + * and operations needed by the script. + * @param aOwnerThread is the script owning thread for security checking. + * @return KErrNone if security check passed, KErrNotFound if + * all actions or contexts needed by the script were not found, + * KErrPermissionDenied if the aOwnerThread does not have sufficient + * capabilities. + */ + TInt CheckSecurity( const RThread& aOwnerThread ); + + /** + * Gets action handler (session) associated with the script. + * @return a reference to action handler listening this script. + */ + MCFActionHandler& ActionHandler() const; + + /** + * Gets script upgrade security level. + * @return const TCapabilitySet&. + */ + const TCapabilitySet& UpgradeSecurity() const; + + /** + * Request operation nodes to clean up persistent data. + * @since S60 5.0 + * @param None. + * @return None. + */ + void CleanupPersistentData(); + + /** + * Checks if this script has a dependency to the operation plug-in + * implementation provided as a parameter. + * @param aUid Provider uid. + * @return ETrue if has dependency. + */ + TBool HasDependency( const TUid& aUid ) const; + + /** + * Returns a copy of script info. + * @return CCFScriptInfo*. + */ + CCFScriptInfo* CopyInfoLC() const; + + /** + * Return owner uid. + * @return TUid&. + */ + const TUid& OwnerUid() const; + + /** + * Return script name. + * @return const TDesC&. + */ + TPtrC Name() const; + + /** + * Return script length. + * @return TInt. + */ + TInt Length() const; + + /** + * Return reference to the info object. + * @return CCFScriptInfo&. + */ + CCFScriptInfo& Info() const; + +public: // Functions from MCFContextSubscriptionListener + + // From MCFContextSubscriptionListener + void ContextIndicationL( CCFContextIndication* aIndication ); + + // From MCFContextSubscriptionListener + TInt Client( RThread& aThread ) const; + + // From MCFContextSubscriptionListener + void HandleContextSubscriptionError( TInt aError, + const TDesC& aSource, + const TDesC& aType ); + +public: // Functions from MCFOperationServices + + /** + * Parses a xml node and returns a pointer to CCFOperationNode instance. + * @param aParent is the parsed parent node for the aNode. + * @param aNode is the node to be parsed. + * @return a ptr to CCFOperationNode instance parsed from the given node, + * Note that the ownership is transferred. Leaves with code + * KErrNotSupported if the node cannot be parsed. + */ + CCFOperationNode* ParseL( CCFOperationNode* aParent, + CMDXMLNode& aNode ); + + /** + * Gets id of the script providing operation services. + * @returns script id of this operation services provider. + */ + TInt ScriptId() const; + + /** + * Checks a script owners capabilities against given security policy. + * This is typically called by the operation nodes when + * the CheckSecurity()-method for them is called. + * @param aPolicy is the security policy. + * @return KErrNone when security check passed, otherwise any of the system + * wide error codes. + */ + TInt CheckScriptOwnerAccess( const TSecurityPolicy& aPolicy ); + + /** + * Gets context interface. + * @return a reference to context interface. + */ + MCFContextInterface& ContextInterface() const; + + /** + * Adds subscription to Context Framework to get indications of context + * events. + * @param aListener is a pointer to listener interface that will be notified + * of the specified context events. + * @return None. If subscribing is unsuccessful, leaves with any of system + * wide error codes. + */ + void SubscribeContextL( MCFScriptListener* aListener ); + + /** + * Removes subscription from Context Framework, cancels indications of + * context events. + * @param aListener is a pointer to listener interface whose context + * subscription is cancelled. + * @return None. + */ + void RemoveSubscription( MCFScriptListener* aListener ); + + /** + * Checks a context read security. + * @param aSource is the context source. + * @param aType is the context type. + * @return KErrNone when security check passed, otherwise any of the system + * wide error codes. + */ + TInt CheckContextReadSecurity( const TDesC& aSource, + const TDesC& aType ); + + /** + * Stores operation data into a persistent file. If the file exists + * the old data is replaced by calling ExternalizeL for the operation. + * @param aFile is the persistent file for operation data. + * @param aOperation is the operation to be stored. + * @return None. + */ + void StoreL( const TDesC& aFile, CCFOperationNode& aOperation ); + + /** + * Restores operation data from a persistent file. If the file exists + * InternalizeL is called for the operation. + * @param aFile is the persistent file containing operation data. + * @param aOperation is the operation to be restored. + * @return None. + */ + void RestoreL( const TDesC& aFile, + CCFOperationNode& aOperation ); + + /** + * Deletes the persistent file. + * Operation node must call this method for all persistent data files + * it owns when Cleanup() -method is called. + * @param aFile file name of the persistent data file. + */ + void Delete( const TDesC& aFile ); + + /** + * Check if there are actions to launch and launch them. + * Should be called after script has been evaluated based on something else + * than context indication, e.g. timer event. + * Note that calling this from normal evaluation during context indication + * results in executing script actions multiple times when script is true. + */ + void LaunchActivatedActions( ); + + /** + * Fires an action. + * @param aEvent is the script event defining the action. Ownership is + * transferred. + * @return None. + */ + void FireActionL( CCFScriptEvent* aEvent ); + + /** + * Fires a context source command action. + * @param aCommand is the context source command. + * @return None. + */ + void FireActionL( const CCFContextSourceCommand& aCommand ); + + /** + * Gets the security policy of a particular action. + * @param aActionId is the identifier of the action. + * @param aPolicy is the security policy which will be set by this method. + * @return KErrNone if action was found, KErrNotFound if not. + */ + TInt GetActionSecurityPolicy( const TDesC& aActionId, + TSecurityPolicy& aPolicy ); + +private: + + /** + * C++ default constructor. + */ + CCFScript( MCFExtendedContextInterface& aCF, + MCFActionHandler& aActionHandler, + MCFSecurityChecker& aSecurityChecker, + MCFPlugInOperation& aPlugInOperation, + RFs& aFs ); + + /** + * By default Symbian 2nd phase constructor is private. + */ + void ConstructL( CMDXMLNode& aStartNode, const TDesC& aName, + TInt aScriptId, const TUid& aOwner, TInt aLength, + MCFScriptOwner* aScriptOwner ); + +private: // New functions + + /** + * Starting point for script tree creation. + * @since Series 60 5.0 + * @param aStartNode node to start parsing from. + * @return KErrNone if successful, otherwise appropriate system wide + * error code. + */ + TInt ParseScriptL( CMDXMLNode& aStartNode ); + + /** + * Evaluates script with a context. + * @since Series 60 4.0 + * @param aContext is the context used for evaluating the script. + * @param aContextLevelDelay will be set to context level delay in + * milliseconds if required by evaluation, otherwise left untouched. + * @return ETrue if any script operation was really evaluated, EFalse + * otherwise. + */ + TBool EvaluateScript( const CCFContextObject& aContext, + TInt& aContextLevelDelay ); + + /** + * Adds new dependency in script. + * The dependency is the implementation uid of the operation plug-in. + * This link is needed since if the operation plug-in is uninstalled, + * all the scripts which has the operation plug-in dependency must be + * deregistered. + * @param aUid Implementation uid of the dependecy. + */ + void AddDependencyL( const TUid& aUid ); + +private: // Data + + // Reference to context services. + MCFExtendedContextInterface& iCF; + + // Reference to the action handler. + MCFActionHandler& iActionHandler; + + // Interface for security checking. + MCFSecurityChecker& iSecurityChecker; + + // Reference to parsing plugin operations. + MCFPlugInOperation& iPlugInOperation; + + // Reference to File server session. + RFs& iFs; + + // Script info + CCFScriptInfo* iInfo; + + // The root node of the script. + CCFScriptRoot* iScriptRoot; + + // Script subscriptions, owned. + RPointerArray< CCFScriptSubscription > iScriptSubscriptions; + + // Script listeners requiring all context indications, not owned. + RPointerArray< MCFScriptListener > iRequiresAll; + + // Script owning thread for security checking. Valid only during when + // CheckSecurity() is called, other times pointer is NULL. + const RThread* iScriptThreadForSecurityCheck; + + // Own: Persistent data handling for scripts. + CCFPersistentData* iPersistentData; + + // Own: Array of operation plug-in uids + RArray iDependencyList; + }; + +#endif // C_CFSCRIPT_H +