/*

 * 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