/*
* Copyright (c) 2005-2007 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:  Helper class for asynchronous operations
*
*/


#ifndef VPBKENGUTILS_CVPBKASYNCOPERATION_H
#define VPBKENGUTILS_CVPBKASYNCOPERATION_H


// INCLUDES
#include <e32base.h>

// FORWARD DECLARATIONS
namespace VPbkEngUtils {

// CLASS DECLARATIONS

/**
 * Asynchronous callback interface
 */
class MAsyncCallback
    {
    public:
        /**
         * Destructor
         */
        virtual ~MAsyncCallback() {}
        
        /**
         * Calls the callback function.
         */
        virtual void operator()() = 0;
        
        /**
         * Called if operator()() leaves.
         */
        virtual void Error(TInt aError) = 0;
    };

/**
 * Contact store asynchrnous operations.
 */
class CVPbkAsyncOperation : public CBase
    {
    public:  // Constructor and destructor
        /**
         * Constructs the operation with priority CActive::EPriorityIdle.
         */
        IMPORT_C CVPbkAsyncOperation();
        
        /**
         * Constructs the operation with aPriority.
         * 
         * @param aPriority the priority for the active object.
         */
        IMPORT_C CVPbkAsyncOperation( CActive::TPriority aPriority );
        
        /**
         * Destructor.
         */
        IMPORT_C ~CVPbkAsyncOperation();

    public:  // New functions
        /**
         * Starts a new callback. Ownership is transferred in case
         * the function does not leave.
         *
         * @param aCallback A callback instance e.g. from CVPbkAsyncCallback.h.
         *                  Ownership is taken.
         */
        IMPORT_C void CallbackL(MAsyncCallback* aCallback);

        /**
         * Cancels and deletes all callbacks in this operation.
         */
        IMPORT_C void Purge();
    
        /**
         * Cancels and deletes the aCallback from this operation.
         * 
         * @param aCallback The callback to delete.
         */
        IMPORT_C void CancelCallback( const MAsyncCallback& aCallback );
        
        /**
         * Returns the number of callbacks in this operation.
         *
         * @return The number of callbacks in this operation.
         */
        IMPORT_C TInt CallbackCount() const;
        
        /**
         * Returns a reference to the callback at position aIndex.
         *
         * @param aIndex The position of the callback.
         * @return A reference to the callback at position aIndex.
         */
        IMPORT_C const MAsyncCallback& CallbackAt( TInt aIndex ) const;
        
    private:  // Implementation
        void IssueRequest();
	    TInt HandleIdleCallback();
        static TInt IdleCallback( TAny* aThis );
        
    private:  // Data
        /// The priority of this operation
        CActive::TPriority iPriority;
        // Owned: Array of callbacks
        RPointerArray<MAsyncCallback> iCallbacks;
        // Not owned: Set if this object is destroyed
        volatile TBool* iDestroyed;
        /// Own: An idle for making the operation asynchronous.
        CIdle* iIdle;
    };

} // namespace VPbkEngUtils


/**
 * A call back class that is identified by an object handle.
 * Can be used e.g. when a single call back must be possible
 * to cancel from CVPbkAsyncObjectOperation.
 */
template<class ObjectHandle>
NONSHARABLE_CLASS(CVPbkAsyncObjectCallback)
    :   public CBase, 
        public VPbkEngUtils::MAsyncCallback
    {
    public:
        /**
         * Constructor
         *
         * @param aObjectHandle This is a handle to the object that identifies
         *        the callback,
         */
        CVPbkAsyncObjectCallback( ObjectHandle& aObjectHandle );
        
        /**
         * Returns the ETrue if the callback is identified by aObjectHandle.
         *
         * @param aObjectHandle
         */
        TBool IsSame( ObjectHandle& aObjectHandle ) const;
        
    private:
        /// Not Own:
        ObjectHandle& iObjectHandle;
    };

/**
 * An operation class template for multiple callbacks that can be
 * identified by an object handle. This enables canceling a single 
 * callback.
 *
 * Object handle could be e.g. an observer.
 */
template<class ObjectHandle>
NONSHARABLE_CLASS(CVPbkAsyncObjectOperation) : public CBase
    {
    public:  // Constructor and destructor
        
        /**
         * Constructs the operation with priority CActive::EPriorityStandard.
         *
         * @return A new instance of this class.
         */
        static CVPbkAsyncObjectOperation* NewL();
        
        /**
         * Destructor
         */
        ~CVPbkAsyncObjectOperation();

    public:  // New functions
        /**
         * Starts a new callback. Ownership is transferred in case 
         * the function does not leave.
         *
         * @param aCallback A callback instance e.g. from CVPbkAsyncCallback.h.
         *                  Ownership is taken.
         */
        void CallbackL( CVPbkAsyncObjectCallback<ObjectHandle>* aCallback );
        
        /**
         * Cancels and deletes all the callbacks in this operation.
         */
        void Purge();
        
        /** 
         * Cancels and deletes a single callback identified by aObjectHandle.
         *
         * @param aObjectHandle A callback identifier.
         */
        void CancelCallback( ObjectHandle* aObjectHandle );
        
    private:
        CVPbkAsyncObjectOperation();
        void ConstructL();
        
    private:  // Data
        /// Own: The async operation that implements most of the functionality.
        VPbkEngUtils::CVPbkAsyncOperation* iAsyncOp;
    };

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectCallback::CVPbkAsyncObjectCallback
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline CVPbkAsyncObjectCallback<ObjectHandle>::CVPbkAsyncObjectCallback( 
        ObjectHandle& aObjectHandle )
        :   iObjectHandle( aObjectHandle )
    {
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectCallback::IsSame
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline TBool CVPbkAsyncObjectCallback<ObjectHandle>::IsSame( 
        ObjectHandle& aObjectHandle ) const
    {
    return &aObjectHandle == &iObjectHandle;
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::CVPbkAsyncObjectOperation
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline CVPbkAsyncObjectOperation<ObjectHandle>::CVPbkAsyncObjectOperation()
    {
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::ConstructL
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline void CVPbkAsyncObjectOperation<ObjectHandle>::ConstructL()
    {
    iAsyncOp = new( ELeave ) VPbkEngUtils::CVPbkAsyncOperation( 
        CActive::EPriorityStandard );
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::NewL
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline CVPbkAsyncObjectOperation<ObjectHandle>* 
        CVPbkAsyncObjectOperation<ObjectHandle>::NewL()
    {
    CVPbkAsyncObjectOperation* self = new( ELeave ) CVPbkAsyncObjectOperation;
    CleanupStack::PushL( self );
    self->ConstructL();
    CleanupStack::Pop( self );
    return self;
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::~CVPbkAsyncObjectOperation
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
CVPbkAsyncObjectOperation<ObjectHandle>::~CVPbkAsyncObjectOperation()
    {
    delete iAsyncOp;
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::CallbackL
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline void CVPbkAsyncObjectOperation<ObjectHandle>::CallbackL(
        CVPbkAsyncObjectCallback<ObjectHandle>* aCallback)
    {
    iAsyncOp->CallbackL( aCallback );
    }

// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::Purge
// -----------------------------------------------------------------------------
//
template<typename ObjectHandle>
inline void CVPbkAsyncObjectOperation<ObjectHandle>::Purge()
    {
    iAsyncOp->Purge();
    }
    
// -----------------------------------------------------------------------------
// CVPbkAsyncObjectOperation::CancelCallback
// -----------------------------------------------------------------------------
//
template<class ObjectHandle>
inline void CVPbkAsyncObjectOperation<ObjectHandle>::CancelCallback(
        ObjectHandle* aObjectHandle)
    {
    const TInt count = iAsyncOp->CallbackCount();
    for ( TInt i = 0; i < count && aObjectHandle; ++i )
        {
        // MAsyncCallback instances can be safely casted to
        // CVPbkAsyncObjectCallback because there can not be any other types
        // in iAsyncOp. CallbackL takes only CVPbkAsyncObjectCallback types 
        // as input.
        const CVPbkAsyncObjectCallback<ObjectHandle>& callback = 
            static_cast<const CVPbkAsyncObjectCallback<ObjectHandle>&>( 
                iAsyncOp->CallbackAt( i ) );
        if ( callback.IsSame( *aObjectHandle ) )
            {
            iAsyncOp->CancelCallback( callback );
            return;
            }
        }
    }

#endif  // VPBKENGUTILS_CVPBKASYNCOPERATION_H
// End of file