/*

* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  

*    Phonebook contact iterator

*

*/

#ifndef __CPbkContactIter_H__

#define __CPbkContactIter_H__

//  INCLUDES

#include    <e32base.h>     // CBase

#include    <cntdb.h>       // TContactIter

// FORWARD DECLARATIONS

class CPbkContactEngine;

class CPbkContactItem;

class CContactItem;

// CLASS DECLARATION

/**

 * Phonebook contact iterator. Only iterates through recognised Phonebook

 * contact cards, not groups or templates. NextL jumps over any other contacts. 

 */

class CPbkContactIter : public CBase

	{

    public:  // Constructors and destructor

        /**

         * Creates a new instace of this class.

         *

         * @param aEngine   Phonebook engine whose contacts to iterate.

         * @param aUseMinimalRead   Use ReadMinimalContactL instead of 

         *                          ReadContactL to read the contacts.

         * @return Contact iterator instance.

         */

        IMPORT_C static CPbkContactIter* NewL

            (CPbkContactEngine& aEngine, TBool aUseMinimalRead=EFalse);

        /**

         * Same as NewL but leaves the created object on the cleanup stack.

         * Creates a new instace of this class.

         *

         * @param aEngine   Phonebook engine whose contacts to iterate.

         * @param aUseMinimalRead   Use ReadMinimalContactL instead of 

         *                          ReadContactL to read the contacts.

         * @return Contact iterator instance.

         */

        IMPORT_C static CPbkContactIter* NewLC

            (CPbkContactEngine& aEngine, TBool aUseMinimalRead=EFalse);

	    /**

         * Destructor.

         */

        ~CPbkContactIter();

    public:  // interface

        /**

         * Intializes the iterator to the first Phonebook contact.

         * @return Id of the first Phonebook contact, KNullContactId if none found.

         */

	    IMPORT_C TContactItemId FirstL();

        /**

         * Advances the iterator to the next Phonebook contact.

         * @return Id of the next Phonebook contact, KNullContactId if none found.

         */

	    IMPORT_C TContactItemId NextL();

        /**

         * Resets the iterator to null state.

         */

	    IMPORT_C void Reset();

        /**

         * Returns the current Phonebook contact, NULL if none.

         * @return  The contact item the iterator is currently pointing at.

         */

        IMPORT_C CPbkContactItem* CurrentL() const;

        /**

         * Returns the current Phonebook contact, NULL if none.

         * Caller is responsible for deleting the contact, thus ownership of the

         * contact item is passed to the client.

         * @return  The contact item the iterator is currently pointing at.

         */

        IMPORT_C CPbkContactItem* GetCurrentL() const;

        __DECLARE_TEST;

    private:  // Implementation

	    CPbkContactIter(CPbkContactEngine& aEngine, TBool aUseMinimalRead);

        CContactItem* ReadPhonebookContactL(TContactItemId aId);

    private:  // Data

		/// Ref: phonebook engine

        CPbkContactEngine& iEngine;

		/// Own: contact iterator

        TContactIter iCmIter;

		/// Own: current item

        mutable CContactItem* iCurrentItem;

		/// Own: current pbk-item

        mutable CPbkContactItem* iCurrentPbkItem;

		/// Own: minimal read flag

        const TBool iUseMinimalRead;

	};

#endif // __CPbkContactIter_H__

// End of File