/*
* Copyright (c) 2004,2006 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Active object wrapper
*
*/



#ifndef C_CAOASYNCWRAPPER_H
#define C_CAOASYNCWRAPPER_H

// INCLUDE FILES
#include <e32base.h>

// LOCAL DEFINITIONS

/**  
 * Panic category for AsyncWrapper
 */
_LIT(  KPanicCategory, "AsyncWrapper" );

/**  
 * Panic reason for AsyncWrapper
 */
const TInt KReason = 0;

// CLASS DEFINITION

/**
 *  Active object wrapper for asynchronous requests.
 *
 *  @lib PDPContextManager2.lib
 *  @since S60 v3.1
 */
template <class T>
NONSHARABLE_CLASS( CAOAsyncWrapper ): public CActive
    {
public:        // Construction

    /**
     * Create a CAOAsyncWrapper object.
     *
     * @since S60 v3.1
     * @param aPt2Object    A ponter to object, for which the following 
     *                      function pointers are called.
     * @param aRequestFpt   A pointer to Request member function.
     * @param aRunLFpt      A pointer to RunL member function.
     * @param aDoCancelFpt  A pointer to DoCancel member function.
     * @param aRunErrorFpt  A pointer to RunError member function. Note:
     *                      aRunErrorFpt is allowed to be NULL, 
                            in contrast to other parameters!
     * @return a pointer to the created instance of CAOAsyncWrapper.
     */
    static CAOAsyncWrapper* NewL( T* aPt2Object,
                              void ( T::*aRequestFpt )( TRequestStatus& ),
                           void ( T::*aRunLFpt )( TInt ),
                           void ( T::*aDoCancelFpt )(),
                           TInt ( T::*aRunErrorFpt )( TInt ) )
        {
        CAOAsyncWrapper* self = NewLC( aPt2Object, aRequestFpt, 
                                   aRunLFpt, aDoCancelFpt, aRunErrorFpt );
        CleanupStack::Pop(self);
        return self;
        };
    
    /**
     * Create a CAOAsyncWrapper object.
     * Created instance is put on the CleanupStack.
     *
     * @since S60 v3.1
     * @param aPt2Object    A ponter to object, for which the following 
     *                      function pointers are called.
     * @param aRequestFpt   A pointer to Request member function.
     * @param aRunLFpt      A pointer to RunL member function.
     * @param aDoCancelFpt  A pointer to DoCancel member function.
     * @param aRunErrorFpt  A pointer to RunError member function. Note:
     *                      aRunErrorFpt is allowed to be NULL, 
     *                      in contrast to other parameters!
     * @return a pointer to the created instance of CAOAsyncWrapper.
     */
    static CAOAsyncWrapper* NewLC( T* aPt2Object,
                              void ( T::*aRequestFpt )( TRequestStatus& ),
                            void ( T::*aRunLFpt )( TInt ),
                            void ( T::*aDoCancelFpt )(),
                            TInt ( T::*aRunErrorFpt )( TInt ) )
        {
        CAOAsyncWrapper* self = new ( ELeave ) CAOAsyncWrapper( aPt2Object,
                                                                aRequestFpt, 
                                                                aRunLFpt,
                                                                aDoCancelFpt,
                                                               aRunErrorFpt );
        CleanupStack::PushL( self );
        self->ConstructL();
        return self;
        };

    /**
     * Destructor. Destroy the object and release all memory objects.
     * Active object is also canceled.
     *
     * @since S60 v3.1
     */
    virtual ~CAOAsyncWrapper()
        {
        Cancel();
        };


public:        // New methods

    /**
     * Issue asynchronous request.
     * Calls in construction given "request" function pointer, if 
     * AO is not already active.
     * Note: IssueRequestL may leave only if iRequestFpt may leave!
     *
     * @since S60 v3.1
     */
    void IssueRequestL()
        {
        if ( !IsActive() )
            {
            (*iPt2Object.*iRequestFpt)( iStatus );
            SetActive();
            }
        };

    /**
     * Issue asynchronous request.
     * Calls in construction given "request" function pointer, if 
     * AO is not already active.
     * Note: Non-leavable method, should be used only if 
     * issue request method is also non-leavable.
     *
     * @since S60 v3.1
     */
    void IssueRequest()
        {
        if ( !IsActive() )
            {
            (*iPt2Object.*iRequestFpt)( iStatus );
            SetActive();
            }
        };


private:    // Construction

    /**
     * Constructor
     *
     * @since S60 v3.1
     * @param aPt2Object    A ponter to object, for which the following 
     *                      function pointers are called.
     * @param aRequestFpt   A pointer to Request member function.
     * @param aRunLFpt      A pointer to RunL member function.
     * @param aDoCancelFpt  A pointer to DoCancel member function.
     * @param aRunErrorFpt  A pointer to RunError member function. Note:
     *                      aRunErrorFpt is allowed to be NULL, 
     *                      in contrast to other parameters!
     */
    CAOAsyncWrapper( T* aPt2Object,
              void ( T::*aRequestFpt )( TRequestStatus& ),
              void ( T::*aRunLFpt )( TInt ),
              void ( T::*aDoCancelFpt )(),
              TInt ( T::*aRunErrorFpt )( TInt ) )  :
    CActive( CActive::EPriorityStandard ),
    iPt2Object( aPt2Object ),
    iRequestFpt( aRequestFpt ),
    iRunLFpt( aRunLFpt ), 
    iDoCancelFpt( aDoCancelFpt ),
    iRunErrorFpt( aRunErrorFpt )
        {
        __ASSERT_ALWAYS( iPt2Object, User::Panic( KPanicCategory, KReason ) );
        __ASSERT_ALWAYS( iRequestFpt,User::Panic( KPanicCategory, KReason ) );
        __ASSERT_ALWAYS( iRunLFpt,   User::Panic( KPanicCategory, KReason ) );
        __ASSERT_ALWAYS( iDoCancelFpt,
                                     User::Panic( KPanicCategory, KReason ) );
        CActiveScheduler::Add( this );        
        };
                
                
    /**
     * Performs second phase construction of this object
     *
     * @since S60 v3.1
     */
    void ConstructL()
        {
        // Empty
        };


private:    

// from CActive

    /**
     * From CActive
     * Cancel outstanding request
     *
     * @since S60 v3.1
     */
    void DoCancel()
        {
        (*iPt2Object.*iDoCancelFpt)();
        };

    /**
     * From CActive
     * Process the completed request.
     *
     * @since S60 v3.1
     */
    void RunL()
        {
        (*iPt2Object.*iRunLFpt)( iStatus.Int() );
        };

    /**
     * From CActive
     * Handle a leave occurred in the RunL().
     * Note: If RunError function pointer is not given in construction,
     * the leave error is to be propagated back to the active scheduler!
     *
     * @since S60 v3.1
     * @param aError the error code of leave
     */
    TInt RunError( TInt aError )
        {
        if ( iRunErrorFpt )
            {
            return (*iPt2Object.*iRunErrorFpt)( aError );
            }
        else
            {
            return aError;
            }
        }


private:    // Member variables

    /**
     * ?description_of_pointer_member
     * Not own.
     */
    T* iPt2Object;

    /**
     * ?description_of_pointer_member
     * Not own.
     */
    void ( T::*iRequestFpt )( TRequestStatus& );

    /**
     * ?description_of_pointer_member
     * Not own.
     */
    void ( T::*iRunLFpt )( TInt );

    /**
     * ?description_of_pointer_member
     * Not own.
     */
    void ( T::*iDoCancelFpt )();

    /**
     * ?description_of_pointer_member
     * Not own.
     */
    TInt ( T::*iRunErrorFpt )( TInt );    // May be NULL

    };

#endif // C_CAOASYNCWRAPPER_H