1 /*

     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  An ECOM interface for the virtual phonebook converter for

    15 *                contact IDs of the Symbian's Contacts Model and

    16 *                Virtual Phonebook contact links.

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

    18 *

    19 */

    20 

    21 

    22 #ifndef CVPBKCONTACTIDCONVERTER_H

    23 #define CVPBKCONTACTIDCONVERTER_H

    24 

    25 // INCLUDE FILES

    26 #include <e32base.h>

    27 #include <VPbkPublicUid.h>

    28 #include <ecom/ecom.h>

    29 

    30 // FORWARD DECLARATIONS

    31 class MVPbkContactStore;

    32 class MVPbkContactLink;

    33 class MVPbkStoreContactField;

    34 class CPbkContactItem;

    35 

    36 /**

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

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

    39  *

    40  * A client has a TContactItemId that needs to be converted

    41  * to MVPbkContactLink or vice versa. 

    42  */

    43 class CVPbkContactIdConverter : public CBase

    44     {

    45     public:

    46         /**

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

    48          *

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

    50          * otherwise this function leaves with KErrNotSupported.

    51          *

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

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

    54          *                      Links and IDs are converted for this store only.

    55          *                      Trying to convert links or IDs from different stores

    56          *                      provides unspecified results.

    57          * @return A new conversion utility object.

    58          */

    59         static CVPbkContactIdConverter* NewL(MVPbkContactStore& aContactStore);

    60         

    61         /**

    62          * Destructor.

    63          */

    64         ~CVPbkContactIdConverter();

    65         

    66     public: // Interface

    67         /**

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

    69          * NewL function.

    70          * 

    71          * Returned value is KNullContactId if the link

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

    73          * 

    74          * @param aLink A link to convert.

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

    76          *         in the contact store given as construction parameter in 

    77          *         NewL.

    78          */

    79         virtual TInt32 LinkToIdentifier(

    80                 const MVPbkContactLink& aLink) const =0;

    81         

    82         /**

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

    84          * in the contact store defined in NewL function.

    85          * 

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

    87          * to caller.

    88          * 

    89          * @param aIdentifier The contact id to convert.

    90          * @return Contact link corresponding the aIdentifier in the contact

    91          *         store given as construction parameter in NewL.

    92          */

    93         virtual MVPbkContactLink* IdentifierToLinkLC(

    94                 TInt32 aIdentifier) const =0;

    95             

    96         /**

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

    98          *

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

   100          * @return A PbkEng field index or KErrNotFound.

   101          */

   102         virtual TInt PbkEngFieldIndexL(

   103                 const MVPbkStoreContactField& aField) const =0;

   104         

   105         /**

   106          * Converts the given link to an new CPbkContactItem.

   107          * 

   108          * Created contact item is left to cleanup stack and

   109          * ownership is transferred to caller. Returns NULL if the

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

   111          *

   112          * @param aLink A link to convert.

   113          * @return A PbkEng contact item corresponding the aLink in

   114          *         the contact store given as construction parameter in NewL.

   115          */

   116         virtual CPbkContactItem* LinkToPbkContactItemLC(

   117                 const MVPbkContactLink& aLink) const =0;

   118         

   119         /**

   120          * Converts the given link to an new CPbkContactItem and locks

   121          * it for modification.

   122          * 

   123          * Created contact item is left to cleanup stack and

   124          * ownership is transferred to caller. Returns NULL if the

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

   126          *

   127          * @see CPbkContactEngine::OpenContactLCX

   128          * @param aLink A link to convert

   129          * @return A PbkEng contact item corresponding the aLink in

   130          *         the contact store given as construction parameter

   131          *         in NewL.

   132          */

   133         virtual CPbkContactItem* LinkToOpenPbkContactItemLCX(

   134                 const MVPbkContactLink& aLink) const =0; 

   135         

   136         /**

   137          * Commits the openned contact item.

   138          * 

   139          * @param aContactItem contact item to commit

   140          */       

   141         virtual void CommitOpenContactItemL(CPbkContactItem& aContactItem) =0;

   142         

   143         /**

   144          * Returns an extension point for this interface or NULL.

   145          *

   146          * @param aExtensionUid no extensions defined currently.

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

   148          */

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

   150                 { return NULL; }

   151             

   152     private: // Data

   153         ///Own: Destructor ID key

   154         TUid iDtorIDKey;

   155     };

   156 

   157     

   158 // INLINE FUNCTIONS

   159 

   160 inline CVPbkContactIdConverter* CVPbkContactIdConverter::NewL(

   161         MVPbkContactStore& aContactStore)

   162     {

   163     TAny* ptr = NULL;

   164     ptr = REComSession::CreateImplementationL(

   165             TUid::Uid(KVPbkContactIdConverterImplementationUid), 

   166             _FOFF(CVPbkContactIdConverter, iDtorIDKey),

   167             static_cast<TAny*>(&aContactStore));

   168 

   169     return reinterpret_cast<CVPbkContactIdConverter*>(ptr);

   170     }

   171     

   172 inline CVPbkContactIdConverter::~CVPbkContactIdConverter()

   173     {

   174     REComSession::DestroyedImplementation(iDtorIDKey);

   175     }

   176     

   177 #endif // CVPBKCONTACTIDCONVERTER_H

   178 

   179 // End of File