2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: The vcard engine for importing/exporting vcards and compact
20 #ifndef CVPBKVCARDENG_H
21 #define CVPBKVCARDENG_H
29 // FORWARD DECLARATIONS
30 class MVPbkFieldTypeList;
31 class CVPbkContactManager;
32 class MVPbkStoreContact;
34 class MVPbkContactOperationBase;
35 class MVPbkSingleContactOperationObserver;
36 class MVPbkContactCopyObserver;
37 class MVPbkContactLink;
38 class MVPbkContactStore;
44 * The vcard engine for importing/exporting vcards and compact business cards.
46 * @lib VPbkVCardEng.lib
48 class CVPbkVCardEng : public CBase
50 public: // Constructors and destructor
52 * Creates VCard engine instance.
53 * @param aContactManager The Contact manager.
54 * @return A new instance of the CVPbkVCardEng.
56 IMPORT_C static CVPbkVCardEng* NewL(
57 CVPbkContactManager& aContactManager);
64 public: // New methods
67 * Reads vCard records from a stream and saves contacts to the store
70 * A client receives links to the created contacts in a call back.
72 * @param aTargetStore The Virtual Phonebook store in which the
73 * information is copied to. The store must be
75 * @param aSourceStream A stream where the vCard data is read from
76 * @param aObserver The observer who is notified when the import
77 * completes. Failed cases:
78 * -KErrNotFound if the card contained fields that
79 * cannot be saved to the target store i.e.
80 * the operation didn't find any fields to copy.
81 * @return A new operation handle owned by the client.
82 * @exception KErrNotFound if the engine didn't find a copy policy
83 * for the target store.
86 IMPORT_C MVPbkContactOperationBase* ImportVCardL(
87 MVPbkContactStore& aTargetStore,
88 RReadStream &aSourceStream,
89 MVPbkContactCopyObserver& aObserver);
92 * Reads vCard records from a stream and saves contacts to the store
95 * A client receives links to the created contacts in a call back.
96 * NOTE: This API is introduced for performance improvements in sync.
97 * When imported for Sync the duplicate policy checks are ignored.
99 * @param aTargetStore The Virtual Phonebook store in which the
100 * information is copied to. The store must be
102 * @param aSourceStream A stream where the vCard data is read from
103 * @param aObserver The observer who is notified when the import
104 * completes. Failed cases:
105 * -KErrNotFound if the card contained fields that
106 * cannot be saved to the target store i.e.
107 * the operation didn't find any fields to copy.
108 * @return A new operation handle owned by the client.
109 * @exception KErrNotFound if the engine didn't find a copy policy
110 * for the target store.
113 IMPORT_C MVPbkContactOperationBase* ImportVCardForSyncL(
114 MVPbkContactStore& aTargetStore,
115 RReadStream &aSourceStream,
116 MVPbkContactCopyObserver& aObserver);
119 * Reads vCard records from a stream and creates contacts
122 * A client handles commiting the contact(s). Otherwise contacts
123 * are not saved to the store.
125 * @param aImportedContact An array for imported contacts from
126 * the client. Contains results after
127 * asynchronous import operation has completed.
128 * @param aTargetStore The Virtual Phonebook Store in which the
129 * information is copied to. The store must be
131 * @param aSourceStream A stream where the vCard data is read from.
132 * @param aObserver An observer for asynchronous import.
133 * The aContact in the call back is always NULL.
134 * @return A new operation handle owned by the client.
137 IMPORT_C MVPbkContactOperationBase* ImportVCardL(
138 RPointerArray<MVPbkStoreContact>& aImportedContacts,
139 MVPbkContactStore& aTargetStore,
140 RReadStream &aSourceStream,
141 MVPbkSingleContactOperationObserver& aObserver );
145 * Reads Compact Business Card records from a stream and saves
146 * contacts to the store asynchronously.
148 * A client receives links to the created contacts in a call back.
150 * @param aTargetStore The Virtual Phonebook Store in which the
151 * information is copied to. The store must be
153 * @param aSourceStream A stream where the card data is read from.
154 * @param aObserver An observer for asynchronous import.
155 * If successful there is one or more contact
156 * links in the array. Failed cases:
157 * -KErrNotSupported if the card is not compact
159 * -KErrCorrupted if the data is corrupted
160 * -KErrNotFound if there were no supported fields
162 * @return A new operation handle owned by the client.
163 * @exception KErrNotFound if the engine didn't find a copy policy
164 * for the target store.
167 IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
168 MVPbkContactStore& aTargetStore,
169 RReadStream &aSourceStream,
170 MVPbkContactCopyObserver& aObserver );
173 * Reads Compact Business Card records from a stream and creates
174 * contacts asynchronously.
176 * A client handles commiting the contact(s). Otherwise contacts
177 * are not saved to the store.
179 * @param aImportedContact An array for imported contacts from
180 * the client. Contains results after
181 * asynchronous import operation has completed.
182 * @param aTargetStore The Virtual Phonebook Store in which the
183 * contacts are created from. The store must be
185 * @param aSourceStream A stream where the card data is read from.
186 * @param aObserver An observer for asynchronous import.
187 * aContact is always NULL in call back.
188 * If successful there is one or more contact
189 * links in the array. Failed cases:
190 * -KErrNotSupported if the card is not compact
192 * -KErrCorrupted if the data is corrupted
193 * -KErrNotFound if there were no supported fields
195 * @return A new operation handle owned by the client.
196 * @exception KErrNotFound if the engine didn't find a copy policy
197 * for the target store.
200 IMPORT_C MVPbkContactOperationBase* ImportCompactBusinessCardL(
201 RPointerArray<MVPbkStoreContact>& aImportedContacts,
202 MVPbkContactStore& aTargetStore,
203 RReadStream &aSourceStream,
204 MVPbkSingleContactOperationObserver& aObserver );
207 * Exports contact information asynchronously to a vCard record.
209 * The client gives the contact whose information is exported.
211 * @param aDestStream A stream where the vCard data is written to.
212 * The data written to the stream is not Committed by this method.
213 * @param aSourceItem A contact whose information is exported.
214 * @param aObserver An observer that is notified when the export completes.
215 * A store contact returned when operation has completed is
217 * @param aBeamed If ETrue, then select fields are masked while exporting VCard
218 * @return A new operation handle owned by the client.
221 IMPORT_C MVPbkContactOperationBase* ExportVCardL(
222 RWriteStream& aDestStream,
223 const MVPbkStoreContact& aSourceItem,
224 MVPbkSingleContactOperationObserver& aObserver);
227 * Exports contact information asynchronously to a vCard record.
229 * The client gives the identifier of the contact that is first loaded
232 * @param aDestStream A stream where the vCard data is written to.
233 * The data written to the stream is not Commited by this method.
234 * @param aContactLink An identifier of the contact that is exported.
235 * @param aObserver An observer that is notified when the export completes.
236 * A store contact returned when operation has completed is
238 * @param aBeamed If ETrue, then select fields are masked while exporting VCard
239 * @return A new operation handle owned by the client.
242 IMPORT_C MVPbkContactOperationBase* ExportVCardL(
243 RWriteStream& aDestStream,
244 const MVPbkContactLink& aContactLink,
245 MVPbkSingleContactOperationObserver& aObserver);
248 * Exports contact information asynchronously to a vCard record.
249 * Note: Includes the fields, X-FAVORITE and X-SELF, during export
251 * The client gives the contact whose information is exported.
253 * @param aDestStream A stream where the vCard data is written to.
254 * The data written to the stream is not Committed by this method.
255 * @param aSourceItem A contact whose information is exported.
256 * @param aObserver An observer that is notified when the export completes.
257 * A store contact returned when operation has completed is
259 * @return A new operation handle owned by the client.
262 IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(
263 RWriteStream& aDestStream,
264 const MVPbkStoreContact& aSourceItem,
265 MVPbkSingleContactOperationObserver& aObserver);
268 * Exports contact information asynchronously to a vCard record.
269 * Note: Includes the fields, X-FAVORITE and X-SELF, during export
271 * The client gives the identifier of the contact that is first loaded
274 * @param aDestStream A stream where the vCard data is written to.
275 * The data written to the stream is not Commited by this method.
276 * @param aContactLink An identifier of the contact that is exported.
277 * @param aObserver An observer that is notified when the export completes.
278 * A store contact returned when operation has completed is
280 * @return A new operation handle owned by the client.
283 IMPORT_C MVPbkContactOperationBase* ExportVCardForSyncL(
284 RWriteStream& aDestStream,
285 const MVPbkContactLink& aContactLink,
286 MVPbkSingleContactOperationObserver& aObserver);
290 * Returns true for those field types that are supported by the vCard
291 * format and this engine.
293 * @param aFieldType A field type that is looked for.
294 * @return ETrue if given field is supported, EFalse otherwise
296 IMPORT_C TBool SupportsFieldType(const MVPbkFieldType& aFieldType);
300 * Returns field types that are supported by vCard engine.
302 * @return Field types that are supported by vCard engine.
304 IMPORT_C const MVPbkFieldTypeList& SupportedFieldTypes();
307 * Reads vCard records from a stream and replaces contacts
310 * A client handles commiting the contact(s). Otherwise contacts
311 * are not saved to the store.
313 * @param aReplaceContact Current contact which needs to replaced with
314 * the contact recevied from server as VcardBuffer. Contains results after
315 * asynchronous import operation has completed.
316 * @param aTargetStore The Virtual Phonebook Store in which the
317 * information is copied to. The store must be
319 * @param aSourceStream A stream where the vCard data is read from.
320 * @param aObserver An observer for asynchronous import.
321 * The aContact in the call back is always NULL.
322 * @return A new operation handle owned by the client.
325 IMPORT_C MVPbkContactOperationBase* CVPbkVCardEng::ImportVCardMergeL(
326 const MVPbkContactLink& aReplaceContact,
327 MVPbkContactStore& aTargetStore,
328 RReadStream& aSourceStream,
329 MVPbkSingleContactOperationObserver& aObserver );
331 private: // Implementation
332 CVPbkVCardEng(CVPbkContactManager& aContactManager);
336 /// Ref: Contact manager reference
337 CVPbkContactManager& iContactManager;
338 /// Own: Data for vCard handling
339 CVPbkVCardData* iData;
343 #endif // CVPBKVCARDENG_H