1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Persistence layer exports
18 #if !defined(__CNTITEM_H__)
21 #if !defined(__E32BASE_H__)
25 #if !defined(__CNTDEF_H__)
29 #if !defined(__CNTFIELD_H__)
36 const TInt KUidStringLength =244;
37 #define KUidStringSeparator '-'
38 class CContactItemField;
39 #define KContactMaxFieldNumber 32
40 class CContactItemViewDef;
43 const TInt KContactFieldSetSearchAll=-1;
44 class CContactItemFieldSet : public CBase
45 /** A contact item's field set. The field set owns an array of contact item fields
46 (CContactItemFields). The field set is owned by a contact item, and can be
47 retrieved using CContactItem::CardFields(). Use functions in class
48 CContactItem to add and remove fields to/from the field set.
50 A field set can contain more than one field of the same type, but this is
51 not advisable as it may cause problems when synchronising the contacts database.
56 friend class CContactItemField;
57 friend class CContactDatabase;
58 friend class CContactTables;
59 friend class RPplContactTable;
60 #ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
61 friend class TCntPersistenceUtility;
62 #endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
64 IMPORT_C static CContactItemFieldSet* NewL();
65 IMPORT_C static CContactItemFieldSet* NewLC();
66 IMPORT_C ~CContactItemFieldSet();
67 inline const CContactItemField& operator[](TInt aIndex) const;
68 inline CContactItemField& operator[](TInt aIndex);
69 inline TInt Find(TFieldType aFieldType) const; // will only find the first such occurence
70 inline TInt Find(TFieldType aFieldType,TUid aMapping) const;
71 IMPORT_C TInt FindNext(TFieldType aFieldType,TInt aStartPos=KContactFieldSetSearchAll) const;
72 IMPORT_C TInt FindNext(TFieldType aFieldType,TUid aMapping,TInt aStartPos=KContactFieldSetSearchAll) const;
73 inline TInt Count() const;
75 IMPORT_C void UpdateFieldL(const CContactItemField& aField, TInt aMatchCount);
76 IMPORT_C void UpdateFieldSyncL(const CContactItemField& aField, TInt aMatchCount);
77 IMPORT_C CContactItemFieldSet& AddL(CContactItemField& aField);
78 IMPORT_C void Remove(TInt aIndex);
79 IMPORT_C void InsertL(TInt aIndex,CContactItemField& aField);
80 IMPORT_C void Move(TInt aFrom, TInt aTo);
81 IMPORT_C TStreamId StoreL(CStreamStore& aStore,RWriteStream& aTextStream,CStreamStore& aBlobStore);
82 TStreamId StoreL(CStreamStore& aStore,RWriteStream& aTextStream,CStreamStore& aBlobStore,CContactTables* aTables);
83 IMPORT_C void RestoreL(CStreamStore& aStore, TStreamId anId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,RReadStream& aReadStream);
84 IMPORT_C void RestoreL(CStreamStore& aStore, TStreamId anId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate, HBufC* aTextBuf);
85 TInt FieldText(TFieldType aFieldType, TDes &aText, TInt aStartPosition) const;
86 CArrayFix<TFieldHeader>* ConstructFieldHeaderArrayLC(RWriteStream& aTextStream, CStreamStore& aBlobStore);
87 TInt FieldTypeCount(const CContactItemFieldSet& aSystemTemplateFields, TInt aStartIndex, const CContactItemField& aField) const;
88 TBool ContainsFieldTypeMapping(const CContentType& aBaseFieldContentType, const TFieldType& aContactFieldType) const;
89 void ExternalizeL(RWriteStream& aStream) const;
90 void InternalizeL(RReadStream& aStream);
92 CContactItemFieldSet();
94 void SetFieldId(CContactItemField& aField);
95 const CContactItemField* FindById(TInt aId) const;
96 IMPORT_C TStreamId StoreL(CStreamStore& aStore,const CContactItem* aTemplate,RWriteStream& aStream,CStreamStore& aBlobStore,CContactTables* aTables);
97 void RestoreL(CStreamStore& aStore, TStreamId anId, CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate,RReadStream& aReadStream,CContactTables* aContactsTable, RArray<TInt>* aEmailIdArray);
98 void RestoreAndAddTemplateL(CStreamStore& aStore, TStreamId aId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate, RReadStream& aReadStream,CContactTables* aContactsTable,RArray<TInt>* aEmailIdArray);
99 TInt MatchTemplateField(const CContentType& aContentType,TUint aUserFlags,TBool &aExactMatch) const;
100 static HBufC* LoadTextStreamLC(RReadStream& aStream);
101 void NonZeroFieldText(TFieldType aFieldType, TDes &aText) const;
104 CArrayPtr<CContactItemField>* iFields;
107 class CContactDatabase;
109 class CContactItem : public CBase
110 /** The abstract base class for contact cards, templates and groups. All contact
111 items are identified by a contact ID, (TContactItemId), have a last modified
112 date/time and own one or more fields (the field set). Contact items also
113 have an access count and attributes (e.g. hidden). Note that fields in a contact
114 item also have attributes. Attribute values specified in the contact item
115 override those in the contained fields. The access count is a record of the
116 number of objects referencing a contact item. A contact item cannot be fully
117 deleted until its access count is zero.
122 friend class CContactCardTemplate;
123 friend class CContactItemPlusGroup;
124 friend class CContactCard;
125 friend class CContactTemplate;
126 friend class CContactGroup;
127 friend class CContactOwnCard;
128 friend class CVCardToContactsAppConverter;
129 friend class CContactICCEntry;
130 friend class RPplContactTable;
131 friend class RPplIdentityTable;
132 friend class RPplPreferencesTable;
133 friend class CPackagerTests; //Comparison test
134 friend class CPackagerCntComparator;
135 friend class CContactDatabase;
136 friend class CPplContactItemManager;
138 IMPORT_C ~CContactItem();
139 /** Gets the contact item's type.
141 @return The contact item's type. */
142 virtual TUid Type() const=0;
143 static CContactItem* NewLC(RReadStream& aStream);
144 IMPORT_C static CContactItem* NewLC(TUid aType);
145 IMPORT_C TContactItemId Id() const;
146 IMPORT_C TContactItemId TemplateRefId() const;
147 IMPORT_C TTime LastModified() const;
148 IMPORT_C void SetLastModified(const TTime& aLastModified);
149 IMPORT_C void AddFieldL(CContactItemField& aField);
150 IMPORT_C void RemoveField(TInt aFieldPos);
151 IMPORT_C void InsertFieldL(CContactItemField& aField,TInt aFieldPos);
152 IMPORT_C CContactItemFieldSet& CardFields() const;
153 IMPORT_C void SetHidden(TBool aHidden);
154 IMPORT_C void SetSystem(TBool aSystem);
155 IMPORT_C TBool IsHidden();
156 IMPORT_C TBool IsSystem();
157 IMPORT_C void UpdateFieldSet(CContactItemFieldSet* aNewFieldSet);
158 IMPORT_C void SetDeleted(TBool aDeleted);
159 IMPORT_C TBool IsDeleted() const;
160 IMPORT_C void SetTemplateRefId(TContactItemId aUid);
161 TContactItemId Agent();
162 inline TBool IsDeletable();
163 inline void IncAccessCount();
164 inline void DecAccessCount();
165 inline TInt AccessCount() const;
166 IMPORT_C void SetUidStringL(TDesC& aString);
167 IMPORT_C TPtrC UidStringL(TInt64 aMachineUniqueId) const;
168 TStreamId PopulateStoreL(CStreamStore& aStore, CArrayFix<TFieldHeader>& aFieldHeaderArray) const;
169 void AddLabelFieldL();
170 IMPORT_C void RestoreTemplateFieldsL(const CContactItemFieldSet& aSystemTemplateFields, const CContactItemFieldSet& aTemplateFields, const CContactItemViewDef& aViewDef);
171 void ClearFieldContent();
173 virtual void ExternalizeL(RWriteStream& aStream) const;
174 virtual void InternalizeL(RReadStream& aStream);
176 #ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
177 IMPORT_C void SetId(TContactItemId aId);
178 IMPORT_C TUint32 Attributes() const;
179 IMPORT_C void SetAttributes(TUint32 aAttributes);
180 IMPORT_C void SetAccessCount(TUint32 aAccessCount);
181 IMPORT_C void SetCreationDate(const TTime& aTime);
185 /** Contact item's attribute flags
187 These flags can be used to set the various attributes of a contact item. */
190 /** To set the contact item's system attribute. */
192 /** To set the contact item's hidden attribute. */
194 /** To set the contact item's hidden attribute. */
195 ECompressedGuid=0x04,
196 /** To set the contact item's Is deleted attribute. */
203 void ConstructL(const CContactItem *aTemplate);
204 void MakeUidStringL(TInt64 aMachineUniqueId);
205 IMPORT_C void SetHasCompressedGuid(TBool aCompressed);
206 TBool GuidIsCompressed() const;
207 TInt NumberOfFieldsToStore() const;
210 CContactItemFieldSet* iFieldSet;
213 TContactItemId iTemplateRefId;
216 TUint32 iAccessCount;
218 friend class CContactDatabase;
221 class CContactItemPlusGroup : public CContactItem
222 /** Abstract base class for CContactGroup, CContactCard and CContactOwnCard.
224 The purpose of this class is to avoid duplication of group functionality
225 in its derived classes.
231 IMPORT_C const CContactIdArray* GroupsJoined() const;
232 IMPORT_C CContactIdArray* GroupsJoinedLC() const;
234 CContactItemPlusGroup();
235 IMPORT_C ~CContactItemPlusGroup();
237 virtual void ExternalizeL(RWriteStream& aStream) const;
238 virtual void InternalizeL(RReadStream& aStream);
240 #ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
241 IMPORT_C void ResetGroups();
242 IMPORT_C void SetGroups(CContactIdArray* aGroups);
246 CContactIdArray* iGroups;
247 friend class CContactDatabase;
248 friend class RPplLookupGroupsTable;
249 friend class RPplGroupMembershipTable;
252 class CContactGroup : public CContactItemPlusGroup
255 A contact group is a contact item which holds a set of associated contact
256 item IDs. The members of the group may be contact cards, own cards, or even
257 other groups. The group has a label which identifies the group to users, e.g.
258 "family", or "colleagues". The type of a contact group is KUidContactGroup,
259 as returned by Type().
261 Objects of this class are constructed using CContactDatabase::CreateContactGroupL()
262 or CreateContactGroupLC(). These functions create the group, optionally with
263 a label, add it to the database, and return a pointer to it.
265 To create an association between a card and a group, use CContactDatabase::AddContactToGroupL()
266 and to remove the association, use RemoveContactFromGroupL(). To find out
267 which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().
269 The function CContactDatabase::GetGroupIdListL() may be used to retrieve a
270 list of IDs for all groups in the database.
276 IMPORT_C static CContactGroup* NewL();
277 IMPORT_C static CContactGroup* NewLC();
278 IMPORT_C ~CContactGroup();
279 public: // from CContactItem
280 IMPORT_C TUid Type() const;
282 // default sorted item array is ascending
283 IMPORT_C CContactIdArray* ItemsContainedLC() const;
284 IMPORT_C const CContactIdArray* ItemsContained() const;
285 IMPORT_C TBool IsSystem() const;
286 IMPORT_C void SetSystem(TBool aSystem);
287 IMPORT_C TBool ContainsItem(TContactItemId aContactId);
288 IMPORT_C void SetGroupLabelL(const TDesC& aLabel);
289 IMPORT_C TPtrC GetGroupLabelL();
290 IMPORT_C TBool HasItemLabelField();
291 IMPORT_C CContactIdArray* GroupsJoinedLC() const;
293 //IMPORT_C void ReservedFunction1();
294 IMPORT_C void AddContactL(TContactItemId aContactId);
295 //IMPORT_C void ReservedFunction2();
296 IMPORT_C void RemoveContactL(TContactItemId aContactId);
297 virtual void ExternalizeL(RWriteStream& aStream) const;
298 virtual void InternalizeL(RReadStream& aStream);
300 #ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
301 IMPORT_C void ResetItems();
302 IMPORT_C void SetItems(CContactIdArray* aItems);
308 CContactIdArray* iItems;
309 friend class CContactDatabase;
310 friend class RPplGroupMembershipTable;
313 class CContactCardTemplate : public CContactItem
314 /** A contact card template.
316 This is a contact item containing a set of fields on which new contact items can
317 be based. Templates have a label which is a string which identifies the template
318 to a user. For instance, 'work template' could indicate a template used
319 to create contact cards in the style of a work colleague. Contact card templates
320 have a type of KUidContactCardTemplate, as returned by Type().
322 Objects of this class cannot be constructed directly because its constructors
323 are protected. Instead, use either CContactDatabase::CreateContactCardTemplateL()
324 or CreateContactCardTemplateLC(). These functions create a contact card template,
325 add it to the database, and return a pointer to it.
327 The function CContactDatabase::GetCardTemplateIdListL() gets a list of the
328 IDs of all contact card templates in the database.
333 friend class CContactDatabase;
334 friend class CContactTables;
335 friend class RPplContactTable;
336 friend class CContactItem;
338 IMPORT_C void SetTemplateLabelL(const TDesC& aLabel);
339 IMPORT_C TPtrC GetTemplateLabelL();
341 IMPORT_C static CContactCardTemplate* NewL();
342 IMPORT_C static CContactCardTemplate* NewLC();
343 IMPORT_C static CContactCardTemplate* NewL(const CContactItem *aTemplate);
344 IMPORT_C static CContactCardTemplate* NewLC(const CContactItem *aTemplate);
345 IMPORT_C TBool HasItemLabelField();
348 Intended usage: Reserved to preserve future BC */
349 IMPORT_C void ReservedFunction1();
351 Intended usage: Reserved to preserve future BC */
352 IMPORT_C void ReservedFunction2();
354 protected: // from CContactItem
355 IMPORT_C TUid Type() const;
357 CContactCardTemplate();
360 class CContactCard : public CContactItemPlusGroup
363 Implements the Type() function declared in class CContactItem.
364 Contact cards may optionally be constructed from a template.
370 IMPORT_C ~CContactCard();
371 IMPORT_C static CContactCard* NewL();
372 IMPORT_C static CContactCard* NewLC();
373 IMPORT_C static CContactCard* NewL(const CContactItem *aTemplate);
374 IMPORT_C static CContactCard* NewLC(const CContactItem *aTemplate);
375 public: // from CContactItem
376 IMPORT_C TUid Type() const;
378 IMPORT_C CContactIdArray* GroupsJoinedLC() const;
382 friend class CContactDatabase;
385 class CContactOwnCard : public CContactItemPlusGroup
388 An own card is a contact card which contains information about the device's
389 owner. This can be sent to another compatible electronic device as a vCard.
390 The contact database recognises a single own card, referred to as the
391 current own card; its ID is returned by CContactDatabase::OwnCardId(). Like
392 a contact card, an own card can be a member of one or more contact card groups.
393 The own card type is identified by a UID of KUidContactOwnCard.
395 Own cards can be constructed using either CContactDatabase::CreateOwnCardLC()
396 or CreateOwnCardL(). These functions create an own card, based on the system
397 template, add it to the database, set it as the database's current own card
398 and return a pointer to it. To change the database's current own card, use
399 CContactDatabase::SetOwnCardL().
405 IMPORT_C ~CContactOwnCard();
406 IMPORT_C static CContactOwnCard* NewL();
407 IMPORT_C static CContactOwnCard* NewLC();
408 IMPORT_C static CContactOwnCard* NewL(const CContactItem *aTemplate);
409 IMPORT_C static CContactOwnCard* NewLC(const CContactItem *aTemplate);
410 public: // from CContactItem
411 IMPORT_C TUid Type() const;
413 IMPORT_C CContactIdArray* GroupsJoinedLC() const;
417 friend class CContactDatabase;
420 class CContactTemplate : public CContactItem
421 /** A contact item template.
423 This is a contact item which is used to seed the initial field set for
426 Non-system (i.e. user-defined) templates are implemented
427 by the CContactCardTemplate class. CContactCardTemplate should be
428 used in preference to CContactTemplate.
434 IMPORT_C static CContactTemplate* NewL();
435 IMPORT_C static CContactTemplate* NewLC();
436 IMPORT_C static CContactTemplate* NewL(const CContactItem *aTemplate);
437 IMPORT_C static CContactTemplate* NewLC(const CContactItem *aTemplate);
438 public: // from CContactItem
439 IMPORT_C TUid Type() const;
445 class CContactICCEntry : public CContactItemPlusGroup
446 /** A contact ICC entry.
452 IMPORT_C ~CContactICCEntry();
453 IMPORT_C static CContactICCEntry* NewL(const CContactItem& aTemplate);
454 static CContactICCEntry* NewL();
455 public: //from CContactItem
463 /** A globally unique identifier enquiry utility.
465 Each contact item has a unique identifier, stored as a descriptor. It is
466 referred to as the 'UID string'. This is a combination of the unique
467 identifier of the database in which the contact item was created, the
468 contact item ID and the date/time of the contact item's creation. ContactGuid
469 provides a single static exported function to enquire whether an item was
470 created in a specified database.
476 IMPORT_C static TContactItemId IsLocalContactUidString(const TDesC& aString, TInt64 aMachineUniqueId);
477 IMPORT_C static TBool GetCreationDate(TDes& aString, TInt64 aMachineUniqueId);
478 static HBufC* CreateGuidLC(const TDesC& aCreationDate,TContactItemId aId, TInt64 aMachineUniqueId);
479 static HBufC* CreateGuidLC(const TTime& aCreationDate,TContactItemId aId, TInt64 aMachineUniqueId);
480 static HBufC* CreateGuidLC(TContactItemId aId, TInt64 aMachineUniqueId);
483 inline const CContactItemField& CContactItemFieldSet::operator[](TInt aIndex) const
484 /** Gets the field located at a specified position in the field set.
486 @param aIndex The position of the field in the field set. This is relative to zero.
487 It must be non-negative and less than the number of objects in the array, otherwise
488 the operator raises a panic.
490 @return A const reference to an element in the array. */
491 { return *(*iFields)[aIndex]; }
493 inline CContactItemField& CContactItemFieldSet::operator[](TInt aIndex)
494 /** Gets the field located at a specified position in the field set.
496 @param aIndex The position of the field in the field set. This is relative to zero.
497 It must be non-negative and less than the number of objects in the array, otherwise
498 the operator raises a panic.
500 @return A non-const reference to an element in the array. */
501 { return *(*iFields)[aIndex]; }
503 inline TInt CContactItemFieldSet::Find(TFieldType aFieldType) const
504 /** Finds the first field in the field set with the specified field type.
506 @param aFieldType The field type of interest.
507 @return If found, the index of the field within the field set, or KErrNotFound
509 { return FindNext(aFieldType,KContactFieldSetSearchAll); }
511 inline TInt CContactItemFieldSet::Find(TFieldType aFieldType,TUid aMapping) const
512 /** Finds the first field in the field set containing both the content type mapping
513 and the field type specified.
515 @param aFieldType The field type of interest.
516 @param aMapping The content type mapping of interest.
517 @return If found, the index of the field within the field set, or KErrNotFound
519 { return FindNext(aFieldType,aMapping,KContactFieldSetSearchAll); }
521 inline TInt CContactItemFieldSet::Count() const
522 /** Gets the number of fields in the field set.
524 @return The number of fields in the field set. */
525 { return iFields->Count(); }
527 inline void CContactItemFieldSet::Reset()
528 /** Deletes all fields in the field set. */
529 { iFields->ResetAndDestroy(); }
531 inline TBool CContactItem::IsDeletable()
532 /** Tests whether the contact item is deletable.
534 This is true if the item's access count is zero.
536 @return ETrue if deletable, EFalse if not deletable. */
537 {return (iAccessCount == 0);}
539 inline void CContactItem::IncAccessCount()
540 /** Increments the contact item's access count. */
543 inline void CContactItem::DecAccessCount()
544 /** Decrements the contact item's access count. */
545 {if(iAccessCount) iAccessCount--;}
547 inline TInt CContactItem::AccessCount() const
548 /** Gets the contact item's access count.
550 @return The item's access count. */
551 {return(iAccessCount);}
553 inline TPtrC CContactItem::Guid()
554 /** Accessor function for Contact Guid.
555 * This is used to cache contact items that are added during a sync.
557 { return iGuid ? *iGuid : TPtrC(KNullDesC); }