Mercurial Mercurial > oss > API_REF > Public_API / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
epoc32/include/app/cntitem.h
branchSymbian3
changeset 4 837f303aceeb
parent 3 e1b950c65cb4 
--- a/epoc32/include/app/cntitem.h	Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/app/cntitem.h	Wed Mar 31 12:33:34 2010 +0100
@@ -1,9 +1,9 @@
 // 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+// under the terms of "Eclipse Public License v1.0"
 // which accompanies this distribution, and is available
-// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
 //
 // Initial Contributors:
 // Nokia Corporation - initial contribution.
@@ -32,23 +32,43 @@
 
 #include <cntdb.h>
 
+/** Maximum length of UID string.
+@publishedAll
+@released
+*/
+const TInt KUidStringLength =244;
 
-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;
-#define KContactMaxFieldNumber 32
 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 
+/** 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. 
+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
 */
@@ -57,9 +77,8 @@
 	friend class CContactDatabase;
 	friend class CContactTables;
 	friend class RPplContactTable;
-#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
     friend class TCntPersistenceUtility;
-#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__	
+
 public:
 	IMPORT_C static CContactItemFieldSet* NewL();
 	IMPORT_C static CContactItemFieldSet* NewLC();
@@ -87,7 +106,8 @@
 	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);	
+	void InternalizeL(RReadStream& aStream);
+
 private:
 	CContactItemFieldSet();
 	void ConstructL();
@@ -107,14 +127,14 @@
 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. 
+/** 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
 */
@@ -137,11 +157,11 @@
 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 static CContactItem* NewLC(TUid aType);
 	IMPORT_C TContactItemId Id() const;
 	IMPORT_C TContactItemId TemplateRefId() const;
 	IMPORT_C TTime LastModified() const;
@@ -151,9 +171,9 @@
 	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 void SetSystem(TBool aSystem);
 	IMPORT_C TBool IsHidden();
-	IMPORT_C TBool IsSystem();    	
+	IMPORT_C TBool IsSystem();
 	IMPORT_C void UpdateFieldSet(CContactItemFieldSet* aNewFieldSet);
 	IMPORT_C void SetDeleted(TBool aDeleted);
 	IMPORT_C TBool IsDeleted() const;
@@ -171,32 +191,30 @@
 	void ClearFieldContent();
 	inline TPtrC Guid();
 	virtual void ExternalizeL(RWriteStream& aStream) const;
-	virtual void InternalizeL(RReadStream& aStream);	
+	virtual void InternalizeL(RReadStream& aStream);
 
-#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__		
 	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);
-#endif
 
 public:
-	/** Contact item's attribute flags 
-		
-	These flags can be used to set the various attributes of a contact item. */ 
-	enum 
+	/** 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 
+	/** 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
 	};
-protected:
+
 private:
 	CContactItem();
 	void ConstructL();
@@ -215,14 +233,13 @@
 	TTime iCreationDate;
 	TUint32 iAccessCount;
 	HBufC* iGuid;
-	friend class CContactDatabase;
 	};
 
 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. 
+The purpose of this class is to avoid duplication of group functionality
+in its derived classes.
 @publishedAll
 @released
 */
@@ -235,12 +252,10 @@
 	IMPORT_C ~CContactItemPlusGroup();
 public:
 	virtual void ExternalizeL(RWriteStream& aStream) const;
-	virtual void InternalizeL(RReadStream& aStream);	
+	virtual void InternalizeL(RReadStream& aStream);
 
-#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__	
 	IMPORT_C void ResetGroups();
 	IMPORT_C void SetGroups(CContactIdArray* aGroups);
-#endif
 
 private:
 	CContactIdArray* iGroups;
@@ -252,22 +267,22 @@
 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, 
+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 
+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 
+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. 
+The function CContactDatabase::GetGroupIdListL() may be used to retrieve a
+list of IDs for all groups in the database.
 @publishedAll
 @released
 */
@@ -289,21 +304,18 @@
 	IMPORT_C TPtrC GetGroupLabelL();
 	IMPORT_C TBool HasItemLabelField();
 	IMPORT_C CContactIdArray* GroupsJoinedLC() const;
-// 
-	//IMPORT_C void ReservedFunction1();
+
 	IMPORT_C void AddContactL(TContactItemId aContactId);
-	//IMPORT_C void ReservedFunction2();
 	IMPORT_C void RemoveContactL(TContactItemId aContactId);
 	virtual void ExternalizeL(RWriteStream& aStream) const;
 	virtual void InternalizeL(RReadStream& aStream);
 
-#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__		
 	IMPORT_C void ResetItems();
-	IMPORT_C void SetItems(CContactIdArray* aItems);	
-#endif
+	IMPORT_C void SetItems(CContactIdArray* aItems);
 
 private:
 	CContactGroup();
+
 private:
 	CContactIdArray* iItems;
 	friend class CContactDatabase;
@@ -313,19 +325,19 @@
 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 
+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, 
+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. 
+The function CContactDatabase::GetCardTemplateIdListL() gets a list of the
+IDs of all contact card templates in the database.
 @publishedAll
 @released
 */
@@ -343,25 +355,24 @@
 	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         */
+
+/** Intended usage: Reserved to preserve future BC */
 	IMPORT_C void ReservedFunction1();
-/**          
-    Intended usage: Reserved to preserve future BC         */
+/** 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. 
+/** A contact card.
 
-Implements the Type() function declared in class CContactItem. 
-Contact cards may optionally be constructed from a template. 
+Implements the Type() function declared in class CContactItem.
+Contact cards may optionally be constructed from a template.
 @publishedAll
 @released
 */
@@ -383,20 +394,20 @@
 	};
 
 class CContactOwnCard : public CContactItemPlusGroup
-/** Own card. 
+/** 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. 
+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(). 
+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
 */
@@ -418,14 +429,14 @@
 	};
 
 class CContactTemplate : public CContactItem
-/** A contact item template. 
+/** A contact item template.
 
-This is a contact item which is used to seed the initial field set for 
+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. 
+Non-system (i.e. user-defined) templates are implemented
+by the CContactCardTemplate class. CContactCardTemplate should be
+used in preference to CContactTemplate.
 @publishedAll
 @released
 */
@@ -443,7 +454,7 @@
 
 
 class CContactICCEntry : public CContactItemPlusGroup
-/** A contact ICC entry. 
+/** A contact ICC entry.
 @publishedAll
 @released
 */
@@ -462,12 +473,12 @@
 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. 
+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
 */
@@ -481,20 +492,20 @@
 	};
 
 inline const CContactItemField& CContactItemFieldSet::operator[](TInt aIndex) const
-/** Gets the field located at a specified position in the field set. 
+/** 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 
+@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. 
+/** 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 
+@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. */
@@ -504,17 +515,17 @@
 /** 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 
+@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 
+/** 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 
+@return If found, the index of the field within the field set, or KErrNotFound
 if not found. */
 	{ return FindNext(aFieldType,aMapping,KContactFieldSetSearchAll); }
 
@@ -529,7 +540,7 @@
 	{ iFields->ResetAndDestroy(); }
 
 inline TBool CContactItem::IsDeletable()
-/** Tests whether the contact item is deletable. 
+/** Tests whether the contact item is deletable.
 
 This is true if the item's access count is zero.
 
@@ -550,8 +561,8 @@
 @return The item's access count. */
 	{return(iAccessCount);}
 
-inline TPtrC CContactItem::Guid() 
-/** Accessor function for Contact Guid. 
+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); }
API_REF/Public_API