/*

* 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