CPbkContactEngine Class Reference

IMPORT_C CContactViewBase& CPbkContactEngine::AllContactsView

Destructor.

Destroys this object and closes the contact database connection. REComSession::FinalClose() is called. Notice that FinalClose -call releases resource handles of already destroyed ECom plugins also outside CPbkContactEngine. See REComSession documentation.

Member Function Documentation

IMPORT_C void CPbkContactEngine::AddContactToGroupL	(	TContactItemId	aItemId,
		TContactItemId	aGroupId
	)

Adds a Contact to a group.

Parameters:

	aItemId	Contact to be added to group.
	aGroupId	Group where the contact will be added to.

See also:: CContactDatabase::AddContactToGroupL

IMPORT_C TContactItemId CPbkContactEngine::AddNewContactL	(	CPbkContactItem &	aContact,
		TBool	aImmediateNotify = `EFalse`
	)

Adds a new contact to the contact database.

Parameters:

	aContact	The new contact item to add.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

Returns:: The id of the new contact item.

See also:: CContactDatabase::AddNewContactL

IMPORT_C CContactViewBase& CPbkContactEngine::AllGroupsViewL

Returns a contact view object containing all the contacts in the database.

Returns:: Contact view containing all the contacts in the database.

See also:: CContactViewBase

IMPORT_C void CPbkContactEngine::CancelCompress

Returns a contact view object containing all the groups in the database.

Returns:: Contact view containing all the groups in the database.

See also:: CContactViewBase

IMPORT_C TBool CPbkContactEngine::CheckCompress

IMPORT_C void CPbkContactEngine::CheckFileSystemSpaceAndCompressL

IMPORT_C void CPbkContactEngine::CloseContactL

Closes a previously opened contact item without saving changes.

Parameters:

Contact item to be closed.

See also:: CContactDatabase::CloseContactL

IMPORT_C void CPbkContactEngine::CommitContactGroupL	(	CContactGroup &	aGroup,
		TBool	aImmediateNotify = `EFalse`
	)

Commits changes to a contact group to the database.

Parameters:

	aId	Groups id
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

See also:: CContactDatabase::CommitContactL

IMPORT_C void CPbkContactEngine::CommitContactL	(	CPbkContactItem &	aContact,
		TBool	aImmediateNotify = `EFalse`
	)

Commit changes to a previously opened contact item into the contact database.

Parameters:

	aContact	Contact item to be updated in the database.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

See also:: CContactDatabase::CommitContactL

IMPORT_C void CPbkContactEngine::CompressL

IMPORT_C CPbkConstants* CPbkContactEngine::Constants

IMPORT_C MPbkContactNameFormat& CPbkContactEngine::ContactNameFormat

IMPORT_C CPbkContactChangeNotifier* CPbkContactEngine::CreateContactChangeNotifierL

MPbkContactDbObserver *

aObserver

Observer to attach to this object.

Creates and returns a new CPbkContactChangeNotifier for the default contact database.

The returned object attaches aObserver to this engine instance as long as the object exists.

Parameters:

aObserver

Returns:: New CPbkContactChangeNotifier object. Caller is responsible of the object.

See also:: CPbkContactChangeNotifier
MPbkContactDbObserver

IMPORT_C CContactGroup* CPbkContactEngine::CreateContactGroupL	(	const TDesC &	aGroupLabel,
		TBool	aInTransaction = `EFalse`
	)

Creates a new contact group.

Parameters:

	aGroupLabel	Group name.
	aInTransaction	See Symbian Contacts Model documentation for CContactDatabase::CreateContactGroupL documentation.

See also:: CContactDatabase::CreateContactGroupL

IMPORT_C CPbkContactIter* CPbkContactEngine::CreateContactIteratorLC ( TBool aUseMinimalRead = EFalse )

Returns a Phonebook contact iterator.

Parameters:

aUseMinimalRead

If ETrue the iterator will use the Symbian Contacts model CContactDatabase::ReadMinimalContactL, EFalse will read all the contact fields. Default behaviour is to read all fields.

See also:: CPbkContactIter::NewL.
CContactDatabase::ReadMinimalContactL

IMPORT_C CPbkContactItem* CPbkContactEngine::CreateEmptyContactL

IMPORT_C CContactDatabase& CPbkContactEngine::Database

Returns a new contact card with default fields.

Returns:: A new empty contact item object.

IMPORT_C void CPbkContactEngine::DeleteContactsOnBackgroundL

Returns the underlying CContactDatabase object.

Use only if this class's API is not enough for your purposes.

Returns:: The underlying Symbian Contacts model CContactDatabase instance.

See also:: CContactDatabase

IMPORT_C void CPbkContactEngine::DeleteContactGroupL	(	TContactItemId	aContactId,
		TBool	aImmediateNotify = `EFalse`
	)

Deletes a contact group from the database.

Parameters:

	aContactId	Contact group to be deleted.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

See also:: CContactDatabase::DeleteContactL

IMPORT_C void CPbkContactEngine::DeleteContactL	(	TContactItemId	aContactId,
		TBool	aImmediateNotify = `EFalse`
	)

Deletes a contact item from the database.

Parameters:

	aContactId	Contact item to be deleted.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

See also:: CContactDatabase::DeleteContactL

IMPORT_C void CPbkContactEngine::DeleteContactsL	(	const CContactIdArray &	aContactIds,
		TBool	aImmediateNotify = `EFalse`
	)

Deletes multiple contact items from the database.

Parameters:

	aContactIds	Contact items to be deleted.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

See also:: CContactDatabase::DeleteContactsL

const CContactIdArray &

aContactIds

IMPORT_C const CPbkFieldsInfo& CPbkContactEngine::FieldsInfo

Deletes multiple contacts from the database in an active object -driven asynchronous background process.

Parameters:

aContactIds

Contacts to delete.

IMPORT_C TContactItemId CPbkContactEngine::DuplicateContactL	(	TContactItemId	aId,
		TBool	aImmediateNotify = `EFalse`
	)

Duplicates a contact in the database.

Parameters:

	aId	Id of the contact to duplicate.
	aImmediateNotify	Send notification to observers immediately. NOTE: send immediately will result in observers (MPbkContactDbObserver) receiving the event twice!

Returns:: Contact id of the new duplicate.

IMPORT_C CContactViewBase& CPbkContactEngine::FilteredContactsViewL

Returns the field type info array.

Returns:: All the Phonebook field types.

See also:: CPbkFieldsInfo

Returns a contact view object containing all the contacts in the database that match a filter.

Parameters:

aFilter

Use CContactDatabase::TContactViewFilter.

See also:: CContactViewBase

IMPORT_C CPbkIdleFinder* CPbkContactEngine::FindAsyncL	(	const TDesC &	aText,
		const CPbkFieldIdArray *	aFieldTypes = `NULL`,
		MIdleFindObserver *	aObserver = `NULL`
	)

Searches all contacts in the database for aText asynchronously.

Parameters:

	aText	Text to search.
	aFieldTypes	Phonebook fields types to at least include in the search. If NULL searches all fields. PLEASE NOTE: The find matches in most cases also other fields than those specified in aFieldTypes. Always loop through the returned contacts to check match in the required fields.
	aObserver	Observer for this operation.

Returns:: CPbkIdleFinder object which is used to access the find results when complete. Deleting this object will cancel this asyncronous find operation.

See also:: CContactDatabase::FindAsyncL.
CPbkIdleFinder

IMPORT_C CContactIdArray* CPbkContactEngine::FindLC	(	const TDesC &	aText,
		const CPbkFieldIdArray *	aFieldTypes = `NULL`
	)

Searches all contacts in the database for aText.

Parameters:

	aText	Text to search.
	aFieldTypes	Phonebook fields types to at least include in the search. If NULL searches all fields. PLEASE NOTE: The find matches in most cases also other fields than those specified in aFieldTypes. Always loop through the returned contacts to check match in the required fields.

Returns:: Array of matching contact IDs.

See also:: CContactDatabase::FindLC.

IMPORT_C RFs& CPbkContactEngine::FsSession

IMPORT_C HBufC* CPbkContactEngine::GetContactTitleL

Returns an open file server session.

Returns:: A handle to a file server session.

const CPbkContactItem &

aItem

Contact item for which to make the title.

Gets a title text for a contact or localised text for unnamed contact if contact contains no title.

Parameters:

aItem

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

IMPORT_C HBufC* CPbkContactEngine::GetContactTitleOrNullL

const MPbkFieldDataArray &

aContactData

The contact field data array.

Similar to GetContactTitleL but returns NULL if contact contains no title.

Uses the MPbkFieldDataArray interface to access the field content.

Parameters:

aContactData

Returns:: Contact title, NULL if field array did not contain any fields used to for constructing contact titles.

See also:: CPbkContactEngine::GetContactTitleL

IMPORT_C TContactItemId CPbkContactEngine::GetSpeedDialFieldL	(	TInt	aSpeedDialPosition,
		TDes &	aPhoneNumber
	)	const

Returns a speed dial contact.

Parameters:

	aSpeedDialPosition	Speed dial position number.
	aPhoneNumber	Phone number

See also:: CContactDatabase::GetSpeedDialFieldL.

IMPORT_C TBool CPbkContactEngine::IsSpeedDialAssigned	(	const CPbkContactItem &	aItem,
		TInt	aFieldIndex
	)	const

Returns ETrue if this field has been assigned a speed dial position.

Parameters:

	aItem	contact Item to check for speed dial.
	aFieldIndex	Index of the field to check. This is an index into aItem.CardFields().

Returns:: ETrue if Speed dial exitst, EFalse if not.

IMPORT_C TBool CPbkContactEngine::IsTitleField

Returns ETrue if field is one of the fields used in building the contact title.

Parameters:

aFieldId

The id of the field.

Returns:: ETrue if aFieldId is type of a field used to build contact titles.

See also:: GetContactTitleL
GetContactTitleOrNullL

IMPORT_C CContactIdArray* CPbkContactEngine::MatchPhoneNumberL	(	const TDesC &	aNumber,
		const TInt	aMatchLengthFromRight
	)

Call-through for new Phone number matching function in 6.2 version of class CContactDatabase.

If you don't need any other functionality from CPbkContactEngine than this consider using the CContactDatabase API directly. See Symbian Contacts Model documentation for CContactDatabase::MatchPhoneNumberL use.

See also:: CContactDatabase::MatchPhoneNumberL(const TDesC&,const TInt)

IMPORT_C TPbkNameOrder CPbkContactEngine::NameDisplayOrderL

IMPORT_C TChar CPbkContactEngine::NameSeparator

An open file server connection. If !=NULL aFs is used instead of a locally created RFs connection. aFs must remain connected for the lifetime of the returned object.

static IMPORT_C CPbkContactEngine* CPbkContactEngine::NewL	(	const TDesC &	aFileName,
		TBool	aReplace = `EFalse`,
		RFs *	aFs = `NULL`
	)	`[static]`

static IMPORT_C CPbkContactEngine* CPbkContactEngine::NewL ( RFs * aFs = NULL ) [static]

Creates a new Phonebook engine object and connects to the default contact database.

If the default database does not exist it is created.

Parameters:

aFs

Returns:: A new instance of this class.

Exceptions:

KErrCorrupt

if the database is corrupted.

IMPORT_C CContactGroup* CPbkContactEngine::OpenContactGroupL

Opens a Contact group for modification.

Parameters:

aId

Groups id

Returns:: Contact group object.

See also:: CContactDatabase::OpenContactL

IMPORT_C CContactGroup* CPbkContactEngine::OpenContactGroupLCX

Opens a Contact group for modification.

Pushes the returned contact group object and a lock item on the cleanup stack.

Parameters:

aId

Groups id

Returns:: Contact group object.

See also:: CContactDatabase::OpenContactLX

IMPORT_C CPbkContactItem* CPbkContactEngine::OpenContactL

Opens a contact and returns a phonebook contact item.

Parameters:

Contact item id to be opened.

Returns:: A Phonebook contact item that is marked as open in the database.

See also:: CContactDatabase::OpenContactL

IMPORT_C CPbkContactItem* CPbkContactEngine::OpenContactLCX

Same as OpenContactL, but leaves a lock record AND the opened contact object on the cleanup stack.

Use CleanupStack::PopAndDestroy(2) to close the contact and destroy the returned object. First pop pops the contact object and second the lock object.

Parameters:

IMPORT_C CContactGroup* CPbkContactEngine::ReadContactGroupL

Contact item id to open.

Returns:: A Phonebook contact item that is marked as open in the database.

See also:: CContactDatabase::OpenContactLX

Reads a Contact group.

Parameters:

aId

Group id.

Returns:: Contact group object.

See also:: CContactDatabase::ReadContactL

IMPORT_C CPbkContactItem* CPbkContactEngine::ReadContactL	(	TContactItemId	aContactId,
		const CPbkFieldIdArray *	aFieldTypes = `NULL`
	)

Reads a contact and returns a phonebook contact item.

Parameters:

	aContactId	Contact item id to be read.
	aFieldTypes	Array of types of fields to read in, all fields are read if NULL (which is default). NOTE: when using this parameter ReadContactL may return more fields than expected; for example if aFieldTypes contains any phonenumber the method may return all phone number fields of the contact.

Returns:: A new Phonebook contact item.

See also:: CContactDatabase::ReadContactL

IMPORT_C CPbkContactItem* CPbkContactEngine::ReadContactLC	(	TContactItemId	aContactId,
		const CPbkFieldIdArray *	aFieldTypes = `NULL`
	)

Same as ReadContactL, but leaves the returned contact item on the cleanup stack.

Parameters:

	aContactId	Contact item id to be read.
	aFieldTypes	Array of types of fields to read in, all fields are read if NULL (which is default). NOTE: when using this parameter ReadContactL may return more fields than expected; for example if aFieldTypes contains any phonenumber the method may return all phone number fields of the contact.

Returns:: A new Phonebook contact item.

IMPORT_C CPbkContactItem* CPbkContactEngine::ReadMinimalContactLC

Same as ReadContactLC but reads only minimal information.

See Symbian Contacts Model documentation for definition of "minimal" in this case.

Parameters:

Contact item id to be read.

Returns:: A new phonebook contact item. Leaves the item on the cleanup stack.

See also:: CContactDatabase::ReadMinimalContactL

IMPORT_C void CPbkContactEngine::RemoveContactFromGroupL	(	TContactItemId	aItemId,
		TContactItemId	aGroupId
	)

Removes a contact from a group.

Parameters:

	aItemId	Contact to be removed from group.
	aGroupId	Group where the contact will be removed from.

See also:: CContactDatabase::RemoveContactFromGroupL

IMPORT_C void CPbkContactEngine::RemoveSpeedDialFieldL	(	TContactItemId	aContactId,
		TInt	aSpeedDialPosition
	)

Removes a speed dial from a contact.

Parameters:

	aContactId	Contact item to remove the speed dial from.
	aSpeedDialPosition	Speed dial position number to remove.

See also:: CContactDatabase::RemoveSpeedDialFieldL.

static IMPORT_C CPbkContactEngine* CPbkContactEngine::ReplaceL ( RFs * aFs = NULL ) [static]

Replaces the default contact database and connects to it.

See Symbian Contacs model documentation for CContactDatabase::ReplaceL for possible leave codes. PLEASE NOTE: all data in the existing database will be lost!

Parameters:

aFs

An open file server connection. If !=NULL aFs is used instead of a locally created RFs connection. aFs must remain connected for the lifetime of the returned object.

Returns:: A new instance of this class.

See also:: CContactDatabase::ReplaceL

IMPORT_C void CPbkContactEngine::SetCompressUi

IMPORT_C void CPbkContactEngine::SetFieldAsSpeedDialL	(	CPbkContactItem &	aItem,
		TInt	aFieldIndex,
		TInt	aSpeedDialPosition
	)

Sets a speed dial to a contact field.

Parameters:

	aItem	Contact item to add speed dial to.
	aFieldIndex	Field index to add Speed dial to.
	aSpeedDialPosition	Speed dial position number to set to the field.

See also:: CContactDatabase::SetFieldAsSpeedDialL

IMPORT_C void CPbkContactEngine::SetNameDisplayOrderL

IMPORT_C void CPbkContactEngine::SetNameSeparatorL

const CPbkSortOrderManager& CPbkContactEngine::SortOrderManager