CPbkContactItem Class Reference

#include <app/CPbkContactItem.h>

class CPbkContactItem : public CBase

Inherits from

CPbkContactItem

Public Member Functions
	~CPbkContactItem()
IMPORT_C TPbkContactItemField &	AddFieldL(CPbkFieldInfo &)
IMPORT_C TPbkContactItemField *	AddOrReturnUnusedFieldL(CPbkFieldInfo &)
IMPORT_C TBool	CanAcceptDataOfType(CPbkFieldInfo &)
IMPORT_C CPbkFieldArray &	CardFields()
IMPORT_C TPbkIconId	ContactIconIdL()
IMPORT_C CContactItem &	ContactItem()
IMPORT_C const CContactItem &	ContactItem()
IMPORT_C TPbkContactItemField *	DefaultEmailField()
IMPORT_C TPbkContactItemField *	DefaultEmailOverSmsField()
IMPORT_C TPbkContactItemField *	DefaultMmsField()
IMPORT_C TPbkContactItemField *	DefaultPhoneNumberField()
IMPORT_C TPbkContactItemField *	DefaultPocField()
IMPORT_C TPbkContactItemField *	DefaultSmsField()
IMPORT_C TPbkContactItemField *	DefaultVideoNumberField()
IMPORT_C TPbkContactItemField *	DefaultVoipField()
IMPORT_C TInt	FindContactItemFieldIndex(const CContactItemField &)
IMPORT_C TPbkContactItemField *	FindField(TPbkFieldId)
IMPORT_C TPbkContactItemField *	FindField(TPbkFieldId, TInt &)
IMPORT_C TPbkContactItemField *	FindField(const CPbkFieldInfo &)
IMPORT_C TPbkContactItemField *	FindField(const CPbkFieldInfo &, TInt &)
IMPORT_C TInt	FindFieldIndex(const TPbkContactItemField &)
IMPORT_C TPbkContactItemField *	FindNextFieldWithPhoneNumber(const TDesC &, TInt, TInt &)
IMPORT_C TPbkContactItemField *	FindNextFieldWithText(const TDesC &, TInt &)
IMPORT_C TPbkContactItemField *	FindSameField(const TPbkContactItemField &)
IMPORT_C HBufC *	GetContactTitleL()
IMPORT_C HBufC *	GetContactTitleOrNullL()
IMPORT_C CContactIdArray *	GroupsJoinedLC()
IMPORT_C TContactItemId	Id()
IMPORT_C CPbkContactItem *	NewL(CContactItem *, const CPbkFieldsInfo &, MPbkContactNameFormat &)
MPbkFieldData &	PbkFieldAt(TInt)
const MPbkFieldData &	PbkFieldAt(TInt)
TInt	PbkFieldCount()
void	PrepareAfterLoadL()
void	PrepareForSaveL()
IMPORT_C void	RemoveDefaultEmailField()
IMPORT_C void	RemoveDefaultEmailOverSmsField()
IMPORT_C void	RemoveDefaultMmsField()
IMPORT_C void	RemoveDefaultPhoneNumberField()
IMPORT_C void	RemoveDefaultPocField()
IMPORT_C void	RemoveDefaultSmsField()
IMPORT_C void	RemoveDefaultVideoNumberField()
IMPORT_C void	RemoveDefaultVoipField()
IMPORT_C void	RemoveField(TInt)
IMPORT_C void	RemoveVoiceTagField()
IMPORT_C void	SetDefaultEmailFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultEmailOverSmsFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultMmsFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultPhoneNumberFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultPocFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultSmsFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultVideoNumberFieldL(TPbkContactItemField *)
IMPORT_C void	SetDefaultVoipFieldL(TPbkContactItemField *)
IMPORT_C void	SetVoiceTagFieldL(TPbkContactItemField *)
IMPORT_C TUid	Type()
IMPORT_C void	UpdateFieldSetL(const CPbkFieldsInfo &)
IMPORT_C TPbkContactItemField *	VoiceTagField()

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

Phonebook Contact item class. Contact items can be read from the contact database by using the Phonebook engine,

See also: CPbkContactEngine. This class extends Symbian Contacts model class CContactItem capabilities to better suit Phonebook application's needs.

Constructor & Destructor Documentation

~CPbkContactItem ( )

~CPbkContactItem

(

)

Destructor.

Member Function Documentation

AddFieldL ( CPbkFieldInfo & )

IMPORT_C TPbkContactItemField &

AddFieldL

(

CPbkFieldInfo &

aFieldInfo

)

Creates a new field based on aFieldInfo and adds it to this contact.

Parameter	Description
aFieldInfo	Type of field to create.

Returns: The created field.

AddOrReturnUnusedFieldL ( CPbkFieldInfo & )

IMPORT_C TPbkContactItemField *

AddOrReturnUnusedFieldL

(

CPbkFieldInfo &

aFieldInfo

)

Finds an unused or creates a new field based on aFieldInfo. An unused field is a field that is in the contact template, but doesnt contain any data, in other words it is empty. So a unused field is preferred ad the next field to add user data before adding a new field to the contact.

Parameter	Description
aFieldInfo	Type of field to search or create.

Returns: Pointer to the found or created field. NULL only if field exists AND field is nonempty AND aFieldInfo.Multiplicity()==EPbkFieldMultiplicityOne.

CanAcceptDataOfType ( CPbkFieldInfo & )

IMPORT_C TBool

CanAcceptDataOfType

(

CPbkFieldInfo &

aFieldInfo

)

const

Returns ETrue if data of type aFieldInfo can be added to this contact.

Parameter	Description
aFieldInfo	The field type that we are trying to add.

Returns: ETrue if the contact can accept this type of data, EFalse otherwise.

CardFields ( )

IMPORT_C CPbkFieldArray &

CardFields

(

)

const

Returns the field set of this contact item.

Returns: Field array of this contact item.

ContactIconIdL ( )

IMPORT_C TPbkIconId

ContactIconIdL

(

)

const

Returns an Phonebook icon id for a contact. This icon id is the icon of the field that is set as the default number to call.

Returns: Icon index for this contact, EPbkNullIconId for no icon.

ContactItem ( )

IMPORT_C CContactItem &

ContactItem

(

)

Converts this object to a CContactItem. Use only if this class's API is not enough.

Returns: The underlying Symbian Contacts model contact item object.

ContactItem ( )

IMPORT_C const CContactItem &

ContactItem

(

)

const

Converts this object to a const CContactItem. Use only if this class's API is not enough.

Returns: The underlying Symbian Contacts model contact item object.

DefaultEmailField ( )

IMPORT_C TPbkContactItemField *

DefaultEmailField

(

)

const

Returns the default email field of this contact.

Returns: Default email field of this contact, NULL if no default set.

DefaultEmailOverSmsField ( )

IMPORT_C TPbkContactItemField *

DefaultEmailOverSmsField

(

)

const

Returns the default EmailOverSms field of this contact.

Returns: Default EmailOverSms field of this contact, NULL if no default set.

DefaultMmsField ( )

IMPORT_C TPbkContactItemField *

DefaultMmsField

(

)

const

Returns the default Mms field of this contact.

Returns: Default Mms field of this contact, NULL if no default set.

DefaultPhoneNumberField ( )

IMPORT_C TPbkContactItemField *

DefaultPhoneNumberField

(

)

const

Returns the default phone number field of this contact.

Returns: Default phone number field of this contact, NULL if no default set.

DefaultPocField ( )

IMPORT_C TPbkContactItemField *

DefaultPocField

(

)

const

Returns the default Poc field of this contact.

Returns: Default Poc field of this contact, NULL if no default set.

DefaultSmsField ( )

IMPORT_C TPbkContactItemField *

DefaultSmsField

(

)

const

Returns the default SMS field of this contact.

Returns: Default SMS field of this contact, NULL if no default set.

DefaultVideoNumberField ( )

IMPORT_C TPbkContactItemField *

DefaultVideoNumberField

(

)

const

Returns the default video number field of this contact.

Returns: Default video number field of this contact, NULL if no default set.

DefaultVoipField ( )

IMPORT_C TPbkContactItemField *

DefaultVoipField

(

)

const

Returns the default VOIP field of this contact.

Returns: Default VOIP field of this contact, NULL if no default set.

FindContactItemFieldIndex ( const CContactItemField & )

IMPORT_C TInt

FindContactItemFieldIndex

(

const CContactItemField &

aField

)

const

Returns aField's index from ContactItem()'s CardFields() or KErrNotFound if not found.

Parameter	Description
aField	The field which index we are querying.

Returns: The fields index in this contact item, KErrNotFound is not found.

FindField ( TPbkFieldId )

IMPORT_C TPbkContactItemField *

FindField

(

TPbkFieldId

aFieldId

)

const

Returns first field matching aFieldId.

Parameter	Description
aFieldId	Field id to search.

Returns: First field matching aFieldId, NULL if none found.

FindField ( TPbkFieldId, TInt & )

IMPORT_C TPbkContactItemField *	FindField	(	TPbkFieldId	aFieldId,
			TInt &	aIndex
		)	const

Returns first field matching aFieldId starting from aIndex.

Parameter	Description
aFieldId	Field id to search.
aIndex	Input: field index where to start the search from, output: index of the found field or -1 if not found.

Returns: Field matching aFieldId, NULL if none found.

FindField ( const CPbkFieldInfo & )

IMPORT_C TPbkContactItemField *

FindField

(

const CPbkFieldInfo &

aFieldInfo

)

const

Returns first field matching aFieldInfo.

Parameter	Description
aFieldInfo	Field type to find from the contact.

Returns: First field matching aFieldInfo, NULL if none found.

FindField ( const CPbkFieldInfo &, TInt & )

IMPORT_C TPbkContactItemField *	FindField	(	const CPbkFieldInfo &	aFieldInfo,
			TInt &	aIndex
		)	const

Returns first field matching aFieldInfo starting from aIndex.

Parameter	Description
aFieldInfo	Field type to find from the contact.
aIndex	Input: field index where to start the search from, output: index of the found field or -1 if not found.

Returns: Field matching aFieldInfo, NULL if none found.

FindFieldIndex ( const TPbkContactItemField & )

IMPORT_C TInt

FindFieldIndex

(

const TPbkContactItemField &

aField

)

const

Returns aField's index from this contact item.

Parameter	Description
aField	Field to search for. Field is matched with TPbkContactItemField::IsSame -function.

FindNextFieldWithPhoneNumber ( const TDesC &, TInt, TInt & )

IMPORT_C TPbkContactItemField *	FindNextFieldWithPhoneNumber	(	const TDesC &	aNumber,
			TInt	aNumberOfDigits,
			TInt &	aIndex
		)	const

Searches phone number fields of this contact for a match. Uses PbkEngUtils::ContainSameDigits to perform the matching.

Parameter	Description
aNumber	Phone number to match to.
aNumberOfDigits	Number of digits to compare from the end of the phone numbers. Full comparison performed if 0.
aIndex	Input: field index where to start the search from, output: index of the found field or KErrNotFound if not found.

Returns: The matching field, NULL if not found.

FindNextFieldWithText ( const TDesC &, TInt & )

IMPORT_C TPbkContactItemField *	FindNextFieldWithText	(	const TDesC &	aText,
			TInt &	aIndex
		)	const

Searches for a text in this contact's fields. Uses TDesC::FindF() search the text from the fields.

Parameter	Description
aIndex	Input: field index from where to start the search, Output: index of the found field or KErrNotFound if not found.

FindSameField ( const TPbkContactItemField & )

IMPORT_C TPbkContactItemField *

FindSameField

(

const TPbkContactItemField &

aField

)

const

Returns field matching aField from this contact item's field set, NULL if not found.

Parameter	Description
aField	The field that we a mathing.

Returns: Matching field or NULL if not found. !FindSameField(field) || FindSameField(field)->IsSame(field)

GetContactTitleL ( )

IMPORT_C HBufC *

GetContactTitleL

(

)

const

Gets a title text for this contact or localized unnamed text.

Returns: A buffer containing the title or localized unnamed text if no title can be generated. Caller is responsible for deleting the returned buffer.

GetContactTitleOrNullL ( )

IMPORT_C HBufC *

GetContactTitleOrNullL

(

)

const

Gets a title text for this contact.

Returns: A buffer containing the title text, NULL if title is empty. Caller is responsible for deleting the returned buffer.

GroupsJoinedLC ( )

IMPORT_C CContactIdArray *

GroupsJoinedLC

(

)

const

Gets the groups this contact belongs to.

See also: CContactItem::GroupsJoinedLC()

Returns: Array of group ids. Caller owns the array.

Id ( )

IMPORT_C TContactItemId

(

)

const

Returns this contact item's id.

NewL ( CContactItem *, const CPbkFieldsInfo &, MPbkContactNameFormat & )

IMPORT_C CPbkContactItem *	NewL	(	CContactItem *	aItem,
			const CPbkFieldsInfo &	aFieldsInfo,
			MPbkContactNameFormat &	aNameFormat
		)	[static]

Creates an instance of this class.

Parameter	Description
aItem	Contact item this object wraps. This object takes ownership of aItem. If this function leaves, ownership is not taken.
aFieldsInfo	Collection of Phonebook field types.
aNameFormat	Contact name formatter.

Returns: A new instance of this class.

PbkFieldAt ( TInt )

MPbkFieldData &

PbkFieldAt

(

TInt

aIndex

)

PbkFieldAt ( TInt )

const MPbkFieldData &

PbkFieldAt

(

TInt

aIndex

)

const

PbkFieldCount ( )

TInt

PbkFieldCount

(

)

const

PrepareAfterLoadL ( )

void

PrepareAfterLoadL

(

)

PrepareForSaveL ( )

void

PrepareForSaveL

(

)

RemoveDefaultEmailField ( )

IMPORT_C void

RemoveDefaultEmailField

(

)

Removes email field default from this contact.

DefaultEmailField()==NULL.

RemoveDefaultEmailOverSmsField ( )

IMPORT_C void

RemoveDefaultEmailOverSmsField

(

)

Removes EmailOverSms field default from this contact.

DefaultEmailOverSmsField()==NULL.

RemoveDefaultMmsField ( )

IMPORT_C void

RemoveDefaultMmsField

(

)

Removes MMS field default from this contact.

DefaultMmsField()==NULL.

RemoveDefaultPhoneNumberField ( )

IMPORT_C void

RemoveDefaultPhoneNumberField

(

)

Removes phone number default from this contact.

DefaultPhoneNumberField()==NULL.

RemoveDefaultPocField ( )

IMPORT_C void

RemoveDefaultPocField

(

)

Removes POC field default from this contact.

DefaultPocField()==NULL.

RemoveDefaultSmsField ( )

IMPORT_C void

RemoveDefaultSmsField

(

)

Removes SMS field default from this contact.

DefaultSmsField()==NULL.

RemoveDefaultVideoNumberField ( )

IMPORT_C void

RemoveDefaultVideoNumberField

(

)

Removes video number default from this contact.

DefaultVideoNumberField()==NULL.

RemoveDefaultVoipField ( )

IMPORT_C void

RemoveDefaultVoipField

(

)

Removes VOIP field default from this contact.

DefaultVoipField()==NULL.

RemoveField ( TInt )

IMPORT_C void

RemoveField

(

TInt

aIndex

)

Deletes field at aIndex.

Parameter	Description
aIndex	Field index to delete from the contact item.

RemoveVoiceTagField ( )

IMPORT_C void

RemoveVoiceTagField

(

)

Removes any voice tag mark from this contact.

VoiceTagField()==NULL. Deprecated

SetDefaultEmailFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultEmailFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default email address field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not an email field.

Parameter	Description
aField	Field to set as default, if NULL email default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultEmailOverSmsFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultEmailOverSmsFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default Sms With Email address field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not an email field.

Parameter	Description
aField	Field to set as default, if NULL Sms With Email default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultMmsFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultMmsFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default MMS address field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not an email field.

Parameter	Description
aField	Field to set as default, if NULL MMS default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultPhoneNumberFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultPhoneNumberFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default phone number field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not a phone number field.

Parameter	Description
aField	Field to set as default, if NULL phone number default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultPocFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultPocFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default POC address field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not an email field.

Parameter	Description
aField	Field to set as default, if NULL POC default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultSmsFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultSmsFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default SMS field to aField.

Exceptions

KErrNotFound	if aField is not this contact's field.
KErrNotSupported	if aField is not a phone number field.

Parameter	Description
aField	Field to set as default, if NULL SMS default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultVideoNumberFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultVideoNumberFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default video number field to aField.

Exceptions

KErrNotFound	if aField is not this contact's field.
KErrNotSupported	if aField is not a phone number field.

Parameter	Description
aField	Field to set as default, if NULL video number default is removed. Guaranteed not to leave if aField is NULL.

SetDefaultVoipFieldL ( TPbkContactItemField * )

IMPORT_C void

SetDefaultVoipFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default VOIP address field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not an email field.

Parameter	Description
aField	Field to set as default, if NULL VOIP default is removed. Guaranteed not to leave if aField is NULL.

SetVoiceTagFieldL ( TPbkContactItemField * )

IMPORT_C void

SetVoiceTagFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's voice tag field to aField.

Exceptions

KErrNotFound	If aField is not this contact's field.
KErrNotSupported	If aField is not a phone number field. (aField && VoiceTagField()->IsSame(*aField)) \|\| (!aField && !VoiceTagField())

Deprecated

Parameter	Description
aField	Field to set as default, if NULL voice tag mark is removed. Guaranteed not to leave if aField is NULL.

Type ( )

IMPORT_C TUid

Type

(

)

const

Returns type of this contact item. The contact types are documented in the Symbian Contacts model CContactItem::Type().

UpdateFieldSetL ( const CPbkFieldsInfo & )

IMPORT_C void

UpdateFieldSetL

(

const CPbkFieldsInfo &

aFieldsInfo

)

Updates this contacts field set to match the field set of the owned CContactItem. No need to call unless contact item's field set has been manipulated directly. In other words remaps the field types of this contact item from the underlying Symbian Contacts model contact item.

Parameter	Description
aFieldsInfo	The new fields set for this contact.

VoiceTagField ( )

IMPORT_C TPbkContactItemField *

VoiceTagField

(

)

const

Returns the voice tag field of this contact. NOTE: If this function is unable to make a connection to the voice tag handling system for some reason, this function will return null.

Deprecated

Returns: Voice tag field of this contact, NULL if no voice tag set.