diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/app/cntitem.h --- 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 +/** 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); }