CPbkContactItem Class Reference

API published in: S60 1st Ed
API deprecated in: S60 5th Ed

Link against: pbkeng.lib

Capability Information

Required Capabilities

ReadUserData WriteUserData

#include <cpbkcontactitem.h>

Inherits MPbkFieldDataArray.

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.


Public Member Functions
	~CPbkContactItem ()
	Destructor.
IMPORT_C TContactItemId	Id () const
	Returns this contact item's id.
IMPORT_C TUid	Type () const
	Returns type of this contact item.
IMPORT_C CContactIdArray *	GroupsJoinedLC () const
	Gets the groups this contact belongs to.
IMPORT_C CContactItem &	ContactItem ()
	Converts this object to a CContactItem.
IMPORT_C const CContactItem &	ContactItem () const
	Converts this object to a const CContactItem.
IMPORT_C CPbkFieldArray &	CardFields () const
	Returns the field set of this contact item.
IMPORT_C TPbkContactItemField &	AddFieldL (CPbkFieldInfo &aFieldInfo)
	Creates a new field based on aFieldInfo and adds it to this contact.
IMPORT_C TBool	CanAcceptDataOfType (CPbkFieldInfo &aFieldInfo) const
	Returns ETrue if data of type aFieldInfo can be added to this contact.
IMPORT_C TPbkContactItemField *	AddOrReturnUnusedFieldL (CPbkFieldInfo &aFieldInfo)
	Finds an unused or creates a new field based on aFieldInfo.
IMPORT_C void	RemoveField (TInt aIndex)
	Deletes field at aIndex.
IMPORT_C void	UpdateFieldSetL (const CPbkFieldsInfo &aFieldsInfo)
	Updates this contacts field set to match the field set of the owned CContactItem.
IMPORT_C TPbkContactItemField *	FindField (TPbkFieldId aFieldId) const
	Returns first field matching aFieldId.
IMPORT_C TPbkContactItemField *	FindField (TPbkFieldId aFieldId, TInt &aIndex) const
	Returns first field matching aFieldId starting from aIndex.
IMPORT_C TPbkContactItemField *	FindField (const CPbkFieldInfo &aFieldInfo) const
	Returns first field matching aFieldInfo.
IMPORT_C TPbkContactItemField *	FindField (const CPbkFieldInfo &aFieldInfo, TInt &aIndex) const
	Returns first field matching aFieldInfo starting from aIndex.
IMPORT_C TInt	FindFieldIndex (const TPbkContactItemField &aField) const
	Returns aField's index from this contact item.
IMPORT_C TInt	FindContactItemFieldIndex (const CContactItemField &aField) const
	Returns aField's index from ContactItem()'s CardFields() or KErrNotFound if not found.
IMPORT_C TPbkContactItemField *	FindNextFieldWithPhoneNumber (const TDesC &aNumber, TInt aNumberOfDigits, TInt &aIndex) const
	Searches phone number fields of this contact for a match.
IMPORT_C TPbkContactItemField *	FindNextFieldWithText (const TDesC &aText, TInt &aIndex) const
	Searches for a text in this contact's fields.
IMPORT_C TPbkContactItemField *	FindSameField (const TPbkContactItemField &aField) const
	Returns field matching aField from this contact item's field set, NULL if not found.
IMPORT_C HBufC *	GetContactTitleL () const
	Gets a title text for this contact or localized unnamed text.
IMPORT_C HBufC *	GetContactTitleOrNullL () const
	Gets a title text for this contact.
IMPORT_C TPbkIconId	ContactIconIdL () const
	Returns an Phonebook icon id for a contact.
IMPORT_C TPbkContactItemField *	DefaultPhoneNumberField () const
	Returns the default phone number field of this contact.
IMPORT_C void	SetDefaultPhoneNumberFieldL (TPbkContactItemField *aField)
	Sets this contact's default phone number field to aField.
IMPORT_C void	RemoveDefaultPhoneNumberField ()
	Removes phone number default from this contact.
IMPORT_C TPbkContactItemField *	DefaultVideoNumberField () const
	Returns the default video number field of this contact.
IMPORT_C void	SetDefaultVideoNumberFieldL (TPbkContactItemField *aField)
	Sets this contact's default video number field to aField.
IMPORT_C void	RemoveDefaultVideoNumberField ()
	Removes video number default from this contact.
IMPORT_C TPbkContactItemField *	DefaultSmsField () const
	Returns the default SMS field of this contact.
IMPORT_C void	SetDefaultSmsFieldL (TPbkContactItemField *aField)
	Sets this contact's default SMS field to aField.
IMPORT_C void	RemoveDefaultSmsField ()
	Removes SMS field default from this contact.
IMPORT_C TPbkContactItemField *	DefaultEmailField () const
	Returns the default email field of this contact.
IMPORT_C void	SetDefaultEmailFieldL (TPbkContactItemField *aField)
	Sets this contact's default email address field to aField.
IMPORT_C void	RemoveDefaultEmailField ()
	Removes email field default from this contact.
IMPORT_C TPbkContactItemField *	DefaultMmsField () const
	Returns the default Mms field of this contact.
IMPORT_C void	SetDefaultMmsFieldL (TPbkContactItemField *aField)
	Sets this contact's default MMS address field to aField.
IMPORT_C void	RemoveDefaultMmsField ()
	Removes MMS field default from this contact.
IMPORT_C TPbkContactItemField *	DefaultPocField () const
	Returns the default Poc field of this contact.
IMPORT_C void	SetDefaultPocFieldL (TPbkContactItemField *aField)
	Sets this contact's default POC address field to aField.
IMPORT_C void	RemoveDefaultPocField ()
	Removes POC field default from this contact.
IMPORT_C TPbkContactItemField *	DefaultVoipField () const
	Returns the default VOIP field of this contact.
IMPORT_C void	SetDefaultVoipFieldL (TPbkContactItemField *aField)
	Sets this contact's default VOIP address field to aField.
IMPORT_C void	RemoveDefaultVoipField ()
	Removes VOIP field default from this contact.
IMPORT_C TPbkContactItemField *	DefaultEmailOverSmsField () const
	Returns the default EmailOverSms field of this contact.
IMPORT_C void	SetDefaultEmailOverSmsFieldL (TPbkContactItemField *aField)
	Sets this contact's default Sms With Email address field to aField.
IMPORT_C void	RemoveDefaultEmailOverSmsField ()
	Removes EmailOverSms field default from this contact.
IMPORT_C TPbkContactItemField *	VoiceTagField () const
	Returns the voice tag field of this contact.
IMPORT_C void	SetVoiceTagFieldL (TPbkContactItemField *aField)
	Sets this contact's voice tag field to aField.
IMPORT_C void	RemoveVoiceTagField ()
	Removes any voice tag mark from this contact.
TInt	PbkFieldCount () const
	Returns the number of field data objects in this array.
MPbkFieldData &	PbkFieldAt (TInt aIndex)
	Returns the field data object at aIndex.
const MPbkFieldData &	PbkFieldAt (TInt aIndex) const
	Returns the const field data object at aIndex.
void	PrepareForSaveL ()
void	PrepareAfterLoadL ()
Static Public Member Functions
static IMPORT_C CPbkContactItem *	NewL (CContactItem *aItem, const CPbkFieldsInfo &aFieldsInfo, MPbkContactNameFormat &aNameFormat)
	Creates an instance of this class.
Friends
IMPORT_C TBool	operator== (const CPbkContactItem &aLeft, const CPbkContactItem &aRight)
	Returns ETrue if aLeft and aRight contents are the same.

Constructor & Destructor Documentation

CPbkContactItem::~CPbkContactItem

(

)

Destructor.

Member Function Documentation

IMPORT_C TPbkContactItemField& CPbkContactItem::AddFieldL

(

CPbkFieldInfo &

aFieldInfo

)

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

Parameters:

aFieldInfo

Type of field to create.

Returns:: The created field.

IMPORT_C TPbkContactItemField* CPbkContactItem::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.

Parameters:

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.

IMPORT_C TBool CPbkContactItem::CanAcceptDataOfType

(

CPbkFieldInfo &

aFieldInfo

)

const

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

Parameters:

aFieldInfo

The field type that we are trying to add.

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

IMPORT_C CPbkFieldArray& CPbkContactItem::CardFields

(

)

const

Returns the field set of this contact item.

Returns:: Field array of this contact item.

IMPORT_C TPbkIconId CPbkContactItem::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.

IMPORT_C const CContactItem& CPbkContactItem::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.

IMPORT_C CContactItem& CPbkContactItem::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.

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultEmailField

(

)

const

Returns the default email field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultEmailOverSmsField

(

)

const

Returns the default EmailOverSms field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultMmsField

(

)

const

Returns the default Mms field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultPhoneNumberField

(

)

const

Returns the default phone number field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultPocField

(

)

const

Returns the default Poc field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultSmsField

(

)

const

Returns the default SMS field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultVideoNumberField

(

)

const

Returns the default video number field of this contact.

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

IMPORT_C TPbkContactItemField* CPbkContactItem::DefaultVoipField

(

)

const

Returns the default VOIP field of this contact.

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

IMPORT_C TInt CPbkContactItem::FindContactItemFieldIndex

(

const CContactItemField &

aField

)

const

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

Parameters:

aField

The field which index we are querying.

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

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

Returns first field matching aFieldInfo starting from aIndex.

Parameters:

	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.

IMPORT_C TPbkContactItemField* CPbkContactItem::FindField

(

const CPbkFieldInfo &

aFieldInfo

)

const

Returns first field matching aFieldInfo.

Parameters:

aFieldInfo

Field type to find from the contact.

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

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

Returns first field matching aFieldId starting from aIndex.

Parameters:

	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.

IMPORT_C TPbkContactItemField* CPbkContactItem::FindField

(

TPbkFieldId

aFieldId

)

const

Returns first field matching aFieldId.

Parameters:

aFieldId

Field id to search.

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

IMPORT_C TInt CPbkContactItem::FindFieldIndex

(

const TPbkContactItemField &

aField

)

const

Returns aField's index from this contact item.

Parameters:

aField

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

Returns:: Index of aField in this contact item's field set, KErrNotFound if not found.

See also:: TPbkContactItemField::IsSame

IMPORT_C TPbkContactItemField* CPbkContactItem::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.

Parameters:

	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.

See also:: PbkEngUtils::ContainSameDigits

IMPORT_C TPbkContactItemField* CPbkContactItem::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.

Parameters:

aIndex

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

Returns:: The matching field, NULL if not found.

See also:: TDesC::FindF

IMPORT_C TPbkContactItemField* CPbkContactItem::FindSameField

(

const TPbkContactItemField &

aField

)

const

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

Parameters:

aField

The field that we a mathing.

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

IMPORT_C HBufC* CPbkContactItem::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.

IMPORT_C HBufC* CPbkContactItem::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.

IMPORT_C CContactIdArray* CPbkContactItem::GroupsJoinedLC

(

)

const

Gets the groups this contact belongs to.

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

See also:: CContactItem::GroupsJoinedLC()

IMPORT_C TContactItemId CPbkContactItem::Id

(

)

const

Returns this contact item's id.

See also:: CContactItem::Id()

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

Creates an instance of this class.

Parameters:

	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.

const MPbkFieldData& CPbkContactItem::PbkFieldAt ( TInt aIndex ) const [virtual]

Returns the const field data object at aIndex.

Returns:: The const field data object at aIndex.

Implements MPbkFieldDataArray.

MPbkFieldData& CPbkContactItem::PbkFieldAt ( TInt aIndex ) [virtual]

Returns the field data object at aIndex.

Parameters:

aIndex

The field to index.

Returns:: The field data object at aIndex.

Implements MPbkFieldDataArray.

TInt CPbkContactItem::PbkFieldCount ( ) const [virtual]

Returns the number of field data objects in this array.

Returns:: The number of field data objects in this array.

Implements MPbkFieldDataArray.

void CPbkContactItem::PrepareAfterLoadL

(

)

void CPbkContactItem::PrepareForSaveL

(

)

IMPORT_C void CPbkContactItem::RemoveDefaultEmailField

(

)

Removes email field default from this contact.

DefaultEmailField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultEmailOverSmsField

(

)

Removes EmailOverSms field default from this contact.

DefaultEmailOverSmsField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultMmsField

(

)

Removes MMS field default from this contact.

DefaultMmsField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultPhoneNumberField

(

)

Removes phone number default from this contact.

DefaultPhoneNumberField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultPocField

(

)

Removes POC field default from this contact.

DefaultPocField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultSmsField

(

)

Removes SMS field default from this contact.

DefaultSmsField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultVideoNumberField

(

)

Removes video number default from this contact.

DefaultVideoNumberField()==NULL.

IMPORT_C void CPbkContactItem::RemoveDefaultVoipField

(

)

Removes VOIP field default from this contact.

DefaultVoipField()==NULL.

IMPORT_C void CPbkContactItem::RemoveField

(

TInt

aIndex

)

Deletes field at aIndex.

Parameters:

aIndex

Field index to delete from the contact item.

IMPORT_C void CPbkContactItem::RemoveVoiceTagField

(

)

Removes any voice tag mark from this contact.

VoiceTagField()==NULL.

Deprecated:

IMPORT_C void CPbkContactItem::SetDefaultEmailFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultEmailOverSmsFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultMmsFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultPhoneNumberFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultPocFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultSmsFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's default SMS field to aField.

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultVideoNumberFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetDefaultVoipFieldL

(

TPbkContactItemField *

aField

)

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

Parameters:

aField

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

Exceptions:

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

IMPORT_C void CPbkContactItem::SetVoiceTagFieldL

(

TPbkContactItemField *

aField

)

Sets this contact's voice tag field to aField.

Parameters:

aField

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

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:

IMPORT_C TUid CPbkContactItem::Type

(

)

const

Returns type of this contact item.

The contact types are documented in the Symbian Contacts model CContactItem::Type().

Returns:: Contact type.

See also:: CContactItem::Type()

IMPORT_C void CPbkContactItem::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.

Parameters:

aFieldsInfo

The new fields set for this contact.

IMPORT_C TPbkContactItemField* CPbkContactItem::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.

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

Deprecated:

Friends And Related Function Documentation

IMPORT_C TBool operator==	(	const CPbkContactItem &	aLeft,
		const CPbkContactItem &	aRight
	)	`[friend]`

Returns ETrue if aLeft and aRight contents are the same.

The documentation for this class was generated from the following file:

cpbkcontactitem.h

CPbkContactItem Class Reference

Capability Information

Detailed Description

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation