1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CVPbkVCardEng.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,345 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: The vcard engine for importing/exporting vcards and compact
1.18 +* business cards.
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef CVPBKVCARDENG_H
1.24 +#define CVPBKVCARDENG_H
1.25 +
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32base.h>
1.29 +#include <f32file.h>
1.30 +#include <s32file.h>
1.31 +
1.32 +// FORWARD DECLARATIONS
1.33 +class MVPbkFieldTypeList;
1.34 +class CVPbkContactManager;
1.35 +class MVPbkStoreContact;
1.36 +class MVPbkFieldType;
1.37 +class MVPbkContactOperationBase;
1.38 +class MVPbkSingleContactOperationObserver;
1.39 +class MVPbkContactCopyObserver;
1.40 +class MVPbkContactLink;
1.41 +class MVPbkContactStore;
1.42 +class CVPbkVCardData;
1.43 +
1.44 +// CLASS DECLARATIONS
1.45 +
1.46 +/**
1.47 + * The vcard engine for importing/exporting vcards and compact business cards.
1.48 + *
1.49 + * @lib VPbkVCardEng.lib
1.50 + */
1.51 +class CVPbkVCardEng : public CBase
1.52 + {
1.53 + public: // Constructors and destructor
1.54 + /**
1.55 + * Creates VCard engine instance.
1.56 + * @param aContactManager The Contact manager.
1.57 + * @return A new instance of the CVPbkVCardEng.
1.58 + */
1.59 + IMPORT_C static CVPbkVCardEng* NewL(
1.60 + CVPbkContactManager& aContactManager);
1.61 +
1.62 + /**
1.63 + * Destructor.
1.64 + */
1.65 + ~CVPbkVCardEng();
1.66 +
1.67 + public: // New methods
1.68 +
1.69 + /**
1.70 + * Reads vCard records from a stream and saves contacts to the store
1.71 + * asynchronously.
1.72 + *
1.73 + * A client receives links to the created contacts in a call back.
1.74 + *
1.75 + * @param aTargetStore The Virtual Phonebook store in which the
1.76 + * information is copied to. The store must be
1.77 + * writable.
1.78 + * @param aSourceStream A stream where the vCard data is read from
1.79 + * @param aObserver The observer who is notified when the import
1.80 + * completes. Failed cases:
1.81 + * -KErrNotFound if the card contained fields that
1.82 + * cannot be saved to the target store i.e.
1.83 + * the operation didn't find any fields to copy.
1.84 + * @return A new operation handle owned by the client.
1.85 + * @exception KErrNotFound if the engine didn't find a copy policy
1.86 + * for the target store.
1.87 + * @asynchronous
1.88 + */
1.89 + IMPORT_C MVPbkContactOperationBase* ImportVCardL(
1.90 + MVPbkContactStore& aTargetStore,
1.91 + RReadStream &aSourceStream,
1.92 + MVPbkContactCopyObserver& aObserver);
1.93 +
1.94 + /**
1.95 + * Reads vCard records from a stream and saves contacts to the store
1.96 + * asynchronously.
1.97 + *
1.98 + * A client receives links to the created contacts in a call back.
1.99 + * NOTE: This API is introduced for performance improvements in sync.
1.100 + * When imported for Sync the duplicate policy checks are ignored.
1.101 + *
1.102 + * @param aTargetStore The Virtual Phonebook store in which the
1.103 + * information is copied to. The store must be
1.104 + * writable.
1.105 + * @param aSourceStream A stream where the vCard data is read from
1.106 + * @param aObserver The observer who is notified when the import
1.107 + * completes. Failed cases:
1.108 + * -KErrNotFound if the card contained fields that
1.109 + * cannot be saved to the target store i.e.
1.110 + * the operation didn't find any fields to copy.
1.111 + * @return A new operation handle owned by the client.
1.112 + * @exception KErrNotFound if the engine didn't find a copy policy
1.113 + * for the target store.
1.114 + * @asynchronous
1.115 + */
1.116 + IMPORT_C MVPbkContactOperationBase* ImportVCardForSyncL(
1.117 + MVPbkContactStore& aTargetStore,
1.118 + RReadStream &aSourceStream,
1.119 + MVPbkContactCopyObserver& aObserver);
1.120 +
1.121 + /**
1.122 + * Reads vCard records from a stream and creates contacts
1.123 + * asynchronously.
1.124 + *
1.125 + * A client handles commiting the contact(s). Otherwise contacts
1.126 + * are not saved to the store.
1.127 + *
1.128 + * @param aImportedContact An array for imported contacts from
1.129 + * the client. Contains results after
1.130 + * asynchronous import operation has completed.
1.131 + * @param aTargetStore The Virtual Phonebook Store in which the
1.132 + * information is copied to. The store must be
1.133 + * writable.
1.134 + * @param aSourceStream A stream where the vCard data is read from.
1.135 + * @param aObserver An observer for asynchronous import.
1.136 + * The aContact in the call back is always NULL.
1.137 + * @return A new operation handle owned by the client.
1.138 + * @asynchronous
1.139 + */
1.140 + IMPORT_C MVPbkContactOperationBase* ImportVCardL(
1.141 + RPointerArray<MVPbkStoreContact>& aImportedContacts,
1.142 + MVPbkContactStore& aTargetStore,
1.143 + RReadStream &aSourceStream,
1.144 + MVPbkSingleContactOperationObserver& aObserver );
1.145 +
1.146 +
1.147 + /**
1.148 + * Reads Compact Business Card records from a stream and saves
1.149 + * contacts to the store asynchronously.
1.150 + *
1.151 + * A client receives links to the created contacts in a call back.
1.152 + *
1.153 + * @param aTargetStore The Virtual Phonebook Store in which the
1.154 + * information is copied to. The store must be
1.155 + * writable.
1.156 + * @param aSourceStream A stream where the card data is read from.
1.157 + * @param aObserver An observer for asynchronous import.
1.158 + * If successful there is one or more contact
1.159 + * links in the array. Failed cases:
1.160 + * -KErrNotSupported if the card is not compact
1.161 + * business card
1.162 + * -KErrCorrupted if the data is corrupted
1.163 + * -KErrNotFound if there were no supported fields
1.164 + * in the card.
1.165 + * @return A new operation handle owned by the client.
1.166 + * @exception KErrNotFound if the engine didn't find a copy policy
1.167 + * for the target store.
1.168 + * @asynchronous
1.169 + */
1.170 + IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
1.171 + MVPbkContactStore& aTargetStore,
1.172 + RReadStream &aSourceStream,
1.173 + MVPbkContactCopyObserver& aObserver );
1.174 +
1.175 + /**
1.176 + * Reads Compact Business Card records from a stream and creates
1.177 + * contacts asynchronously.
1.178 + *
1.179 + * A client handles commiting the contact(s). Otherwise contacts
1.180 + * are not saved to the store.
1.181 + *
1.182 + * @param aImportedContact An array for imported contacts from
1.183 + * the client. Contains results after
1.184 + * asynchronous import operation has completed.
1.185 + * @param aTargetStore The Virtual Phonebook Store in which the
1.186 + * contacts are created from. The store must be
1.187 + * writable.
1.188 + * @param aSourceStream A stream where the card data is read from.
1.189 + * @param aObserver An observer for asynchronous import.
1.190 + * aContact is always NULL in call back.
1.191 + * If successful there is one or more contact
1.192 + * links in the array. Failed cases:
1.193 + * -KErrNotSupported if the card is not compact
1.194 + * business card
1.195 + * -KErrCorrupted if the data is corrupted
1.196 + * -KErrNotFound if there were no supported fields
1.197 + * in the card.
1.198 + * @return A new operation handle owned by the client.
1.199 + * @exception KErrNotFound if the engine didn't find a copy policy
1.200 + * for the target store.
1.201 + * @asynchronous
1.202 + */
1.203 + IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
1.204 + RPointerArray<MVPbkStoreContact>& aImportedContacts,
1.205 + MVPbkContactStore& aTargetStore,
1.206 + RReadStream &aSourceStream,
1.207 + MVPbkSingleContactOperationObserver& aObserver );
1.208 +
1.209 + /**
1.210 + * Exports contact information asynchronously to a vCard record.
1.211 + *
1.212 + * The client gives the contact whose information is exported.
1.213 + *
1.214 + * @param aDestStream A stream where the vCard data is written to.
1.215 + * The data written to the stream is not Committed by this method.
1.216 + * @param aSourceItem A contact whose information is exported.
1.217 + * @param aObserver An observer that is notified when the export completes.
1.218 + * A store contact returned when operation has completed is
1.219 + * always NULL.
1.220 + * @param aBeamed If ETrue, then select fields are masked while exporting VCard
1.221 + * @return A new operation handle owned by the client.
1.222 + * @asynchronous
1.223 + */
1.224 + IMPORT_C MVPbkContactOperationBase* ExportVCardL(
1.225 + RWriteStream& aDestStream,
1.226 + const MVPbkStoreContact& aSourceItem,
1.227 + MVPbkSingleContactOperationObserver& aObserver);
1.228 +
1.229 + /**
1.230 + * Exports contact information asynchronously to a vCard record.
1.231 + *
1.232 + * The client gives the identifier of the contact that is first loaded
1.233 + * and then exported.
1.234 + *
1.235 + * @param aDestStream A stream where the vCard data is written to.
1.236 + * The data written to the stream is not Commited by this method.
1.237 + * @param aContactLink An identifier of the contact that is exported.
1.238 + * @param aObserver An observer that is notified when the export completes.
1.239 + * A store contact returned when operation has completed is
1.240 + * always NULL.
1.241 + * @param aBeamed If ETrue, then select fields are masked while exporting VCard
1.242 + * @return A new operation handle owned by the client.
1.243 + * @asynchronous
1.244 + */
1.245 + IMPORT_C MVPbkContactOperationBase* ExportVCardL(
1.246 + RWriteStream& aDestStream,
1.247 + const MVPbkContactLink& aContactLink,
1.248 + MVPbkSingleContactOperationObserver& aObserver);
1.249 +
1.250 + /**
1.251 + * Exports contact information asynchronously to a vCard record.
1.252 + * Note: Includes the fields, X-FAVORITE and X-SELF, during export
1.253 + *
1.254 + * The client gives the contact whose information is exported.
1.255 + *
1.256 + * @param aDestStream A stream where the vCard data is written to.
1.257 + * The data written to the stream is not Committed by this method.
1.258 + * @param aSourceItem A contact whose information is exported.
1.259 + * @param aObserver An observer that is notified when the export completes.
1.260 + * A store contact returned when operation has completed is
1.261 + * always NULL.
1.262 + * @return A new operation handle owned by the client.
1.263 + * @asynchronous
1.264 + */
1.265 + IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(
1.266 + RWriteStream& aDestStream,
1.267 + const MVPbkStoreContact& aSourceItem,
1.268 + MVPbkSingleContactOperationObserver& aObserver);
1.269 +
1.270 + /**
1.271 + * Exports contact information asynchronously to a vCard record.
1.272 + * Note: Includes the fields, X-FAVORITE and X-SELF, during export
1.273 + *
1.274 + * The client gives the identifier of the contact that is first loaded
1.275 + * and then exported.
1.276 + *
1.277 + * @param aDestStream A stream where the vCard data is written to.
1.278 + * The data written to the stream is not Commited by this method.
1.279 + * @param aContactLink An identifier of the contact that is exported.
1.280 + * @param aObserver An observer that is notified when the export completes.
1.281 + * A store contact returned when operation has completed is
1.282 + * always NULL.
1.283 + * @return A new operation handle owned by the client.
1.284 + * @asynchronous
1.285 + */
1.286 + IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(
1.287 + RWriteStream& aDestStream,
1.288 + const MVPbkContactLink& aContactLink,
1.289 + MVPbkSingleContactOperationObserver& aObserver);
1.290 +
1.291 +
1.292 + /**
1.293 + * Returns true for those field types that are supported by the vCard
1.294 + * format and this engine.
1.295 + *
1.296 + * @param aFieldType A field type that is looked for.
1.297 + * @return ETrue if given field is supported, EFalse otherwise
1.298 + */
1.299 + IMPORT_C TBool SupportsFieldType(const MVPbkFieldType& aFieldType);
1.300 +
1.301 +
1.302 + /**
1.303 + * Returns field types that are supported by vCard engine.
1.304 + *
1.305 + * @return Field types that are supported by vCard engine.
1.306 + */
1.307 + IMPORT_C const MVPbkFieldTypeList& SupportedFieldTypes();
1.308 +
1.309 + /**
1.310 + * Reads vCard records from a stream and replaces contacts
1.311 + * asynchronously.
1.312 + *
1.313 + * A client handles commiting the contact(s). Otherwise contacts
1.314 + * are not saved to the store.
1.315 + *
1.316 + * @param aReplaceContact Current contact which needs to replaced with
1.317 + * the contact recevied from server as VcardBuffer. Contains results after
1.318 + * asynchronous import operation has completed.
1.319 + * @param aTargetStore The Virtual Phonebook Store in which the
1.320 + * information is copied to. The store must be
1.321 + * writable.
1.322 + * @param aSourceStream A stream where the vCard data is read from.
1.323 + * @param aObserver An observer for asynchronous import.
1.324 + * The aContact in the call back is always NULL.
1.325 + * @return A new operation handle owned by the client.
1.326 + * @asynchronous
1.327 + */
1.328 + IMPORT_C MVPbkContactOperationBase* CVPbkVCardEng::ImportVCardMergeL(
1.329 + const MVPbkContactLink& aReplaceContact,
1.330 + MVPbkContactStore& aTargetStore,
1.331 + RReadStream& aSourceStream,
1.332 + MVPbkSingleContactOperationObserver& aObserver );
1.333 +
1.334 + private: // Implementation
1.335 + CVPbkVCardEng(CVPbkContactManager& aContactManager);
1.336 + void ConstructL();
1.337 +
1.338 + private: // Data
1.339 + /// Ref: Contact manager reference
1.340 + CVPbkContactManager& iContactManager;
1.341 + /// Own: Data for vCard handling
1.342 + CVPbkVCardData* iData;
1.343 + };
1.344 +
1.345 +
1.346 +#endif // CVPBKVCARDENG_H
1.347 +
1.348 +// End of file