/*
* 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