CContactDatabase Class Reference

aContactId

)

Closes the contact item, allowing other applications to access it. Specifying a contact item that is not open, or cannot be found, is harmless. This function does not commit any changes made to the item. Despite the trailing L in the function's name, this function cannot leave.

Parameters
aContactId	The ID of the contact to close.

Capability
None

CloseTables ( )

IMPORT_C void

CloseTables

(

)

This method is no longer required and should not be called.

Closes all database tables. After a rollback and recover all tables need to be closed and re-opened before the database can be accessed again.

Deprecated

Capability
WriteUserData

CntServerResourceCount ( )

IMPORT_C TInt

CntServerResourceCount

(

)

Debug only.

Return Value: return the heap size usage of the server in debug mode, 0 in release mode.

Capability
None

CommitContactL ( const CContactItem & )

IMPORT_C void

CommitContactL

(

const CContactItem &

aContact

)

Overwrites a contact item with the values contained in aContact. The contact item is also closed by this call.

Parameters
aContact	Contains the new values for the contact item.

Leave Codes
KErrAccessDenied	The contact item is not locked by the caller.
KErrNotFound	The contact item's ID is not present in the database.
KErrDiskFull	The disk does not have enough free space to perform the operation.
KErrNotSupported	The contact item cannot be committed because it contains invalid data.

Capability
ReadUserData
WriteUserData

CompactL ( )

IMPORT_C void

CompactL

(

)

This function does nothing and has been deprecated.

Deprecated

Capability
WriteUserData

CompressRequired ( )

IMPORT_C TBool

CompressRequired

(

)

This function is deprecated. It always returns EFalse.

Deprecated

Return Value: EFalse

Capability
None

ConnectionId ( )

IMPORT_C TUint

ConnectionId

(

)

const

Gets the ID of the connection to the Contacts server.

This can be compared with the connection IDs of incoming messages to identify which connection generated the message.

Return Value: The ID of the connection to the Contacts server.

Capability
None

ContactDatabaseExistsL ( const TDesC & )

IMPORT_C TBool

ContactDatabaseExistsL

(

const TDesC &

aFileName

)

[static]

A method to determine if a named contact database exists.

If the file is found, it is tested for the correct UIDs.

In v8.1, contact databases can be located in any directory on any writeable drive, and the format of the filename must include an absolute directory path such as c:\system\data\contacts.cdb.

From v9.0 onwards, contact databases can only be located in the correct data caged subdirectory. The filenames must have no path, for example c:contacts.cdb. The maximum length for the drive, filename and extension is 190 characters.

Parameters
aFileName	The contact database to search for.

Return Value: ETrue if the file is found, EFalse otherwise.

Leave Codes
KErrNotReady	There is no media present in the drive.
KErrBadName	The filename is invalid; for example it contains wildcard characters or the drive is missing.
KErrNotFound	The database file was not found or it did not have the correct UIDs.
KErrCorrupt	The file is not a valid database
KErrArgument	if the given descriptor contains more than the maximum length of 190 characters.

Capability
None

ContactIdByGuidL ( const TDesC & )

IMPORT_C TContactItemId

ContactIdByGuidL

(

const TDesC &

aGuid

)

Searches the contact tables for the contact described by aGuid.

Parameters
aGuid	Describes the contact item to be found.

Return Value: The unique id of the contact item within the database.

Leave Codes
KErrNotReady	The database is not yet ready to read from, could be because an asynchronous open is in progress or because a recover is required after a rollback.
KErrBadHandle	An asynchronous open either failed or was cancelled.
KErrLocked	The database has been closed for a restore.

Capability
ReadUserData

ContactMatchesHintFieldL ( TInt, TContactItemId )

IMPORT_C TBool	ContactMatchesHintFieldL	(	TInt	aBitWiseFilter,
			TContactItemId	aContactId
		)

Tests whether a contact item's hint bit field matches a filter.

For a match to occur, the item must be of the correct type for inclusion in the database (as returned by GetDbViewContactType()) and its hint bit field (which indicates whether the item contains a work or home telephone number, fax number or email address) must match the filter, according to the rules described in TContactViewFilter.

Parameters
aBitWiseFilter	The filter to compare the item against. This is a combination of TContactViewFilter values.
aContactId	The ID of the item in the database.

Return Value: ETrue if the item is of the correct type for inclusion in the database, and its hint bit field matches the specified filter, EFalse if either of these conditions are not met.

Capability
None

ContactsChangedSinceL ( const TTime & )

IMPORT_C CContactIdArray *

ContactsChangedSinceL

(

const TTime &

aTime

)

Gets an array of contacts modified since the specified date/time. The array includes those contacts that have changed since the beginning of the specified micro-second. The caller takes ownership of the returned object.

Parameters
aTime	The date/time of interest.

Return Value: Pointer to the array of contacts modified since the specified time.

Capability
ReadUserData

CountL ( )

IMPORT_C TInt

CountL

(

)

Gets the number of CContactItems in the database. The count includes non-system template items. It does not include items marked as deleted.

Deprecated

Return Value: The number of contact items in the database.

Capability
None

CreateCompressorLC ( )

IMPORT_C CContactActiveCompress *

CreateCompressorLC

(

)

This function is deprecated. It returns an object whose functions do nothing.

Deprecated

Return Value: Pointer to an active compressor.

Capability
WriteUserData

CreateContactCardTemplateL ( const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactCardTemplateL	(	const TDesC &	aTemplateLabel,
			TBool	aInTransaction = EFalse
		)

Creates a contact card template based on the system template and adds it to the database.

A template label must be specifed. This can be changed later using CContactCardTemplate::SetTemplateLabelL().

The caller takes ownership of the returned object.

Parameters
aTemplateLabel	The string to set as the template label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the contact card template.

Capability
WriteUserData

CreateContactCardTemplateL ( const CContactItem *, const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactCardTemplateL	(	const CContactItem *	aTemplate,
			const TDesC &	aTemplateLabel,
			TBool	aInTransaction = EFalse
		)

Creates a contact card template and adds it to the database.

The new template's field set is based on the specified contact item. This could be a contact card, an own card, another template or even a group. Note that no field data is copied into the new template. All of the new template's fields are marked as template fields.

A template label must be specifed. This can be changed later using CContactCardTemplate::SetTemplateLabelL().

The caller takes ownership of the returned object.

Parameters
aTemplate	Pointer to an instance of a CContactItem-derived class. This is used to initialise the new template's field set.
aTemplateLabel	The string to set as the template label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the contact card template.

Capability
WriteUserData

CreateContactCardTemplateLC ( const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactCardTemplateLC	(	const TDesC &	aTemplateLabel,
			TBool	aInTransaction = EFalse
		)

Creates a contact card template based on the system template and adds it to the database.

A template label must be specifed. This can be changed later using CContactCardTemplate::SetTemplateLabelL().

The pointer to the template is left on the cleanup stack. The caller takes ownership of the returned object.

Parameters
aTemplateLabel	The string to set as the template label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the contact card template.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

CreateContactCardTemplateLC ( const CContactItem *, const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactCardTemplateLC	(	const CContactItem *	aTemplate,
			const TDesC &	aTemplateLabel,
			TBool	aInTransaction = EFalse
		)

Creates a contact card template and adds it to the database.

A template label must be specifed. This can be changed later using CContactCardTemplate::SetTemplateLabelL().

The pointer to the object is left on the cleanup stack. The caller takes ownership of it.

Parameters
aTemplate	Pointer to an instance of a CContactItem-derived class. This is used to initialise the new template's field set.
aTemplateLabel	The string to set as the template label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the contact card template.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

CreateContactGroupL ( TBool )

IMPORT_C CContactItem *

CreateContactGroupL

(

aInTransaction = EFalse

)

Creates a new contact group with a default label of 'Group Label' and adds it to the database.

The caller takes ownership of the returned object.

Parameters
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the newly created contact group.

Capability
WriteUserData

CreateContactGroupL ( const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactGroupL	(	const TDesC &	aGroupLabel,
			TBool	aInTransaction = EFalse
		)

Creates a new contact group with a specified label and adds it to the database.

The caller takes ownership of the returned object.

Parameters
aGroupLabel	The string to set as the group label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the newly created contact group.

Capability
WriteUserData

CreateContactGroupLC ( TBool )

IMPORT_C CContactItem *

CreateContactGroupLC

(

aInTransaction = EFalse

)

Creates a new contact group with a default label of 'Group Label' and adds it to the database.

The caller takes ownership of the returned object.

Parameters
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the newly created contact group.

Capability
WriteUserData

CreateContactGroupLC ( const TDesC &, TBool )

IMPORT_C CContactItem *	CreateContactGroupLC	(	const TDesC &	aGroupLabel,
			TBool	aInTransaction = EFalse
		)

Creates a new contact group with a specified label and adds it to the database.

The pointer to the group is left on the cleanup stack. The caller takes ownership of the returned object.

Parameters
aGroupLabel	The string to set as the group label.
aInTransaction	This argument should be ignored by developers.

Return Value: Pointer to the newly created contact group.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

CreateL ( TThreadAccess )

IMPORT_C CContactDatabase *

CreateL

(

aAccess = ESingleThread

)

[static]

Creates and opens an empty contact database using the default database name.

Parameters
aAccess	The default (ESingleThread) allows access to the session with the database server from a single client thread only (as in v5 and v5.1). EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers

Return Value: A pointer to the new contact database.

Leave Codes
KErrAlreadyExists	The database already exists.
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

CreateL ( const TDesC &, TThreadAccess )

IMPORT_C CContactDatabase *	CreateL	(	const TDesC &	aFileName,
			TThreadAccess	aAccess = ESingleThread
		)	[static]

Creates and opens a named contact database.

Parameters
aFileName	The filename of the database to create.
aAccess	The default (ESingleThread) allows access to the session with the database server from a single client thread only (as in v5 and v5.1). EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers

Return Value: A pointer to the new contact database.

Leave Codes
KErrAlreadyExists	The database already exists.
KErrBadName	The filename is invalid; for example it contains wildcard characters or the drive letter is missing.
KErrDiskFull	The disk does not have enough free space to perform the operation.
KErrArgument	if the given descriptor contains more than the maximum length of 190 characters.

Capability
WriteUserData

CreateOwnCardL ( )

IMPORT_C CContactItem *

CreateOwnCardL

(

)

Creates a default own card based on the system template and adds it to the database. This is set as the database's current own card, replacing any existing current own card. The caller takes ownership of the returned object.

Return Value: Pointer to the new default own card.

Capability
WriteUserData

CreateOwnCardLC ( )

IMPORT_C CContactItem *

CreateOwnCardLC

(

)

Return Value: Pointer to the new default own card. The pointer is left on the cleanup stack.

Capability
WriteUserData

CreateRecoverLC ( )

IMPORT_C CContactActiveRecover *

CreateRecoverLC

(

)

This function is deprecated. It returns an object whose functions do nothing.

Deprecated

Return Value: Pointer to an active recoverer.

Capability
WriteUserData

CreateV2L ( TThreadAccess )

IMPORT_C CContactDatabase *

CreateV2L

(

aAccess = ESingleThread

)

[static]

DamageDatabaseL ( TInt )

IMPORT_C void

DamageDatabaseL

(

TInt

aSecretCode

)

Debug Only

Capability
WriteUserData

DatabaseBeginL ( TBool )

IMPORT_C void

DatabaseBeginL

(

aIsInTransaction

)

Starts a new transaction, without placing a cleanup item to rollback the database onto the cleanupstack. This is to enable clients to call contacts methods from an active object.

Parameters
aIsInTransaction	ETrue if transaction already started

Leave Codes
KErrDiskFull	if used storage space above threshold

Capability
WriteUserData

DatabaseBeginLC ( TBool )

IMPORT_C void

DatabaseBeginLC

(

aIsInTransaction

)

Starts a new transaction. Places and leaves a cleanup item to rollback the database on the cleanupstack.

Parameters
aIsInTransaction	Used to determine whether or not to start the transaction depending on if a transaction is currently in progress.

Leave Codes
KErrDiskFull	There is insufficient disk space.

DatabaseCommit ( TBool, TRequestStatus *& )

IMPORT_C void	DatabaseCommit	(	TBool	aIsInTransaction,
			TRequestStatus *&	aStatus
		)

Asynchronous commit of an existing transaction, without popping a cleanup item.

Parameters
aIsInTransaction	ETrue if transaction already started
aStatus	Valid status to that will contain the completion value

Capability
WriteUserData

DatabaseCommitL ( TBool )

IMPORT_C void

DatabaseCommitL

(

aIsInTransaction

)

Commits an existing transaction, without popping a cleanup item.

Parameters
aIsInTransaction	ETrue if transaction already started

Capability
WriteUserData

DatabaseCommitLP ( TBool )

IMPORT_C void

DatabaseCommitLP

(

aIsInTransaction

)

Commits an existing transaction, pops the rollback cleanup item off the CleanupStack. Closes the database if the connection state is EDbConnectionNeedToCloseForRestore.

Parameters
aIsInTransaction	Used to determine whether or not to commit the transaction depending on whether a transaction is currently in progress.

DatabaseDrive ( TDriveUnit & )

IMPORT_C TBool

DatabaseDrive

(

TDriveUnit &

aDriveUnit

)

[static]

Gets the current database drive. The database drive is the drive on which the default contact database is located. Note: this function can leave.

See also: CContactDatabase::SetDatabaseDrive() CContactDatabase::GetDefaultNameL()

Parameters
aDriveUnit	On return, contains the database drive.

Return Value: ETrue if the database drive has been set using SetDatabaseDriveL(). Otherwise EFalse and in this case, the function returns drive c: in aDriveUnit as the current drive.

Leave Codes
KErrNoMemory	Out of memory.

Capability
None

DatabaseRollback ( )

IMPORT_C void

DatabaseRollback

(

)

Force a rollback of the database.

Capability
WriteUserData

DefaultContactDatabaseExistsL ( )

IMPORT_C TBool

DefaultContactDatabaseExistsL

(

)

[static]

A static method to determine if the default contact database exists.

It searches the drive set by SetDatabaseDriveL(), or if no drive has been set, it searches drive c:.

If the file is found, it is tested for the correct UIDs.

Return Value: ETrue if the file is found, EFalse otherwise.

Leave Codes
KErrNotReady	There is no media present in the drive.
KErrNotFound	The database file was not found or it did not have the correct UIDs.
KErrCorrupt	The file is not a valid database

Capability
None

DeleteContactL ( TContactItemId )

IMPORT_C void

DeleteContactL

(

aContactId

)

Deletes a contact item.

Note: if the contact's access count is greater than zero, the contact is not fully deleted from the database. A 'skeleton' of the contact is left, containing only basic information, and no field data. The skeleton contact can still be accessed if a record of its contact ID has been retained (or call DeletedContactsLC()). The skeleton is removed when the access count is zero.

Parameters
aContactId	The contact item ID of the contact to delete.

Leave Codes
KErrNotFound	aContactId is not present in the database.
KErrInUse	The contact item is open.
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
ReadUserData
WriteUserData

DeleteContactsL ( const CContactIdArray & )

IMPORT_C void

DeleteContactsL

(

const CContactIdArray &

aContactIds

)

Deletes an array of contacts.

The function commits the changes for every 32 (for 9.5 onwards it commits after every 50) contacts deleted, and compresses the database as required. A changed message is not sent for every contact deleted, instead a single unknown change event message (EContactDbObserverEventUnknownChanges) is sent after all the contacts have been deleted and the changes committed.

Parameters
aContactIds	An array of contacts to delete.

Leave Codes
KErrNotFound	A contact item ID contained in the array is not present in the database.
KErrInUse	One or more of the contact items is open.
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData
ReadUserData

DeleteContactsV2L ( const CContactIdArray & )

IMPORT_C void

DeleteContactsV2L

(

const CContactIdArray &

aContactIds

)

Not supporte anymore.

Leave Codes
KErrInNotSupported	Always.

DeleteDatabaseL ( const TDesC & )

IMPORT_C void

DeleteDatabaseL

(

const TDesC &

aFileName

)

[static]

A static method to delete a named contact database.

If the file is found, it is tested for the correct UIDs.

In v8.1, contact databases can be located in any directory on any writeable drive, and the format of the filename must include an absolute directory path such as c:\system\data\contacts.cdb.

Parameters
aFileName	The contact database file to delete.

Leave Codes
KErrBadName	The filename is invalid; for example it contains wildcard characters or the drive is missing.
KErrInUse	Another client has the database open.
KErrNotFound	The database file was not found or it did not have the correct UIDs.
KErrArgument	if the given descriptor contains more than the maximum length of 190 characters.

Capability
WriteUserData

DeleteDefaultFileL ( )

IMPORT_C void

DeleteDefaultFileL

(

)

[static]

Deletes the default contact database.

Leave Codes
KErrInUse	Another client has the database open.
KErrNotFound	The database file was not found or it did not have the correct UIDs.

Capability
WriteUserData

DeletedContactsLC ( )

IMPORT_C CContactIdArray *

DeletedContactsLC

(

)

Gets an array of IDs for contact items that still exist in the database, but are marked as deleted. These are contact items which have been deleted, but which have a non-zero access count. The caller takes ownership of the returned object.

Debug only.

Return Value: Pointer to the array of contacts marked as deleted.

Capability
ReadUserData

ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, TBool )

IMPORT_C void	ExportSelectedContactsL	(	const TUid &	aFormat,
			const CContactIdArray &	aSelectedContactIds,
			RWriteStream &	aWriteStream,
			TInt	aOption,
			TBool	aExportPrivateFields = ETrue
		)

Converts an array of contact items to vCards and exports them to a write stream.

The default character set CVersitParser::EUTF8CharSet is used to convert into. If you need a different character set, use the other overload of this function.

Parameters
aFormat	Indicates the format for imported and exported contacts. Must have a value of KUidVCardConvDefaultImpl.
aSelectedContactIds	Array of contact IDs to export.
aWriteStream	The stream to write to.
aOption	Indicates the options for import and export. See the TOptions enum.
aExportPrivateFields	ETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

Leave Codes
KErrNotSupported	aFormat.iUid is not KUidVCardConvDefaultImpl.
KErrNotFound	One or more of the contact items does not exist in the database.

Capability
ReadUserData

ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, const Versit::TVersitCharSet, TBool )

IMPORT_C void	ExportSelectedContactsL	(	const TUid &	aFormat,
			const CContactIdArray &	aSelectedContactIds,
			RWriteStream &	aWriteStream,
			TInt	aOption,
			const Versit::TVersitCharSet	aCharSet,
			TBool	aExportPrivateFields = ETrue
		)

Converts an array of contact items to vCards and exports them to a write stream using the specified character set.

Parameters
aFormat	Indicates the format for imported and exported contacts. Must have a value of KUidVCardConvDefaultImpl.
aSelectedContactIds	Array of contact IDs to export.
aWriteStream	The stream to write to.
aOption	Indicates the options for import and export. See the TOptions enum.
aCharSet	The character set to convert into.
aExportPrivateFields	ETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

Leave Codes
KErrNotSupported	aFormat.iUid is not KUidVCardConvDefaultImpl.
KErrNotFound	One or more of the contact items does not exist in the database.

Capability
ReadUserData

ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, const TInt64, MConverterCallBack *, const TVCardVersion, const TBool, Versit::TVersitCharSet, TBool )

IMPORT_C void	ExportSelectedContactsL	(	const TUid &	aFormat,
			const CContactIdArray &	aSelectedContactIds,
			RWriteStream &	aWriteStream,
			TInt	aOption,
			const TInt64	aContactFieldFilter,
			MConverterCallBack *	aCallback,
			const TVCardVersion	aVersion,
			const TBool	aExportTel,
			Versit::TVersitCharSet	aCharSet = Versit::EUTF8CharSet,
			TBool	aExportPrivateFields = ETrue
		)

Converts an array of contact items to PBAP compliant vCards following vCard2.1 and vCard3.0 specifications and exports them to a write stream using UTF-8 as the character set. It also provides support for exporting contacts as standard vCard2.1.

Parameters
aFormat	Indicates the format for imported and exported contacts. It should have a value of KUidPBAPVCardConvImpl if user wants to export contacts as PBAP specific vCards and KUidVCardConvDefaultImpl for standard vCard2.1.
aSelectedContactIds	Array of contact IDs to export.
aWriteStream	The stream to write to.
aOption	Indicates the options for import and export. See the TOptions enum.
aContactFieldFilter	64-bit filter,specifies the contact fields to export, argument value not considered for standard vCard2.1 export.
aCallback	Calls client which has to implement class MConverterCallBack, used to add intra-contact properties, argument value not considered for standard vCard2.1 export.
aVersion	TVCardVersion specifies vCard version to which contacts should be exported.
aExportTel	If TEL property should be exported, it should be set to ETrue, argument value not considered for standard vCard2.1 export.
aCharSet	The character set to convert into.Must be UTF-8 for PBAP export, provided as default value.
aExportPrivateFields	ETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

Leave Codes
KErrNotSupported	aFormat.iUid is not KUidPBAPVCardConvImpl for PBAP export.
KErrNotSupported	aFormat.iUid is not KUidVCardConvDefaultImpl for standard vCard2.1 export.
KErrNotSupported	aCharSet is other than UTF-8 for PBAP export.
KErrNotFound	One or more of the contact items does not exist in the database.

Capability
ReadUserData

FileSize ( )

IMPORT_C TInt

FileSize

(

)

const

Gets the size of the database file in bytes.

Return Value: The size of the contact database.

Capability
None

FileUid ( )

IMPORT_C TPtrC

FileUid

(

)

Gets the database's UID. This value is used to identify a particular contact database. The database UID is generated when the database is first created.

Note: This method can leave.

Return Value: Descriptor containing the database UID.

Capability
None

FilterDatabaseL ( CCntFilter & )

IMPORT_C void

FilterDatabaseL

(

CCntFilter &

aFilter

)

Filters the database. On return, aFilter contains an array of filtered contact item IDs.

Parameters
aFilter	The filter to use. On return, contains a filtered array of contact item IDs.

Capability
ReadUserData

FindAsyncL ( const TDesC &, const CContactItemFieldDef , MIdleFindObserver )

IMPORT_C CIdleFinder *	FindAsyncL	(	const TDesC &	aText,
			const CContactItemFieldDef *	aFieldDef,
			MIdleFindObserver *	aObserver
		)

Searches the database asynchronously for a text string. The function searches the fields contained in the field definition asynchronously using the MIdleFindObserver and CIdleFinder classes. The caller takes ownership of the returned object.

Parameters
aText	The text to search for.
aFieldDef	Specifies the fields to search.
aObserver	Implements the callback function IdleFindCallback(). NULL if no observer is needed.

Return Value: A CIdle-derived object which provides information about the progress of the operation, and which can be used to retrieve an array of contact IDs.

FindInTextDefAsyncL ( const MDesCArray &, MIdleFindObserver *, const TCallBack & )

IMPORT_C CIdleFinder *	FindInTextDefAsyncL	(	const MDesCArray &	aFindWords,
			MIdleFindObserver *	aObserver,
			const TCallBack &	aWordParserCallback
		)

Asynchronously searches the database for an array of words.

This function works in the same way as its corresponding variant in FindInTextDefLC(), except that it operates asynchronously using the MIdleFindObserver and CIdleFinder classes. The caller takes ownership of the returned object.

Parameters
aFindWords	An array of words to find.
aObserver	Implements the callback function IdleFindCallback(). May be NULL if no observer is needed.
aWordParserCallback	A function to break the text in the contact down into a list of words.

Return Value: A CIdle-derived object which provides information about the progress of the operation, and which can be used to retrieve an array of contact IDs.

FindInTextDefAsyncL ( const MDesC16Array &, MIdleFindObserver *, const TCallBack & )

IMPORT_C CIdleFinder *	FindInTextDefAsyncL	(	const MDesC16Array &	aFindWords,
			MIdleFindObserver *	aObserver,
			const TCallBack &	aWordParserCallback
		)

FindInTextDefAsyncL ( const MDesCArray &, const CContactTextDef , MIdleFindObserver , const TCallBack & )

IMPORT_C CIdleFinder *	FindInTextDefAsyncL	(	const MDesCArray &	aFindWords,
			const CContactTextDef *	aTextDef,
			MIdleFindObserver *	aObserver,
			const TCallBack &	aWordParserCallback
		)

Asynchronously searches the database for an array of words.

Parameters
aFindWords	An array of words to find.
aTextDef	The text definition.
aObserver	Implements the callback function IdleFindCallback(). May be NULL if no observer is needed.
aWordParserCallback	A function to break the text in the contact down into a list of words.

Return Value: A CIdle-derived object which provides information about the progress of the operation, and which can be used to retrieve an array of contact IDs.

FindInTextDefAsyncL ( const MDesC16Array &, const CContactTextDef , MIdleFindObserver , const TCallBack & )

IMPORT_C CIdleFinder *	FindInTextDefAsyncL	(	const MDesC16Array &	aFindWords,
			const CContactTextDef *	aTextDef,
			MIdleFindObserver *	aObserver,
			const TCallBack &	aWordParserCallback
		)

FindInTextDefLC ( const MDesCArray &, const TCallBack & )

IMPORT_C CContactIdArray *	FindInTextDefLC	(	const MDesCArray &	aFindWords,
			const TCallBack &	aWordParserCallback
		)

Enables the user to search the database for a string containing text that is stored in one or more fields.

The string is specified as an array of words.

For example, a user might want to search for the string "John Smith". To the user the string is a single item, but the text which makes up the string is stored in two separate fields in the database.

The caller of this function needs to provide an array of words to find (aFindWords), and a function to break down the text in the contact item into a list of words (aWordParserCallback).

The array of words to find would typically not contain punctuation. For example if the user searches for 'Smith, John' this would be passed to this function as an array of two words: 'Smith' and 'John', with the separator being discarded.

For a match to succeed, all words in the aFindWords array must match words in the array generated from the contact item by the aWordParserCallback function. To match, the word generated from the contact item must begin with the search word, i.e. a search for "Sm" would find any word beginning in "Sm". If a word is specified twice in the aFindWords array, then it must exist in two separate places in the contact item.

The function only searches the fields contained in the currently set text definition.

The caller takes ownership of the returned object.

Parameters
aFindWords	An array of words to find.
aWordParserCallback	A function supplied by the caller to break the text in the contact down into a list of words.

Return Value: Array of contact IDs.

FindInTextDefLC ( const MDesC16Array &, const TCallBack & )

IMPORT_C CContactIdArray *	FindInTextDefLC	(	const MDesC16Array &	aFindWords,
			const TCallBack &	aWordParserCallback
		)

FindInTextDefLC ( const MDesCArray &, CContactTextDef *, const TCallBack & )

IMPORT_C CContactIdArray *	FindInTextDefLC	(	const MDesCArray &	aFindWords,
			CContactTextDef *	aTextDef,
			const TCallBack &	aWordParserCallback
		)

Enables the user to search the database for a string containing text that is stored in one or more fields.

The string is specified as an array of words.

For example, a user might want to search for the string "John Smith". To the user the string is a single item, but the text which makes up the string is stored in two separate fields in the database.

The caller of this function needs to provide an array of words to find (aFindWords), and a function to break down the text in the contact item into a list of words (aWordParserCallback).

The function only searches the fields contained in the text definition aTextDef.

The caller takes ownership of the returned object.

Parameters
aFindWords	An array of words to find.
aTextDef	The text definition.
aWordParserCallback	A function supplied by the caller to break the text in the contact down into a list of words.

Return Value: Array of contact IDs.

FindInTextDefLC ( const MDesC16Array &, CContactTextDef *, const TCallBack & )

IMPORT_C CContactIdArray *	FindInTextDefLC	(	const MDesC16Array &	aFindWords,
			CContactTextDef *	aTextDef,
			const TCallBack &	aWordParserCallback
		)

FindLC ( const TDesC &, const CContactItemFieldDef * )

IMPORT_C CContactIdArray *	FindLC	(	const TDesC &	aText,
			const CContactItemFieldDef *	aFieldDef
		)

Searches the database for a text string. The function searches the fields contained in the field definition. The caller takes ownership of the returned object. There is a limit of 255 characters on the search string length, due to the implementation of the DBMS API, which also has a search string length restriction of 255 chars. If the search string passed in is over 255 characters this method will leave with KErrArgument.

Parameters
aText	The text to search for.
aFieldDef	Specifies the fields to search.

Return Value: Array of contact IDs identifying the contact items which contain the specified text.

GetCardTemplateIdListL ( )

IMPORT_C CContactIdArray *

GetCardTemplateIdListL

(

)

const

Gets a copy of the database's template ID list. This is a list of the IDs of all contact card templates which have been added to the database. The caller takes ownership of the returned object.

Return Value: Pointer to a copy of the database's template ID list. This does not include the system template. NULL if there are no templates in the database.

GetCurrentDatabase ( TDes & )

IMPORT_C TInt

GetCurrentDatabase

(

TDes &

aDatabase

)

const

Where there are multiple contact databases on a device, this function can be used to enquire which database is the current one. The current database functions are provided as part of current item functionality. In order to pass a current item from one contacts model client to another, the receiving client needs to be using the same database.

The current database is a path and filename, set using SetCurrentDatabase() which is persisted by the contacts server.

Deprecated

Parameters
aDatabase	The path and filename of the current database. KNullDesC if no current database has been set.

Return Value: KErrNone if the function completed successfully, otherwise one of the standard error codes.

Capability
None

GetCurrentItem ( )

IMPORT_C TContactItemId

GetCurrentItem

(

)

const

Gets the ID of the current item, as set by SetCurrentItem(). The current item ID is initialised to KNullContactId when the database is opened.

Return Value: The ID of the current item.

Capability
None

GetDbViewContactType ( )

IMPORT_C TUid

GetDbViewContactType

(

)

const

Gets the type of contact items which are included in sorted views of the database, as set by SetDbViewContactType().

Deprecated

Return Value: Specifies a contact type. One of the following: KUidContactCard (contact cards), KUidContactGroup (contact item groups), KUidContactOwnCard (own cards), KUidContactCardTemplate (templates which are not system, in other words, which have been added to the database), KUidContactItem (all of the above)

GetDefaultNameL ( TDes & )

IMPORT_C void

GetDefaultNameL

(

TDes &

aDes

)

[static]

Gets the file name of the default contact database.

By default it is on drive C: but this can be changed using SetDatabaseDriveL().

Parameters
aDes	On return, contains the drive and filename of the default contact database. From v9.0 onwards, this has the form driveletter:filename, in other words, it does not include a path.

Capability
None

GetGroupIdListL ( )

IMPORT_C CContactIdArray *

GetGroupIdListL

(

)

const

Returns a copy of the database's group ID list. This is a list which contains the contact item IDs for each group in the database. The caller takes ownership of the returned object.

Return Value: Pointer to an array containing the contact item IDs for each group in the database. NULL if there are no groups in the database.

GetLastSyncDateL ( TContactSyncId, TTime & )

IMPORT_C void	GetLastSyncDateL	(	TContactSyncId	aSyncId,
			TTime &	aSyncDate
		)

Gets the date/time the database was last synchronised with a particular sync ID, as set by SetLastSyncDateL().

Deprecated

Parameters
aSyncId	This argument should be ignored by developers.
aSyncDate	On return contains the date/time the database was last synchronised with the sync ID specified.

Leave Codes
KErrNotFound	The ID cannot be found in the database.

GetSpeedDialFieldL ( TInt, TDes & )

IMPORT_C TContactItemId	GetSpeedDialFieldL	(	TInt	aSpeedDialPosition,
			TDes &	aPhoneNumber
		)

Returns the ID of the contact item whose telephone number field is mapped to the speed dial position specified. This function is provided so that information may be displayed about a contact item whose telephone number is being dialled using speed dialling.

The function also retrieves the telephone number stored in the field.

Parameters
aSpeedDialPosition	The speed dial position. This is an integer in the range 1 to 9 inclusive. If outside this range, the function leaves with KErrArgument.
aPhoneNumber	On return, contains the telephone number which is mapped to the speed dial position specified. Returns KNullDesC if the speed dial position requested has not been set.

Return Value: The ID of the contact item for which the speed dial has been set.

Capability
ReadUserData

GroupCount ( )

TInt

GroupCount

(

)

const [inline]

Gets the number of groups that exist in the database. DeprecatedGets the number of groups that exist in the database. Deprecated

Return Value: The number of groups that exist in the database.The number of groups that exist in the database.

HandleDatabaseEventL ( RDbNotifier::TEvent )

void

HandleDatabaseEventL

(

RDbNotifier::TEvent

)

[inline, virtual]

Reimplemented from MContactDbPrivObserver::HandleDatabaseEventL(RDbNotifier::TEvent)

HandleDatabaseEventL ( const TContactDbObserverEvent & )

IMPORT_C void

HandleDatabaseEventL

(

const TContactDbObserverEvent &

aEvent

)

[virtual]

Reimplemented from MContactDbPrivObserver::HandleDatabaseEventL(const TContactDbObserverEvent &)

Handle the Database event

Parameters
aEvent	Database change event

HandleDiskSpaceEvent ( TInt )

void

HandleDiskSpaceEvent

(

TInt

aDrive

)

[virtual]

Reimplemented from MContactStorageObserver::HandleDiskSpaceEvent(TInt)

Default behaviour for handling a low disk event - This function is unimplemented.

ICCTemplateIdL ( )

IMPORT_C TContactItemId

ICCTemplateIdL

(

)

Returns the ID of the template that should be used with CContactICCEntry items.

Return Value: A template ID.

Capability
None

ICCTemplateIdL ( TUid )

IMPORT_C TContactItemId

ICCTemplateIdL

(

TUid

aPhonebookUid

)

Returns the ID of the template that should be used with CContactICCEntry items belonging to the phonebook with TUid aPhonebookUid.

Parameters
aPhonebookUid	The phonebook ID.

Return Value: A template ID.

Capability
None

ImportContactsL ( const TUid &, RReadStream &, TBool &, TInt )

IMPORT_C CArrayPtr< CContactItem > *	ImportContactsL	(	const TUid &	aFormat,
			RReadStream &	aReadStream,
			TBool &	aImportSuccessful,
			TInt	aOption
		)

Imports one or more vCards from a read stream. The vCards are converted into contact items, and added to the database. If at least one contact item was successfully imported, aImportSuccessful is set to ETrue. If EImportSingleContact is specified in aOption, the read stream marker is left at the next position, ready to read the next contact item. The caller takes ownership of the returned object.

Parameters
aFormat	Indicates the format for imported and exported contacts. Its value must be KUidVCardConvDefaultImpl.
aReadStream	The stream to read from.
aImportSuccessful	On return, ETrue if at least one contact was successfully imported. EFalse if not.
aOption	Indicates the options for import and export. See the TOptions enum.

Return Value: The array of contact items imported.

Leave Codes
KErrNotSupported	aFormat.iUid is not KUidVCardConvDefaultImpl.

Capability
WriteUserData

IsDamaged ( )

IMPORT_C TBool

IsDamaged

(

)

const

This function is deprecated. It always returns EFalse.

Deprecated

Return Value: EFalse

Capability
None

IsICCSynchronisedL ( )

IsICCSynchronisedL

(

)

ListDatabasesL ( )

IMPORT_C CDesCArray *

ListDatabasesL

(

)

[static]

A static method to list the contact databases on all drives.

In v8.1, this function finds contact databases located anywhere on the drives, and the format of the returned filenames is c:\system\data\contacts.cdb.

From v9.0 onwards, this function finds contact databases only in the correct data caged subdirectory. The returned filenames have no path, for example c:contacts.cdb. The maximum length for the drive, filename and extension is 190 characters.

In either case, the filenames returned are in the correct format for Open(), OpenL(), CreateL(), ReplaceL() and DeleteDatabaseL().

Return Value: An array containing zero or more contact database names.

Leave Codes
KErrNoMemory	Out of memory.

Capability
ReadUserData

ListDatabasesL ( TDriveUnit )

IMPORT_C CDesCArray *

ListDatabasesL

(

TDriveUnit

aDriveUnit

)

[static]

A static method to list the contact databases on a specified drive.

In v8.1, this function finds contact databases located anywhere on the drive, and the format of the returned filenames is c:\system\data\contacts.cdb.

In either case, the filenames returned are in the correct format for Open(), OpenL(), CreateL(), ReplaceL() and DeleteDatabaseL().

Parameters
aDriveUnit	The drive unit to search for contact databases.

Return Value: An array containing zero or more contact database names.

Leave Codes
KErrNoMemory	Out of memory.

Capability
ReadUserData

LockServerCallBackL ( TUint )

IMPORT_C TInt

LockServerCallBackL

(

TUint

aServerOperation

)

For BC.

LockServerCleanup ( )

IMPORT_C void

LockServerCleanup

(

)

For BC.

LockServerConnectL ( const TDesC & )

IMPORT_C CContactDatabase *

LockServerConnectL

(

const TDesC &

aFileName

)

[static]

For BC.

LockServerConnectL ( const TDesC &, TInt )

IMPORT_C CContactDatabase *	LockServerConnectL	(	const TDesC &	aFileName,
			TInt	aOperation
		)	[static]

For BC.

MachineId ( )

IMPORT_C TInt64

MachineId

(

)

const

Returns a number unique to the contacts database. This value may be passed to CContactItem::UidStringL().

Return Value: The database's unique ID.

Capability
None

MatchPhoneNumberL ( const TDesC & )

IMPORT_C CContactIdArray *

MatchPhoneNumberL

(

const TDesC &

aNumber

)

It makes a lookup of Contacts by comparing Contact numbers with an input number as TDesc& (aNumber). The amount of digits from the right to match two numbers is read from configuration. Returns an array of contact item IDs for all the contact items which may contain the specified telephone number in a telephone, fax or mobile type field.

The method returns an array of candidate matches. Punctuation (e.g. spaces), '+' and other alphabetic characters are ignored when comparing. Leading zeros are removed.

The comparison method used is not exact. The amount of digits from the right that is used to compare input and Contact phone numbers is read from configuration. If Dynamic Matching is enabled by configuration and more digits are available in both numbers, 1 or 2 (as maximum) extra digits are used for phone numbers comparison. If both input and Contact phone numbers are shorter than aMatchLengthFromRight, they match if they are identical.

Additionally, if the contacts model phone parser (CNTPHONE.DLL) is available, then any DTMF digits are also excluded from the comparision.

Parameters
aNumber	Phone number string. If the length of phone number string is greater than KCntMaxTextFieldLength then only the first KCntMaxTextFieldLength characters are used in the match.

Return Value: Array of contact IDs which are candidate matches.CContactIdArray of candidate Contact matches.

Capability
ReadUserData

MatchPhoneNumberL ( const TDesC &, TInt )

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

It makes a lookup of Contacts by comparing Contact numbers with an input number as TDesc& (aNumber) using an input amount of digits from the right (aMatchLengthFromRight) to match two numbers. DeprecatedUse the version of the method that does not require aMatchLengthFromRight.

This method is the same as CContactDatabase::MatchPhoneNumberL(const TDesC& aNumber) with the difference that another parameter is requested: The amount of digits from the right that is used to compare input and Contact phone numbers is not read from configuration, but the client needs to provide it.

Notes: Due to the way numbers are stored in the database, it is recommended that at least 7 match digits are specified even when matching a number containing fewer digits. Failure to follow this guideline may (depending on the database contents) mean that the function will not return the expected Contacts Id set.

DeprecatedUse the version of the method that does not requre aMatchLengthFromRight.

Parameters
aNumber	Phone number string. If the length of phone number string is greater than KCntMaxTextFieldLength then only the first KCntMaxTextFieldLength characters are used in the match.
aMatchLengthFromRight	Number of digits from the right of the phone number to use Up to 15 digits can be specified, and it is recommended that at least 7 match digits are specified.

Return Value: Array of contact IDs which are candidate matches. CContactIdArray of candidate Contact matches.

Capability
ReadUserData

NullUidValue ( )

TInt

NullUidValue

(

)

[static, inline]

Gets the NULL contact ID value.

Return Value: KNullContactId.

Open ( TRequestStatus &, TThreadAccess )

IMPORT_C CContactOpenOperation *	Open	(	TRequestStatus &	aStatus,
			TThreadAccess	aAccess = ESingleThread
		)	[static]

Opens the default contact database asynchronously.

The Contacts server is asked to prepare the database to be opened. This may include cleaning up incomplete writes from when the device was last switched off, or updating the database format.

If an error is encountered starting the asynchronous open the return value is NULL and the error is returned in the TRequestStatus parameter.

Errors from the asynchronous open include: KErrNotFound The database file was not found or it did not have the correct UIDs. KErrLocked The file is in use by another client. Other system wide error codes.

If the return value is not NULL the ownership of the CContactOpenOperation object is passed to the client. This may be deleted before the asynchronous open completes.

When the client supplied TRequestStatus is completed with KErrNone the TakeDatabase() method of CContactOpenOperation is called to pass ownership of the open database to the client.

Open ( const TDesC &, TRequestStatus &, TThreadAccess )

IMPORT_C CContactOpenOperation *	Open	(	const TDesC &	aFileName,
			TRequestStatus &	aStatus,
			TThreadAccess	aAccess = ESingleThread
		)	[static]

Opens a named contact database asynchronously.

The Contacts server is asked to prepare the database to be opened. This may include cleaning up incomplete writes from when the device was last switched off, or updating the database format.

In v8.1, contact databases can be located in any directory on any writeable drive, and the format of the filename must include an absolute directory path such as c:\system\data\contacts.cdb.

If an empty path is entered, it will be treated as a request to open the default contact database.

If an error is encountered starting the asynchronous open the return value is NULL and the error is returned in the TRequestStatus parameter.

Errors from the asynchronous open include: KErrNotFound The database file was not found or it did not have the correct UIDs. KErrLocked The file is in use by another client. KErrBadName The filename is invalid; for example it includes wildcard characters or the drive is missing. Other system wide error codes.

If the return value is not NULL the ownership of the CContactOpenOperation object is passed to the client. This may be deleted before the asynchronous open completes.

When the client supplied TRequestStatus is completed with KErrNone the TakeDatabase() method of CContactOpenOperation is called to pass ownership of the open database to the client.

OpenContactL ( TContactItemId )

IMPORT_C CContactItem *

OpenContactL

(

aContactId

)

Opens a contact item for editing.

The returned contact item is locked and left open until either CommitContactL() or CloseContactL() is called.

This function uses a view definition that loads every field. If you need to specify your own view definition use the other overload of this function.

The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to open.

Return Value: The open, locked contact.

Leave Codes
KErrInUse	The contact item is already open.
KErrNotFound	The contact item is not present in the database.

Capability
WriteUserData

OpenContactL ( TContactItemId, const CContactItemViewDef & )

IMPORT_C CContactItem *	OpenContactL	(	TContactItemId	aContactId,
			const CContactItemViewDef &	aViewDef
		)

Opens a contact item for editing, leaving the lock record on the cleanup stack.

The returned item is locked and left open until either CommitContactL() or CloseContactL() is called.

This function uses the specified view definition. Note: Care should be taken when specifying a view definition because when committing the contact item any fields not loaded by the view definition are deleted from the item.

The caller takes ownership of the returned object.

Deprecated

Parameters
aContactId	The ID of the contact item to open.
aViewDef	The view definition.

Return Value: The open, locked contact item.

Leave Codes
KErrInUse	The contact item is already open
KErrNotFound	The contact item is not present in the database.

Capability
WriteUserData

OpenContactLX ( TContactItemId )

IMPORT_C CContactItem *

OpenContactLX

(

aContactId

)

Opens a contact item for editing using a specified view definition.

The returned contact item is locked and left open until either CommitContactL() or CloseContactL() is called.

Note: care should be taken when specifying a view definition because when committing the contact item, any fields not loaded by the view definition are deleted from the item.

The caller takes ownership of the returned object.

Deprecated

Parameters
aContactId	The ID of the contact item to open.

Return Value: The open, locked contact.

Leave Codes
KErrInUse	The contact item is already open.
KErrNotFound	The contact item is not present in the database.

Capability
WriteUserData

OpenContactLX ( TContactItemId, const CContactItemViewDef & )

IMPORT_C CContactItem *	OpenContactLX	(	TContactItemId	aContactId,
			const CContactItemViewDef &	aViewDef
		)

Opens a contact item for editing, leaving the lock record on the cleanup stack.

The returned item is locked and left open until either CommitContactL() or CloseContactL() is called.

The caller takes ownership of the returned object.

Deprecated

Parameters
aContactId	The ID of the contact item to open.
aViewDef	The view definition.

Return Value: The open, locked contact item.

Leave Codes
KErrInUse	The contact item is already open
KErrNotFound	The contact item is not present in the database.

Capability
WriteUserData

OpenDatabaseAsyncL ( TRequestStatus &, const TDesC & )

void	OpenDatabaseAsyncL	(	TRequestStatus &	aStatus,
			const TDesC &	aFileName = KNullDesC
		)

OpenL ( TThreadAccess )

IMPORT_C CContactDatabase *

OpenL

(

aAccess = ESingleThread

)

[static]

Opens the default contact database.

Note: clients should not assume any knowledge of the default database name or location because they may be changed in future releases.

Parameters
aAccess	The default (ESingleThread) allows access to the session with the database server from a single client thread only (as in v5 and v5.1). EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers

Return Value: Pointer to the open contact database.

Leave Codes
KErrNotFound	The database file was not found or it did not have the correct UIDs.
KErrLocked	Another client is writing to the database.
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
ReadUserData

OpenL ( const TDesC &, TThreadAccess )

IMPORT_C CContactDatabase *	OpenL	(	const TDesC &	aFileName,
			TThreadAccess	aAccess = ESingleThread
		)	[static]

Opens a named contact database.

Parameters
aFileName	The filename of the database to open.
aAccess	The default (ESingleThread) allows access to the session with the database server from a single client thread only (as in v5 and v5.1). EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers

Return Value: A pointer to the open contact database.

Leave Codes
KErrNotFound	The database file was not found or it did not have the correct UIDs.
KErrLocked	Another client is writing to the database.
KErrBadName	The filename is invalid; for example it contains wildcard characters or the drive is missing.
KErrDiskFull	The disk does not have enough free space to perform the operation.
KErrArgument	if the given descriptor contains more than the maximum length of 190 characters.

Capability
ReadUserData

OpenTablesL ( )

IMPORT_C void

OpenTablesL

(

)

This method is no longer required and should not be called.

Opens all database tables. After a rollback and recover all tables need to be closed and re-opened before the database can be accessed again.

Deprecated

Capability
ReadUserData

OpenV2L ( TThreadAccess )

IMPORT_C CContactDatabase *

OpenV2L

(

aAccess = ESingleThread

)

[static]

OverrideMachineUniqueId ( TInt64 )

IMPORT_C void

OverrideMachineUniqueId

(

TInt64

aMachineUniqueId

)

Debug only.

Parameters
aMachineUniqueId	The Machine ID to set.

Capability
None

OwnCardId ( )

IMPORT_C TContactItemId

OwnCardId

(

)

const

Returns the ID of the database's current own card.

Having obtained this ID, the client may then open the own card in the same way as an ordinary contact card (using ReadContactL() or OpenContactL()).

Return Value: The ID of the database's current own card. KNullContactId if the own card has been deleted or has not yet been set.

Capability
None

PhonebookGroupIdL ( )

IMPORT_C TContactItemId

PhonebookGroupIdL

(

)

Returns the ID of the contacts model group which represents the ADN phonebook.

Return Value: Group ID.

Capability
None

PrefTemplateId ( )

IMPORT_C TContactItemId

PrefTemplateId

(

)

const

Returns the ID of the database's preferred template, as set by SetPrefTemplateL(). KNullContactId if not set. The preferred template is for clients who may have multiple templates but want to identify one as preferred.

Return Value: The ID of the database's current preferred template.

Capability
None

ReadContactAndAgentL ( TContactItemId )

IMPORT_C CArrayPtr< CContactItem > *

ReadContactAndAgentL

(

aContactId

)

Reads a contact item and an agent if the item has an agent field. The item and agent (if present) are returned in an array. The function uses the database's default view definition (as set by SetViewDefinitionL()). The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to read.

Return Value: Pointer to an array containing the contact item and agent, if present.

Leave Codes
KErrNotFound	The specified contact item cannot be found in the database.

Capability
ReadUserData

ReadContactL ( TContactItemId )

IMPORT_C CContactItem *

ReadContactL

(

aContactId

)

Reads a contact item without locking it.

This function uses the default view definition (as set by SetViewDefinitionL()). The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to read.

Return Value: Pointer to the contact item.

Leave Codes
KErrNotFound	The specified contact item does not exist in the database.

Capability
ReadUserData

ReadContactL ( TContactItemId, const CContactItemViewDef & )

IMPORT_C CContactItem *	ReadContactL	(	TContactItemId	aContactId,
			const CContactItemViewDef &	aViewDef
		)

Reads a contact item without locking it.

This function uses the view definition specified. The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to read.
aViewDef	The view definition to use.

Return Value: Pointer to the contact item.

Leave Codes
KErrNotFound	The specified contact item does not exist in the database.

Capability
ReadUserData

ReadContactLC ( TContactItemId )

IMPORT_C CContactItem *

ReadContactLC

(

aContactId

)

Reads a contact item without locking it.

This function uses the default view definition (as set by SetViewDefinitionL()). The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to read.

Return Value: Pointer to the contact item. This is left on the cleanup stack.

Leave Codes
KErrNotFound	The specified contact item does not exist in the database.

Capability
ReadUserData

ReadContactLC ( TContactItemId, const CContactItemViewDef & )

IMPORT_C CContactItem *	ReadContactLC	(	TContactItemId	aContactId,
			const CContactItemViewDef &	aViewDef
		)

Reads a contact item without locking it.

This function uses the view definition specified. The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact item to read.
aViewDef	The view definition to use.

Return Value: Pointer to the contact item. This is left on the cleanup stack.

Leave Codes
KErrNotFound	The specified contact item does not exist in the database.

Capability
ReadUserData

ReadContactTextDefL ( const CContactItem &, TDes & )

IMPORT_C void	ReadContactTextDefL	(	const CContactItem &	aItem,
			TDes &	aResult
		)

Reads text into a descriptor from a pre-loaded contact item.

This function uses the database's current text definition (as set using CContactDatabase::SetTextDefinitionL()).

Parameters
aItem	The contact item to read.
aResult	On return, contains the text read from the contact item aItem, using the database's current text definition.

Capability
ReadUserData

ReadContactTextDefL ( const CContactItem &, TDes &, CContactTextDef * )

IMPORT_C void	ReadContactTextDefL	(	const CContactItem &	aItem,
			TDes &	aResult,
			CContactTextDef *	aTextDef
		)

Reads text into a descriptor from a pre-loaded contact item, using the specified text definition.

Parameters
aItem	The contact item to read.
aResult	On return, contains the text read from the contact item aItem, using the text definition specified in aTextDef.
aTextDef	The text definition to use.

Capability
ReadUserData

ReadContactTextDefL ( TContactItemId, TDes & )

IMPORT_C void	ReadContactTextDefL	(	TContactItemId	aContactId,
			TDes &	aResult
		)

Reads text from a contact item stored in the database into a descriptor.

This function uses the database's currently set text definition (as set using CContactDatabase::SetTextDefinitionL()).

Parameters
aContactId	The ID of the contact to read.
aResult	On return, contains the text read from the contact item identified by aContactId, using the database's current text definition.

Leave Codes
KErrNotFound	The specified contact item cannot be found in the database.

Capability
ReadUserData

ReadContactTextDefL ( TContactItemId, TDes &, CContactTextDef * )

IMPORT_C void	ReadContactTextDefL	(	TContactItemId	aContactId,
			TDes &	aResult,
			CContactTextDef *	aTextDef
		)

Reads text from a contact item stored in the database into a descriptor using the specified text definition.

Parameters
aContactId	The ID of the contact to read.
aResult	On return, contains the text read from the contact item identified by aContactId, using the text definition specified in aTextDef.
aTextDef	The text definition to use.

Leave Codes
KErrNotFound	The specified contact item cannot be found in the database.

Capability
ReadUserData

ReadMinimalContactL ( TContactItemId )

IMPORT_C CContactItem *

ReadMinimalContactL

(

aContactId

)

Reads a contact item (contact card, own card, template, or contact group), but does not read the group or template information.

This function is identical to the variant of ReadContactL() which uses the database's default view definition, except that this function does not read:

the list of group members and the group label (if the item is a CContactGroup)
the template label (if the item is a CContactCardTemplate)
the list of groups to which the item belongs, if any (not applicable to templates)
any fields inherited from a non-system template, if any (not applicable if the item is a CContactCardTemplate)

Notes:

This function is faster than the standard reading function (ReadContactL()), which needs to match the template fields and groups etc.

The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact to read.

Return Value: Pointer to the contact whose ID is aContactId.

Leave Codes
KErrNotFound	The specified contact item cannot be found in the database.

Capability
ReadUserData

ReadMinimalContactLC ( TContactItemId )

IMPORT_C CContactItem *

ReadMinimalContactLC

(

aContactId

)

Reads a contact item (contact card, own card, template, or contact group), but does not read the group or template information.

This function is identical to the variant of ReadContactLC() which uses the server's default view definition, except that this function does not read:

the list of group members and the group label (if the item is a CContactGroup)
the template label (if the item is a CContactCardTemplate)
the list of groups to which the item belongs, if any (not applicable to templates)
any fields inherited from a non-system template, if any (not applicable if the item is a CContactCardTemplate)

Notes:

This function is faster than the standard reading function (ReadContactLC()), which needs to match the template fields and groups etc.

The caller takes ownership of the returned object.

Parameters
aContactId	The ID of the contact to read.

Return Value: Pointer to the contact whose ID is aContactId. The contact is left on the cleanup stack.

Leave Codes
KErrNotFound	The specified contact item cannot be found in the database.

Capability
ReadUserData

RecoverL ( )

IMPORT_C void

RecoverL

(

)

Recovers the database from a rollback. It first closes all tables and then reopens them after the recover.

Capability
WriteUserData

RecreateSystemTemplateL ( const TDesC & )

IMPORT_C void

RecreateSystemTemplateL

(

const TDesC &

aFileName

)

[static]

A static method to recreate the system template.

Parameters
aFileName	The contact database filename.

Leave Codes
KErrBadName	The filename is invalid; for example it contains wildcard characters or the drive letter is missing.
KErrArgument	if the given descriptor contains more than the maximum length of 190 characters.

Capability
ReadUserData
WriteUserData

RemoveContactFromGroupL ( CContactItem &, CContactItem & )

IMPORT_C void	RemoveContactFromGroupL	(	CContactItem &	aItem,
			CContactItem &	aGroup
		)

Removes the association between a contact item and a group.

Parameters
aItem	The item to remove.
aGroup	The group from which the item should be removed.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

RemoveContactFromGroupL ( TContactItemId, TContactItemId )

IMPORT_C void	RemoveContactFromGroupL	(	TContactItemId	aItemId,
			TContactItemId	aGroupId
		)

Removes the association between a contact item and a group.

The item and group are identified by their IDs.

Parameters
aItemId	The ID of the item to remove.
aGroupId	The ID of the group from which the item should be removed.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

RemoveContactsFromGroupL ( RArray< TContactItemId > &, TContactItemId )

IMPORT_C void	RemoveContactsFromGroupL	(	RArray< TContactItemId > &	aItemIdList,
			TContactItemId	aGroupId
		)

Removes the association between a list of contact items and a group.

The items and the group are identified by their IDs.

Parameters
aGroupId	The ID of the group from which the items should be removed.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
WriteUserData

RemoveObserver ( const MContactDbObserver & )

void IMPORT_C

RemoveObserver

(

const MContactDbObserver &

aChangeNotifier

)

RemoveObserverV2 ( const MContactDbObserverV2 & )

void IMPORT_C

RemoveObserverV2

(

const MContactDbObserverV2 &

aChangeNotifier

)

RemoveSpeedDialFieldL ( TContactItemId, TInt )

IMPORT_C void	RemoveSpeedDialFieldL	(	TContactItemId	aContactId,
			TInt	aSpeedDialPosition
		)

Removes the mapping between a contact item field and a speed dial position.

Removes the KUidSpeedDialXxx UID from the field's content type, removes the field's speed dial attribute and commits the changes to the item.

Parameters
aContactId	The ID of the contact item containing the speed dial field.
aSpeedDialPosition	The speed dial position. This is an integer in the range 1 to 9 inclusive. If outside this range, the function leaves with KErrArgument.

Leave Codes
KErrDiskFull	The disk does not have enough free space to perform the operation.

Capability
ReadUserData
WriteUserData

ReplaceL ( TThreadAccess )

IMPORT_C CContactDatabase *

ReplaceL

(