CContactItemField Class Reference

#include <app/cntfield.h>

Link against: cntmodel.lib

class CContactItemField : public CBase

Inherits from

  • CContactItemField
    Public Member Functions
    ~CContactItemField()
    IMPORT_C voidAddFieldTypeL(TFieldType)
    IMPORT_C CContactAgentField *AgentStorage()
    IMPORT_C const CContentType &ContentType()
    voidCopyStorageL(const CContactItemField &)
    IMPORT_C CContactDateField *DateTimeStorage()
    TBool DoSynchronize()
    voidExternalizeL(RWriteStream &)
    IMPORT_C voidGetFieldText(TDes &)
    IMPORT_C TBoolHasCustomFilter(EContactFieldFlags &)
    TBool HasExtraStream()
    IMPORT_C TIntId()
    voidInternalizeL(RReadStream &)
    TBool IsCustomFilterable()
    TBool IsDeleted()
    TBool IsDisabled()
    TBool IsHidden()
    TBool IsPrivate()
    TBool IsReadOnly()
    TBool IsSpeedDial()
    TBool IsTemplate()
    IMPORT_C TBoolIsTemplateLabelField()
    IMPORT_C TBoolIsValidLabel(const TDesC &, TInt &)
    IMPORT_C TPtrCLabel()
    TBool LabelUnspecified()
    IMPORT_C CContactItemField *NewL(TStorageType)
    IMPORT_C CContactItemField *NewL(TStorageType, TFieldType)
    IMPORT_C CContactItemField *NewL(const CContactItemField &)
    IMPORT_C CContactItemField *NewL(TStorageType, const CContentType &)
    IMPORT_C CContactItemField *NewLC()
    IMPORT_C CContactItemField *NewLC(TStorageType)
    IMPORT_C CContactItemField *NewLC(TStorageType, TFieldType)
    IMPORT_C CContactItemField *NewLC(const CContactItemField &)
    IMPORT_C CContactItemField *NewLC(TStorageType, const CContentType &)
    TBool OverRidesLabel()
    voidPopulateStoreL(RStoreWriteStream &, TInt, CArrayFix< TFieldHeader > &)
    voidPrepareFieldAsTemplateL(CContactItemFieldSet &)
    IMPORT_C voidRemoveFieldType(TFieldType)
    IMPORT_C voidReset()
    IMPORT_C voidResetStore()
    IMPORT_C TStreamIdRestoreFieldTypesL(RReadStream &, const CContactItemFieldSet *)
    IMPORT_C voidRestoreHeaderL(RReadStream &, const CContactItemFieldSet *)
    IMPORT_C TBoolRestoreIfMatchL(RReadStream &, const CContactItemFieldDef *, const CContactItemFieldSet *, HBufC *, TInt)
    TBool RestoreIfMatchL(RReadStream &, TFieldType, const CContactItemFieldSet *, HBufC *, TInt)
    IMPORT_C voidRestoreTextL(HBufC *, TInt)
    IMPORT_C voidSetCustomFilterable(EContactFieldFlags)
    voidSetDeleted(TBool)
    IMPORT_C voidSetDisabled(TBool)
    IMPORT_C voidSetHidden(TBool)
    IMPORT_C voidSetHintType(TInt)
    IMPORT_C voidSetId(TInt)
    IMPORT_C voidSetLabel(HBufC *)
    IMPORT_C voidSetLabelL(const TDesC &)
    IMPORT_C voidSetMapping(TUid)
    voidSetOverRidesLabel(TBool)
    IMPORT_C voidSetPrivate(TBool)
    IMPORT_C voidSetReadOnly(TBool)
    IMPORT_C voidSetSpeedDial(TBool)
    IMPORT_C voidSetSynchronize(TBool)
    IMPORT_C voidSetTemplateField(TBool)
    IMPORT_C voidSetUserAddedField(TBool)
    IMPORT_C voidSetUserFlags(TUint)
    voidSetUsesTemplateTypes(TBool)
    IMPORT_C CContactFieldStorage *Storage()
    IMPORT_C TStorageTypeStorageType()
    IMPORT_C CContactStoreField *StoreStorage()
    TInt TemplateFieldId()
    IMPORT_C CContactTextField *TextStorage()
    voidUpdateFieldFlags(const CContactItemFieldSet &)
    TBool UserAddedField()
    IMPORT_C TUintUserFlags()
    TBool UsesTemplateTypes()
    Protected Member Functions
    voidUsesTemplateData(TInt)
    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()

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

    Constructor & Destructor Documentation

    ~CContactItemField ( )

    IMPORT_C~CContactItemField()

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

    Member Function Documentation

    AddFieldTypeL ( TFieldType )

    IMPORT_C voidAddFieldTypeL(TFieldTypeaFieldType)

    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.

    ParameterDescription
    aFieldTypeThe field type to append to the field's content type.

    AgentStorage ( )

    IMPORT_C CContactAgentField *AgentStorage()const

    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.

    Returns: Field's storage as a CContactAgentField*.

    ContentType ( )

    IMPORT_C const CContentType &ContentType()const

    Gets the field's content type.

    Returns: Reference to the field's content type.

    CopyStorageL ( const CContactItemField & )

    voidCopyStorageL(const CContactItemField &aField)

    DateTimeStorage ( )

    IMPORT_C CContactDateField *DateTimeStorage()const

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

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

    Returns: Field's storage as a CContactDateField*.

    DoSynchronize ( )

    TBool DoSynchronize()const [inline]

    Gets the value of the field's synchronise attribute.

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

    ExternalizeL ( RWriteStream & )

    voidExternalizeL(RWriteStream &aStream)const

    Externalises a CContactItemField object to a write stream.

    ParameterDescription
    aStreamStream to which the object should be externalised.

    GetFieldText ( TDes & )

    IMPORT_C voidGetFieldText(TDes &aText)const

    HasCustomFilter ( EContactFieldFlags & )

    IMPORT_C TBoolHasCustomFilter(EContactFieldFlags &contactFieldFlag)const

    Determine if a custom filter exists. If it does, return the filter type.

    ParameterDescription
    contactFieldFlagThe custom filter type if one exists.

    Returns: ETrue if custom filter exists.

    HasExtraStream ( )

    TBool HasExtraStream()const [inline]

    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.

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

    Id ( )

    IMPORT_C TIntId()const

    Gets the field ID.

    Returns: The field ID.

    InternalizeL ( RReadStream & )

    voidInternalizeL(RReadStream &aStream)

    Internalises a CContactItemField object from a read stream.

    ParameterDescription
    aStreamStream from which the object should be internalised.

    IsCustomFilterable ( )

    TBool IsCustomFilterable()const [inline]

    Tests the value of the user defined filter attribute.

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

    IsDeleted ( )

    TBool IsDeleted()const [inline]

    Gets the value of the field's deleted attribute.

    Returns: ETrue if the field is deleted, otherwise EFalse.

    IsDisabled ( )

    TBool IsDisabled()const [inline]

    Gets the value of the field's disabled attribute.

    Returns: ETrue if disabled attribute set, EFalse if not set.

    IsHidden ( )

    TBool IsHidden()const [inline]

    Gets the value of the field's hidden attribute.

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

    IsPrivate ( )

    TBool IsPrivate()const [inline]

    Tests whether the field's private attribute is set.

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

    IsReadOnly ( )

    TBool IsReadOnly()const [inline]

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

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

    IsSpeedDial ( )

    TBool IsSpeedDial()const [inline]

    Tests whether the field is a speed dial field.

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

    IsTemplate ( )

    TBool IsTemplate()const [inline]

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

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

    IsTemplateLabelField ( )

    IMPORT_C TBoolIsTemplateLabelField()const

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

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

    IsValidLabel ( const TDesC &, TInt & )

    IMPORT_C TBoolIsValidLabel(const TDesC &aLabel,
    TInt &aInvalidPos
    )[static]

    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)

    ParameterDescription
    aLabelThe field label to test.
    aInvalidPosOn return, contains the character position within the label of the first invalid character. The first character position is zero.

    Returns: ETrue if valid, EFalse if invalid.

    Label ( )

    IMPORT_C TPtrCLabel()const

    Gets the field's label.

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

    LabelUnspecified ( )

    TBool LabelUnspecified()const [inline]

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

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

    NewL ( TStorageType )

    IMPORT_C CContactItemField *NewL(TStorageTypeaType)[static]

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

    The field's label and content type are unspecified.

    ParameterDescription
    aTypeThe field's storage type.

    Returns: Pointer to the newly created contact item field.

    NewL ( TStorageType, TFieldType )

    IMPORT_C CContactItemField *NewL(TStorageTypeaType,
    TFieldTypeaFieldType
    )[static]

    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.

    ParameterDescription
    aTypeThe field's storage type.
    aFieldTypeThe field type as defined in cntdef.h.

    Returns: Pointer to the newly created contact item field.

    NewL ( const CContactItemField & )

    IMPORT_C CContactItemField *NewL(const CContactItemField &aField)[static]

    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.

    ParameterDescription
    aFieldThe contact field to copy.

    Returns: Pointer to the newly created contact item field.

    NewL ( TStorageType, const CContentType & )

    IMPORT_C CContactItemField *NewL(TStorageTypeaType,
    const CContentType &aContentType
    )[static]

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

    The field's label is unspecified.

    ParameterDescription
    aTypeThe field's storage type.
    aContentTypeThe field's content type.

    Returns: Pointer to the newly created contact item field.

    NewLC ( )

    IMPORT_C CContactItemField *NewLC()[static]

    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.

    Returns: Pointer to the newly created contact item field.

    NewLC ( TStorageType )

    IMPORT_C CContactItemField *NewLC(TStorageTypeaType)[static]

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

    The field's label and content type are unspecified.

    ParameterDescription
    aTypeThe field's storage type.

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

    NewLC ( TStorageType, TFieldType )

    IMPORT_C CContactItemField *NewLC(TStorageTypeaType,
    TFieldTypeaFieldType
    )[static]

    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.

    ParameterDescription
    aTypeThe field's storage type.
    aFieldTypeThe field type as defined in cntdef.h.

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

    NewLC ( const CContactItemField & )

    IMPORT_C CContactItemField *NewLC(const CContactItemField &aField)[static]

    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.

    ParameterDescription
    aFieldThe contact field to copy.

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

    NewLC ( TStorageType, const CContentType & )

    IMPORT_C CContactItemField *NewLC(TStorageTypeaType,
    const CContentType &aContentType
    )[static]

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

    The field's label is unspecified.

    ParameterDescription
    aTypeThe field's storage type.
    aContentTypeThe field's content type.

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

    OverRidesLabel ( )

    TBool OverRidesLabel()const [inline]

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

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

    PopulateStoreL ( RStoreWriteStream &, TInt, CArrayFix< TFieldHeader > & )

    voidPopulateStoreL(RStoreWriteStream &aRootStream,
    TIntaCount,
    CArrayFix< TFieldHeader > &aFieldHeaderArray
    )const

    Part of the system template update implementation. This could be used for a generic update method at a later stage.

    PrepareFieldAsTemplateL ( CContactItemFieldSet & )

    voidPrepareFieldAsTemplateL(CContactItemFieldSet &aSystemTemplateFieldSet)
    Part of the system template update implementation. This could be used for a generic update method at a later stage.
    Since
    7.0

    RemoveFieldType ( TFieldType )

    IMPORT_C voidRemoveFieldType(TFieldTypeaFieldType)

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

    ParameterDescription
    aFieldTypeThe field type to remove from the field's content type.

    Reset ( )

    IMPORT_C voidReset()

    ResetStore ( )

    IMPORT_C voidResetStore()

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

    RestoreFieldTypesL ( RReadStream &, const CContactItemFieldSet * )

    IMPORT_C TStreamIdRestoreFieldTypesL(RReadStream &aRootStream,
    const CContactItemFieldSet *aSystemTemplateFields
    )

    Decode given blob header stream into contact field relevent data.

    ParameterDescription
    aRootStreamreference to the blob header stream to be decoded.
    aSystemTemplateFieldscached template fields.

    Returns: the stream id of content data stored in data store

    RestoreHeaderL ( RReadStream &, const CContactItemFieldSet * )

    IMPORT_C voidRestoreHeaderL(RReadStream &aStream,
    const CContactItemFieldSet *aSystemTemplateFields
    )

    RestoreIfMatchL ( RReadStream &, const CContactItemFieldDef *, const CContactItemFieldSet *, HBufC *, TInt )

    IMPORT_C TBoolRestoreIfMatchL(RReadStream &aStream,
    const CContactItemFieldDef *aFieldDef,
    const CContactItemFieldSet *aSystemTemplateFields,
    HBufC *aTextStream,
    TIntaTextIndex
    )

    RestoreIfMatchL ( RReadStream &, TFieldType, const CContactItemFieldSet *, HBufC *, TInt )

    TBool RestoreIfMatchL(RReadStream &aStream,
    TFieldTypeaFieldType,
    const CContactItemFieldSet *aSystemTemplateFields,
    HBufC *aTextStream,
    TIntaTextIndex
    )

    RestoreTextL ( HBufC *, TInt )

    IMPORT_C voidRestoreTextL(HBufC *aTextStream,
    TIntaTextFieldIndex
    )

    SetCustomFilterable ( EContactFieldFlags )

    IMPORT_C voidSetCustomFilterable(EContactFieldFlagsaContactFilterType)

    SetDeleted ( TBool )

    voidSetDeleted(TBoolaDeleted)

    SetDisabled ( TBool )

    IMPORT_C voidSetDisabled(TBoolaDisabled)

    Sets the value of the disabled attribute.

    ParameterDescription
    aDisabledETrue to set the disabled attribute, EFalse to unset the attribute.

    SetHidden ( TBool )

    IMPORT_C voidSetHidden(TBoolaHidden)

    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.

    ParameterDescription
    aHiddenETrue for hidden, EFalse for displayed.

    SetHintType ( TInt )

    IMPORT_C voidSetHintType(TIntaType)

    SetId ( TInt )

    IMPORT_C voidSetId(TIntaId)

    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.

    ParameterDescription
    aIdThe new field ID.

    SetLabel ( HBufC * )

    IMPORT_C voidSetLabel(HBufC *aLabel)

    Sets the field label.

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

    ParameterDescription
    aLabelThe new field label.

    SetLabelL ( const TDesC & )

    IMPORT_C voidSetLabelL(const TDesC &aLabel)

    Sets the field label.

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

    ParameterDescription
    aLabelThe new field label.

    SetMapping ( TUid )

    IMPORT_C voidSetMapping(TUidaMapping)

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

    ParameterDescription
    aMappingThe new mapping for the field's content type.

    SetOverRidesLabel ( TBool )

    voidSetOverRidesLabel(TBoolaValue)

    SetPrivate ( TBool )

    IMPORT_C voidSetPrivate(TBoolaTemplateField)

    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.

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

    SetReadOnly ( TBool )

    IMPORT_C voidSetReadOnly(TBoolaReadOnly)

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

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

    SetSpeedDial ( TBool )

    IMPORT_C voidSetSpeedDial(TBoolaSpeedDialField)

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

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

    SetSynchronize ( TBool )

    IMPORT_C voidSetSynchronize(TBoolaSynchronize)

    Sets the value of the field's synchronise attribute.

    ParameterDescription
    aSynchronizeETrue to set synchronise attribute, EFalse to unset it.

    SetTemplateField ( TBool )

    IMPORT_C voidSetTemplateField(TBoolaTemplateField)

    Sets whether the field is a template field.

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

    SetUserAddedField ( TBool )

    IMPORT_C voidSetUserAddedField(TBoolaUserAddedField)

    Sets the user added field attribute.

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

    SetUserFlags ( TUint )

    IMPORT_C voidSetUserFlags(TUintaFlags)

    Sets the value of the user flags.

    ParameterDescription
    aFlagsThe user flags value.

    SetUsesTemplateTypes ( TBool )

    voidSetUsesTemplateTypes(TBoolaUsesTemplateTypes)

    Storage ( )

    IMPORT_C CContactFieldStorage *Storage()const

    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().

    Returns: The field's base storage type.

    StorageType ( )

    IMPORT_C TStorageTypeStorageType()const

    Gets the field's storage type.

    Returns: The field's storage type.

    StoreStorage ( )

    IMPORT_C CContactStoreField *StoreStorage()const

    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.

    Returns: Field's storage as a CContactStoreField*.

    TemplateFieldId ( )

    TInt TemplateFieldId()const

    TextStorage ( )

    IMPORT_C CContactTextField *TextStorage()const

    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.

    Returns: The field's storage as a CContactTextField*.

    UpdateFieldFlags ( const CContactItemFieldSet & )

    voidUpdateFieldFlags(const CContactItemFieldSet &aTemplateFieldSet)

    UserAddedField ( )

    TBool UserAddedField()const [inline]

    Gets the value of the user added field attribute.

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

    UserFlags ( )

    IMPORT_C TUintUserFlags()const

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

    Returns: The user flags value.

    UsesTemplateData ( TInt )

    voidUsesTemplateData(TIntaTemplateFieldId)[protected]

    UsesTemplateTypes ( )

    TBool UsesTemplateTypes()const [inline]

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

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