// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

 // All rights reserved.

 // This component and the accompanying materials are made available

 // under the terms of "Eclipse Public License v1.0"

 // which accompanies this distribution, and is available

 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

 //

 // Initial Contributors:

 // Nokia Corporation - initial contribution.

 //

 // Contributors:

 //

 // Description:

 // Persistence layer exports

 // 

 //

 #if !defined(__CNTITEM_H__)

 #define __CNTITEM_H__

 #if !defined(__E32BASE_H__)

 #include <e32base.h>

 #endif

 #if !defined(__CNTDEF_H__)

 #include <cntdef.h>

 #endif

 #if !defined(__CNTFIELD_H__)

 #include <cntfield.h>

 #endif

 #include <cntdb.h>

 /** Maximum length of UID string.

 @publishedAll

 @released

 */

 const TInt KUidStringLength =244;

 /** UID string separator character

 @publishedAll

 @released

 */

 #define KUidStringSeparator '-'

 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

 /** Constant used by vCard import/export.

 @internalComponent

 */

 #define KContactMaxFieldNumber 32

 #endif

 class CContactItemField;

 class CContactItemViewDef;

 class CContactItem;

 /** Constant to indicate that all fields in the fieldset should be searched.

 @publishedAll

 @released

 */

 const TInt KContactFieldSetSearchAll=-1;

 class CContactItemFieldSet : public CBase

 /** A contact item's field set. The field set owns an array of contact item fields

 (CContactItemFields). The field set is owned by a contact item, and can be

 retrieved using CContactItem::CardFields(). Use functions in class

 CContactItem to add and remove fields to/from the field set.

 A field set can contain more than one field of the same type, but this is

 not advisable as it may cause problems when synchronising the contacts database.

 @publishedAll

 @released

 */

 	{

 	friend class CContactItemField;

 	friend class CContactDatabase;

 	friend class CContactTables;

 	friend class RPplContactTable;

     friend class TCntPersistenceUtility;

 public:

 	IMPORT_C static CContactItemFieldSet* NewL();

 	IMPORT_C static CContactItemFieldSet* NewLC();

 	IMPORT_C ~CContactItemFieldSet();

 	inline const CContactItemField& operator[](TInt aIndex) const;

 	inline CContactItemField& operator[](TInt aIndex);

 	inline TInt Find(TFieldType aFieldType) const; // will only find the first such occurence

 	inline TInt Find(TFieldType aFieldType,TUid aMapping) const;

 	IMPORT_C TInt FindNext(TFieldType aFieldType,TInt aStartPos=KContactFieldSetSearchAll) const;

 	IMPORT_C TInt FindNext(TFieldType aFieldType,TUid aMapping,TInt aStartPos=KContactFieldSetSearchAll) const;

 	inline TInt Count() const;

 	inline void Reset();

 	IMPORT_C void UpdateFieldL(const CContactItemField& aField, TInt aMatchCount);

 	IMPORT_C void UpdateFieldSyncL(const CContactItemField& aField, TInt aMatchCount);

 	IMPORT_C CContactItemFieldSet& AddL(CContactItemField& aField);

 	IMPORT_C void Remove(TInt aIndex);

 	IMPORT_C void InsertL(TInt aIndex,CContactItemField& aField);

 	IMPORT_C void Move(TInt aFrom, TInt aTo);

 	IMPORT_C TStreamId StoreL(CStreamStore& aStore,RWriteStream& aTextStream,CStreamStore& aBlobStore);

 	TStreamId StoreL(CStreamStore& aStore,RWriteStream& aTextStream,CStreamStore& aBlobStore,CContactTables* aTables);

 	IMPORT_C void RestoreL(CStreamStore& aStore, TStreamId anId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,RReadStream& aReadStream);

 	IMPORT_C void RestoreL(CStreamStore& aStore, TStreamId anId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate, HBufC* aTextBuf);

 	TInt FieldText(TFieldType aFieldType, TDes &aText, TInt aStartPosition) const;

 	CArrayFix<TFieldHeader>* ConstructFieldHeaderArrayLC(RWriteStream& aTextStream, CStreamStore& aBlobStore);

 	TInt FieldTypeCount(const CContactItemFieldSet& aSystemTemplateFields, TInt aStartIndex, const CContactItemField& aField) const;

 	TBool ContainsFieldTypeMapping(const CContentType& aBaseFieldContentType, const TFieldType& aContactFieldType) const;

 	void ExternalizeL(RWriteStream& aStream) const;

 	void InternalizeL(RReadStream& aStream);

 private:

 	CContactItemFieldSet();

 	void ConstructL();

 	void SetFieldId(CContactItemField& aField);

 	const CContactItemField* FindById(TInt aId) const;

 	IMPORT_C TStreamId StoreL(CStreamStore& aStore,const CContactItem* aTemplate,RWriteStream& aStream,CStreamStore& aBlobStore,CContactTables* aTables);

 	void RestoreL(CStreamStore& aStore, TStreamId anId, CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate,RReadStream& aReadStream,CContactTables* aContactsTable, RArray<TInt>* aEmailIdArray);

 	void RestoreAndAddTemplateL(CStreamStore& aStore, TStreamId aId,CStreamStore* aBlobStore,const CContactItemViewDef& aViewDef,const CContactItem* aTemplate, RReadStream& aReadStream,CContactTables* aContactsTable,RArray<TInt>* aEmailIdArray);

 	TInt MatchTemplateField(const CContentType& aContentType,TUint aUserFlags,TBool &aExactMatch) const;

 	static HBufC* LoadTextStreamLC(RReadStream& aStream);

 	void NonZeroFieldText(TFieldType aFieldType, TDes &aText) const;

 private:

 	CArrayPtr<CContactItemField>* iFields;

 	};

 class CContactDatabase;

 class RCntModel;

 class CContactItem : public CBase

 /** The abstract base class for contact cards, templates and groups. All contact

 items are identified by a contact ID, (TContactItemId), have a last modified

 date/time and own one or more fields (the field set). Contact items also

 have an access count and attributes (e.g. hidden). Note that fields in a contact

 item also have attributes. Attribute values specified in the contact item

 override those in the contained fields. The access count is a record of the

 number of objects referencing a contact item. A contact item cannot be fully

 deleted until its access count is zero.

 @publishedAll

 @released

 */

 	{

 	friend class CContactCardTemplate;

 	friend class CContactItemPlusGroup;

 	friend class CContactCard;

 	friend class CContactTemplate;

 	friend class CContactGroup;

 	friend class CContactOwnCard;

 	friend class CVCardToContactsAppConverter;

 	friend class CContactICCEntry;

 	friend class RPplContactTable;

 	friend class RPplIdentityTable;

 	friend class RPplPreferencesTable;

 	friend class CPackagerTests; //Comparison test

 	friend class CPackagerCntComparator;

 	friend class CContactDatabase;

 	friend class CPplContactItemManager;

 public:

 	IMPORT_C ~CContactItem();

 	/** Gets the contact item's type.

 	@return The contact item's type. */

 	virtual TUid Type() const=0;

 	static CContactItem* NewLC(RReadStream& aStream);

 	IMPORT_C static CContactItem* NewLC(TUid aType);

 	IMPORT_C TContactItemId Id() const;

 	IMPORT_C TContactItemId TemplateRefId() const;

 	IMPORT_C TTime LastModified() const;

 	IMPORT_C void SetLastModified(const TTime& aLastModified);

 	IMPORT_C void AddFieldL(CContactItemField& aField);

 	IMPORT_C void RemoveField(TInt aFieldPos);

 	IMPORT_C void InsertFieldL(CContactItemField& aField,TInt aFieldPos);

 	IMPORT_C CContactItemFieldSet& CardFields() const;

 	IMPORT_C void SetHidden(TBool aHidden);

 	IMPORT_C void SetSystem(TBool aSystem);

 	IMPORT_C TBool IsHidden();

 	IMPORT_C TBool IsSystem();

 	IMPORT_C void UpdateFieldSet(CContactItemFieldSet* aNewFieldSet);

 	IMPORT_C void SetDeleted(TBool aDeleted);

 	IMPORT_C TBool IsDeleted() const;

 	IMPORT_C void SetTemplateRefId(TContactItemId aUid);

 	TContactItemId Agent();

 	inline TBool IsDeletable();

 	inline void IncAccessCount();

 	inline void DecAccessCount();

 	inline TInt AccessCount() const;

 	IMPORT_C void SetUidStringL(TDesC& aString);

 	IMPORT_C TPtrC UidStringL(TInt64 aMachineUniqueId) const;

 	TStreamId PopulateStoreL(CStreamStore& aStore, CArrayFix<TFieldHeader>& aFieldHeaderArray) const;

 	void AddLabelFieldL();

 	IMPORT_C void RestoreTemplateFieldsL(const CContactItemFieldSet& aSystemTemplateFields, const CContactItemFieldSet& aTemplateFields, const CContactItemViewDef& aViewDef);

 	void ClearFieldContent();

 	inline TPtrC Guid();

 	virtual void ExternalizeL(RWriteStream& aStream) const;

 	virtual void InternalizeL(RReadStream& aStream);

 	IMPORT_C void SetId(TContactItemId aId);

 	IMPORT_C TUint32 Attributes() const;

 	IMPORT_C void SetAttributes(TUint32 aAttributes);

 	IMPORT_C void SetAccessCount(TUint32 aAccessCount);

 	IMPORT_C void SetCreationDate(const TTime& aTime);

 public:

 	/** Contact item's attribute flags

 	These flags can be used to set the various attributes of a contact item. */

 	enum

 	{

 	/** To set the contact item's system attribute. */

 	ESystem=0x01,

 	/** To set the contact item's hidden attribute. */

 	EHidden=0x02,

 	/** To set the contact item's hidden attribute. */

 	ECompressedGuid=0x04,

 	/** To set the contact item's Is deleted attribute. */

 	EDeleted=0x08

 	};

 private:

 	CContactItem();

 	void ConstructL();

 	void ConstructL(const CContactItem *aTemplate);

 	void MakeUidStringL(TInt64 aMachineUniqueId);

 	IMPORT_C void SetHasCompressedGuid(TBool aCompressed);

 	TBool GuidIsCompressed() const;

 	TInt NumberOfFieldsToStore() const;

 private:

 	CContactItemFieldSet* iFieldSet;

 	TUint32 iAttributes;

 	TContactItemId iId;

 	TContactItemId iTemplateRefId;

 	TTime iLastModified;

 	TTime iCreationDate;

 	TUint32 iAccessCount;

 	HBufC* iGuid;

 	};

 class CContactItemPlusGroup : public CContactItem

 /** Abstract base class for CContactGroup, CContactCard and CContactOwnCard.

 The purpose of this class is to avoid duplication of group functionality

 in its derived classes.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C const CContactIdArray* GroupsJoined() const;

 	IMPORT_C CContactIdArray* GroupsJoinedLC() const;

 protected:

 	CContactItemPlusGroup();

 	IMPORT_C ~CContactItemPlusGroup();

 public:

 	virtual void ExternalizeL(RWriteStream& aStream) const;

 	virtual void InternalizeL(RReadStream& aStream);

 	IMPORT_C void ResetGroups();

 	IMPORT_C void SetGroups(CContactIdArray* aGroups);

 private:

 	CContactIdArray* iGroups;

 	friend class CContactDatabase;

 	friend class RPplLookupGroupsTable;

 	friend class RPplGroupMembershipTable;

 	};

 class CContactGroup : public CContactItemPlusGroup

 /** A contact group.

 A contact group is a contact item which holds a set of associated contact

 item IDs. The members of the group may be contact cards, own cards, or even

 other groups. The group has a label which identifies the group to users, e.g.

 "family", or "colleagues". The type of a contact group is KUidContactGroup,

 as returned by Type().

 Objects of this class are constructed using CContactDatabase::CreateContactGroupL()

 or CreateContactGroupLC(). These functions create the group, optionally with

 a label, add it to the database, and return a pointer to it.

 To create an association between a card and a group, use CContactDatabase::AddContactToGroupL()

 and to remove the association, use RemoveContactFromGroupL(). To find out

 which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().

 The function CContactDatabase::GetGroupIdListL() may be used to retrieve a

 list of IDs for all groups in the database.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C static CContactGroup* NewL();

 	IMPORT_C static CContactGroup* NewLC();

 	IMPORT_C ~CContactGroup();

 public: // from CContactItem

 	IMPORT_C TUid Type() const;

 public:

 	// default sorted item array is ascending

 	IMPORT_C CContactIdArray* ItemsContainedLC() const;

 	IMPORT_C const CContactIdArray* ItemsContained() const;

 	IMPORT_C TBool IsSystem() const;

 	IMPORT_C void SetSystem(TBool aSystem);

 	IMPORT_C TBool ContainsItem(TContactItemId aContactId);

 	IMPORT_C void SetGroupLabelL(const TDesC& aLabel);

 	IMPORT_C TPtrC GetGroupLabelL();

 	IMPORT_C TBool HasItemLabelField();

 	IMPORT_C CContactIdArray* GroupsJoinedLC() const;

 	IMPORT_C void AddContactL(TContactItemId aContactId);

 	IMPORT_C void RemoveContactL(TContactItemId aContactId);

 	virtual void ExternalizeL(RWriteStream& aStream) const;

 	virtual void InternalizeL(RReadStream& aStream);

 	IMPORT_C void ResetItems();

 	IMPORT_C void SetItems(CContactIdArray* aItems);

 private:

 	CContactGroup();

 private:

 	CContactIdArray* iItems;

 	friend class CContactDatabase;

 	friend class RPplGroupMembershipTable;

 	};

 class CContactCardTemplate : public CContactItem

 /** A contact card template.

 This is a contact item containing a set of fields on which new contact items can

 be based. Templates have a label which is a string which identifies the template

 to a user. For instance, 'work template' could indicate a template used

 to create contact cards in the style of a work colleague. Contact card templates

 have a type of KUidContactCardTemplate, as returned by Type().

 Objects of this class cannot be constructed directly because its constructors

 are protected. Instead, use either CContactDatabase::CreateContactCardTemplateL()

 or CreateContactCardTemplateLC(). These functions create a contact card template,

 add it to the database, and return a pointer to it.

 The function CContactDatabase::GetCardTemplateIdListL() gets a list of the

 IDs of all contact card templates in the database.

 @publishedAll

 @released

 */

 	{

 	friend class CContactDatabase;

 	friend class CContactTables;

 	friend class RPplContactTable;

 	friend class CContactItem;

 public:

 	IMPORT_C void SetTemplateLabelL(const TDesC& aLabel);

 	IMPORT_C TPtrC GetTemplateLabelL();

 protected:

 	IMPORT_C static CContactCardTemplate* NewL();

 	IMPORT_C static CContactCardTemplate* NewLC();

 	IMPORT_C static CContactCardTemplate* NewL(const CContactItem *aTemplate);

 	IMPORT_C static CContactCardTemplate* NewLC(const CContactItem *aTemplate);

 	IMPORT_C TBool HasItemLabelField();

 /** Intended usage: Reserved to preserve future BC */

 	IMPORT_C void ReservedFunction1();

 /** Intended usage: Reserved to preserve future BC */

 	IMPORT_C void ReservedFunction2();

 protected: // from CContactItem

 	IMPORT_C TUid Type() const;

 private:

 	CContactCardTemplate();

 	};

 class CContactCard : public CContactItemPlusGroup

 /** A contact card.

 Implements the Type() function declared in class CContactItem.

 Contact cards may optionally be constructed from a template.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C ~CContactCard();

 	IMPORT_C static CContactCard* NewL();

 	IMPORT_C static CContactCard* NewLC();

 	IMPORT_C static CContactCard* NewL(const CContactItem *aTemplate);

 	IMPORT_C static CContactCard* NewLC(const CContactItem *aTemplate);

 public: // from CContactItem

 	IMPORT_C TUid Type() const;

 public:

 	IMPORT_C CContactIdArray* GroupsJoinedLC() const;

 private:

 	CContactCard();

 private:

 	friend class CContactDatabase;

 	};

 class CContactOwnCard : public CContactItemPlusGroup

 /** Own card.

 An own card is a contact card which contains information about the device's

 owner. This can be sent to another compatible electronic device as a vCard.

 The contact database recognises a single own card, referred to as the

 current own card; its ID is returned by CContactDatabase::OwnCardId(). Like

 a contact card, an own card can be a member of one or more contact card groups.

 The own card type is identified by a UID of KUidContactOwnCard.

 Own cards can be constructed using either CContactDatabase::CreateOwnCardLC()

 or CreateOwnCardL(). These functions create an own card, based on the system

 template, add it to the database, set it as the database's current own card

 and return a pointer to it. To change the database's current own card, use

 CContactDatabase::SetOwnCardL().

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C ~CContactOwnCard();

 	IMPORT_C static CContactOwnCard* NewL();

 	IMPORT_C static CContactOwnCard* NewLC();

 	IMPORT_C static CContactOwnCard* NewL(const CContactItem *aTemplate);

 	IMPORT_C static CContactOwnCard* NewLC(const CContactItem *aTemplate);

 public: // from CContactItem

 	IMPORT_C TUid Type() const;

 public:

 	IMPORT_C CContactIdArray* GroupsJoinedLC() const;

 private:

 	CContactOwnCard();

 private:

 	friend class CContactDatabase;

 	};

 class CContactTemplate : public CContactItem

 /** A contact item template.

 This is a contact item which is used to seed the initial field set for

 other contact items.

 Non-system (i.e. user-defined) templates are implemented

 by the CContactCardTemplate class. CContactCardTemplate should be

 used in preference to CContactTemplate.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C static CContactTemplate* NewL();

 	IMPORT_C static CContactTemplate* NewLC();

 	IMPORT_C static CContactTemplate* NewL(const CContactItem *aTemplate);

 	IMPORT_C static CContactTemplate* NewLC(const CContactItem *aTemplate);

 public: // from CContactItem

 	IMPORT_C TUid Type() const;

 private:

 	CContactTemplate();

 	};

 class CContactICCEntry : public CContactItemPlusGroup

 /** A contact ICC entry.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C ~CContactICCEntry();

 	IMPORT_C static CContactICCEntry* NewL(const CContactItem& aTemplate);

 	static CContactICCEntry* NewL();

 public: //from CContactItem

 	TUid Type() const;

 private:

 	CContactICCEntry();

 	};

 class ContactGuid

 /** A globally unique identifier enquiry utility.

 Each contact item has a unique identifier, stored as a descriptor. It is

 referred to as the 'UID string'. This is a combination of the unique

 identifier of the database in which the contact item was created, the

 contact item ID and the date/time of the contact item's creation. ContactGuid

 provides a single static exported function to enquire whether an item was

 created in a specified database.

 @publishedAll

 @released

 */

 	{

 public:

 	IMPORT_C static TContactItemId IsLocalContactUidString(const TDesC& aString, TInt64 aMachineUniqueId);

 	IMPORT_C static TBool GetCreationDate(TDes& aString, TInt64 aMachineUniqueId);

 	static HBufC* CreateGuidLC(const TDesC& aCreationDate,TContactItemId aId, TInt64 aMachineUniqueId);

 	static HBufC* CreateGuidLC(const TTime& aCreationDate,TContactItemId aId, TInt64 aMachineUniqueId);

 	static HBufC* CreateGuidLC(TContactItemId aId, TInt64 aMachineUniqueId);

 	};

 inline const CContactItemField& CContactItemFieldSet::operator[](TInt aIndex) const

 /** Gets the field located at a specified position in the field set.

 @param aIndex The position of the field in the field set. This is relative to zero.

 It must be non-negative and less than the number of objects in the array, otherwise

 the operator raises a panic.

 @return A const reference to an element in the array. */

 	{ return *(*iFields)[aIndex]; }

 inline CContactItemField& CContactItemFieldSet::operator[](TInt aIndex)

 /** Gets the field located at a specified position in the field set.

 @param aIndex The position of the field in the field set. This is relative to zero.

 It must be non-negative and less than the number of objects in the array, otherwise

 the operator raises a panic.

 @return A non-const reference to an element in the array. */

 	{ return *(*iFields)[aIndex]; }

 inline TInt CContactItemFieldSet::Find(TFieldType aFieldType) const

 /** Finds the first field in the field set with the specified field type.

 @param aFieldType The field type of interest.

 @return If found, the index of the field within the field set, or KErrNotFound

 if not found. */

 	{ return FindNext(aFieldType,KContactFieldSetSearchAll); }

 inline TInt CContactItemFieldSet::Find(TFieldType aFieldType,TUid aMapping) const

 /** Finds the first field in the field set containing both the content type mapping

 and the field type specified.

 @param aFieldType The field type of interest.

 @param aMapping The content type mapping of interest.

 @return If found, the index of the field within the field set, or KErrNotFound

 if not found. */

 	{ return FindNext(aFieldType,aMapping,KContactFieldSetSearchAll); }

 inline TInt CContactItemFieldSet::Count() const

 /** Gets the number of fields in the field set.

 @return The number of fields in the field set. */

 	{ return iFields->Count(); }

 inline void CContactItemFieldSet::Reset()

 /** Deletes all fields in the field set. */

 	{ iFields->ResetAndDestroy(); }

 inline TBool CContactItem::IsDeletable()

 /** Tests whether the contact item is deletable.

 This is true if the item's access count is zero.

 @return ETrue if deletable, EFalse if not deletable. */

 	{return (iAccessCount == 0);}

 inline void CContactItem::IncAccessCount()

 /** Increments the contact item's access count. */

 	{iAccessCount++;}

 inline void CContactItem::DecAccessCount()

 /** Decrements the contact item's access count. */

 	{if(iAccessCount) iAccessCount--;}

 inline TInt CContactItem::AccessCount() const

 /** Gets the contact item's access count.

 @return The item's access count. */

 	{return(iAccessCount);}

 inline TPtrC CContactItem::Guid()

 /** Accessor function for Contact Guid.

  * This is used to cache contact items that are added during a sync.

  @return Guid    */

  { return iGuid ? *iGuid : TPtrC(KNullDesC); }

 #endif