1 /*

     2 * Copyright (c) 2007 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:  Active object helper class.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef BTUIACTIVE_H

    21 #define BTUIACTIVE_H

    22 

    23 

    24 #include <e32base.h>

    25 

    26 class CBTUIActive;

    27 

    28 /**

    29  *  Class MBTUIActiveObserver

    30  *

    31  *  Callback class for receiving a completed active object event.

    32  *  Users of CBTUIActive need to derive from this class. 

    33  * 

    34  *  @since S60 v5.0

    35  */

    36 class MBTUIActiveObserver

    37     {

    38 

    39 public:

    40 

    41     /**

    42      * Callback to notify that an outstanding request has completed.

    43      *

    44      * @since S60 v5.0

    45      * @param aActive Pointer to the active object that completed.

    46      * @param aId The ID that identifies the outstanding request.

    47      * @param aStatus The status of the completed request.

    48      */

    49     virtual void RequestCompletedL( CBTUIActive* aActive, TInt aId, 

    50                                     TInt aStatus ) = 0;

    51 

    52     /**

    53      * Callback to notify that an error has occurred in RunL.

    54      *

    55      * @param aActive Pointer to the active object that completed.

    56      * @param aId The ID that identifies the outstanding request.

    57      * @param aStatus The status of the completed request.

    58      */

    59     virtual void HandleError( CBTUIActive* aActive, TInt aId, 

    60                                     TInt aError ) = 0;

    61 

    62     };

    63 

    64 

    65 /**

    66  *  Class CBTUIActive

    67  *

    68  *  Base clase for active objects used in BTUI

    69  *

    70  *  @since S60 v5.0

    71  */

    72 NONSHARABLE_CLASS( CBTUIActive ) : public CActive

    73     {

    74 

    75 public:

    76 

    77     /**

    78      * Two-phase constructor

    79      *

    80      * @since S60 v5.0

    81      * @param aObserver Pointer to callback interface that receives notification

    82      *                  that the request has been completed.

    83      * @param aId The request ID

    84      * @param aPriority Active Object Priority 

    85      * @return Pointer to the constructed CBTUIActive object.

    86      */

    87     static CBTUIActive* NewL( MBTUIActiveObserver* aObserver, 

    88                                 TInt aId, TInt aPriority );

    89 

    90     /**

    91      * Destructor

    92      */

    93     virtual ~CBTUIActive();

    94 

    95     /**

    96      * Get the request ID of this active object.

    97      *

    98      * @since S60 v5.0

    99      * @return The request ID of this active object.

   100      */

   101     TInt RequestId();

   102     

   103     /**

   104      * Set a new request ID for this active object.

   105      *

   106      * @since S60 v5.0

   107      * @param The new request ID of this active object.

   108      */

   109     void SetRequestId( TInt aId );

   110     

   111     /**

   112      * Activate the active object.

   113      *

   114      * @since S60 v5.0

   115      */

   116     void GoActive();

   117 

   118     /**

   119      * Cancel an outstanding request.

   120      *

   121      * @since S60 v5.0

   122      */

   123     void CancelRequest();

   124 

   125     /**

   126      * Get a reference to the active object request status.

   127      *

   128      * @since S60 v5.0

   129      * @return Reference to the active object request status.

   130      */

   131     TRequestStatus& RequestStatus();

   132 

   133 // from base class CActive

   134 

   135     /**

   136      * From CActive.

   137      * Called by the active scheduler when the request has been cancelled.

   138      *

   139      * @since S60 v5.0

   140      */

   141     void DoCancel();

   142 

   143     /**

   144      * From CActive.

   145      * Called by the active scheduler when the request has been completed.

   146      *

   147      * @since S60 v5.0

   148      */

   149     void RunL();

   150 

   151     /**

   152      * From CActive.

   153      * Called by the active scheduler when an error in RunL has occurred.

   154      * Error handling is really done by callback in HandleError().

   155      *

   156      * @since S60 v5.0

   157      * @param aError Error occured in Active Object's RunL().

   158      * @return KErrNone. 

   159      */

   160     TInt RunError( TInt aError );

   161 

   162 private:

   163 

   164     /**

   165      * C++ default constructor

   166      *

   167      * @since S60 v5.0

   168      * @param aObserver Pointer to callback interface that receives notification

   169      *                  that the request has been completed.

   170      * @param aId ID of the request (for the client to keep track of multiple 

   171      *            active objects).

   172      * @param aPriority Priority of 

   173      */

   174     CBTUIActive( MBTUIActiveObserver* aObserver, TInt aId, TInt aPriority );

   175 

   176     /**

   177      * Symbian 2nd-phase constructor

   178      *

   179      * @since S60 v5.0

   180      */

   181     void ConstructL();

   182 

   183 private: // data

   184 

   185     /**

   186      * ID of the request (used only by our client).

   187      */

   188     TInt iRequestId;

   189 

   190     /**

   191      * Our observer.

   192      * Not own.

   193      */

   194     MBTUIActiveObserver* iObserver;

   195 

   196     };

   197 

   198 

   199 #endif // BTUIACTIVE_H