1 /*

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

    19 #define BTSIMPLEACTIVE_H

    20 

    21 #include <e32base.h>

    22 

    23 class CBtSimpleActive;

    24 

    25 /**

    26  * APIs from this class offer functionalities that are common in mw and app 

    27  * components of Bluetooth packages. They do not serve as domain APIs.

    28  * 

    29  * Using these from external components is risky, due to possible source

    30  * and binary breaks in future.

    31  * 

    32  */

    33 

    34 

    35 /**

    36  *  Class MBtSimpleActiveObserver

    37  *

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

    39  *  Users of CBtSimpleActive need to derive from this class. 

    40  *

    41  *  @lib bteng*.lib

    42  *  @since S60 v3.2

    43  */

    44 class MBtSimpleActiveObserver

    45     {

    46 public:

    47 

    48     /**

    49      * Callback from RunL() to notify that an outstanding request has completed.

    50      *

    51      * @since Symbian^4

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

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

    54      */

    55     virtual void RequestCompletedL( CBtSimpleActive* aActive, TInt aStatus ) = 0;

    56 

    57     /**

    58      * Callback from Docancel() for handling cancelation of an outstanding request.

    59      *

    60      * @since Symbian^4

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

    62      */

    63     virtual void CancelRequest( TInt aRequestId ) = 0;

    64 

    65     /**

    66      * Callback from RunError() to notify that an error has occurred in RunL.

    67      *

    68      * @since Symbian^4

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

    70      * @param aError The error occurred in RunL.

    71      */

    72     virtual void HandleError( CBtSimpleActive* aActive, TInt aError ) = 0;

    73     };

    74 

    75 /**

    76  *  Class CBtSimpleActive.

    77  *  

    78  *  This Active Object provides its client a TRequestStatus for performing 

    79  *  asynchronous requests. It does not know the detail of the asynch operation.

    80  *  All of AO callbacks, such as RunL, will be delegated to the client

    81  *  for processing, via interface MBtSimpleActiveObserver.

    82  *  

    83  */

    84 NONSHARABLE_CLASS ( CBtSimpleActive ): public CActive

    85     {

    86 

    87 public:

    88 

    89     /**

    90      * Two-phase constructor

    91      *

    92      * @since Symbian^4

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

    94      *                  that the request has been completed.

    95      * @param aId Identifier for the CBtSimpleActive instance.

    96      * @param aPriority The priority of the active object.

    97      * @return Pointer to the constructed CBtSimpleActive object.

    98      */

    99     IMPORT_C static CBtSimpleActive* NewL( MBtSimpleActiveObserver& aObserver, TInt aId,

   100                                 TInt aPriority = CActive::EPriorityStandard );

   101 

   102     /**

   103      * Destructor

   104      */

   105     IMPORT_C virtual ~CBtSimpleActive();

   106 

   107     /**

   108      * Get the request ID of this active object.

   109      *

   110      * @since Symbian^4

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

   112      */

   113     IMPORT_C TInt RequestId();

   114 

   115     /**

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

   117      *

   118      * @since Symbian^4

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

   120      */

   121     IMPORT_C void SetRequestId( TInt aId );

   122 

   123     /**

   124      * Activate the active object.

   125      *

   126      * @since Symbian^4

   127      */

   128     IMPORT_C void GoActive();

   129 

   130     /**

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

   132      *

   133      * @since Symbian^4

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

   135      */

   136     IMPORT_C TRequestStatus& RequestStatus();

   137 

   138 private:

   139 // from base class CActive

   140 

   141     /**

   142      * From CActive.

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

   144      *

   145      * @since S60 v3.2

   146      */

   147     void DoCancel();

   148 

   149     /**

   150      * From CActive.

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

   152      *

   153      * @since S60 v3.2

   154      */

   155     void RunL();

   156 

   157     /**

   158      * From CActive.

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

   160      *

   161      * @since S60 v3.2

   162      */

   163     TInt RunError( TInt aError );

   164 

   165 private:

   166 

   167     /**

   168      * C++ default constructor

   169      *

   170      * @since S60 v3.2

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

   172      *                  that the request has been completed.

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

   174      *            active objects).

   175      * @param aPriority Priority of 

   176      */

   177     CBtSimpleActive( MBtSimpleActiveObserver& aObserver, TInt aId, TInt aPriority );

   178 

   179 private: // data

   180 

   181     /**

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

   183      */

   184     TInt iRequestId;

   185 

   186     /**

   187      * Our observer.

   188      * Not own.

   189      */

   190     MBtSimpleActiveObserver& iObserver;

   191 

   192     };

   193 

   194 #endif // BTSIMPLEACTIVE_H