/*

* 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:  An ECOM interface for the virtual phonebook converter for

*                contact IDs of the Symbian's Contacts Model and

*                Virtual Phonebook contact links.

*                NOTE: Must be used only with contact model stores.

*

*/

#ifndef CVPBKCONTACTIDCONVERTER_H

#define CVPBKCONTACTIDCONVERTER_H

// INCLUDE FILES

#include <e32base.h>

#include <vpbkpublicuid.h>

#include <ecom/ecom.h>

// FORWARD DECLARATIONS

class MVPbkContactStore;

class MVPbkContactLink;

class MVPbkStoreContactField;

class CPbkContactItem;

/**

 * An ECOM interface for the virtual phonebook converter for contact IDs

 * of the Symbian's Contacts Model and Virtual Phonebook contact links.

 *

 * A client has a TContactItemId that needs to be converted

 * to MVPbkContactLink or vice versa. 

 */

class CVPbkContactIdConverter : public CBase

    {

    public:

        /**

         * Creates a new conversion utility object for given contact store.

         *

         * The given contact store must be from the cntdb domain,

         * otherwise this function leaves with KErrNotSupported.

         *

         * @exception KErrNotSupported if aContactStore is not from cntdb domain.

         * @param aContactStore Contact store that is used for conversion.

         *                      Links and IDs are converted for this store only.

         *                      Trying to convert links or IDs from different stores

         *                      provides unspecified results.

         * @return A new conversion utility object.

         */

        static CVPbkContactIdConverter* NewL(MVPbkContactStore& aContactStore);

        /**

         * Destructor.

         */

        ~CVPbkContactIdConverter();

    public: // Interface

        /**

         * Converts the given link to an Id in the contact store defined in

         * NewL function.

         * 

         * Returned value is KNullContactId if the link

         * is from any other store than the one given in NewL.

         * 

         * @param aLink A link to convert.

         * @return A contact item id (TContactItemId) corresponding the aLink

         *         in the contact store given as construction parameter in 

         *         NewL.

         */

        virtual TInt32 LinkToIdentifier(

                const MVPbkContactLink& aLink) const =0;

        /**

         * Converts the given identifier (TContactItemId) to a contact link 

         * in the contact store defined in NewL function.

         * 

         * Created link is left to cleanup stack and ownership is transferred

         * to caller.

         * 

         * @param aIdentifier The contact id to convert.

         * @return Contact link corresponding the aIdentifier in the contact

         *         store given as construction parameter in NewL.

         */

        virtual MVPbkContactLink* IdentifierToLinkLC(

                TInt32 aIdentifier) const =0;

        /**

         * Returns a PbkEng field index for a Virtual Phonebook field.

         *

         * @param aField A Virtual Phonebook field to be converted.

         * @return A PbkEng field index or KErrNotFound.

         */

        virtual TInt PbkEngFieldIndexL(

                const MVPbkStoreContactField& aField) const =0;

        /**

         * Converts the given link to an new CPbkContactItem.

         * 

         * Created contact item is left to cleanup stack and

         * ownership is transferred to caller. Returns NULL if the

         * link is from any other store than the one given in NewL.

         *

         * @param aLink A link to convert.

         * @return A PbkEng contact item corresponding the aLink in

         *         the contact store given as construction parameter in NewL.

         */

        virtual CPbkContactItem* LinkToPbkContactItemLC(

                const MVPbkContactLink& aLink) const =0;

        /**

         * Converts the given link to an new CPbkContactItem and locks

         * it for modification.

         * 

         * Created contact item is left to cleanup stack and

         * ownership is transferred to caller. Returns NULL if the

         * link is from any other store than the one given in NewL.

         *

         * @see CPbkContactEngine::OpenContactLCX

         * @param aLink A link to convert

         * @return A PbkEng contact item corresponding the aLink in

         *         the contact store given as construction parameter

         *         in NewL.

         */

        virtual CPbkContactItem* LinkToOpenPbkContactItemLCX(

                const MVPbkContactLink& aLink) const =0; 

        /**

         * Commits the openned contact item.

         * 

         * @param aContactItem contact item to commit

         */       

        virtual void CommitOpenContactItemL(CPbkContactItem& aContactItem) =0;

        /**

         * Returns an extension point for this interface or NULL.

         *

         * @param aExtensionUid no extensions defined currently.

         * @return An extension point for this interface or NULL.

         */

        virtual TAny* ContactIdConverterExtension( TUid /*aExtensionUid*/ )

                { return NULL; }

    private: // Data

        ///Own: Destructor ID key

        TUid iDtorIDKey;

    };

// INLINE FUNCTIONS

inline CVPbkContactIdConverter* CVPbkContactIdConverter::NewL(

        MVPbkContactStore& aContactStore)

    {

    TAny* ptr = NULL;

    ptr = REComSession::CreateImplementationL(

            TUid::Uid(KVPbkContactIdConverterImplementationUid), 

            _FOFF(CVPbkContactIdConverter, iDtorIDKey),

            static_cast<TAny*>(&aContactStore));

    return reinterpret_cast<CVPbkContactIdConverter*>(ptr);

    }

inline CVPbkContactIdConverter::~CVPbkContactIdConverter()

    {

    REComSession::DestroyedImplementation(iDtorIDKey);

    }

#endif // CVPBKCONTACTIDCONVERTER_H

// End of File