1 /*

     2 * Copyright (c) 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 #ifndef CPACTIONHANDLERTHREAD_H_

    19 #define CPACTIONHANDLERTHREAD_H_

    20 

    21 #include <e32base.h>

    22 #include <eikenv.h>

    23 #include <eikappui.h>

    24 

    25 class MLiwInterface;

    26 class CLiwGenericParamList;

    27 class CCPActionManager;

    28 

    29 /**

    30  * The function to be passed as an argument to RThread::Create.

    31  * 

    32  * It just calls CCPActionHandlerThread::ThreadFunction. The only

    33  * reason this declaration is in the header file is to let

    34  * CCPActionHandlerThread declare friendship with this funcion.

    35  * 

    36  * @param aParam pointer to CCPActionHandlerThread object

    37  * @return error code

    38  */

    39 TInt CPExecutionThreadFunction( TAny* aParam );

    40 

    41 /**

    42  * Action handler thread.

    43  * 

    44  * Provides easy-to-use interface for executing plugin actions

    45  * in a separate thread.

    46  * @since S60 5.0

    47  */

    48 class CCPActionHandlerThread: public CBase

    49     {

    50     friend TInt CPExecutionThreadFunction( TAny* );

    51     

    52 public:

    53     

    54     /**

    55      * Creates new instance of CCPActionHandlerThread.

    56      * 

    57      * @return new instance of CCPActionHandlerThread

    58      */

    59     static CCPActionHandlerThread* NewL();

    60     

    61     /**

    62      * Creates new instance of CCPActionHandlerThread.

    63      * 

    64      * @return new instance of CCPActionHandlerThread

    65      */

    66     static CCPActionHandlerThread* NewLC();

    67     

    68     /**

    69      * Destructor.

    70      * Stops the action execution thread.

    71      */

    72     ~CCPActionHandlerThread();

    73 

    74     /**

    75      * Executes an action handler action in the action execution thread.

    76      * 

    77      * @param aActionParams action parameters

    78      */

    79     void ExecuteL( const CLiwGenericParamList& aActionParams );

    80     

    81     /**

    82      * Starts the action execution thread.

    83      * 

    84      * Creates a new instance of action execution thread

    85      * provided it is not running already.

    86      */

    87     void StartExecutionThreadIfNeededL();

    88     

    89     /**

    90      * Checks whether action execution thread is alive.

    91      * 

    92      * @return ETrue if the thread is alive, EFalse otherwise.

    93      */

    94     TBool ExecutionThreadRunning();

    95 

    96 private:

    97     /**

    98      * Constructor.

    99      */

   100     CCPActionHandlerThread();

   101     

   102     /**

   103      * 2nd phase constructor.

   104      */

   105     void ConstructL();

   106     

   107     /**

   108      * This function is run is a separate thread. It creates

   109      * CServerEikonEnv and CServerAppUi objects, which provide

   110      * a trap cleanup and an active scheduler for the thread and

   111      * then starts the active scheduler.

   112      * 

   113      * @return error code

   114      */

   115     TInt ThreadFunction();

   116     

   117 private: // internal data types

   118 

   119     /**

   120      *  EIkonEnv for the server process.

   121      */

   122     class CServerEikonEnv : public CEikonEnv

   123         {

   124     public:

   125         void DestroyEnvironment();

   126         void ConstructL();

   127         };

   128 

   129     /**

   130      * EikAppUi for the server process.

   131      */

   132     class CServerAppUi : public CEikAppUi

   133         {

   134     public:

   135         ~CServerAppUi();

   136         void ConstructL();

   137         };

   138     

   139     /**

   140      * A simple active object for executin actions.

   141      * Objects of this class are created and destroyed

   142      * by action execution thread. 

   143      */

   144     class CActionExecutorAO: public CActive

   145         {

   146     public:

   147         /**

   148          * Factory method.

   149          */

   150         static CActionExecutorAO* NewL();

   151         /**

   152          * Factory method. 

   153          */

   154         static CActionExecutorAO* NewLC();

   155         /**

   156          * Destructor.

   157          */

   158         ~CActionExecutorAO();

   159         /**

   160          * The RunL method which is run whever an action needs

   161          * to be executed in the action execution thread.

   162          * It just executes the action using the parameters

   163          * supplied with a call to SetActionParams. If that

   164          * parameters are NULL, it stops the active scheduler

   165          * thus terminating action execution thread.

   166          */

   167         void RunL();

   168         /**

   169          * A dummy cancel method required by Symbian.

   170          */

   171         void DoCancel();

   172         /**

   173          * Returns a pointer to this active object's iStatus

   174          * member variable.

   175          */

   176         TRequestStatus* RequestStatus();

   177         /**

   178          * TODO

   179          * Sets paramters of the action to be executed in RunL.

   180          * This method is supposed to be called from the main CPS thread.

   181          * @param aActionParams action parameters

   182          */

   183         void SetActionParams( const CLiwGenericParamList* aActionParams );

   184     private:

   185         /**

   186          * Constructor.

   187          */

   188         CActionExecutorAO();

   189         /**

   190          * 2nd phase constructor.

   191          */

   192         void ConstructL();

   193     private:

   194         /**

   195          * Parameters of the action to be executed in RunL.

   196          * Not own.

   197          */

   198         const CLiwGenericParamList* iActionParams;

   199         /**

   200          * Action manager instance.

   201          * Own.

   202          */

   203         CCPActionManager* iActionManager;

   204         };

   205     

   206 private: // data

   207     /**

   208      * Handle to the action execution thread.

   209      * Own.

   210      */

   211     RThread iActionExecThread;

   212     

   213     /**

   214      * Active object created in the action execution thread.

   215      * Own.

   216      */

   217     CActionExecutorAO *iActionExecutorAO;

   218     

   219     /**

   220      * ETrue if action execution thread was started at least once.

   221      */

   222     TBool iActionExecThreadStarted;

   223     

   224     /**

   225      * A counter for naming action execution thread.

   226      * 

   227      * Every action execution thread has a number appended to its name.

   228      * When the thread dies (i.e. as a result of panic in a plugin), a

   229      * new instance of that thread is started with the number in the name

   230      * increased by one.

   231      */

   232     TUint iThreadNum;

   233     };

   234 

   235 #endif /* CPACTIONHANDLERTHREAD_H_ */