/*

* Copyright (c) 2002-2004 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:  Definition of the Script Engine API. API is for Script Engine

*                internal use only.

*

*/

#ifndef M_CFSCRIPTENGINEINTERFACE_H

#define M_CFSCRIPTENGINEINTERFACE_H

#include <e32base.h>

class MCFActionHandler;

class MCFScriptOwner;

/**

 *  MCFScriptEngineInterface defines the API of the Script Engine component.

 *

 *  @lib CFScriptEngine.lib

 *  @since Series 60 2.6

 */

class MCFScriptEngineInterface

    {

public:

    // New functions

    /**

     * Removes a script by its Id.

     * Only owners of the script can remove the script.

     * @since Series 60 2.6

     * @param aScriptId is id of the script to remove.

     * @param aOwner Owner thread of the script.

     * @return KErrNone if successful.

     */

    virtual TInt RemoveScriptById( TInt aScriptId, const RThread& aOwner ) = 0;

    /**

     * Removes all scripts that are added by the session aSession.

     * @since Series 60 2.6

     * @return number of scripts removed.

     */

    virtual TInt RemoveScriptsBySession(const MCFActionHandler& aSession ) = 0;

    /**

     * Remove script by script name.

     * 

     * @since S60 5.0

     * @param aScriptName Script name.

     * @param aOwner Owner thread of the script.

     * @return KErrNone if no errors.

     */

    virtual TInt RemoveScriptByName( const TDesC& aScriptName,

        const TUid& aOwnerUid ) = 0;

    /**

     * Remove scripts by the script owner Uid (SID).

     * 

     * @since S60 5.0

     * @param aUid Owner Uid.

     * @return KErrNone if no errors.

     */

    virtual TInt RemoveScriptByUid( const TUid& aUid ) = 0;

    /**

     * Adds a new script to the script engine, activating the script at the

     * same time.

     * @since Series 60 2.6

     * @param aName Script's name, filename or secure id from client thread.

     * @param aScript is a new script to be added.

     * @param aOwner is the owner's unique Uid.

     * @param aOwnerThread The thread adding the script, used for script

     * security checking.

     * @param aSession is a session that is notified when the script fires.

     * @param aScriptOwner Pointer to the script owner session.

     * @return script id given to the script by the handler.

     * 	Returned value is < 0 if aScript could not be parsed.

     */

    virtual TInt AddScript( const TDesC& aName, const TDesC8& aScript,

        const TUid& aOwner, const RThread& aOwnerThread,

        MCFActionHandler& aSession, MCFScriptOwner* aScriptOwner ) = 0;

    /**

     * Number of scripts by specified owner.

     * @since Series 60 2.6

     * @param aOwner script owner's Uid.

     * @return integer indicating number of scripts by the passed owner.

     */

    virtual TInt NumberOfScriptsByOwner( const TUid& aOwner ) = 0;

    /**

     * @since Series 60 2.6

     * @return total number of script owned.

     */

    virtual TInt NumberOfScripts( ) = 0;

    /**

     * Method for getting the length of the script descriptor.

     * @since Series 60 2.6

     * @param aScriptId script's unique Id number.

     * @return the length of the script (KErrNotFound if script not found).

     */

    virtual TInt ScriptLength( TInt aScriptId ) = 0;

    /**

     * Method for getting all script Ids to a descriptor.

     * @since Series 60 2.6

     * @return array containing all the script Ids.

     */

    virtual const RArray< TInt >& GetEveryScriptId( ) = 0;

    /**

     * Method for getting all script Ids to a descriptor according to given owner.

     * @since Series 60 2.6

     * @param aScriptOwner TUid of the owner of the scripts.

     * @return array containing all the script Ids.

     */

    virtual const RArray< TInt >& GetEveryScriptIdByOwner(

        const TUid& aScriptOwner ) = 0;

    /**

     * Method for updating (by replacing) a script.

     * @since Series 60 2.6

     * @param aScriptId Id of the script to be updated.

     * @param aUpdatedScript descriptor containing the new script.

     * @return KErrnone if successful, system wide error code otherwise.

     */

    virtual TInt UpdateScript( TInt aScriptID, const RThread& aOwnerThread,

        const TDesC8& aUpdatedScript, MCFScriptOwner* aScriptOwner ) = 0;

    /**

     * Save script in to disk.

     * 

     * @since S60 5.0

     * @param aScript Script to save.

     * @param aScriptId Id of the script where the data belongs to.

     * @param aOwnerUid Owner of the script.

     * @return KErrNone if no errors.

     */

    virtual TInt SaveScript( const TDesC8& aScript, TInt aScriptId,

        const TUid& aOwnerUid ) = 0;

    /**

     * Delete script by its name.

     * 

     * @since S60 5.0

     * @param aScriptName Name of the script.

     * @param aOwnerUid Owner of the script.

     * @return KErrNone if no errors.

     */

    virtual TInt DeleteScriptByName( const TDesC& aScriptName,

        const TUid& aOwnerUid ) = 0;

    /**

     * Delete scripts by owner uid.

     * 

     * @since S60 5.0

     * @param aUid Owner's uid.

     * @return KErrNone if no errors.

     */

    virtual TInt DeleteScriptByUid( const TUid& aUid ) = 0;

    /**

     * Check if the script name is already reserved.

     * 

     * @since S60 5.0

     * @param aScriptName Name of the script.

     * @param aOwnerUid Uid of the script owner.

     * @param aScriptId Id of the script found.

     * @return ETrue if the name is reserved.

     */

    virtual TBool AlreadyExists( const TDesC& aScriptName,

        const TUid& aOwnerUid, TInt& aScriptId ) const = 0;

    /**

     * Cleanup persistent data from a script identified by name.

     * 

     * @since S60 5.0

     * @param aScriptName Name of the script.

     * @param aOwnerUid Owner of the scripts.

     * @return KErrNone if no errors.

     */

    virtual void CleanupPersistentDataByName( const TDesC& aScriptName,

        const TUid& aOwnerUid ) = 0;

    /**

     * Cleanup persistent data from all scripts identified by owner uid.

     * 

     * @since S60 5.0

     * @param aOwnerUid Owner of the scripts.

     * @return KErrNone if no errors.

     */

    virtual void CleanupPersistentDataByUid( const TUid& aOwnerUid ) = 0;

    /**

     * Restore upgraded rom based script with the orginal script found

     * in rom.

     * 

     * @since S60 5.0

     * @param aScriptId Script id of the existing script.

     * @param aOwnerUid Owner of the scripts.

     * @param aClient Client thread for security checking.

     * @return KErrNone if no errors.

     */

    virtual TInt RestoreRomScript( TInt aScriptId, const TUid& aOwnerUid,

        const RThread& aClient ) = 0;

    /**

     * Parses the script and checks that client is allowed to upgrade

     * rom based script. The upgrade must have at least the same

     * upgrade capability level and the client must have the same

     * capabilities.

     * @param aScript The upgrade script.

     * @param aClient Client process thread.

     * @return KErrNone if upgrade is allowed.

     */

    virtual TInt IsUpgradeAllowed( const TDesC& aName, const TDesC8& aScript,

        const TUid& aOwner, const RThread& aOwnerThread,

        MCFActionHandler& aActionHandler ) = 0;

    /**

     * Removes scripts which provider has been unsintalled.

     * The script information can be stored so that the deregistered

     * scripts can be reloaded after wards.

     * @param aProviderUid Operation plug-in implementation uid.

     * @param aRollback Enable rollback.

     * @return KErrNone if no errors.

     */

    virtual TInt RemoveScriptByProviderUid( const TUid& aProviderUid,

        TBool aRollback ) = 0;

    /**

     * Restores scripts which have been stored after removing scripts by

     * provider uid.

     */

    virtual void RollbackScripts() = 0;

    /**

     * Deregister script owner.

     * @param aScriptOwner Pointer to the script owner.

     */

    virtual void DeregisterScriptOwner( MCFScriptOwner* aScriptOwner ) = 0;

    };

#endif // M_CFSCRIPTENGINEINTERFACE_H