1 /*

     2 * Copyright (c) 2002-2005 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:  This is the storage of asynchronous imps requests and

    15 *                background tasks.

    16 *

    17 */

    18 

    19 

    20 #ifndef CCAREQUESTMAPPER_H

    21 #define CCAREQUESTMAPPER_H

    22 

    23 // INCLUDES

    24 

    25 #include "PublicEngineDefinitions.h"

    26 #include "MCABackgroundInterface.h"

    27 #include "MCABackgroundCallback.h"

    28 #include "MCABackGroundTaskObserver.h"

    29 #include <ImpsDetailed.h>

    30 

    31 // FORWARD DECLARATIONS

    32 class CCARequest;

    33 class TBackgroundNotifier;

    34 class CCABackgroundTask;

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39 *  Maps requests to responses. Used e.g. CreateGroupL.

    40 *  Handles background tasks.

    41 *

    42 *  @lib CAEngine.lib

    43 *  @since 1.2

    44 */

    45 class CCARequestMapper : public CBase

    46             , public MCABackgroundInterface

    47             , public MCABackgroundCallback

    48     {

    49     public:  // Constructors and destructor

    50 

    51         /**

    52         * Two-phased constructor.

    53         */

    54         static CCARequestMapper* NewL();

    55 

    56         /**

    57         * Destructor.

    58         */

    59         virtual ~CCARequestMapper();

    60 

    61     public: // From MCABackgroundInterface

    62 

    63         /**

    64         * @see MCABackgroundInterface

    65         */

    66         TInt RegisterBackgroundTask(

    67             MCABackgroundTask* aBackgroundTask,

    68             TCABackgroundTasks aTaskID,

    69             TInt aSubTasks = 1

    70         );

    71         /**

    72         * @see MCABackgroundInterface

    73         */

    74         TInt RegisterBackgroundObserver(

    75             MCABackgroundObserver* BackgroundObserver,

    76             TInt aTaskMask,

    77             TInt aEventMask

    78         );

    79         /**

    80         * @see MCABackgroundInterface

    81         */

    82         TInt BackgroundTaskStatus(

    83             TCABackgroundTasks aTaskID

    84         );

    85 

    86         /**

    87         * @see MCABackgroundInterface

    88         */

    89         TInt UnRegisterBackgroundObserver(

    90             MCABackgroundObserver* aBackgroundObserver

    91         );

    92 

    93     private: // From MCABackgroundCallback

    94 

    95         /**

    96          * @see MCABackgroundCallback::HandleBackgroundTask

    97          */

    98         TInt HandleBackgroundTask(

    99             MCABackgroundInterface::TCABackgroundTasks aTask );

   100 

   101     public: // New functions

   102         /**

   103         *

   104         * @param aState specifies the new network state.

   105         */

   106         void HandleNetworkStateChange( TNetworkState aState );

   107 

   108         /**

   109         * Creates request object and starts waiting if wanted.

   110         * CCARequestMapper owns the instance of created request, so remember to

   111         * call RemoveRequest/RemoveRequestAndLeaveIfErrorL when request is no

   112         * longer needed!!!

   113         * @since 1.2

   114         * @param aOpId Operation Id of request made

   115         * @param aWait Start asynchronous waiting

   116         * @param aDestroyAfterComplete Can the request be destroyed after it

   117         * has completed

   118         * @param aCallBack Callback function to be executed after request is

   119         *                  completed

   120         * @return Pointer to request object

   121         */

   122         CCARequest* CreateRequestL( TInt aOpId,

   123                                     TBool aWait = ETrue,

   124                                     TBool aDestroyAfterComplete = EFalse,

   125                                     TCallBack aCallBack = NULL );

   126 

   127         /**

   128         * Finds request according to OpId

   129         * @since 1.2

   130         * @param aOpId Operation Id of request

   131         * @return Pointer to request object

   132         */

   133         const CCARequest* FindRequest( TInt aOpId );

   134 

   135         /**

   136         * Removes request from queue

   137         * @since 1.2

   138         * @param aRequest Request to be removed

   139         */

   140         void RemoveRequest( CCARequest* aRequest );

   141 

   142         /**

   143         * Removes request from queue, and leaves if request's error code

   144         * differs from KErrNone

   145         * @since 1.2

   146         * @param aRequest Request to be removed

   147         */

   148         void RemoveRequestAndLeaveIfErrorL( CCARequest* aRequest );

   149 

   150         /**

   151         * Handles responses to requests, so remember to call this from your

   152         * code if you want request to be processed!!!

   153         * @since 1.2

   154         * @param aOpId Operation Id of response

   155         * @param aErrorCode Response's error-code

   156         */

   157         void HandleRequest( TInt aOpId, TInt aErrorCode );

   158 

   159         /**

   160         * Cancels all pending requests

   161         */

   162         void CancelAllRequests();

   163 

   164         /**

   165         * Number of waiting requests

   166         * @return Number of waiting requests

   167         */

   168         TInt WaitCount();

   169 

   170         /**

   171         * Cancels all pending requests

   172         */

   173         void ReportWaitStart();

   174 

   175         /**

   176         * Cancels all pending requests

   177         */

   178         void ReportWaitStop();

   179 

   180         /**

   181         * Register to receive notifications related to

   182         * start and completetion of background task

   183         * @param MCABackGroundTaskObserver- object

   184         */

   185         void RegisterBackGroundTaskObserver( MCABackGroundTaskObserver* aObserver );

   186 

   187         /**

   188          * UnRegister from receiving notifications related to

   189          * start and completetion of backgroundtask

   190          */

   191         void UnRegisterBackGroundTaskObserver( MCABackGroundTaskObserver* aObserver );

   192 

   193         /**

   194          * To know whether Background task has started

   195          * @return TBool

   196          */

   197         TBool IsBackgroundTaskPending();

   198 

   199         /**

   200          * Notify about the state

   201          * start and completetion of backgroundtask

   202          */

   203         void NotifyBackgroundTaskObservers( );

   204 

   205     private:

   206 

   207         /**

   208         * C++ default constructor.

   209         */

   210         CCARequestMapper();

   211 

   212         /**

   213          * Finds request for given operation id

   214          * @param aOpId is operation id

   215          */

   216         CCARequest* DoFindRequest( TInt aOpId );

   217 

   218         /**

   219          * Notifies background observers

   220          * @param aTaskPosition index of the task in iBackgroundTasks

   221          * @param aStatus new status to publis to observers

   222          * @param aSubTaksNumber numer of the current subtask

   223          * @param aLeaveCode leave code if the subtask if is there any,

   224          *                   KErrNone otherwise

   225          */

   226         void NotifyBackgroundObservers(

   227             TInt aTaskPosition,

   228             TCABackgroundStatus aStatus,

   229             TInt aSubTaskNumber,

   230             TInt aLeaveCode = 0

   231         );

   232 

   233         /**

   234         * Registers background task

   235         * @param aBackgroundTask pointer of instance

   236         * @param aTaskID is id of task

   237         * @param aSubTasks is number of subtask, positive

   238         * @return KErrNone on success, system wide error code otherwise

   239         */

   240         TInt RegisterBackgroundTaskL(

   241             MCABackgroundTask* aBackgroundTask,

   242             TCABackgroundTasks aTaskID,

   243             TInt aSubTasks = 1

   244         );

   245 

   246 

   247     private:    // Data

   248         RPointerArray<CCARequest> iRequestArray;

   249         TInt iWaitCount;

   250 

   251         //do own

   252         TBool iBackgroundProcessing;

   253 

   254         RArray<TBackgroundNotifier> iBackgroundObservers;

   255         RPointerArray<CCABackgroundTask> iBackgroundTasks;

   256 

   257         // for background task

   258         RPointerArray<MCABackGroundTaskObserver> iBackGroundTaskObserver;

   259 

   260     };

   261 

   262 /**

   263 *  Encapsulates information about a background observer

   264 *  Internal, used by CCARequestMapper

   265 *

   266 *  @lib CAEngine.lib

   267 *  @since 1.2

   268 */

   269 class TBackgroundNotifier

   270     {

   271     public: // New functions

   272 

   273         /**

   274         * Constructor

   275         * @param aBackgroundObserver pointer to background observer

   276         * @param aObserverTaskMask task mask ( bitmap )

   277         * @param aObserverEventMask event mask ( bitmap )

   278         */

   279         TBackgroundNotifier( MCABackgroundObserver* aBackgroundObserver

   280                              , TInt aObserverTaskMask = 0

   281                                                         , TInt aObserverEventMask = 0

   282                            );

   283         /**

   284         * Equality relation on TBackgroundNotifier

   285         * this is required for RArray<TBackgroundNotifier>::Find()

   286         *

   287         * @param aA for comapre

   288         * @param aB for compare

   289         * @retrun ETrue if iObservers are the same, EFalse otherwise

   290         */

   291 

   292         static TBool Identity( const TBackgroundNotifier& aA

   293                                , const TBackgroundNotifier& aB

   294                              );

   295 

   296     public:

   297         //does not own

   298         MCABackgroundObserver* iObserver;

   299         //for binary and operation,

   300         // see MCABackgroundInterface::TCABackgroundTasks

   301         TInt iTaskMask;

   302         //for binary and operation,

   303         // see MCABackgroundInterface::TCABackgroundStatus

   304         TInt iEventMask;

   305     };

   306 

   307 #endif      // CCAREQUESTMAPPER_H

   308 

   309 // End of File