Collapse all Symbian^3 Application Developer Library

CPbkContactItem Class Reference

class CPbkContactItem : public CBase

Phonebook Contact item class. Contact items can be read from the contact database by using the Phonebook engine, CPbkContactEngine . This class extends Symbian Contacts model class CContactItem capabilities to better suit Phonebook application's needs.

Inherits from

CPbkContactItem
- CBase

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

Private Member Functions
	CPbkContactItem ( MPbkContactNameFormat &)
void	ConstructL ( CContactItem *, const CPbkFieldsInfo &)
void	CreateFieldArrayL ( CContactItem &, const CPbkFieldsInfo &)
TInt	InsertionPos (const TPbkContactItemField &)

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

Private Member Type Definitions
typedef	CPbkContactItem SelfType

Private Attributes
	__DECLARE_TEST
CPbkFieldArray	iFields
CContactItem *	iItem
MPbkContactNameFormat &	iNameFormat

Constructor & Destructor Documentation

CPbkContactItem(MPbkContactNameFormat &)

CPbkContactItem

(

MPbkContactNameFormat &

aNameFormat

)

[private, inline]

C++ constructor.

Parameters

MPbkContactNameFormat & aNameFormat

~CPbkContactItem()

~CPbkContactItem

(

)

Destructor.

Member Functions Documentation

AddFieldL(CPbkFieldInfo &)

IMPORT_C TPbkContactItemField &

AddFieldL

(

CPbkFieldInfo &

aFieldInfo

)

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

Parameters

CPbkFieldInfo & aFieldInfo

Type of field to create.

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.

Parameters

CPbkFieldInfo & aFieldInfo

Type of field to search or create.

CanAcceptDataOfType(CPbkFieldInfo &)

IMPORT_C TBool

CanAcceptDataOfType

(

CPbkFieldInfo &

aFieldInfo

)

const

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

Parameters

CPbkFieldInfo & aFieldInfo

The field type that we are trying to add.

CardFields()

IMPORT_C CPbkFieldArray &

CardFields

(

)

const

Returns the field set of this contact item.

ConstructL(CContactItem *, const CPbkFieldsInfo &)

void	ConstructL	(	CContactItem *	aItem,
			const CPbkFieldsInfo &	aFieldsInfo
		)	[private, inline]

Second phase constructor.

Parameters

CContactItem * aItem
const CPbkFieldsInfo & aFieldsInfo

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.

ContactItem()

IMPORT_C CContactItem &

ContactItem

(

)

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

ContactItem()

IMPORT_C const CContactItem &

ContactItem

(

)

const

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

CreateFieldArrayL(CContactItem &, const CPbkFieldsInfo &)

void	CreateFieldArrayL	(	CContactItem &	aContactItem,
			const CPbkFieldsInfo &	aFieldsInfo
		)	[private]

Parameters

CContactItem & aContactItem
const CPbkFieldsInfo & aFieldsInfo

DefaultEmailField()

IMPORT_C TPbkContactItemField *

DefaultEmailField

(

)

const

Returns the default email field of this contact.

DefaultEmailOverSmsField()

IMPORT_C TPbkContactItemField *

DefaultEmailOverSmsField

(

)

const

Returns the default EmailOverSms field of this contact.

DefaultMmsField()

IMPORT_C TPbkContactItemField *

DefaultMmsField

(

)

const

Returns the default Mms field of this contact.

DefaultPhoneNumberField()

IMPORT_C TPbkContactItemField *

DefaultPhoneNumberField

(

)

const

Returns the default phone number field of this contact.

DefaultPocField()

IMPORT_C TPbkContactItemField *

DefaultPocField

(

)

const

Returns the default Poc field of this contact.

DefaultSmsField()

IMPORT_C TPbkContactItemField *

DefaultSmsField

(

)

const

Returns the default SMS field of this contact.

DefaultVideoNumberField()

IMPORT_C TPbkContactItemField *

DefaultVideoNumberField

(

)

const

Returns the default video number field of this contact.

DefaultVoipField()

IMPORT_C TPbkContactItemField *

DefaultVoipField

(

)

const

Returns the default VOIP field of this contact.

FindContactItemFieldIndex(const CContactItemField &)

IMPORT_C TInt

FindContactItemFieldIndex

(

const CContactItemField &

aField

)

const

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

Parameters

const CContactItemField & aField

The field which index we are querying.

FindField(TPbkFieldId)

IMPORT_C TPbkContactItemField *

FindField

(

TPbkFieldId

aFieldId

)

const

Returns first field matching aFieldId.

Parameters

TPbkFieldId aFieldId

Field id to search.

FindField(TPbkFieldId, TInt &)

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

Returns first field matching aFieldId starting from aIndex.

Parameters

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

FindField(const CPbkFieldInfo &)

IMPORT_C TPbkContactItemField *

FindField

(

const CPbkFieldInfo &

aFieldInfo

)

const

Returns first field matching aFieldInfo.

Parameters

const CPbkFieldInfo & aFieldInfo

Field type to find from the contact.

FindField(const CPbkFieldInfo &, TInt &)

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

Returns first field matching aFieldInfo starting from aIndex.

Parameters

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

FindFieldIndex(const TPbkContactItemField &)

IMPORT_C TInt

FindFieldIndex

(

const TPbkContactItemField &

aField

)

const

Returns aField's index from this contact item.

TPbkContactItemField::IsSame

Parameters

const TPbkContactItemField & 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.

PbkEngUtils::ContainSameDigits

Parameters

const TDesC & aNumber	Phone number to match to.
TInt aNumberOfDigits	Number of digits to compare from the end of the phone numbers. Full comparison performed if 0.
TInt & aIndex	Input: field index where to start the search from, output: index of the found field or KErrNotFound 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.

TDesC::FindF

Parameters

const TDesC & aText
TInt & 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.

Parameters

const TPbkContactItemField & aField

The field that we a mathing.

GetContactTitleL()

IMPORT_C HBufC *

GetContactTitleL

(

)

const

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

GetContactTitleOrNullL()

IMPORT_C HBufC *

GetContactTitleOrNullL

(

)

const

Gets a title text for this contact.

GroupsJoinedLC()

IMPORT_C CContactIdArray *

GroupsJoinedLC

(

)

const

Gets the groups this contact belongs to. CContactItem::GroupsJoinedLC()

Id()

IMPORT_C TContactItemId

(

)

const

Returns this contact item's id. CContactItem::Id()

InsertionPos(const TPbkContactItemField &)

TInt

InsertionPos

(

const TPbkContactItemField &

aField

)

const [private]

Returns insertion position for aField.

Parameters

const TPbkContactItemField & aField

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

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

Creates an instance of this class.

Parameters

CContactItem * aItem	Contact item this object wraps. This object takes ownership of aItem. If this function leaves, ownership is not taken.
const CPbkFieldsInfo & aFieldsInfo	Collection of Phonebook field types.
MPbkContactNameFormat & aNameFormat	Contact name formatter.

PbkFieldAt(TInt)

MPbkFieldData &

PbkFieldAt

(

TInt

aIndex

)

Parameters

TInt aIndex

PbkFieldAt(TInt)

const MPbkFieldData &

PbkFieldAt

(

TInt

aIndex

)

const

Parameters

TInt aIndex

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.

Parameters

TInt aIndex

Field index to delete from the contact item.

RemoveVoiceTagField()

IMPORT_C void

RemoveVoiceTagField

(

)

Removes any voice tag mark from this contact.

VoiceTagField() ==NULL.

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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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.

Parameters

TPbkContactItemField * 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())

Parameters

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

Parameters

const CPbkFieldsInfo & 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.