1 /*

     2 * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Definition of the Script Engine API. API is for Script Engine

    15 *                internal use only.

    16 *

    17 */

    18 

    19 

    20 #ifndef M_CFSCRIPTENGINEINTERFACE_H

    21 #define M_CFSCRIPTENGINEINTERFACE_H

    22 

    23 #include <e32base.h>

    24 

    25 class MCFActionHandler;

    26 class MCFScriptOwner;

    27 

    28 /**

    29  *  MCFScriptEngineInterface defines the API of the Script Engine component.

    30  *

    31  *  @lib CFScriptEngine.lib

    32  *  @since Series 60 2.6

    33  */

    34 class MCFScriptEngineInterface

    35     {

    36 public:

    37     // New functions

    38 

    39     /**

    40      * Removes a script by its Id.

    41      * Only owners of the script can remove the script.

    42      * @since Series 60 2.6

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

    44      * @param aOwner Owner thread of the script.

    45      * @return KErrNone if successful.

    46      */

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

    48 

    49     /**

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

    51      * @since Series 60 2.6

    52      * @return number of scripts removed.

    53      */

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

    55 

    56     /**

    57      * Remove script by script name.

    58      * 

    59      * @since S60 5.0

    60      * @param aScriptName Script name.

    61      * @param aOwner Owner thread of the script.

    62      * @return KErrNone if no errors.

    63      */

    64     virtual TInt RemoveScriptByName( const TDesC& aScriptName,

    65         const TUid& aOwnerUid ) = 0;

    66 

    67     /**

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

    69      * 

    70      * @since S60 5.0

    71      * @param aUid Owner Uid.

    72      * @return KErrNone if no errors.

    73      */

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

    75 

    76     /**

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

    78      * same time.

    79      * @since Series 60 2.6

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

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

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

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

    84      * security checking.

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

    86      * @param aScriptOwner Pointer to the script owner session.

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

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

    89      */

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

    91         const TUid& aOwner, const RThread& aOwnerThread,

    92         MCFActionHandler& aSession, MCFScriptOwner* aScriptOwner ) = 0;

    93 

    94     /**

    95      * Number of scripts by specified owner.

    96      * @since Series 60 2.6

    97      * @param aOwner script owner's Uid.

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

    99      */

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

   101 

   102     /**

   103      * @since Series 60 2.6

   104      * @return total number of script owned.

   105      */

   106     virtual TInt NumberOfScripts( ) = 0;

   107 

   108     /**

   109      * Method for getting the length of the script descriptor.

   110      * @since Series 60 2.6

   111      * @param aScriptId script's unique Id number.

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

   113      */

   114     virtual TInt ScriptLength( TInt aScriptId ) = 0;

   115 

   116     /**

   117      * Method for getting all script Ids to a descriptor.

   118      * @since Series 60 2.6

   119      * @return array containing all the script Ids.

   120      */

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

   122 

   123     /**

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

   125      * @since Series 60 2.6

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

   127      * @return array containing all the script Ids.

   128      */

   129     virtual const RArray< TInt >& GetEveryScriptIdByOwner(

   130         const TUid& aScriptOwner ) = 0;

   131 

   132     /**

   133      * Method for updating (by replacing) a script.

   134      * @since Series 60 2.6

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

   136      * @param aUpdatedScript descriptor containing the new script.

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

   138      */

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

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

   141 

   142     /**

   143      * Save script in to disk.

   144      * 

   145      * @since S60 5.0

   146      * @param aScript Script to save.

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

   148      * @param aOwnerUid Owner of the script.

   149      * @return KErrNone if no errors.

   150      */

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

   152         const TUid& aOwnerUid ) = 0;

   153 

   154     /**

   155      * Delete script by its name.

   156      * 

   157      * @since S60 5.0

   158      * @param aScriptName Name of the script.

   159      * @param aOwnerUid Owner of the script.

   160      * @return KErrNone if no errors.

   161      */

   162     virtual TInt DeleteScriptByName( const TDesC& aScriptName,

   163         const TUid& aOwnerUid ) = 0;

   164 

   165     /**

   166      * Delete scripts by owner uid.

   167      * 

   168      * @since S60 5.0

   169      * @param aUid Owner's uid.

   170      * @return KErrNone if no errors.

   171      */

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

   173 

   174     /**

   175      * Check if the script name is already reserved.

   176      * 

   177      * @since S60 5.0

   178      * @param aScriptName Name of the script.

   179      * @param aOwnerUid Uid of the script owner.

   180      * @param aScriptId Id of the script found.

   181      * @return ETrue if the name is reserved.

   182      */

   183     virtual TBool AlreadyExists( const TDesC& aScriptName,

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

   185 

   186     /**

   187      * Cleanup persistent data from a script identified by name.

   188      * 

   189      * @since S60 5.0

   190      * @param aScriptName Name of the script.

   191      * @param aOwnerUid Owner of the scripts.

   192      * @return KErrNone if no errors.

   193      */

   194     virtual void CleanupPersistentDataByName( const TDesC& aScriptName,

   195         const TUid& aOwnerUid ) = 0;

   196 

   197     /**

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

   199      * 

   200      * @since S60 5.0

   201      * @param aOwnerUid Owner of the scripts.

   202      * @return KErrNone if no errors.

   203      */

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

   205 

   206     /**

   207      * Restore upgraded rom based script with the orginal script found

   208      * in rom.

   209      * 

   210      * @since S60 5.0

   211      * @param aScriptId Script id of the existing script.

   212      * @param aOwnerUid Owner of the scripts.

   213      * @param aClient Client thread for security checking.

   214      * @return KErrNone if no errors.

   215      */

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

   217         const RThread& aClient ) = 0;

   218 

   219     /**

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

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

   222      * upgrade capability level and the client must have the same

   223      * capabilities.

   224      * @param aScript The upgrade script.

   225      * @param aClient Client process thread.

   226      * @return KErrNone if upgrade is allowed.

   227      */

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

   229         const TUid& aOwner, const RThread& aOwnerThread,

   230         MCFActionHandler& aActionHandler ) = 0;

   231 

   232     /**

   233      * Removes scripts which provider has been unsintalled.

   234      * The script information can be stored so that the deregistered

   235      * scripts can be reloaded after wards.

   236      * @param aProviderUid Operation plug-in implementation uid.

   237      * @param aRollback Enable rollback.

   238      * @return KErrNone if no errors.

   239      */

   240     virtual TInt RemoveScriptByProviderUid( const TUid& aProviderUid,

   241         TBool aRollback ) = 0;

   242 

   243     /**

   244      * Restores scripts which have been stored after removing scripts by

   245      * provider uid.

   246      */

   247     virtual void RollbackScripts() = 0;

   248     

   249     /**

   250      * Deregister script owner.

   251      * @param aScriptOwner Pointer to the script owner.

   252      */

   253     virtual void DeregisterScriptOwner( MCFScriptOwner* aScriptOwner ) = 0;

   254     };

   255 

   256 #endif // M_CFSCRIPTENGINEINTERFACE_H

   257