CContactItemFieldSet Class Reference

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.

Inherits from

Public Member Functions
~CContactItemFieldSet ()
IMPORT_C CContactItemFieldSet & AddL ( CContactItemField &)
CArrayFix < TFieldHeader > * ConstructFieldHeaderArrayLC ( RWriteStream &, CStreamStore &)
TBool ContainsFieldTypeMapping (const CContentType &, const TFieldType &)
TInt Count ()
void ExternalizeL ( RWriteStream &)
TInt FieldText ( TFieldType , TDes &, TInt )
TInt FieldTypeCount (const CContactItemFieldSet &, TInt , const CContactItemField &)
TInt Find ( TFieldType )
TInt Find ( TFieldType , TUid )
IMPORT_C TInt FindNext ( TFieldType , TInt )
IMPORT_C TInt FindNext ( TFieldType , TUid , TInt )
IMPORT_C void InsertL ( TInt , CContactItemField &)
void InternalizeL ( RReadStream &)
IMPORT_C void Move ( TInt , TInt )
IMPORT_C CContactItemFieldSet * NewL ()
IMPORT_C CContactItemFieldSet * NewLC ()
IMPORT_C void Remove ( TInt )
void Reset ()
IMPORT_C void RestoreL ( CStreamStore &, TStreamId , CStreamStore *, const CContactItemViewDef &, RReadStream &)
IMPORT_C void RestoreL ( CStreamStore &, TStreamId , CStreamStore *, const CContactItemViewDef &, const CContactItem *, HBufC *)
IMPORT_C TStreamId StoreL ( CStreamStore &, RWriteStream &, CStreamStore &)
TStreamId StoreL ( CStreamStore &, RWriteStream &, CStreamStore &, CContactTables *)
IMPORT_C void UpdateFieldL (const CContactItemField &, TInt )
IMPORT_C void UpdateFieldSyncL (const CContactItemField &, TInt )
const CContactItemField & operator[] ( TInt )
CContactItemField & operator[] ( TInt )
Private Member Functions
CContactItemFieldSet ()
void ConstructL ()
const CContactItemField * FindById ( TInt )
HBufC * LoadTextStreamLC ( RReadStream &)
TInt MatchTemplateField (const CContentType &, TUint , TBool &)
void NonZeroFieldText ( TFieldType , TDes &)
void RestoreAndAddTemplateL ( CStreamStore &, TStreamId , CStreamStore *, const CContactItemViewDef &, const CContactItem *, RReadStream &, CContactTables *, RArray < TInt > *)
void RestoreL ( CStreamStore &, TStreamId , CStreamStore *, const CContactItemViewDef &, const CContactItem *, RReadStream &, CContactTables *, RArray < TInt > *)
void SetFieldId ( CContactItemField &)
IMPORT_C TStreamId StoreL ( CStreamStore &, const CContactItem *, RWriteStream &, CStreamStore &, CContactTables *)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
CArrayPtr < CContactItemField > * iFields

Constructor & Destructor Documentation

CContactItemFieldSet()

CContactItemFieldSet ( ) [private]

~CContactItemFieldSet()

IMPORT_C ~CContactItemFieldSet ( )

The destructor frees all resources owned by the field set, prior to its destruction.

Member Functions Documentation

AddL(CContactItemField &)

IMPORT_C CContactItemFieldSet & AddL ( CContactItemField & aField )

Appends a field to the field set. The field set takes ownership of the field.

Parameters

CContactItemField & aField Reference to the field to add to the field set. The field's ID is updated.

ConstructFieldHeaderArrayLC(RWriteStream &, CStreamStore &)

CArrayFix < TFieldHeader > * ConstructFieldHeaderArrayLC ( RWriteStream & aTextStream,
CStreamStore & aBlobStore
)
Part of the system template update implementation. This could be used for a generic update method at a later stage.
Since
7.0

Parameters

RWriteStream & aTextStream
CStreamStore & aBlobStore

ConstructL()

void ConstructL ( ) [private]

ContainsFieldTypeMapping(const CContentType &, const TFieldType &)

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

Parameters

const CContentType & aBaseFieldContentType
const TFieldType & aContactFieldType

Count()

TInt Count ( ) const [inline]

Gets the number of fields in the field set.

ExternalizeL(RWriteStream &)

void ExternalizeL ( RWriteStream & aStream ) const

Externalises a CContactItemFieldSet object to a write stream.

Parameters

RWriteStream & aStream Stream to which the object should be externalised.

FieldText(TFieldType, TDes &, TInt)

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

Parameters

TFieldType aFieldType
TDes & aText
TInt aStartPosition

FieldTypeCount(const CContactItemFieldSet &, TInt, const CContactItemField &)

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

Parameters

const CContactItemFieldSet & aSystemTemplateFields
TInt aStartIndex
const CContactItemField & aField

Find(TFieldType)

TInt Find ( TFieldType aFieldType ) const [inline]

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

Parameters

TFieldType aFieldType The field type of interest.

Find(TFieldType, TUid)

TInt Find ( TFieldType aFieldType,
TUid aMapping
) const [inline]

Finds the first field in the field set containing both the content type mapping and the field type specified.

Parameters

TFieldType aFieldType The field type of interest.
TUid aMapping The content type mapping of interest.

FindById(TInt)

const CContactItemField * FindById ( TInt aId ) const [private]

Parameters

TInt aId

FindNext(TFieldType, TInt)

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

Finds the next field in the field set with the specified field type.

Parameters

TFieldType aFieldType The field type of interest.
TInt aStartPos =  KContactFieldSetSearchAll The index within the field set array at which to start the search. By default set to KContactFieldSetSearchAll, to find the first field. Must be a valid array index, or the function raises a panic.

FindNext(TFieldType, TUid, TInt)

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

Finds the next field in the field set containing both the content type mapping and the field type specified.

Parameters

TFieldType aFieldType The field type of interest.
TUid aMapping The content type mapping of interest.
TInt aStartPos =  KContactFieldSetSearchAll The index within the array at which to start the search. By default set to KContactFieldSetSearchAll, to find the first field. Must be a valid array index, or the function raises a panic.

InsertL(TInt, CContactItemField &)

IMPORT_C void InsertL ( TInt aIndex,
CContactItemField & aField
)

Inserts a field into the field set.

Parameters

TInt aIndex The position in the field set at which to insert the field. If equal to or greater than the number of elements in the field set, the field is appended to the field set.
CContactItemField & aField Reference to the field to add to the field set. The field's ID is updated.

InternalizeL(RReadStream &)

void InternalizeL ( RReadStream & aStream )

Internalises a CContactItemFieldSet object from a read stream.

Parameters

RReadStream & aStream Stream from which the object should be internalised.

LoadTextStreamLC(RReadStream &)

HBufC * LoadTextStreamLC ( RReadStream & aStream ) [private, static]

Parameters

RReadStream & aStream

MatchTemplateField(const CContentType &, TUint, TBool &)

TInt MatchTemplateField ( const CContentType & aContentType,
TUint aUserFlags,
TBool & aExactMatch
) const [private]

Find and return the index of the best matched template field. The method uses a matching algorithm which compares the content type of the template fields with that of the incoming contact item.

Matching Algorithm Steps: ========================

The algorithm is based on a scoring mechanism counting 'hits' and 'misses' in order to find the best possible field match within the fieldset of the template.

1. Loop through all the contact item fields of the template.

For each template field:

2. Perform a strict, or exact, match between the vCard mappings of the template field and the field to be matched. 3. If the vCard mappings match exactly, compare User Flags values and amend the overall score accordingly. 4. Loop through all the field types (TFieldType array) stored as part of the content type of the field to be matched.

For each field type of the field to be matched:

5. Loop through the field types of the iterated template field to find a field type match. Amend the 'hits' and 'misses' count accordingly. 6. Calculate the overall score weighing the 'hits' and 'misses' count. 7. Amend the overall score count in order to account for special cases (e.g. user defined fields) 8. Compare the overall score with the best score. If score > current best score, replace the 'bestScore' count and 'bestMatch' index.

9. Return the 'bestMatch' field index of the template field.

Parameters

const CContentType & aContentType The content type of the field to find a match for.
TUint aUserFlags The user flags of the field to find a match for.
TBool & aExactMatch Boolean to indicate an exact field match within the template.

Move(TInt, TInt)

IMPORT_C void Move ( TInt aFrom,
TInt aTo
)

Changes a field's position within the field set.

Both indexes specified must be valid (i.e. between zero and Count() -1 inclusive), or the function raises a panic.

Parameters

TInt aFrom The index of the field to move.
TInt aTo The index of the new position within the field set.

NewL()

IMPORT_C CContactItemFieldSet * NewL ( ) [static]

Allocates and constructs a new field set.

NewLC()

IMPORT_C CContactItemFieldSet * NewLC ( ) [static]

Allocates and constructs a new field set.

NonZeroFieldText(TFieldType, TDes &)

void NonZeroFieldText ( TFieldType aFieldType,
TDes & aText
) const [private]

Get the first non-empty text field

Parameters

TFieldType aFieldType
TDes & aText

Remove(TInt)

IMPORT_C void Remove ( TInt aIndex )

Removes a field from the field set.

Parameters

TInt aIndex The index of the field to delete. Must be a valid index within the field set or the function raises a panic.

Reset()

void Reset ( ) [inline]

Deletes all fields in the field set.

RestoreAndAddTemplateL(CStreamStore &, TStreamId, CStreamStore *, const CContactItemViewDef &, const CContactItem *, RReadStream &, CContactTables *, RArray< TInt > *)

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

Parameters

CStreamStore & aStore
TStreamId aId
CStreamStore * aBlobStore
const CContactItemViewDef & aViewDef
const CContactItem * aTemplate
RReadStream & aReadStream
CContactTables * aContactsTable
RArray < TInt > * aEmailIdArray

RestoreL(CStreamStore &, TStreamId, CStreamStore *, const CContactItemViewDef &, RReadStream &)

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

Restores the field set using a view definition.

Parameters

CStreamStore & aStore Store from which to restore the field set.
TStreamId anId The root stream ID of aStore.
CStreamStore * aBlobStore If specified, the stream store from which data stored in non-text fields is read.
const CContactItemViewDef & aViewDef The view definition to use.
RReadStream & aReadStream Read stream from which data stored in text fields (with a storage type of KStorageTypeText) is read.

RestoreL(CStreamStore &, TStreamId, CStreamStore *, const CContactItemViewDef &, const CContactItem *, HBufC *)

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

The overload that doesn't use dangerous CContactItemFieldSet::LoadTextStreamLC(aReadStream) method. LoadTextStreamLC relies on the stream to know its size, but now all types of streams support this functionality. In order to avoid calling LoadTextStreamLC, aTextBuf is already loaded in HBufC in the caller function. The caller function had access to the table and can use ColLength() API to get the lebgth of the field.

Parameters

CStreamStore & aStore
TStreamId anId
CStreamStore * aBlobStore
const CContactItemViewDef & aViewDef
const CContactItem * aTemplate
HBufC * aTextBuf

RestoreL(CStreamStore &, TStreamId, CStreamStore *, const CContactItemViewDef &, const CContactItem *, RReadStream &, CContactTables *, RArray< TInt > *)

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

Parameters

CStreamStore & aStore
TStreamId anId
CStreamStore * aBlobStore
const CContactItemViewDef & aViewDef
const CContactItem * aTemplate
RReadStream & aReadStream
CContactTables * aContactsTable
RArray < TInt > * aEmailIdArray

SetFieldId(CContactItemField &)

void SetFieldId ( CContactItemField & aField ) [private]

Parameters

CContactItemField & aField

StoreL(CStreamStore &, RWriteStream &, CStreamStore &)

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

Stores the field set to a stream store.

Parameters

CStreamStore & aStore Stream store to which the field set is written.
RWriteStream & aTextStream Stream to which data stored in text fields (with a storage type of KStorageTypeText) is written.
CStreamStore & aBlobStore Stream store to which data stored in non-text fields is written.

StoreL(CStreamStore &, RWriteStream &, CStreamStore &, CContactTables *)

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

Parameters

CStreamStore & aStore
RWriteStream & aTextStream
CStreamStore & aBlobStore
CContactTables * aTables

StoreL(CStreamStore &, const CContactItem *, RWriteStream &, CStreamStore &, CContactTables *)

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

Parameters

CStreamStore & aStore
const CContactItem * aTemplate
RWriteStream & aStream
CStreamStore & aBlobStore
CContactTables * aTables

UpdateFieldL(const CContactItemField &, TInt)

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

Updates a field in the field set. The field whose content type matches aField's content type is replaced by aField. The second parameter is used to identify which matching field is updated. Specify 1 to update the first matching field, 2 for the second and so on. If there is no field in the field set which matches aField's content type, then aField is appended to the field set.

Parameters

const CContactItemField & aField The new field information.
TInt aMatchCount Identifies which matching field in the field set should be updated.

UpdateFieldSyncL(const CContactItemField &, TInt)

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

Updates a field in the field set. Searches the set for a matching field. Deletes the matching set's field if any. Adds the aField to the set anyway. Uses the IsEqualForSyncUpdate() function to compare two CContentType objects, rather than the default equals operator. Takes care to hold the PREF, VoiceDial, and SpeedDial properties in the updated field.

Parameters

const CContactItemField & aField Specifies both the type of the field to update and the updated field's value.
TInt aMatchCount Gives the offset of the matching field to update in the order of the set (i.e. 1, means update the first matching field in the set; 2, means update the second matching field in the set).

operator[](TInt)

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

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

Parameters

TInt 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.

operator[](TInt)

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

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

Parameters

TInt 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.

Member Data Documentation

CArrayPtr< CContactItemField > * iFields

CArrayPtr < CContactItemField > * iFields [private]