1.1 --- a/epoc32/include/app/cntitem.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/app/cntitem.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,9 +1,9 @@
1.4 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 // All rights reserved.
1.6 // This component and the accompanying materials are made available
1.7 -// 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
1.8 +// under the terms of "Eclipse Public License v1.0"
1.9 // which accompanies this distribution, and is available
1.10 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 //
1.13 // Initial Contributors:
1.14 // Nokia Corporation - initial contribution.
1.15 @@ -32,23 +32,43 @@
1.16
1.17 #include <cntdb.h>
1.18
1.19 +/** Maximum length of UID string.
1.20 +@publishedAll
1.21 +@released
1.22 +*/
1.23 +const TInt KUidStringLength =244;
1.24
1.25 -const TInt KUidStringLength =244;
1.26 +/** UID string separator character
1.27 +@publishedAll
1.28 +@released
1.29 +*/
1.30 #define KUidStringSeparator '-'
1.31 +
1.32 +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
1.33 +/** Constant used by vCard import/export.
1.34 +@internalComponent
1.35 +*/
1.36 +#define KContactMaxFieldNumber 32
1.37 +#endif
1.38 +
1.39 class CContactItemField;
1.40 -#define KContactMaxFieldNumber 32
1.41 class CContactItemViewDef;
1.42 class CContactItem;
1.43
1.44 +/** Constant to indicate that all fields in the fieldset should be searched.
1.45 +@publishedAll
1.46 +@released
1.47 +*/
1.48 const TInt KContactFieldSetSearchAll=-1;
1.49 +
1.50 class CContactItemFieldSet : public CBase
1.51 -/** A contact item's field set. The field set owns an array of contact item fields
1.52 -(CContactItemFields). The field set is owned by a contact item, and can be
1.53 -retrieved using CContactItem::CardFields(). Use functions in class
1.54 +/** A contact item's field set. The field set owns an array of contact item fields
1.55 +(CContactItemFields). The field set is owned by a contact item, and can be
1.56 +retrieved using CContactItem::CardFields(). Use functions in class
1.57 CContactItem to add and remove fields to/from the field set.
1.58
1.59 -A field set can contain more than one field of the same type, but this is
1.60 -not advisable as it may cause problems when synchronising the contacts database.
1.61 +A field set can contain more than one field of the same type, but this is
1.62 +not advisable as it may cause problems when synchronising the contacts database.
1.63 @publishedAll
1.64 @released
1.65 */
1.66 @@ -57,9 +77,8 @@
1.67 friend class CContactDatabase;
1.68 friend class CContactTables;
1.69 friend class RPplContactTable;
1.70 -#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.71 friend class TCntPersistenceUtility;
1.72 -#endif //__SYMBIAN_CNTMODEL_USE_SQLITE__
1.73 +
1.74 public:
1.75 IMPORT_C static CContactItemFieldSet* NewL();
1.76 IMPORT_C static CContactItemFieldSet* NewLC();
1.77 @@ -87,7 +106,8 @@
1.78 TInt FieldTypeCount(const CContactItemFieldSet& aSystemTemplateFields, TInt aStartIndex, const CContactItemField& aField) const;
1.79 TBool ContainsFieldTypeMapping(const CContentType& aBaseFieldContentType, const TFieldType& aContactFieldType) const;
1.80 void ExternalizeL(RWriteStream& aStream) const;
1.81 - void InternalizeL(RReadStream& aStream);
1.82 + void InternalizeL(RReadStream& aStream);
1.83 +
1.84 private:
1.85 CContactItemFieldSet();
1.86 void ConstructL();
1.87 @@ -107,14 +127,14 @@
1.88 class CContactDatabase;
1.89 class RCntModel;
1.90 class CContactItem : public CBase
1.91 -/** The abstract base class for contact cards, templates and groups. All contact
1.92 -items are identified by a contact ID, (TContactItemId), have a last modified
1.93 -date/time and own one or more fields (the field set). Contact items also
1.94 -have an access count and attributes (e.g. hidden). Note that fields in a contact
1.95 -item also have attributes. Attribute values specified in the contact item
1.96 -override those in the contained fields. The access count is a record of the
1.97 -number of objects referencing a contact item. A contact item cannot be fully
1.98 -deleted until its access count is zero.
1.99 +/** The abstract base class for contact cards, templates and groups. All contact
1.100 +items are identified by a contact ID, (TContactItemId), have a last modified
1.101 +date/time and own one or more fields (the field set). Contact items also
1.102 +have an access count and attributes (e.g. hidden). Note that fields in a contact
1.103 +item also have attributes. Attribute values specified in the contact item
1.104 +override those in the contained fields. The access count is a record of the
1.105 +number of objects referencing a contact item. A contact item cannot be fully
1.106 +deleted until its access count is zero.
1.107 @publishedAll
1.108 @released
1.109 */
1.110 @@ -137,11 +157,11 @@
1.111 public:
1.112 IMPORT_C ~CContactItem();
1.113 /** Gets the contact item's type.
1.114 -
1.115 +
1.116 @return The contact item's type. */
1.117 virtual TUid Type() const=0;
1.118 static CContactItem* NewLC(RReadStream& aStream);
1.119 - IMPORT_C static CContactItem* NewLC(TUid aType);
1.120 + IMPORT_C static CContactItem* NewLC(TUid aType);
1.121 IMPORT_C TContactItemId Id() const;
1.122 IMPORT_C TContactItemId TemplateRefId() const;
1.123 IMPORT_C TTime LastModified() const;
1.124 @@ -151,9 +171,9 @@
1.125 IMPORT_C void InsertFieldL(CContactItemField& aField,TInt aFieldPos);
1.126 IMPORT_C CContactItemFieldSet& CardFields() const;
1.127 IMPORT_C void SetHidden(TBool aHidden);
1.128 - IMPORT_C void SetSystem(TBool aSystem);
1.129 + IMPORT_C void SetSystem(TBool aSystem);
1.130 IMPORT_C TBool IsHidden();
1.131 - IMPORT_C TBool IsSystem();
1.132 + IMPORT_C TBool IsSystem();
1.133 IMPORT_C void UpdateFieldSet(CContactItemFieldSet* aNewFieldSet);
1.134 IMPORT_C void SetDeleted(TBool aDeleted);
1.135 IMPORT_C TBool IsDeleted() const;
1.136 @@ -171,32 +191,30 @@
1.137 void ClearFieldContent();
1.138 inline TPtrC Guid();
1.139 virtual void ExternalizeL(RWriteStream& aStream) const;
1.140 - virtual void InternalizeL(RReadStream& aStream);
1.141 + virtual void InternalizeL(RReadStream& aStream);
1.142
1.143 -#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.144 IMPORT_C void SetId(TContactItemId aId);
1.145 IMPORT_C TUint32 Attributes() const;
1.146 IMPORT_C void SetAttributes(TUint32 aAttributes);
1.147 IMPORT_C void SetAccessCount(TUint32 aAccessCount);
1.148 IMPORT_C void SetCreationDate(const TTime& aTime);
1.149 -#endif
1.150
1.151 public:
1.152 - /** Contact item's attribute flags
1.153 -
1.154 - These flags can be used to set the various attributes of a contact item. */
1.155 - enum
1.156 + /** Contact item's attribute flags
1.157 +
1.158 + These flags can be used to set the various attributes of a contact item. */
1.159 + enum
1.160 {
1.161 - /** To set the contact item's system attribute. */
1.162 - ESystem=0x01,
1.163 - /** To set the contact item's hidden attribute. */
1.164 - EHidden=0x02,
1.165 - /** To set the contact item's hidden attribute. */
1.166 - ECompressedGuid=0x04,
1.167 - /** To set the contact item's Is deleted attribute. */
1.168 - EDeleted=0x08
1.169 + /** To set the contact item's system attribute. */
1.170 + ESystem=0x01,
1.171 + /** To set the contact item's hidden attribute. */
1.172 + EHidden=0x02,
1.173 + /** To set the contact item's hidden attribute. */
1.174 + ECompressedGuid=0x04,
1.175 + /** To set the contact item's Is deleted attribute. */
1.176 + EDeleted=0x08
1.177 };
1.178 -protected:
1.179 +
1.180 private:
1.181 CContactItem();
1.182 void ConstructL();
1.183 @@ -215,14 +233,13 @@
1.184 TTime iCreationDate;
1.185 TUint32 iAccessCount;
1.186 HBufC* iGuid;
1.187 - friend class CContactDatabase;
1.188 };
1.189
1.190 class CContactItemPlusGroup : public CContactItem
1.191 /** Abstract base class for CContactGroup, CContactCard and CContactOwnCard.
1.192
1.193 -The purpose of this class is to avoid duplication of group functionality
1.194 -in its derived classes.
1.195 +The purpose of this class is to avoid duplication of group functionality
1.196 +in its derived classes.
1.197 @publishedAll
1.198 @released
1.199 */
1.200 @@ -235,12 +252,10 @@
1.201 IMPORT_C ~CContactItemPlusGroup();
1.202 public:
1.203 virtual void ExternalizeL(RWriteStream& aStream) const;
1.204 - virtual void InternalizeL(RReadStream& aStream);
1.205 + virtual void InternalizeL(RReadStream& aStream);
1.206
1.207 -#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.208 IMPORT_C void ResetGroups();
1.209 IMPORT_C void SetGroups(CContactIdArray* aGroups);
1.210 -#endif
1.211
1.212 private:
1.213 CContactIdArray* iGroups;
1.214 @@ -252,22 +267,22 @@
1.215 class CContactGroup : public CContactItemPlusGroup
1.216 /** A contact group.
1.217
1.218 -A contact group is a contact item which holds a set of associated contact
1.219 -item IDs. The members of the group may be contact cards, own cards, or even
1.220 -other groups. The group has a label which identifies the group to users, e.g.
1.221 -"family", or "colleagues". The type of a contact group is KUidContactGroup,
1.222 +A contact group is a contact item which holds a set of associated contact
1.223 +item IDs. The members of the group may be contact cards, own cards, or even
1.224 +other groups. The group has a label which identifies the group to users, e.g.
1.225 +"family", or "colleagues". The type of a contact group is KUidContactGroup,
1.226 as returned by Type().
1.227
1.228 -Objects of this class are constructed using CContactDatabase::CreateContactGroupL()
1.229 -or CreateContactGroupLC(). These functions create the group, optionally with
1.230 +Objects of this class are constructed using CContactDatabase::CreateContactGroupL()
1.231 +or CreateContactGroupLC(). These functions create the group, optionally with
1.232 a label, add it to the database, and return a pointer to it.
1.233
1.234 -To create an association between a card and a group, use CContactDatabase::AddContactToGroupL()
1.235 -and to remove the association, use RemoveContactFromGroupL(). To find out
1.236 +To create an association between a card and a group, use CContactDatabase::AddContactToGroupL()
1.237 +and to remove the association, use RemoveContactFromGroupL(). To find out
1.238 which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().
1.239
1.240 -The function CContactDatabase::GetGroupIdListL() may be used to retrieve a
1.241 -list of IDs for all groups in the database.
1.242 +The function CContactDatabase::GetGroupIdListL() may be used to retrieve a
1.243 +list of IDs for all groups in the database.
1.244 @publishedAll
1.245 @released
1.246 */
1.247 @@ -289,21 +304,18 @@
1.248 IMPORT_C TPtrC GetGroupLabelL();
1.249 IMPORT_C TBool HasItemLabelField();
1.250 IMPORT_C CContactIdArray* GroupsJoinedLC() const;
1.251 -//
1.252 - //IMPORT_C void ReservedFunction1();
1.253 +
1.254 IMPORT_C void AddContactL(TContactItemId aContactId);
1.255 - //IMPORT_C void ReservedFunction2();
1.256 IMPORT_C void RemoveContactL(TContactItemId aContactId);
1.257 virtual void ExternalizeL(RWriteStream& aStream) const;
1.258 virtual void InternalizeL(RReadStream& aStream);
1.259
1.260 -#ifdef __SYMBIAN_CNTMODEL_USE_SQLITE__
1.261 IMPORT_C void ResetItems();
1.262 - IMPORT_C void SetItems(CContactIdArray* aItems);
1.263 -#endif
1.264 + IMPORT_C void SetItems(CContactIdArray* aItems);
1.265
1.266 private:
1.267 CContactGroup();
1.268 +
1.269 private:
1.270 CContactIdArray* iItems;
1.271 friend class CContactDatabase;
1.272 @@ -313,19 +325,19 @@
1.273 class CContactCardTemplate : public CContactItem
1.274 /** A contact card template.
1.275
1.276 -This is a contact item containing a set of fields on which new contact items can
1.277 -be based. Templates have a label which is a string which identifies the template
1.278 -to a user. For instance, 'work template' could indicate a template used
1.279 -to create contact cards in the style of a work colleague. Contact card templates
1.280 +This is a contact item containing a set of fields on which new contact items can
1.281 +be based. Templates have a label which is a string which identifies the template
1.282 +to a user. For instance, 'work template' could indicate a template used
1.283 +to create contact cards in the style of a work colleague. Contact card templates
1.284 have a type of KUidContactCardTemplate, as returned by Type().
1.285
1.286 -Objects of this class cannot be constructed directly because its constructors
1.287 -are protected. Instead, use either CContactDatabase::CreateContactCardTemplateL()
1.288 -or CreateContactCardTemplateLC(). These functions create a contact card template,
1.289 +Objects of this class cannot be constructed directly because its constructors
1.290 +are protected. Instead, use either CContactDatabase::CreateContactCardTemplateL()
1.291 +or CreateContactCardTemplateLC(). These functions create a contact card template,
1.292 add it to the database, and return a pointer to it.
1.293
1.294 -The function CContactDatabase::GetCardTemplateIdListL() gets a list of the
1.295 -IDs of all contact card templates in the database.
1.296 +The function CContactDatabase::GetCardTemplateIdListL() gets a list of the
1.297 +IDs of all contact card templates in the database.
1.298 @publishedAll
1.299 @released
1.300 */
1.301 @@ -343,25 +355,24 @@
1.302 IMPORT_C static CContactCardTemplate* NewL(const CContactItem *aTemplate);
1.303 IMPORT_C static CContactCardTemplate* NewLC(const CContactItem *aTemplate);
1.304 IMPORT_C TBool HasItemLabelField();
1.305 -//
1.306 -/**
1.307 - Intended usage: Reserved to preserve future BC */
1.308 +
1.309 +/** Intended usage: Reserved to preserve future BC */
1.310 IMPORT_C void ReservedFunction1();
1.311 -/**
1.312 - Intended usage: Reserved to preserve future BC */
1.313 +/** Intended usage: Reserved to preserve future BC */
1.314 IMPORT_C void ReservedFunction2();
1.315
1.316 protected: // from CContactItem
1.317 IMPORT_C TUid Type() const;
1.318 +
1.319 private:
1.320 CContactCardTemplate();
1.321 };
1.322
1.323 class CContactCard : public CContactItemPlusGroup
1.324 -/** A contact card.
1.325 +/** A contact card.
1.326
1.327 -Implements the Type() function declared in class CContactItem.
1.328 -Contact cards may optionally be constructed from a template.
1.329 +Implements the Type() function declared in class CContactItem.
1.330 +Contact cards may optionally be constructed from a template.
1.331 @publishedAll
1.332 @released
1.333 */
1.334 @@ -383,20 +394,20 @@
1.335 };
1.336
1.337 class CContactOwnCard : public CContactItemPlusGroup
1.338 -/** Own card.
1.339 +/** Own card.
1.340
1.341 -An own card is a contact card which contains information about the device's
1.342 -owner. This can be sent to another compatible electronic device as a vCard.
1.343 -The contact database recognises a single own card, referred to as the
1.344 -current own card; its ID is returned by CContactDatabase::OwnCardId(). Like
1.345 -a contact card, an own card can be a member of one or more contact card groups.
1.346 +An own card is a contact card which contains information about the device's
1.347 +owner. This can be sent to another compatible electronic device as a vCard.
1.348 +The contact database recognises a single own card, referred to as the
1.349 +current own card; its ID is returned by CContactDatabase::OwnCardId(). Like
1.350 +a contact card, an own card can be a member of one or more contact card groups.
1.351 The own card type is identified by a UID of KUidContactOwnCard.
1.352
1.353 -Own cards can be constructed using either CContactDatabase::CreateOwnCardLC()
1.354 -or CreateOwnCardL(). These functions create an own card, based on the system
1.355 -template, add it to the database, set it as the database's current own card
1.356 -and return a pointer to it. To change the database's current own card, use
1.357 -CContactDatabase::SetOwnCardL().
1.358 +Own cards can be constructed using either CContactDatabase::CreateOwnCardLC()
1.359 +or CreateOwnCardL(). These functions create an own card, based on the system
1.360 +template, add it to the database, set it as the database's current own card
1.361 +and return a pointer to it. To change the database's current own card, use
1.362 +CContactDatabase::SetOwnCardL().
1.363 @publishedAll
1.364 @released
1.365 */
1.366 @@ -418,14 +429,14 @@
1.367 };
1.368
1.369 class CContactTemplate : public CContactItem
1.370 -/** A contact item template.
1.371 +/** A contact item template.
1.372
1.373 -This is a contact item which is used to seed the initial field set for
1.374 +This is a contact item which is used to seed the initial field set for
1.375 other contact items.
1.376
1.377 -Non-system (i.e. user-defined) templates are implemented
1.378 -by the CContactCardTemplate class. CContactCardTemplate should be
1.379 -used in preference to CContactTemplate.
1.380 +Non-system (i.e. user-defined) templates are implemented
1.381 +by the CContactCardTemplate class. CContactCardTemplate should be
1.382 +used in preference to CContactTemplate.
1.383 @publishedAll
1.384 @released
1.385 */
1.386 @@ -443,7 +454,7 @@
1.387
1.388
1.389 class CContactICCEntry : public CContactItemPlusGroup
1.390 -/** A contact ICC entry.
1.391 +/** A contact ICC entry.
1.392 @publishedAll
1.393 @released
1.394 */
1.395 @@ -462,12 +473,12 @@
1.396 class ContactGuid
1.397 /** A globally unique identifier enquiry utility.
1.398
1.399 -Each contact item has a unique identifier, stored as a descriptor. It is
1.400 -referred to as the 'UID string'. This is a combination of the unique
1.401 -identifier of the database in which the contact item was created, the
1.402 -contact item ID and the date/time of the contact item's creation. ContactGuid
1.403 -provides a single static exported function to enquire whether an item was
1.404 -created in a specified database.
1.405 +Each contact item has a unique identifier, stored as a descriptor. It is
1.406 +referred to as the 'UID string'. This is a combination of the unique
1.407 +identifier of the database in which the contact item was created, the
1.408 +contact item ID and the date/time of the contact item's creation. ContactGuid
1.409 +provides a single static exported function to enquire whether an item was
1.410 +created in a specified database.
1.411 @publishedAll
1.412 @released
1.413 */
1.414 @@ -481,20 +492,20 @@
1.415 };
1.416
1.417 inline const CContactItemField& CContactItemFieldSet::operator[](TInt aIndex) const
1.418 -/** Gets the field located at a specified position in the field set.
1.419 +/** Gets the field located at a specified position in the field set.
1.420
1.421 -@param aIndex The position of the field in the field set. This is relative to zero.
1.422 -It must be non-negative and less than the number of objects in the array, otherwise
1.423 +@param aIndex The position of the field in the field set. This is relative to zero.
1.424 +It must be non-negative and less than the number of objects in the array, otherwise
1.425 the operator raises a panic.
1.426
1.427 @return A const reference to an element in the array. */
1.428 { return *(*iFields)[aIndex]; }
1.429
1.430 inline CContactItemField& CContactItemFieldSet::operator[](TInt aIndex)
1.431 -/** Gets the field located at a specified position in the field set.
1.432 +/** Gets the field located at a specified position in the field set.
1.433
1.434 -@param aIndex The position of the field in the field set. This is relative to zero.
1.435 -It must be non-negative and less than the number of objects in the array, otherwise
1.436 +@param aIndex The position of the field in the field set. This is relative to zero.
1.437 +It must be non-negative and less than the number of objects in the array, otherwise
1.438 the operator raises a panic.
1.439
1.440 @return A non-const reference to an element in the array. */
1.441 @@ -504,17 +515,17 @@
1.442 /** Finds the first field in the field set with the specified field type.
1.443
1.444 @param aFieldType The field type of interest.
1.445 -@return If found, the index of the field within the field set, or KErrNotFound
1.446 +@return If found, the index of the field within the field set, or KErrNotFound
1.447 if not found. */
1.448 { return FindNext(aFieldType,KContactFieldSetSearchAll); }
1.449
1.450 inline TInt CContactItemFieldSet::Find(TFieldType aFieldType,TUid aMapping) const
1.451 -/** Finds the first field in the field set containing both the content type mapping
1.452 +/** Finds the first field in the field set containing both the content type mapping
1.453 and the field type specified.
1.454
1.455 @param aFieldType The field type of interest.
1.456 @param aMapping The content type mapping of interest.
1.457 -@return If found, the index of the field within the field set, or KErrNotFound
1.458 +@return If found, the index of the field within the field set, or KErrNotFound
1.459 if not found. */
1.460 { return FindNext(aFieldType,aMapping,KContactFieldSetSearchAll); }
1.461
1.462 @@ -529,7 +540,7 @@
1.463 { iFields->ResetAndDestroy(); }
1.464
1.465 inline TBool CContactItem::IsDeletable()
1.466 -/** Tests whether the contact item is deletable.
1.467 +/** Tests whether the contact item is deletable.
1.468
1.469 This is true if the item's access count is zero.
1.470
1.471 @@ -550,8 +561,8 @@
1.472 @return The item's access count. */
1.473 {return(iAccessCount);}
1.474
1.475 -inline TPtrC CContactItem::Guid()
1.476 -/** Accessor function for Contact Guid.
1.477 +inline TPtrC CContactItem::Guid()
1.478 +/** Accessor function for Contact Guid.
1.479 * This is used to cache contact items that are added during a sync.
1.480 @return Guid */
1.481 { return iGuid ? *iGuid : TPtrC(KNullDesC); }