/*
* 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 Single Entry Fetch dialog API.
*
*/


#ifndef __CPbkSingleEntryFetchDlg_H__
#define __CPbkSingleEntryFetchDlg_H__

//  INCLUDES
#include <e32base.h>    // CBase
#include <cntdef.h>     // TContactItemId

//  FORWARD DECLARATIONS
class CContactViewBase;
class CPbkFetchDlg;
class CPbkContactEngine;
class MObjectProvider;
class MPbkFetchKeyCallback;
class MPbkFetchDlgAccept;


// CLASS DECLARATION
/**
 * Phonebook Single Entry Fetch API. This class is used to construct 
 * a Phonebook UI dialog where the user is able to select a single 
 * contact entry from a contact list. The user selection is then returned 
 * to the client.
 */
class CPbkSingleEntryFetchDlg : 
        public CBase
    {
    public:  // Types
        /**
         * Single entry fetch parameter class. 
         */
        class TParams
            {
            public:  // Input parameters
                /**
                 * Contact database. If NULL, the contact database is 
                 * retrieved from TLS or constructed if not available.
                 * If you have a Contact database on the client side
                 * please supply it here. 
                 */
                CPbkContactEngine* iPbkEngine;

                /**
                 * Contact view to display. If NULL, loads the default
                 * contact view containing all names in the contact
                 * database.
                 * @see CPbkContactEngine::AllContactsView()
                 * @see CPbkContactEngine::FilteredContactsViewL()
                 */
                CContactViewBase* iContactView;

                /**
                 * OPTIONAL: Fetch key event callback. 
                 * If NULL, not applicable.
                 */
                MPbkFetchKeyCallback* iFetchKeyCallback;

                /**
                 * OPTIONAL: Fetch accept callback.
                 * If NULL, not applicable.
                 */
                MPbkFetchDlgAccept* iFetchDlgAccept;

            public:  // Output parameters
                /**
                 * Returns the id of the selected entry, undefined if the dialog
                 * is canceled.
                 */
                TContactItemId iSelectedEntry;

            public: // Additional input parameters
                /**
                 * OPTIONAL: Fetch softkey resource ID.
                 * If 0, default softkeys are used.
                 */
                TInt iCbaId;

            public:  // Constructors
                /**
                 * C++ Constructor.
                 */
                IMPORT_C TParams();

                // Compiler-generated destructor is ok for this class

            private:  // Unimplemented functions
                /// Unimplemented copy constructor
                TParams(const TParams&);
                /// Unimplemented assignment operator
                TParams& operator=(const TParams&);

            private:  // data
				/// Own: spare data
                TInt32 iSpare1;
            };

    public:  // Interface
        /**
         * Creates a new single entry fetch dialog.
         *
         * @param aParams   Fetch parameters, @see TParams
         * @return New instance of this class.
         */
        IMPORT_C static CPbkSingleEntryFetchDlg* NewL(TParams& aParams);

        /**
         * @see CCoeControl::SetMopParent(MObjectProvider* aParent)
         */
        IMPORT_C void SetMopParent(MObjectProvider* aParent);

        /**
         * Sets *aSelfPtr to NULL when this dialog is destroyed.
         * @precond !aSelfPtr || *aSelfPtr==this
         */
        IMPORT_C void ResetWhenDestroyed(CPbkSingleEntryFetchDlg** aSelfPtr);

        /**
         * Executes this dialog.
         * NOTE: this object is deleted when ExecuteLD returns or leaves!
         * NOTE: current status pane layout is replaced with the Phonebook
         * one. Restoring the original pane is left to be the responsibility
         * of the caller.
         *
         * @return A non-zero value if accepted, 0 if canceled.
         */
        IMPORT_C TInt ExecuteLD();

        /**
         * Destructor. Also cancels this dialog and makes ExecuteLD return.
         */
        ~CPbkSingleEntryFetchDlg();

    private:  // Implementation
        CPbkSingleEntryFetchDlg(TParams& aParams);
        void ConstructL();
        static void Panic(TInt aReason);

    private:  // Data
        /// Own: parameters
        TParams& iParams;
        /// Own: fetch dialog
        CPbkFetchDlg* iFetchDlg;
        /// Ref: Phonebook engine
        CPbkContactEngine* iPbkEngine;
        /// Own: Phonebook engine
        CPbkContactEngine* iOwnPbkEngine;
        /// Ref: contact view to use for fetcing
        CContactViewBase* iContactView;
        /// Ref: set to ETrue in destructor
        TBool* iDestroyedPtr;
        /// Ref: pointer to self
        CPbkSingleEntryFetchDlg** iSelfPtr;
        /// Own: Object Provider
        MObjectProvider* iObjectProvider;
    };

#endif // __CPbkSingleEntryFetchDlg_H__

// End of File