williamr@4: /*
williamr@4: * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: * All rights reserved.
williamr@4: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@4: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: *
williamr@4: * Initial Contributors:
williamr@4: * Nokia Corporation - initial contribution.
williamr@4: *
williamr@4: * Contributors:
williamr@4: *
williamr@4: * Description:  The vcard engine for importing/exporting vcards and compact
williamr@4: *                business cards.
williamr@4: *
williamr@4: */
williamr@4: 
williamr@4: 
williamr@4: #ifndef CVPBKVCARDENG_H
williamr@4: #define CVPBKVCARDENG_H
williamr@4: 
williamr@4: 
williamr@4: // INCLUDES
williamr@4: #include <e32base.h>
williamr@4: #include <f32file.h>
williamr@4: #include <s32file.h>
williamr@4: 
williamr@4: // FORWARD DECLARATIONS
williamr@4: class MVPbkFieldTypeList;
williamr@4: class CVPbkContactManager;
williamr@4: class MVPbkStoreContact;
williamr@4: class MVPbkFieldType;
williamr@4: class MVPbkContactOperationBase;
williamr@4: class MVPbkSingleContactOperationObserver;
williamr@4: class MVPbkContactCopyObserver;
williamr@4: class MVPbkContactLink;
williamr@4: class MVPbkContactStore;
williamr@4: class CVPbkVCardData;
williamr@4: 
williamr@4: // CLASS DECLARATIONS
williamr@4: 
williamr@4: /**
williamr@4:  * The vcard engine for importing/exporting vcards and compact business cards.
williamr@4:  * 
williamr@4:  * @lib VPbkVCardEng.lib
williamr@4:  */
williamr@4: class CVPbkVCardEng : public CBase
williamr@4:     {
williamr@4:     public:  // Constructors and destructor
williamr@4:         /**
williamr@4:          * Creates VCard engine instance.
williamr@4:          * @param aContactManager The Contact manager.
williamr@4:          * @return A new instance of the CVPbkVCardEng.
williamr@4:          */
williamr@4:         IMPORT_C static CVPbkVCardEng* NewL(
williamr@4:                 CVPbkContactManager& aContactManager);
williamr@4: 
williamr@4:         /**
williamr@4:          * Destructor.
williamr@4:          */
williamr@4:         ~CVPbkVCardEng();
williamr@4: 
williamr@4:     public: // New methods
williamr@4: 
williamr@4:         /**
williamr@4:          * Reads vCard records from a stream and saves contacts to the store
williamr@4:          * asynchronously. 
williamr@4:          * 
williamr@4:          * A client receives links to the created contacts in a call back.
williamr@4:          *
williamr@4:          * @param aTargetStore The Virtual Phonebook store in which the 
williamr@4:          *                     information is copied to. The store must be 
williamr@4:          *                     writable.
williamr@4:          * @param aSourceStream A stream where the vCard data is read from
williamr@4:          * @param aObserver The observer who is notified when the import
williamr@4:          *                  completes. Failed cases:
williamr@4:          *                  -KErrNotFound if the card contained fields that
williamr@4:          *                  cannot be saved to the target store i.e. 
williamr@4:          *                  the operation didn't find any fields to copy.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @exception KErrNotFound if the engine didn't find a copy policy
williamr@4:          *                         for the target store.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ImportVCardL(
williamr@4:                 MVPbkContactStore& aTargetStore, 
williamr@4:                 RReadStream &aSourceStream,
williamr@4:                 MVPbkContactCopyObserver& aObserver);
williamr@4:                 
williamr@4:         /**
williamr@4:          * Reads vCard records from a stream and saves contacts to the store
williamr@4:          * asynchronously. 
williamr@4:          * 
williamr@4:          * A client receives links to the created contacts in a call back.
williamr@4:          * NOTE: This API is introduced for performance improvements in sync.
williamr@4:          *       When imported for Sync the duplicate policy checks are ignored.
williamr@4:          *
williamr@4:          * @param aTargetStore The Virtual Phonebook store in which the 
williamr@4:          *                     information is copied to. The store must be 
williamr@4:          *                     writable.
williamr@4:          * @param aSourceStream A stream where the vCard data is read from
williamr@4:          * @param aObserver The observer who is notified when the import
williamr@4:          *                  completes. Failed cases:
williamr@4:          *                  -KErrNotFound if the card contained fields that
williamr@4:          *                  cannot be saved to the target store i.e. 
williamr@4:          *                  the operation didn't find any fields to copy.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @exception KErrNotFound if the engine didn't find a copy policy
williamr@4:          *                         for the target store.
williamr@4:          * @asynchronous
williamr@4:          */        
williamr@4:         IMPORT_C MVPbkContactOperationBase* ImportVCardForSyncL(
williamr@4:                 MVPbkContactStore& aTargetStore, 
williamr@4:                 RReadStream &aSourceStream,
williamr@4:                 MVPbkContactCopyObserver& aObserver);                
williamr@4:                 
williamr@4:         /**
williamr@4:          * Reads vCard records from a stream and creates contacts
williamr@4:          * asynchronously. 
williamr@4:          *
williamr@4:          * A client handles commiting the contact(s). Otherwise contacts
williamr@4:          * are not saved to the store.
williamr@4: 		 *
williamr@4: 		 * @param aImportedContact An array for imported contacts from
williamr@4: 		 *                         the client. Contains results after
williamr@4: 		 *                         asynchronous import operation has completed.
williamr@4: 		 * @param aTargetStore The Virtual Phonebook Store in which the 
williamr@4: 		 *                     information is copied to. The store must be 
williamr@4: 		 *                     writable.
williamr@4:          * @param aSourceStream A stream where the vCard data is read from.
williamr@4:          * @param aObserver An observer for asynchronous import.
williamr@4:          *                  The aContact in the call back is always NULL.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ImportVCardL(
williamr@4:                 RPointerArray<MVPbkStoreContact>& aImportedContacts,
williamr@4:                 MVPbkContactStore& aTargetStore, 
williamr@4:                 RReadStream &aSourceStream,
williamr@4:                 MVPbkSingleContactOperationObserver& aObserver );
williamr@4:             
williamr@4:               
williamr@4:         /**
williamr@4:          * Reads Compact Business Card records from a stream and saves
williamr@4:          * contacts to the store asynchronously. 
williamr@4:          *
williamr@4:          * A client receives links to the created contacts in a call back.
williamr@4: 		 *
williamr@4: 		 * @param aTargetStore The Virtual Phonebook Store in which the 
williamr@4: 		 *                     information is copied to. The store must be 
williamr@4: 		 *                     writable.
williamr@4:          * @param aSourceStream A stream where the card data is read from.
williamr@4:          * @param aObserver An observer for asynchronous import.
williamr@4:          *                  If successful there is one or more contact
williamr@4:          *                  links in the array. Failed cases:
williamr@4:          *                  -KErrNotSupported if the card is not compact 
williamr@4:          *                  business card
williamr@4:          *                  -KErrCorrupted if the data is corrupted
williamr@4:          *                  -KErrNotFound if there were no supported fields
williamr@4:          *                  in the card.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @exception KErrNotFound if the engine didn't find a copy policy
williamr@4:          *                         for the target store.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
williamr@4:             MVPbkContactStore& aTargetStore,
williamr@4: 			RReadStream &aSourceStream,
williamr@4:             MVPbkContactCopyObserver& aObserver );
williamr@4:         
williamr@4:         /**
williamr@4:          * Reads Compact Business Card records from a stream and creates
williamr@4:          * contacts asynchronously. 
williamr@4:          *
williamr@4:          * A client handles commiting the contact(s). Otherwise contacts
williamr@4:          * are not saved to the store.
williamr@4: 		 *
williamr@4: 		 * @param aImportedContact An array for imported contacts from
williamr@4: 		 *                         the client. Contains results after
williamr@4: 		 *                         asynchronous import operation has completed. 
williamr@4: 		 * @param aTargetStore The Virtual Phonebook Store in which the 
williamr@4: 		 *                     contacts are created from. The store must be 
williamr@4: 		 *                     writable.
williamr@4:          * @param aSourceStream A stream where the card data is read from.
williamr@4:          * @param aObserver An observer for asynchronous import.
williamr@4:          *                  aContact is always NULL in call back.
williamr@4:          *                  If successful there is one or more contact
williamr@4:          *                  links in the array. Failed cases:
williamr@4:          *                  -KErrNotSupported if the card is not compact 
williamr@4:          *                  business card
williamr@4:          *                  -KErrCorrupted if the data is corrupted
williamr@4:          *                  -KErrNotFound if there were no supported fields
williamr@4:          *                  in the card.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @exception KErrNotFound if the engine didn't find a copy policy
williamr@4:          *                         for the target store.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
williamr@4:             RPointerArray<MVPbkStoreContact>& aImportedContacts,
williamr@4:             MVPbkContactStore& aTargetStore,
williamr@4: 			RReadStream &aSourceStream,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver );
williamr@4: 
williamr@4:         /**
williamr@4:          * Exports contact information asynchronously to a vCard record.
williamr@4: 		 *
williamr@4: 		 * The client gives the contact whose information is exported.
williamr@4: 		 *
williamr@4: 		 * @param aDestStream A stream where the vCard data is written to.
williamr@4: 		 *        The data written to the stream is not Committed by this method.
williamr@4: 		 * @param aSourceItem A contact whose information is exported.
williamr@4:          * @param aObserver An observer that is notified when the export completes.
williamr@4:          *          A store contact returned when operation has completed is
williamr@4:          *          always NULL.
williamr@4:          * @param aBeamed If ETrue, then select fields are masked while exporting VCard
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ExportVCardL( 
williamr@4:             RWriteStream& aDestStream, 
williamr@4:             const MVPbkStoreContact& aSourceItem,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver);
williamr@4: 
williamr@4:         /**
williamr@4:          * Exports contact information asynchronously to a vCard record.
williamr@4:          * 
williamr@4:          * The client gives the identifier of the contact that is first loaded
williamr@4:          * and then exported.
williamr@4:          *
williamr@4:          * @param aDestStream A stream where the vCard data is written to.
williamr@4:          *        The data written to the stream is not Commited by this method.
williamr@4:          * @param aContactLink An identifier of the contact that is exported.
williamr@4:          * @param aObserver An observer that is notified when the export completes.
williamr@4:          *          A store contact returned when operation has completed is
williamr@4:          *          always NULL.
williamr@4:          * @param aBeamed If ETrue, then select fields are masked while exporting VCard
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ExportVCardL(
williamr@4:             RWriteStream& aDestStream, 
williamr@4:             const MVPbkContactLink& aContactLink,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver);
williamr@4:             
williamr@4:         /**
williamr@4:         * Exports contact information asynchronously to a vCard record.
williamr@4:          * Note: Includes the fields, X-FAVORITE and X-SELF, during export
williamr@4:          *
williamr@4:          * The client gives the contact whose information is exported.
williamr@4:          *
williamr@4:          * @param aDestStream A stream where the vCard data is written to.
williamr@4:          *        The data written to the stream is not Committed by this method.
williamr@4:          * @param aSourceItem A contact whose information is exported.
williamr@4:         * @param aObserver An observer that is notified when the export completes.
williamr@4:         *          A store contact returned when operation has completed is
williamr@4:         *          always NULL.
williamr@4:         * @return A new operation handle owned by the client.
williamr@4:         * @asynchronous
williamr@4:         */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL( 
williamr@4:             RWriteStream& aDestStream, 
williamr@4:             const MVPbkStoreContact& aSourceItem,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver);
williamr@4: 
williamr@4:         /**
williamr@4:          * Exports contact information asynchronously to a vCard record.
williamr@4:          * Note: Includes the fields, X-FAVORITE and X-SELF, during export
williamr@4:          * 
williamr@4:          * The client gives the identifier of the contact that is first loaded
williamr@4:          * and then exported.
williamr@4:          *
williamr@4:          * @param aDestStream A stream where the vCard data is written to.
williamr@4:          *        The data written to the stream is not Commited by this method.
williamr@4:          * @param aContactLink An identifier of the contact that is exported.
williamr@4:          * @param aObserver An observer that is notified when the export completes.
williamr@4:          *          A store contact returned when operation has completed is
williamr@4:          *          always NULL.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @asynchronous
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(
williamr@4:             RWriteStream& aDestStream, 
williamr@4:             const MVPbkContactLink& aContactLink,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver);
williamr@4:             
williamr@4:                     
williamr@4:         /** 
williamr@4:          * Returns true for those field types that are supported by the vCard
williamr@4:          * format and this engine.
williamr@4:          *
williamr@4:          * @param aFieldType A field type that is looked for.
williamr@4:          * @return ETrue if given field is supported, EFalse otherwise
williamr@4:          */
williamr@4:         IMPORT_C TBool SupportsFieldType(const MVPbkFieldType& aFieldType);
williamr@4: 
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns field types that are supported by vCard engine.
williamr@4:          *
williamr@4:          * @return Field types that are supported by vCard engine.
williamr@4:          */
williamr@4:         IMPORT_C const MVPbkFieldTypeList& SupportedFieldTypes();
williamr@4:         
williamr@4:         /**
williamr@4:          * Reads vCard records from a stream and replaces contacts
williamr@4:          * asynchronously. 
williamr@4:          *
williamr@4:          * A client handles commiting the contact(s). Otherwise contacts
williamr@4:          * are not saved to the store.
williamr@4: 		 *
williamr@4: 		 * @param aReplaceContact Current contact which needs to replaced with
williamr@4: 		 *                         the contact recevied from server as VcardBuffer. Contains results after
williamr@4: 		 *                         asynchronous import operation has completed.
williamr@4: 		 * @param aTargetStore The Virtual Phonebook Store in which the 
williamr@4: 		 *                     information is copied to. The store must be 
williamr@4: 		 *                     writable.
williamr@4:          * @param aSourceStream A stream where the vCard data is read from.
williamr@4:          * @param aObserver An observer for asynchronous import.
williamr@4:          *                  The aContact in the call back is always NULL.
williamr@4:          * @return A new operation handle owned by the client.
williamr@4:          * @asynchronous
williamr@4:          */   
williamr@4:         IMPORT_C MVPbkContactOperationBase* CVPbkVCardEng::ImportVCardMergeL(
williamr@4:             const MVPbkContactLink& aReplaceContact,
williamr@4:             MVPbkContactStore& aTargetStore, 
williamr@4:             RReadStream& aSourceStream,
williamr@4:             MVPbkSingleContactOperationObserver& aObserver );
williamr@4: 
williamr@4:     private: // Implementation
williamr@4:         CVPbkVCardEng(CVPbkContactManager& aContactManager);
williamr@4:         void ConstructL();
williamr@4: 
williamr@4:     private: // Data
williamr@4:         /// Ref: Contact manager reference
williamr@4:         CVPbkContactManager&                        iContactManager;
williamr@4:         /// Own: Data for vCard handling
williamr@4:         CVPbkVCardData*                             iData;
williamr@4:     };
williamr@4: 
williamr@4: 
williamr@4: #endif  // CVPBKVCARDENG_H
williamr@4: 
williamr@4: // End of file