--- /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 <e32base.h>
+#include <e32std.h>
+#include <f32file.h>
+
+#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<TUid> iDependencyList;
+ };
+
+#endif // C_CFSCRIPT_H
+