/*

* Copyright (c) 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:  Transaction queue implementation

*

*/

#ifndef SENSRVTRANSACTIONQUEUE_H

#define SENSRVTRANSACTIONQUEUE_H

#include <e32base.h>

class CSensrvTransaction;

class CSensrvSession;

/**

 * Simple to use transaction queue.

 *

 * @since S60 5.0

 */

class CSensrvTransactionQueue : public CBase

    {

    public:

        /**

        * Removal type specifies what should be done to removed transaction.

        */

        enum TRemovalType

            {

            ERemovalTypeUndefined, ///< Only valid removal type for non-owning queues

            ERemovalTypeComplete,  ///< Completes and deletes transaction

            ERemovalTypeCancel,    ///< Completes with KErrCancel and deletes transaction

            ERemovalTypeTransfer   ///< Transaction is just removed, not deleted or completed

            };

        /**

        * Linkable transaction pointer.

        */

        class TLinkableTransactionPtr

            {

            public:

                TLinkableTransactionPtr()

                    {

                    }

                /**

                * Link item for queueing transaction pointers

                */

                TSglQueLink iLink;

                /**

                * Transaction pointer

                * Not owned.

                */

                CSensrvTransaction* iTransaction;

            };

        /**

        * Two phase constructor.

        *

        * @since S60 5.0

        * @param aOwned Indicates if queue owns transactions or is

        *        it used simply to store the pointers.

        *        If transactions are owned, deleting queue will

        *        also delete all transactions.

        * @return New CSensrvTransactionQueue instance

        * @exception KErrNoMemory Out of memory.

        */

        static CSensrvTransactionQueue* NewL(TBool aOwned);

        /**

        * Destructor.

        */

        virtual ~CSensrvTransactionQueue();

        /**

        * Adds transaction to the the queue

        *

        * @since S60 5.0

        * @param aTransaction The transaction to be added.

        * @param aLast If ETrue, transaction is added to the end of

        *        the queue, otherwise it is added to the beginning.

        * @return KErrNoMemory: Out of memory.

        *         KErrArgument: NULL transaction.

        */

        TInt Add(CSensrvTransaction* aTransaction, TBool aLast = ETrue);

        /**

        * Removes specified transaction from queue, if it is there.

        * If queue owns the transactions, the removed transaction

        * may be completed and deleted, depending on removal type. 

        *

        * @since S60 5.0

        * @param aTransaction The transaction to be removed.

        * @param aRemovalType Determines removal type.

        * @see TRemovalType

        */

        void Remove(CSensrvTransaction* aTransaction,

                    TRemovalType aRemovalType = ERemovalTypeUndefined);

        /**

        * Removes all transactions initiated by specified session

        * from queue.

        * If queue owns the transactions, the transactions

        * are completed with KErrCancel and are deleted. Otherwise 

        * does not delete or complete transactions.

        *

        * @since S60 5.0

        * @param aSession The session to match.

        */

        void Remove(CSensrvSession* aSession);

        /**

        * Removes all transactions with timestamp older than

        * specified cutoff time. 

        *

        * @since S60 5.0

        * @param aCutoffTime Transactions older that this time

        *        will be removed.

        * @return Number of transactions removed.

        */

        TInt RemoveObsolete(const TTime& aCutoffTime);

        /**

        * Removes all transactions.

        *

        * @since S60 5.0

        */

        void RemoveAll();

        /**

        * Gets pointer to first transaction in queue.

        * Transaction stays in the queue.

        *

        * @since S60 5.0

        * @return Pointer to first transaction in queue or NULL if empty.

        */

        CSensrvTransaction* First();

        /**

        * Checks if queue is empty

        *

        * @since S60 5.0

        * @return ETrue if queue is empty.

        */

        inline TBool IsEmpty() {return iTransactionPtrList.IsEmpty(); };

    private:

        /**

        * C++ constructor

        *

        * @since S60 5.0

        * @param aOwner Indicates if queue owns transactions or is

        *        it used simply to store the pointers.

        *        Deleting queue will delete all transactions if transactions

        *        are owned.

        */

        CSensrvTransactionQueue(TBool aOwned);

        /**

        * 2nd phase of construction

        *

        * @since S60 5.0

        */

        void ConstructL();

        /**

        * Gets pointer to the TLinkableTransactionPtr in queue

        * corresponding to specified transaction.

        * Transaction stays in the queue.

        *

        * @since S60 5.0

        * @param aTransaction The transaction to be found.

        * @return Pointer to TLinkableTransactionPtr or NULL if not found.

        */

        TLinkableTransactionPtr* FindTransactionPtr(CSensrvTransaction* aTransaction);  

        /**

        * Removes linkable transaction pointer and deletes it. 

        * If transactions are owned, they are completed with KErrCancel

        * or whatever error code they currently have.

        *

        * @since S60 5.0

        * @param aPtr Linkable transaction pointer to remove 

        * @param aRemovalType Determines removal type.

        * @see TRemovalType

        */

        void RemovePtr(TLinkableTransactionPtr* aPtr, TRemovalType aRemovalType);

    private:

        /**

        * Holds transaction pointers of transactions.

        * Queued pointer objects are owned.

        */

        TSglQue<TLinkableTransactionPtr> iTransactionPtrList;

        /**

        * Iterator for transaction queue

        */        

        TSglQueIter<TLinkableTransactionPtr> iTransactionPtrIter;

        /**

        * Indicates whether or not this queue owns the transactions it holds.

        */

        TBool iOwned;

        /**

        * Heap where the queue resides. 

        * Transactions must reside in the same heap.

        * Not own.

        */

        RHeap* iHeap;

    };

#endif // SENSRVTRANSACTIONQUEUE_H