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