1 /*

     2 * Copyright (c) 2002 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:  Manager to recover important operations.

    15 *

    16 */

    17 

    18 

    19 #ifndef CPHONERECOVERYSYSTEM_H

    20 #define CPHONERECOVERYSYSTEM_H

    21 

    22 // INCLUDES

    23 #include    <coemain.h>

    24 #include    <e32base.h>

    25 #include    "ctelerecoverysystem.h"

    26 

    27 // CONSTANTS

    28 const TInt KNullId = -1;

    29 const TInt KIdContainerSize = 10;

    30 

    31 // MACROS     

    32 

    33 

    34 // DATA TYPES

    35 typedef TInt TPhoneRecoveryId;

    36 typedef TInt8 TPhoneRecoveryPriority;

    37 

    38 typedef TPhoneRecoveryId TRecoveryId;

    39 typedef TPhoneRecoveryPriority TRecoveryPriority;

    40 

    41 

    42 

    43 // FORWARD DECLARATIONS

    44 class CPhoneTimer;

    45 //class CTeleRecoverySystem;

    46 

    47 // CLASS DECLARATION

    48 

    49 /**

    50 *  If an operation fails, phone application may be leaved to incorrect states. 

    51 *  By using recovery system, failed operation will be tried again some time 

    52 *  later. This may enhance the robustness of phone application.

    53 * 

    54 *  Return value from callback function

    55 *  KErrNone: EStateIdle

    56 *  KErrNoMemory, KErrInUse, KErrServerTerminated, KErrServerBusy, KErrNotRead,

    57 *  KErrAccessDenied, KErrLocked, KErrDiskFull, KErrTimedOut: EStateWaiting

    58 *  Otherwise: EStatePending

    59 *  If call back function leaves, then the error of leave is used as return 

    60 *  value.

    61 *  Note: In the recovery callback function, CPhoneRecoverySystem::AddL(...) or

    62 *  CPhoneRecoverySystem::Add(...) should never be called. 

    63 *  

    64 *  @since 1.0

    65 */

    66 class CPhoneRecoverySystem 

    67     : public CCoeStatic

    68     {

    69     public:  // Constructors and destructor

    70 

    71         /**

    72         * First call initializes the singleton object. Subsequent calls return

    73         * instance.

    74         * @return the created instance.

    75         */

    76         IMPORT_C static CPhoneRecoverySystem* Instance();

    77 

    78         /**

    79         * Destructor.

    80         */

    81         ~CPhoneRecoverySystem();

    82        

    83     public: // new function

    84 

    85         /**

    86         * Adds a new item with given priority & state. Returns Null id if it

    87         * failed. Same item must not be added twice. Callback's return value

    88         * indicates how many steps there are to be done, 0 - no more steps. 

    89         * Error code or leave - failure.

    90         * Priority indicates importantance of the action.

    91         *

    92         * @param aCallBack callback.

    93         * @param aPriority priority.

    94         * @param aState start state.

    95         * @return identifier.

    96         */

    97         TRecoveryId Add( TCallBack aCallBack, 

    98             TRecoveryPriority aPriority, 

    99             CTeleRecoverySystem::TRecoveryState aState );

   100 

   101         /**

   102         * Add a new item to the recovery system. The function may leave if

   103         * OOM. 

   104         *

   105         * @param aCallBack callback.

   106         * @param aPriority priority.

   107         * @param aState start state.

   108         * @return identifier.

   109         */

   110         IMPORT_C TRecoveryId AddL( TCallBack aCallBack,

   111             TRecoveryPriority aPriority,

   112             CTeleRecoverySystem::TRecoveryState aState );

   113     

   114         /**

   115         * Removes item.

   116         *

   117         * @param aId identifier of the item to be removed.

   118         */

   119         IMPORT_C static void Remove( TRecoveryId aId );

   120     

   121         /**

   122         * Sets state. Note: The timer will not be started if the state is

   123         * set to be waiting.

   124         *

   125         * @param aId identifier.

   126         * @param aState new state.

   127         */

   128         void SetState( TRecoveryId aId, 

   129             CTeleRecoverySystem::TRecoveryState aState );

   130     

   131         /**

   132         * Resets pending recovery actions back to waiting.

   133         */

   134         void ResetPending();

   135     

   136         /**

   137         * Recovers one step or all steps synchronously. Even if it's solved

   138         * it should call the method.

   139         *

   140         * @param aId identifier.

   141         * @param aPriority priority.

   142         * @param aAllSteps ETrue if all steps need to be run.

   143         * @return error code.

   144         */

   145         IMPORT_C TInt RecoverNow( TRecoveryId aId, 

   146             TRecoveryPriority aPriority, 

   147             TBool aAllSteps = EFalse );

   148 

   149         /**

   150         * Informs that precondition has been satisfied.

   151         */

   152         IMPORT_C void EnablePreconditionL();

   153 

   154                         

   155        /**

   156         * Create tele recovery system

   157         */    

   158         CTeleRecoverySystem* CreateRecoverySystemL();

   159 

   160     private: // New functions

   161 

   162         /**

   163         * Removes recovery id item.

   164         *

   165         * @param aId identifier of the item to be removed.

   166         */

   167         void RemoveId( TRecoveryId aId );

   168     

   169     private: // private structures

   170         

   171         // Defines structure containing information

   172         // of a recovery item.

   173         class TRecoveryItem

   174             {

   175             public:

   176                 // Identifier

   177                 TRecoveryId iId;

   178                 // Callback

   179                 TCallBack iCallBack;

   180                 // Priority

   181                 TRecoveryPriority iPriority;

   182                 // State

   183                 CTeleRecoverySystem::TRecoveryState iState;

   184             };

   185 

   186     private: //private function

   187 

   188         /**

   189         * Two-phased constructor.

   190         * @return new instance.

   191         */

   192         static CPhoneRecoverySystem* NewL();

   193 

   194         /**

   195         * C++ constructor.

   196         */

   197         CPhoneRecoverySystem();

   198          

   199         /**

   200         * Adds id to container which holds all the ids this singleton

   201         * has given out via AddL method.

   202         * @param aId - Id to be added in container

   203         * @exception -1 (KErrNoSpace) is thrown if there isn't room in the container

   204         */

   205         void AddIdToContainer( TRecoveryId aId );

   206         

   207         /**

   208         * Removes given id from the container which holds all the ids this singleton

   209         * has given out via AddL method.

   210         * @param aId - Id to be removed from container

   211         */

   212         void RemoveFromContainer( TRecoveryId aId );

   213         

   214         /**

   215         * This is called from destructor. Method removes all the ids from recovery

   216         * system that are hold within container. This is done this way because

   217         * this singleton object is actually destructed by coeenv before some of

   218         * object's clients' destructor is called where it would try to remove

   219         * id from the recovery system. Now this way we do not leak any resources.

   220         */

   221         void RemoveAllIdsFromContainer();

   222 

   223 

   224     private:    // Data  

   225            

   226         // Timer for recovery

   227         CPhoneTimer* iTimer;

   228 

   229         // Timer for recovery all steps

   230         CPhoneTimer* iAllStepsTimer;

   231 

   232         // Id counter for TRecoveryId

   233         TInt iIdCounter;

   234 

   235         // Count the ticks

   236         TInt iTickCounter;

   237 

   238 #ifdef _DEBUG

   239         // Debug: to prevent modification of recovery system in 

   240         // recovery callback.

   241         TBool iIsCallBack;

   242 #endif // _DEBUG

   243 

   244         // ETrue if precondition ok

   245         TBool iPrecondOk;

   246 

   247         // ETrue if precondition SIM ok

   248         TBool iPrecondSimOk;

   249 

   250         // Keycount - recovery counter is checked only after some keypresses

   251         TInt iKeyCount;

   252         

   253         // Reference to Tele recovery system.

   254         CTeleRecoverySystem* iRecoverySystem;

   255         

   256         // Container for allocated recovery ids

   257         TFixedArray< TInt, KIdContainerSize > iIdContainer;

   258 

   259     };

   260 

   261 #endif      // CPHONERECOVERYSYSTEM_H   

   262             

   263 // End of File