CContactItemField in Application Engines CNTMODEL

class CContactItemField : public CBase;

Description

A field in a contact item.

Fields are grouped into a field set (CContactItemFieldSet), which is owned by the contact item.

The contact item field stores the field data. The data may be text, a date/time value, or an agent, as indicated by the storage type (TStorageType). The storage type is also owned by the field. Note that numeric field data is not supported. All numbers, for instance telephone or fax numbers are stored as text.

Fields also have a content type, attributes and a label. The label is a string which identifies the field to a user e.g. First name, Last name.

The following attributes are supported:

hidden: the field is not displayed if the view definition masks hidden fields

disabled: the field cannot be deleted from the original template and thus is marked as disabled

read only: the field cannot be written to

synchronise: used by Connectivity applications; set by default for all contact item fields

user added: the field was added by the user and was not taken from the template

template: indicates that the field is part of a template. Template fields differ from other fields in that they are persisted when they do not contain any data.

speed dial: the field contains a telephone number which maps to one of the nine possible speed dial positions.

These attributes can be set using member functions of this class, but they are normally set automatically by other functions, for instance when setting a speed dial field, CContactDatabase automatically sets the field's speed dial attribute.

Derivation

CBase - Base class for all classes to be instantiated on the heap

CContactItemField - A field in a contact item

Members

Defined in CContactItemField:

AddFieldTypeL()Appends a field type to the field's content type
AgentStorage()Gets a pointer to the field's storage as a CContactAgentField
ContentType()Gets the field's content type
DateTimeStorage()Returns a pointer to the field's storage as a CContactDateField
DoSynchronize()Gets the value of the field's synchronise attribute
HasExtraStream()Tests whether the field needs an extra stream to store information not contained in the template
Id()Gets the field ID
IsCustomFilterable()Tests the value of the user defined filter attribute
IsDeleted()Gets the value of the field's deleted attribute
IsDisabled()Gets the value of the field's disabled attribute
IsHidden()Gets the value of the field's hidden attribute
IsPrivate()Tests whether the field's private attribute is set
IsReadOnly()Gets the value of the field's read only attribute
IsSpeedDial()Tests whether the field is a speed dial field
IsTemplate()Tests whether the field is in a template, as set by SetTemplateField()
IsTemplateLabelField()Tests whether the field is a template label field (a field which holds the label for a contact card template: see class CContactCardTemplate)
IsValidLabel()Tests whether a field label is valid
Label()Gets the field's label
LabelUnspecified()Tests whether the field's label has been set, either by a call to SetLabel() or by inheriting a label specified in the template
NewL()Allocates and constructs a contact item field with a storage type
NewL()Allocates and constructs a contact item field with a storage type and a field type
NewL()Allocates and constructs a contact item field based on another one
NewL()Allocates and constructs a contact item field with a content type and a storage type
NewLC()Allocates and constructs a new default contact item field
NewLC()Allocates and constructs a contact item field with a storage type
NewLC()Allocates and constructs a contact item field with a storage type and a field type
NewLC()Allocates and constructs a contact item field based on another one
NewLC()Allocates and constructs a contact item field with a content type and a storage type
OverRidesLabel()Tests whether the field's label (as set by SetLabel()) overrides the label specified in the field's template
RemoveFieldType()Removes a field type from the field's content type
ResetStore()Resets the field storage
RestoreHeaderL()
SetDisabled()Sets the value of the disabled attribute
SetHidden()Sets the value of the hidden attribute
SetHintType()
SetId()Sets the ID which uniquely identifies a field within a field set..
SetLabel()Sets the field label
SetLabelL()Sets the field label
SetMapping()Sets the vCard mapping for the field's content type
SetPrivate()Sets the value of the field's private attribute
SetReadOnly()Sets the value of the field's read only attribute
SetSpeedDial()Sets the value of the field's speed dial attribute
SetSynchronize()Sets the value of the field's synchronise attribute
SetTemplateField()Sets whether the field is a template field
SetUserAddedField()Sets the user added field attribute
SetUserFlags()Sets the value of the user flags
Storage()Gets a pointer to the field's base storage
StorageType()Gets the field's storage type
StoreStorage()Gets a pointer to the field's storage as a CContactStoreField
TextStorage()Gets a pointer to the field's storage as a CContactTextField
UserAddedField()Gets the value of the user added field attribute
UserFlags()Gets the value of the user flags, as set by SetUserFlags()
UsesTemplateTypes()Tests whether or not the field's content type is based on a template
~CContactItemField()Frees all resources owned by the field (the label, the stored data and the content type), prior to its destruction

Inherited from CBase:

Delete()Deletes the specified object
Extension_()Extension function
operator new()Initialises the object to binary zeroes

static IMPORT_C CContactItemField *NewLC();

Description

Allocates and constructs a new default contact item field.

The field's storage type, content type and label are unspecified. The ESynchronize attribute is set.

Return value

CContactItemField *

Pointer to the newly created contact item field.

static IMPORT_C CContactItemField *NewL(TStorageType aType);

Description

Allocates and constructs a contact item field with a storage type.

The field's label and content type are unspecified.

Parameters


                                 						TStorageType aType

The field's storage type.

Return value

CContactItemField *

Pointer to the newly created contact item field.

static IMPORT_C CContactItemField *NewLC(TStorageType aType);

Description

Allocates and constructs a contact item field with a storage type.

The field's label and content type are unspecified.

Parameters


                                 						TStorageType aType

The field's storage type.

Return value

CContactItemField *

Pointer to the newly created contact item field. This is left on the cleanup stack.

static IMPORT_C CContactItemField *NewL(TStorageType aType, TFieldType aFieldType);

Description

Allocates and constructs a contact item field with a storage type and a field type.

The field's content type is initialised with the field type, and its vCard mapping is set by default to KNullUid. The field's label is unspecified.

Parameters

`TStorageType aType`	The field's storage type.
`TFieldType aFieldType`	The field type as defined in cntdef.h.

Return value

CContactItemField *

Pointer to the newly created contact item field.

static IMPORT_C CContactItemField *NewLC(TStorageType aType, TFieldType aFieldType);

Description

Allocates and constructs a contact item field with a storage type and a field type.

The field's content type is initialised with the field type, and its vCard mapping is set by default to KNullUid. The field's label is unspecified.

Parameters

`TStorageType aType`	The field's storage type.
`TFieldType aFieldType`	The field type as defined in cntdef.h.

Return value

CContactItemField *

Pointer to the newly created contact item field. This is left on the cleanup stack.

static IMPORT_C CContactItemField *NewL(const CContactItemField &aField);

Description

Allocates and constructs a contact item field based on another one.

All details (content type, storage type, attributes and label) are copied from the specified field.

Parameters

const CContactItemField &aField

The contact field to copy.

Return value

CContactItemField *

Pointer to the newly created contact item field.

static IMPORT_C CContactItemField *NewLC(const CContactItemField &aField);

Description

Allocates and constructs a contact item field based on another one.

All details (content type, storage type, attributes and label) are copied from the specified field.

Parameters

const CContactItemField &aField

The contact field to copy.

Return value

CContactItemField *

Pointer to the newly created contact item field. This is left on the cleanup stack.

static IMPORT_C CContactItemField *NewL(TStorageType aType, const CContentType &aContentType);

Description

Allocates and constructs a contact item field with a content type and a storage type.

The field's label is unspecified.

Parameters

`TStorageType aType`	The field's storage type.
`const CContentType &aContentType`	The field's content type.

Return value

CContactItemField *

Pointer to the newly created contact item field.

static IMPORT_C CContactItemField *NewLC(TStorageType aType, const CContentType &aContentType);

Description

Allocates and constructs a contact item field with a content type and a storage type.

The field's label is unspecified.

Parameters

`TStorageType aType`	The field's storage type.
`const CContentType &aContentType`	The field's content type.

Return value

CContactItemField *

Pointer to the newly created contact item field. This is left on the cleanup stack.

IMPORT_C ~CContactItemField();

Description

Frees all resources owned by the field (the label, the stored data and the content type), prior to its destruction.

IMPORT_C TStorageType StorageType() const;

Description

Gets the field's storage type.

Return value

TStorageType

The field's storage type.

IMPORT_C const CContentType &ContentType() const;

Description

Gets the field's content type.

Return value

const CContentType &

Reference to the field's content type.

inline TBool IsHidden() const;

Description

Gets the value of the field's hidden attribute.

Return value


                                 						TBool

ETrue if hidden attribute is set, EFalse if not set.

inline TBool IsReadOnly() const;

Description

Gets the value of the field's read only attribute.

Return value


                                 						TBool

ETrue if read only attribute set, EFalse if not set.

inline TBool IsDisabled() const;

Description

Gets the value of the field's disabled attribute.

Return value


                                 						TBool

ETrue if disabled attribute set, EFalse if not set.

inline TBool IsTemplate() const;

Description

Tests whether the field is in a template, as set by SetTemplateField().

Return value


                                 						TBool

ETrue if field is a template field. EFalse if not.

inline TBool IsPrivate() const;

Description

Tests whether the field's private attribute is set.

Return value


                                 						TBool

True if the field's private attribute is set, false if not.

inline TBool IsSpeedDial() const;

Description

Tests whether the field is a speed dial field.

Return value


                                 						TBool

True if the field is a speed dial field, false if not.

inline TBool DoSynchronize() const;

Description

Gets the value of the field's synchronise attribute.

Return value


                                 						TBool

ETrue if synchronise attribute is set, EFalse if not set.

inline TBool OverRidesLabel() const;

Description

Tests whether the field's label (as set by SetLabel()) overrides the label specified in the field's template.

Return value


                                 						TBool

True if the field's label overrides the label specified in the template; false if not.

inline TBool HasExtraStream() const;

Description

Tests whether the field needs an extra stream to store information not contained in the template. This is the case if the field's content type is not based on a template, or if the field has a label which overrides the label specified in the template.

Return value


                                 						TBool

True if the field uses an extra stream; false if not.

inline TBool UsesTemplateTypes() const;

Description

Tests whether or not the field's content type is based on a template.

Return value


                                 						TBool

True if the field's content type is based on a template; false if not.

inline TBool LabelUnspecified() const;

Description

Tests whether the field's label has been set, either by a call to SetLabel() or by inheriting a label specified in the template.

Return value


                                 						TBool

True if the field's label has been set, false if not.

inline TBool UserAddedField() const;

Description

Gets the value of the user added field attribute.

Return value


                                 						TBool

ETrue if the user added attribute is set, EFalse if not.

inline TBool IsCustomFilterable() const;

Description

Tests the value of the user defined filter attribute.

Return value


                                 						TBool

ETrue if the user defined filter attribute is set, EFalse if not.

IMPORT_C void SetHintType(TInt aType);

Description

Parameters


                                 						TInt aType

IMPORT_C TPtrC Label() const;

Description

Gets the field's label.

Return value

TPtrC

The field label. If no label has been set, its length is zero.

IMPORT_C void ResetStore();

Description

Resets the field storage. The field's store is deleted, then re-allocated.

IMPORT_C CContactFieldStorage *Storage() const;

Description

Gets a pointer to the field's base storage.

Rather than using this function and then casting to a specific storage class, one of the following functions should normally be used: TextStorage(), StoreStorage(), AgentStorage(), or DateTimeStorage().

Return value

CContactFieldStorage *

The field's base storage type.

IMPORT_C CContactTextField *TextStorage() const;

Description

Gets a pointer to the field's storage as a CContactTextField.

If the field's storage type is not KStorageTypeText, this function raises a panic.

Return value

CContactTextField *

The field's storage as a CContactTextField*.

IMPORT_C CContactStoreField *StoreStorage() const;

Description

Gets a pointer to the field's storage as a CContactStoreField.

This indicates the field data is stored in a descriptor or descriptor array. If the field storage type is not KStorageTypeStore, this function raises a panic.

Return value

CContactStoreField *

Field's storage as a CContactStoreField*.

IMPORT_C CContactAgentField *AgentStorage() const;

Description

Gets a pointer to the field's storage as a CContactAgentField.

An agent is a property in a vCard which contains another person's contact details. If the field storage type is not KStorageTypeContactItemId, this function raises a panic.

Return value

CContactAgentField *

Field's storage as a CContactAgentField*.

IMPORT_C CContactDateField *DateTimeStorage() const;

Description

Returns a pointer to the field's storage as a CContactDateField.

If the field storage type is not KStorageTypeDateTime, this function raises a panic.

Return value

CContactDateField *

Field's storage as a CContactDateField*.

IMPORT_C void AddFieldTypeL(TFieldType aFieldType);

Description

Appends a field type to the field's content type.

Note that certain combinations of field types are not valid and should not be used.

Parameters


                                 						TFieldType aFieldType

The field type to append to the field's content type.

IMPORT_C void RemoveFieldType(TFieldType aFieldType);

Description

Removes a field type from the field's content type.

Parameters


                                 						TFieldType aFieldType

The field type to remove from the field's content type.

IMPORT_C void SetMapping(TUid aMapping);

Description

Sets the vCard mapping for the field's content type.

Parameters


                                 						TUid aMapping

The new mapping for the field's content type.

IMPORT_C void SetHidden(TBool aHidden);

Description

Sets the value of the hidden attribute.

If hidden fields are included in the view definition, the field is displayed like other fields. If the view definition masks hidden fields, it is not displayed. See the TMode enumeration defined in class CContactItemViewDef.

Parameters


                                 						TBool aHidden

ETrue for hidden, EFalse for displayed.

IMPORT_C void SetReadOnly(TBool aReadOnly);

Description

Sets the value of the field's read only attribute.

Parameters


                                 						TBool aReadOnly

ETrue to set the field's read only attribute, EFalse to unset the attribute.

IMPORT_C void SetSynchronize(TBool aSynchronize);

Description

Sets the value of the field's synchronise attribute.

Parameters


                                 						TBool aSynchronize

ETrue to set synchronise attribute, EFalse to unset it.

IMPORT_C void SetDisabled(TBool aDisabled);

Description

Sets the value of the disabled attribute.

Parameters


                                 						TBool aDisabled

ETrue to set the disabled attribute, EFalse to unset the attribute.

IMPORT_C void SetLabelL(const TDesC &aLabel);

Description

Sets the field label.

The label is allocated using TDesC::AllocL(), so the function can leave. Any existing label is replaced.

Parameters

const TDesC &aLabel

The new field label.

IMPORT_C void SetLabel(HBufC *aLabel);

Description

Sets the field label.

The field takes ownership of aLabel so the function cannot leave.

Parameters


                                 						HBufC *aLabel

The new field label.

IMPORT_C void SetUserAddedField(TBool aUserAddedField);

Description

Sets the user added field attribute.

Parameters


                                 						TBool aUserAddedField

ETrue to set the field's user added attribute, EFalse to unset it.

IMPORT_C void SetTemplateField(TBool aTemplateField);

Description

Sets whether the field is a template field.

Parameters


                                 						TBool aTemplateField

ETrue to set the field's Is template attribute. EFalse to unset it.

IMPORT_C void SetPrivate(TBool aTemplateField);

Description

Sets the value of the field's private attribute.

This is used by the contact database when exporting a contact item as a vCard, to identify fields which should not be exported.

Parameters


                                 						TBool aTemplateField

ETrue to set the field's private attribute, EFalse to unset it.

IMPORT_C void SetSpeedDial(TBool aSpeedDialField);

Description

Sets the value of the field's speed dial attribute.

Parameters


                                 						TBool aSpeedDialField

ETrue if the field should be a speed dial field, EFalse if not.

IMPORT_C void SetId(TInt aId);

Description

Sets the ID which uniquely identifies a field within a field set..

Note that the field ID value is initialised when the field is added to the field set (using CContactItemFieldSet::AddL()). It is equivalent to the field's index within the field set array, and should not normally be changed.

Parameters


                                 						TInt aId

The new field ID.

IMPORT_C TInt Id() const;

Description

Gets the field ID.

Return value

TInt

The field ID.

IMPORT_C TUint UserFlags() const;

Description

Gets the value of the user flags, as set by SetUserFlags().

Return value

TUint

The user flags value.

IMPORT_C void SetUserFlags(TUint aFlags);

Description

Sets the value of the user flags.

Parameters


                                 						TUint aFlags

The user flags value.

static IMPORT_C TBool IsValidLabel(const TDesC &aLabel, TInt &aInvalidPos);

Description

Tests whether a field label is valid.

Note: the label is invalid if it contains any of the following characters:

[] (left or right square bracket)

= (equals sign)

. (dot)

: (colon)

, (comma)

Parameters

`const TDesC &aLabel`	The field label to test.
`TInt &aInvalidPos`	On return, contains the character position within the label of the first invalid character. The first character position is zero.

Return value

TBool

ETrue if valid, EFalse if invalid.

IMPORT_C TBool IsTemplateLabelField() const;

Description

Tests whether the field is a template label field (a field which holds the label for a contact card template: see class CContactCardTemplate).

Return value

TBool

ETrue if the field is a template label field, EFalse if not.

IMPORT_C void RestoreHeaderL(RReadStream &aStream, const CContactItemFieldSet *aSystemTemplateFields);

Description

Parameters

`RReadStream &aStream`
`const CContactItemFieldSet *aSystemTemplateFields`

inline TBool IsDeleted() const;

Description

Gets the value of the field's deleted attribute.

Return value


                                 						TBool

ETrue if the field is deleted, otherwise EFalse.

Class CContactItemField

Description

Derivation

Members

Construction and destruction

NewLC()

Description

Return value

NewL()

Description

Parameters

Return value

NewLC()

Description

Parameters

Return value

NewL()

Description

Parameters

Return value

NewLC()

Description

Parameters

Return value

NewL()

Description

Parameters

Return value

NewLC()

Description

Parameters

Return value

NewL()

Description

Parameters

Return value

NewLC()

Description

Parameters

Return value