1 /*

     2 * Copyright (c) 2002-2008 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:  

    15 *

    16 */

    17 

    18 

    19 #ifndef C_CFSCRIPT_H

    20 #define C_CFSCRIPT_H

    21 

    22 #include <e32base.h>

    23 #include <e32std.h>

    24 #include <f32file.h>

    25 

    26 #include "cfcontextsubscriptionlistener.h"

    27 #include "cfoperationservices.h"

    28 #include "CFSecurityChecker.h"

    29 

    30 class MCFActionHandler;

    31 class MCFContextInterface;

    32 class CCFContextObject;

    33 class CCFContextSubscriptionImpl;

    34 class CCFScriptSubscription;

    35 class CCFScriptRoot;

    36 class CCFOperationNode;

    37 class CCFScriptEvent;

    38 class CMDXMLNode;

    39 class MCFPlugInOperation;

    40 class MCFPersistentDataInterface;

    41 class CCFPersistentData;

    42 class CCFScriptInfo;

    43 class MCFScriptOwner;

    44 

    45 /**

    46  * Client to ContextManager context object changes; subscribes all

    47  * CCFContextObject needed for the script. When the script's value changes

    48  * from EFalse to ETrue, the callback in CCFScriptHandler is called.

    49 

    50  * @lib CFScriptEngine

    51  * @since Series 60 2.6

    52  */

    53 NONSHARABLE_CLASS( CCFScript ): public CBase,

    54 public MCFContextSubscriptionListener,

    55 public MCFOperationServices

    56     {

    57 public: // Constructors and destructor

    58 

    59     /**

    60      * Two-phased constructor.

    61      * @param aStartNode contains XML node where the script starts

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

    63      * @param aScriptId is id for this script

    64      * @param aActionHandler is MCFActionHandler that is notified when

    65      *  notify action fires.

    66      */

    67     static CCFScript* NewL( CMDXMLNode& aStartNode,

    68         const TDesC& aName,

    69         TInt aScriptId,

    70         const TUid& aOwner,

    71         MCFActionHandler& aActionHandler,

    72         TInt aLength,

    73         MCFExtendedContextInterface& aCF,

    74         MCFSecurityChecker& aSecurityChecker,

    75         MCFPlugInOperation& aPlugInOperation,

    76         RFs& aFs,

    77         MCFScriptOwner* aScriptOwner );

    78 

    79     /**

    80      * Two-phased constructor that leaves object to the cleanup stack.

    81      * @param aStartNode contains XML node where the script starts

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

    83      * @param aScriptId is id for this script

    84      * @param aActionHandler is MCFActionHandler that is notified when

    85      *  notify action fires.

    86      */

    87     static CCFScript* NewLC( CMDXMLNode& aStartNode,

    88         const TDesC& aName,

    89         TInt aScriptId,

    90         const TUid& aOwner,

    91         MCFActionHandler& aActionHandler,

    92         TInt aLength,

    93         MCFExtendedContextInterface& aCF,

    94         MCFSecurityChecker& aSecurityChecker,

    95         MCFPlugInOperation& aPlugInOperation,

    96         RFs& aFs,

    97         MCFScriptOwner* aScriptOwner );

    98 

    99     /**

   100      * Destructor.

   101      */

   102     ~CCFScript();

   103 

   104 public: // New functions

   105 

   106     /**

   107      * Activates the script by activating the script root.

   108      */

   109     void ActivateL();

   110 

   111     /**

   112      * Check that aOwnerThread has capabilities to do subscriptions

   113      * and operations needed by the script.

   114      * @param aOwnerThread is the script owning thread for security checking.

   115      * @return KErrNone if security check passed, KErrNotFound if

   116      *   all actions or contexts needed by the script were not found,

   117      *   KErrPermissionDenied if the aOwnerThread does not have sufficient

   118      *   capabilities.

   119      */

   120     TInt CheckSecurity( const RThread& aOwnerThread );

   121 

   122     /**

   123      * Gets action handler (session) associated with the script.

   124      * @return a reference to action handler listening this script.

   125      */

   126     MCFActionHandler& ActionHandler() const;

   127 

   128     /**

   129      * Gets script upgrade security level.

   130      * @return const TCapabilitySet&.

   131      */

   132     const TCapabilitySet& UpgradeSecurity() const;

   133 

   134     /**

   135      * Request operation nodes to clean up persistent data.

   136      * @since S60 5.0

   137      * @param None.

   138      * @return None.

   139      */

   140     void CleanupPersistentData();

   141 

   142     /**

   143      * Checks if this script has a dependency to the operation plug-in

   144      * implementation provided as a parameter.

   145      * @param aUid Provider uid.

   146      * @return ETrue if has dependency.

   147      */

   148     TBool HasDependency( const TUid& aUid ) const;

   149 

   150     /**

   151      * Returns a copy of script info.

   152      * @return CCFScriptInfo*.

   153      */

   154     CCFScriptInfo* CopyInfoLC() const;

   155     

   156     /**

   157      * Return owner uid.

   158      * @return TUid&.

   159      */

   160     const TUid& OwnerUid() const;

   161     

   162     /**

   163      * Return script name.

   164      * @return const TDesC&.

   165      */

   166     TPtrC Name() const;

   167     

   168     /**

   169      * Return script length.

   170      * @return TInt.

   171      */

   172     TInt Length() const;

   173     

   174     /**

   175      * Return reference to the info object.

   176      * @return CCFScriptInfo&.

   177      */

   178     CCFScriptInfo& Info() const;

   179 

   180 public: // Functions from MCFContextSubscriptionListener

   181 

   182     // From MCFContextSubscriptionListener

   183     void ContextIndicationL( CCFContextIndication* aIndication );

   184 

   185     // From MCFContextSubscriptionListener

   186     TInt Client( RThread& aThread ) const;

   187 

   188     // From MCFContextSubscriptionListener

   189     void HandleContextSubscriptionError( TInt aError,

   190         const TDesC& aSource,

   191         const TDesC& aType );

   192 

   193 public: // Functions from MCFOperationServices

   194 

   195     /**

   196      * Parses a xml node and returns a pointer to CCFOperationNode instance.

   197      * @param aParent is the parsed parent node for the aNode.

   198      * @param aNode is the node to be parsed.

   199      * @return a ptr to CCFOperationNode instance parsed from the given node,

   200      *   Note that the ownership is transferred. Leaves with code

   201      *   KErrNotSupported if the node cannot be parsed.

   202      */

   203     CCFOperationNode* ParseL( CCFOperationNode* aParent,

   204         CMDXMLNode& aNode );

   205 

   206     /**

   207      * Gets id of the script providing operation services.

   208      * @returns script id of this operation services provider.

   209      */

   210     TInt ScriptId() const;

   211 

   212     /**

   213      * Checks a script owners capabilities against given security policy.

   214      * This is typically called by the operation nodes when 

   215      * the CheckSecurity()-method for them is called.

   216      * @param aPolicy is the security policy.

   217      * @return KErrNone when security check passed, otherwise any of the system

   218      *   wide error codes.

   219      */

   220     TInt CheckScriptOwnerAccess( const TSecurityPolicy& aPolicy );

   221 

   222     /**

   223      * Gets context interface.

   224      * @return a reference to context interface.

   225      */

   226     MCFContextInterface& ContextInterface() const;

   227 

   228     /**

   229      * Adds subscription to Context Framework to get indications of context

   230      * events.

   231      * @param aListener is a pointer to listener interface that will be notified

   232      *  of the specified context events.

   233      * @return None. If subscribing is unsuccessful, leaves with any of system

   234      *   wide error codes.

   235      */

   236     void SubscribeContextL( MCFScriptListener* aListener );

   237 

   238     /**

   239      * Removes subscription from Context Framework, cancels indications of

   240      * context events.

   241      * @param aListener is a pointer to listener interface whose context

   242      *   subscription is cancelled.

   243      * @return None.

   244      */

   245     void RemoveSubscription( MCFScriptListener* aListener );

   246 

   247     /**

   248      * Checks a context read security.

   249      * @param aSource is the context source.

   250      * @param aType is the context type.

   251      * @return KErrNone when security check passed, otherwise any of the system

   252      *   wide error codes.

   253      */

   254     TInt CheckContextReadSecurity( const TDesC& aSource,

   255         const TDesC& aType );

   256 

   257     /**

   258      * Stores operation data into a persistent file. If the file exists

   259      * the old data is replaced by calling ExternalizeL for the operation.

   260      * @param aFile is the persistent file for operation data.

   261      * @param aOperation is the operation to be stored.

   262      * @return None.

   263      */

   264     void StoreL( const TDesC& aFile, CCFOperationNode& aOperation );

   265 

   266     /**

   267      * Restores operation data from a persistent file. If the file exists

   268      * InternalizeL is called for the operation.

   269      * @param aFile is the persistent file containing operation data.

   270      * @param aOperation is the operation to be restored.

   271      * @return None.

   272      */

   273     void RestoreL( const TDesC& aFile,

   274         CCFOperationNode& aOperation );

   275 

   276     /**

   277      * Deletes the persistent file.

   278      * Operation node must call this method for all persistent data files

   279      * it owns when Cleanup() -method is called.

   280      * @param aFile file name of the persistent data file.

   281      */

   282     void Delete( const TDesC& aFile );

   283 

   284     /**

   285      * Check if there are actions to launch and launch them.

   286      * Should be called after script has been evaluated based on something else

   287      * than context indication, e.g. timer event.

   288      * Note that calling this from normal evaluation during context indication

   289      * results in executing script actions multiple times when script is true.

   290      */

   291     void LaunchActivatedActions( );

   292 

   293     /**

   294      * Fires an action.

   295      * @param aEvent is the script event defining the action. Ownership is

   296      *   transferred.

   297      * @return None.

   298      */

   299     void FireActionL( CCFScriptEvent* aEvent );

   300 

   301     /**

   302     * Fires a context source command action.

   303     * @param aCommand is the context source command.

   304     * @return None.

   305     */

   306     void FireActionL( const CCFContextSourceCommand& aCommand );

   307 

   308     /**

   309      * Gets the security policy of a particular action.

   310      * @param aActionId is the identifier of the action.

   311      * @param aPolicy is the security policy which will be set by this method.

   312      * @return KErrNone if action was found, KErrNotFound if not.

   313      */

   314     TInt GetActionSecurityPolicy( const TDesC& aActionId,

   315         TSecurityPolicy& aPolicy );

   316 

   317 private:

   318 

   319     /**

   320      * C++ default constructor.

   321      */

   322     CCFScript( MCFExtendedContextInterface& aCF,

   323         MCFActionHandler& aActionHandler,

   324         MCFSecurityChecker& aSecurityChecker,

   325         MCFPlugInOperation& aPlugInOperation,

   326         RFs& aFs );

   327 

   328     /**

   329      * By default Symbian 2nd phase constructor is private.

   330      */

   331     void ConstructL( CMDXMLNode& aStartNode, const TDesC& aName,

   332         TInt aScriptId, const TUid& aOwner, TInt aLength,

   333         MCFScriptOwner* aScriptOwner );

   334 

   335 private: // New functions

   336 

   337     /**

   338      * Starting point for script tree creation.

   339      * @since Series 60 5.0

   340      * @param aStartNode node to start parsing from.

   341      * @return KErrNone if successful, otherwise appropriate system wide

   342      *   error code.

   343      */

   344     TInt ParseScriptL( CMDXMLNode& aStartNode );

   345 

   346     /**

   347      * Evaluates script with a context.

   348      * @since Series 60 4.0

   349      * @param aContext is the context used for evaluating the script.

   350      * @param aContextLevelDelay will be set to context level delay in

   351      *  milliseconds if required by evaluation, otherwise left untouched.

   352      * @return ETrue if any script operation was really evaluated, EFalse

   353      *   otherwise.

   354      */

   355     TBool EvaluateScript( const CCFContextObject& aContext,

   356         TInt& aContextLevelDelay );

   357 

   358     /**

   359      * Adds new dependency in script.

   360      * The dependency is the implementation uid of the operation plug-in.

   361      * This link is needed since if the operation plug-in is uninstalled,

   362      * all the scripts which has the operation plug-in dependency must be

   363      * deregistered.

   364      * @param aUid Implementation uid of the dependecy.

   365      */

   366     void AddDependencyL( const TUid& aUid );

   367 

   368 private: // Data

   369 

   370     // Reference to context services.

   371     MCFExtendedContextInterface& iCF;

   372 

   373     // Reference to the action handler.

   374     MCFActionHandler& iActionHandler;

   375 

   376     // Interface for security checking.

   377     MCFSecurityChecker& iSecurityChecker;

   378 

   379     // Reference to parsing plugin operations.

   380     MCFPlugInOperation& iPlugInOperation;

   381 

   382     // Reference to File server session.

   383     RFs& iFs;

   384 

   385     // Script info

   386     CCFScriptInfo* iInfo;

   387 

   388     // The root node of the script.

   389     CCFScriptRoot* iScriptRoot;

   390 

   391     // Script subscriptions, owned.

   392     RPointerArray< CCFScriptSubscription > iScriptSubscriptions;

   393 

   394     // Script listeners requiring all context indications, not owned.

   395     RPointerArray< MCFScriptListener > iRequiresAll;

   396 

   397     // Script owning thread for security checking. Valid only during when

   398     // CheckSecurity() is called, other times pointer is NULL.

   399     const RThread* iScriptThreadForSecurityCheck;

   400 

   401     // Own: Persistent data handling for scripts.

   402     CCFPersistentData* iPersistentData;

   403 

   404     // Own: Array of operation plug-in uids

   405     RArray<TUid> iDependencyList;

   406     };

   407 

   408 #endif // C_CFSCRIPT_H

   409