Class CContactItem

CContactItem

Support

Supported from 5.0

Description

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

Derivation

CBase Base class for all classes to be instantiated on the heap CContactItem The abstract base class for contact cards, templates and groups

Defined in CContactItem:
AccessCount(), AddFieldL(), CardFields(), DecAccessCount(), Id(), IncAccessCount(), InsertFieldL(), IsDeletable(), IsDeleted(), IsHidden(), IsSystem(), LastModified(), RemoveField(), SetDeleteFlag(), SetDeleted(), SetHidden(), SetLastModified(), SetSystem(), SetTemplateRefId(), SetUidStringL(), TemplateRefId(), Type(), UidStringL(), UpdateFieldSet(), ~CContactItem()

Inherited from CBase:
operator new()

~CContactItem();

Description

The destructor frees all resources owned by the contact item, prior to its destruction.

virtual TUid Type() const=0;

Description

Gets the contact item's type.

Return value

TUid The contact item's type.

TContactItemId Id() const;

Description

Gets the contact item's ID.

Return value

TContactItemId The contact item's ID.

TContactItemId TemplateRefId() const;

Support

Supported from 6.0

Description

Gets the ID of the template which was used to create this contact item.

Return value

TContactItemId The ID of the template on which this item is based. KNullContactId if the item is not based on a template.

void SetTemplateRefId(TContactItemId aUid);

Support

Supported from 6.0

Description

Sets the ID of the template on which this contact item is based.

Parameters

TContactItemId aUid The ID of the template on which this item is based.

void SetUidStringL(TDesC& aString);

Support

Supported from 5.1

Description

Sets the item's UID string. Replaces any existing string. Contact items have a globally unique identifier, stored as a descriptor which is provided for vCard support. It is a combination of the database's unique identifier (see CContactDatabase::MachineId()), the contact item ID and the date/time of the contact item's creation.

Parameters

TDesC& aString The contact item's UID string.

TPtrC UidStringL(TInt64 aMachineUniqueId) const;

Description

Returns a descriptor which contains the item's UID string. Contact items have a globally unique identifier, stored as a descriptor. This is provided for vCard support. It is a combination of the database's unique identifier, the contact item ID and the date/time of the contact item's creation.

Parameters

TInt64 aMachineUniqueId The database's unique identifier. This can be retrieved using CContactDatabase::MachineId().

Return value

TPtrC The item's UID string.

TTime LastModified() const;

Description

Gets the contact item's last modified date/time.

Return value

TTime The contact item's last modified date/time.

void SetLastModified(const TTime& aLastModified);

Description

Sets the last modified date/time value stored in the local copy of the contact item. This value is returned by LastModified() for this copy of the item.

This function has no effect on the item's last modified date/time which is stored in the database — this is always the date/time the contact was last committed.

This function is provided for use by connectivity, e.g. when synchronising contact items.

Parameters

const TTime& aLastModified The contact item's last modified date/time.

void AddFieldL(CContactItemField& aField);

Description

Appends a field to the contact item's field set. The contact item takes ownership of the field.

Parameters

CContactItemField& aField The field to append to the contact item's field set.

void RemoveField(TInt aFieldPos);

Description

Removes a field from the contact item's field set. A panic occurs if the specified field does not exist in the field set.

Parameters

TInt aFieldPos Index within the field set of the field to remove.

void InsertFieldL(CContactItemField& aField,TInt aFieldPos);

Description

Inserts a field into the contact item's field set. The contact item takes ownership of the field.

Parameters

CContactItemField& aField The field to insert into the contact item's field set. TInt aFieldPos The position in the field set at which to insert the field. If this value is greater than the total number of fields, it is appended. The position is relative to zero, i.e. zero implies that the element is inserted at the beginning of the array.

CContactItemFieldSet& CardFields() const;

Description

Gets a reference to the contact item's field set.

Return value

CContactItemFieldSet& A reference to the contact item's field set.

void UpdateFieldSet(CContactItemFieldSet* aNewFieldSet);

Description

Replaces the contact item's field set.

Parameters

CContactItemFieldSet* aNewFieldSet The new field set with which to replace the existing one.

void SetHidden(TBool aHidden);

Description

Sets the contact item's hidden attribute. Hidden means that the item is not displayed if the view definition excludes hidden fields.

Parameters

TBool aHidden ETrue to set the hidden attribute for the item, EFalse to unset it.

void SetSystem(TBool aSystem);

Description

Sets the contact item's system attribute. Note that the system attribute is not currently used in the contacts model.

Parameters

TBool aSystem ETrue to set the system attribute, EFalse to unset it.

TBool IsHidden();

Description

Tests the value of the contact item's hidden attribute. Hidden means that the item is not displayed if the view definition excludes hidden fields.

Return value

TBool ETrue if hidden, EFalse if not.

TBool IsSystem();

Description

Tests the value of the contact item's system attribute. Note that the system attribute is not currently used in the contacts model.

Return value

TBool ETrue if system, EFalse if not.

Description

Note: the functions in this section are provided for use by Connectivity applications.

TBool IsDeletable();

Description

Tests whether the contact item is deletable. This is true if the contact item's access count is zero.

Return value

TBool ETrue if deletable, EFalse if not deletable.

void SetDeleteFlag(TBool aValue);

Support

Withdrawn in 5.1

Description

Sets the value of the contact item's delete flag.

This flag indicates whether an attempt has been made to delete the contact item, but because the item's access count is greater than zero, its data persists and the item should just be marked as deleted.

Parameters

TBool aValue ETrue to set the delete flag. EFalse to unset it.

void SetDeleted(TBool aDeleted);

Support

Supported from 5.1

Description

Sets the value of the contact item's Is deleted attribute.

If the attribute is set, this means that an attempt has been made to delete the contact item, but because the item's access count is greater than zero, its data persists and the item is just marked as deleted.

Parameters

TBool aDeleted ETrue to set the Is deleted attribute. EFalse to unset it.

TBool IsDeleted();

Support

Supported from 5.1

Description

Tests the value of the Is deleted attribute/flag as set by SetDeleted() (or SetDeleteFlag() in EPOC Release 5).

Return value

TBool ETrue if deleted, EFalse if not.

Description

Note: the functions in this section are provided for use by Connectivity applications.

void IncAccessCount();

Description

Increments the contact item's access count.

void DecAccessCount();

Description

Decrements the contact item's access count.

TInt AccessCount() const;

Description

Gets the contact item's access count.

Return value

TInt The contact item's access count.