EPOC   SDK Home Glossary Indexes Previous Next Up

CContactDatabase class


Contents


CContactDatabase class — Database of contact items

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behaviour.

MContactDbPrivObserver

Abstract: defines HandleDatabaseEventL() function

Defined in

cntdb.h

Link against

cntmodel.lib

Description

CContactDatabase provides access to a database of contact items.

More than one contact database can exist on an EPOC device, but there is always a single default contact database. The default database is the database which is loaded by default when the Contacts application starts up. Its filename is contacts.cdb. The default database can be moved between drives, but must always be stored in the \system\data\ folder.

Items within the contact database can be opened or read. Opening an item locks it, so that changes can be made to the item; reading does not cause locking, so no changes can be made. Changes to the item can be commited to the database using CommitContactL(). Committing can only take place if the item has been locked.

Contact items can be added to and removed from the database. When deleting a contact item, it is important to consider that each contact item has an access count, and the item cannot be fully deleted unless its access count is zero. This is to prevent contact items from being deleted until it is safe to do so. An item's access count is greater than zero if for example it has been synchronized with a PC scheduler application, or, if the item is a template, it must not be deleted if other items are referencing it.

The CContactDatabase API provides the ability to search and sort the database. It also provides separate phone number matching functions. Phone number matching provides a high speed method of indexing and looking up phone numbers. This is primarily intended for looking up caller IDs on incoming calls. Before looking up phone numbers, the index must be created. This only needs to be done once, when the contact database is opened. From then on, the index is automatically maintained by the server. Index creation is started by a call to InitLoadPhoneMatchesL(). Then, it is updated using calls to LoadPhoneMatchesL().

The following functions defined in class CContactDatabase are not supported in EPOC Release 5. If called, they leave with KErrNotSupported.


Create and open


OpenL() — Open the default contact database

static CContactDatabase* OpenL();

Description

Opens the default contact database.

The default name for the contact database is hard coded as \system\data\contacts.cdb. By default it is assumed to be on drive c:, but this can be changed using the SetDatabaseDriveL() function.

Return value

CContactDatabase*

The default database.

Leave considerations

The function leaves with KErrNotFound if the default database file does not exist.

Note

Clients should not assume any knowledge of the database name or location — they may be changed in future releases.


OpenL() — Open the named contact database

static CContactDatabase* OpenL(const TDesC& aFileName);

Description

Open the specified contact database.

Arguments

const TDesC& aFileName

The path and filename of the database to open.

Return value

CContactDatabase*

Pointer to the open contact database.

Leave considerations

The function leaves with KErrNotFound if the database file does not exist.


CreateL() — Create a default contact database

static CContactDatabase* CreateL();

Description

Create and open an empty contact database with the default name.

Return value

CContactDatabase*

Pointer to the new default database.

Leave considerations

This function leaves with KErrAlreadyExists if the database file already exists.


CreateL() — Create a named contact database

static CContactDatabase* CreateL(const TDesC& aFileName);

Description

Create and open an empty contact database with the specified name.

Arguments

const TDesC& aFileName

The path and filename of the database to create.

Return value

CContactDatabase*

Pointer to the new contact database.

Leave considerations

This function leaves with KErrAlreadyExists if the database file already exists.


ReplaceL() — Replace default database

static CContactDatabase* ReplaceL();

Description

Create and open an empty contact database with the default name. This replaces any existing file of the same name.

Return value

CContactDatabase*

Pointer to the new contact database.


ReplaceL() — Replace database with specified name

static CContactDatabase* ReplaceL(const TDesC& aFileName);

Description

Create and open an empty contact database with the specified filename. This replaces any existing file of the same name.

Arguments

const TDesC& aFileName

The path and filename of the database to create.

Return value

CContactDatabase*

Pointer to the new contact database.


DeleteDefaultFileL() — Delete default contact database

static void DeleteDefaultFileL();

Description

Delete the default contact database as retrieved by GetDefaultNameL().


Location


DatabaseDrive() — Get database drive

static TBool DatabaseDrive(TDriveUnit& aDriveUnit);

Description

Retrieve the currently set database drive.

The database drive is the drive on which the default contact database is located.

Arguments

TDriveUnit& aDriveUnit

On return, contains the database drive.

Return value

TBool

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.


SetDatabaseDriveL() — Set database drive

static void SetDatabaseDriveL(TDriveUnit aDriveUnit, TBool aCopy=ETrue);

Description

Set the contact database drive and optionally move the default contact database from its current location to the new drive. This function guarantees an all or nothing operation. If the database is not successfully moved, the drive setting is not updated to reflect the change.

Arguments

TDriveUnit aDriveUnit

The drive to which to move the database.

TBool aCopy=ETrue

ETrue to move the existing file to \system\data\ on the specified drive. EFalse does not move the file.

Leave considerations

If there is no media present in the drive, the function leaves with KErrNotReady.

Notes

This function is used for example by the Contacts application; see the Tools|Preferences... menu option to change the disk for the contacts store.


FindContactFile() — Get the location of contact file

static TBool FindContactFile(TDes& aFileName);

Description

This function finds the location of the contact database with the default file name (\system\data\contacts.cdb). Drives are searched using class TFindFile and the name of the first file found is copied into aFileName.

Arguments

TDes& aFileName

On return, contains the full path and filename of the default contact database.

Return value

TBool

EFalse if no file is found. ETrue if a file is found.


GetDefaultNameL() — Get path and filename of default contact database

static void GetDefaultNameL(TDes& aDes);

Description

Get the full file name of the default contact database.

The name of the default contact database is \system\data\contacts.cdb. By default it is assumed to be on drive c:, but this can be changed using the SetDatabaseDriveL() function.

This function cannot leave.

Arguments

TDes& aDes

On return, contains the full path and filename of the default contact database.


View and text definitions


SetViewDefinitionL() — Set current view definition

void SetViewDefinitionL(CContactViewDef* aView);

Description

Set the current view definition. The contact database takes ownership of the view definition specified.

Arguments

CContactViewDef* aView

The view definition.


SetTextDefinitionL() — Set current text definition

void SetTextDefinitionL(CContactTextDef* aView);

Description

Set the current text definition. The contact database takes ownership of the text definition specified.

Arguments

CContactTextDef* aView

The new text definition.


TextDefinition() — Get current text definition

const CContactTextDef* TextDefinition() const;

Description

Return a pointer to the current text definition.

Return value

CContactTextDef*

A pointer to the current text definition.


Open and close a contact


OpenContactL() — Open a contact for editing, optionally specifying a view definition

CContactItem* OpenContactL(TContactItemId aContactId);

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

Description

Both of these functions open the contact for editing. The returned contact is locked and left open until either CommitContactL() or CloseContactL() is called.

The variant of the function which does not take a view definition parameter uses a view definition which loads every field.

Arguments

TContactItemId aContactId

The ID of the contact to open.

const CContactItemViewDef& aViewDef

If specified, the view definition.

Return value

CContactItem*

The open, locked contact.

Leave considerations

This function leaves with KErrInUse if the contact is already locked or KErrNotFound if the contact is not present in the database.

Notes

Care should be taken when specifying a view definition because when committing the contact any fields not loaded by the view definition are deleted from the contact.


OpenContactLX() — Open a contact for editing, optionally specifying a view definition

CContactItem* OpenContactLX(TContactItemId aContactId);

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

Description

Both of these functions open the contact item for editing. The returned contact is locked and left open until either CommitContactL() or CloseContactL() is called.

The variant of the function which does not take a view definition parameter uses a view definition which loads every field.

The LX suffix means that the lock record of the contact item is left on the cleanup stack.

Arguments

TContactItemId aContactId

The ID of the contact to open.

const CContactItemViewDef& aViewDef

The view definition.

Return value

CContactItem*

The open, locked contact.

Leave considerations

This function leaves with KErrInUse if the contact is already locked or KErrNotFound if the contact is not present in the database.

Notes

Care should be taken when specifying a view definition because when committing the contact any fields not loaded by the view definition are deleted from the contact.


CloseContactL() — Close a contact

void CloseContactL(TContactItemId aContactId);

Description

Close 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.

Arguments

TContactItemId aContactId

The ID of the contact to close.


CommitContactL() — Overwrite a contact

void CommitContactL(const CContactItem& aContact);

Description

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

Arguments

const CContactItem& aContact

Contains the new values for the contact item.

Leave considerations

This function leaves with KErrAccessDenied if the contact item is not locked by the caller, or with KErrNotFound if the contact item's ID is not present in the database.


Reading


ReadContactL() — Read a contact, optionally specifying a view definition

CContactItem* ReadContactL(TContactItemId aContactId);

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

Description

Both of these functions read the contact item specified. Unlike OpenContactL(), these functions do not lock the contact.

The variant of the function which does not take a view definition parameter uses a view definition which loads every field.

Arguments

TContactItemId aContactId

The ID of the contact item to read.

const CContactItemViewDef& aViewDef

If specified, the view definition to use.

Return value

CContactItem*

Pointer to the contact item read.

Leave considerations

If the specified contact item does not exist in the database, these functions leave with KErrNotFound.


ReadContactLC() — Read a contact, optionally specifying a view definition

CContactItem* ReadContactLC(TContactItemId aContactId);

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

Description

Both of these functions read the contact specified. Unlike OpenContactL(), these functions do not lock the contact.

The variant of the function which does not take a view definition parameter uses a view definition which loads every field.

Arguments

TContactItemId aContactId

The ID of the contact to read.

const CContactItemViewDef& aViewDef

If specified, the view definition to use.

Return value

CContactItem*

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

Leave considerations

If the specified contact does not exist in the database, these functions leave with KErrNotFound.


ReadContactTextDefL() — Read pre-loaded contact using text definition

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

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

Description

Both of these functions read text into aResult from a pre-loaded contact item, using a text definition.

The variant of the function which does not take a text definition parameter uses the database's currently set text definition (as set using CContactDatabase::SetTextDefinitionL()).

Arguments

const CContactItem& aItem

The contact item to read.

TDes& aResult

On return, contains the text read from the contact item aItem, using either the database's current text definition or the text definition specified in aTextDef.

CContactTextDef* aTextDef

If specified, the text definition to use.


ReadContactTextDefL() — Read contact using text definition

void ReadContactTextDefL(TContactItemId aContactId, TDes& aResult);

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

Description

Both of these functions read text from a contact item stored in the database into aResult. They use the database's currently set text definition (as set using CContactDatabase::SetTextDefinitionL()), or, if specified, the text definition aTextDef. The contact item is identified by its contact ID.

Arguments

TContactItemId aContactId

The ID of the contact to read.

TDes& aResult

On return, contains the text read from the contact item identified by aContactId, using either the database's current text definition or the text definition specified in aTextDef.

CContactTextDef* aTextDef

If specified, the text definition to use.

Leave considerations

If the contact identified by aContactId does not exist in the database, these functions leave with KErrNotFound.


Add and remove items


AddNewContactL() — Add new contact

TContactItemId AddNewContactL(CContactItem& aContact);

Description

Add a new contact item to the database and return its contact ID.

Arguments

CContactItem& aContact

The contact item to add to the database.

Return value

TContactItemId

The ID of the new contact item.


DeleteContactL() — Delete a contact

void DeleteContactL(TContactItemId aContactId);

Description

Delete the specified contact item.

Arguments

TContactItemId aContactId

The ID of the contact to delete.

Notes

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.

Leave considerations

Leaves with KErrNotFound if aContactId is not present in the database.

Leaves with KErrInUse if the contact is open.


DeleteContactsL() — Delete array of contacts

void DeleteContactsL(const CContactIdArray& aContactIds);

Description

Delete an array of contacts. The function commits the database for every 16 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 the contacts have been deleted and all the changes committed.

Arguments

const CContactIdArray& aContactIds

An array of contacts to delete.

Leave considerations

Leaves with KErrNotFound if any contact ID contained in the array is not present in the database.

Leaves with KErrInUse if any of the contacts are open.


Import and export


ImportContactsL() — Import contacts from read stream

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

Description

Import one or more contacts from aReadStream into the database. If at least one contact was successfully imported, aImportSuccessful is set to ETrue. When using the EImportSingleContact option, the read stream marker is left at the next position, ready to read the next contact.

Arguments

const TUid& aFormat

Indicates the format for imported and exported contacts.

In EPOC Release 5, only one format is supported, KVersitEntityUidVCard.

RReadStream& aReadStream

The stream to read from.

TBool& aImportSuccessful

ETrue if at least one contact was successfully imported. EFalse if not.

TInt aOption

Indicates the options for import and export.

See the TOptions enum.

Return value

CArrayPtr<CContactItem>*

The array of contacts imported.

Leave considerations

This function leaves with KErrNotSupported if aFormat.iUid is not KVersitEntityUidVCard.


ExportSelectedContactsL() — Export contacts to write stream

void ExportSelectedContactsL(const TUid& aFormat,const CContactIdArray& aSelectedContactIds,RWriteStream& aWriteStream,TInt aOption);

Description

Export the specified array of contacts to the write stream.

Arguments

const TUid& aFormat

Indicates the format for imported and exported contacts.

In EPOC Release 5 only one format is supported, KVersitEntityUidVCard.

const CContactIdArray& aSelectedContactIds

Array of contact IDs to export.

RWriteStream& aWriteStream

The stream to write to.

TInt aOption

Indicates the options for import and export.

See the TOptions enum.

Leave considerations

This function leaves with KErrNotSupported if aFormat.iUid is not KVersitEntityUidVCard.

If any of the contacts do not exist in the database, the function leaves with KErrNotFound.


Search


FindLC() — Find text

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

Description

Search the database for the specified text in all of the fields identified by a field definition.

Arguments

const TDesC& aText

The text to search for.

const CContactItemFieldDef *aFieldDef

Specifies the fields to search.

Return value

CContactIdArray*

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


FindAsyncL() — Find text asynchronously

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

Description

Search the database for the specified text in all of the fields identified by aFieldDef.

Works asynchronously using the MIdleFindObserver and CIdleFinder classes.

Arguments

const TDesC& aText

The text to search for.

const CContactItemFieldDef *aFieldDef

Specifies the fields to search.

MIdleFindObserver *aObserver

Implements the callback function IdleFindCallback(). May be NULL if no observer is needed.

Return value

CIdleFinder*

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.


FindInTextDefLC() — Find array of words

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

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

Description

The purpose of this function is to allow the user to search the database for a string containing text which 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". Although to the end user the string is a single item, 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 specified by the text definition aTextDef, if specified. If not specified, the function uses the currently set text definition.

Arguments

const MDesCArray& aFindWords

An array of words to find.

const TCallBack& aWordParserCallback

A function supplied by the caller to break the text in the contact down into a list of words.

CContactTextDef* aTextDef

If specified, the text definition.

Return value

CContactIdArray*

Array of contact IDs.


FindInTextDefAsyncL() — Find array of words asynchronously

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

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

Description

Search the database for an array of words.

These two functions work in the same way as the corresponding variants of FindInTextDefLC(), except that they operate asynchronously using the MIdleFindObserver and CIdleFinder classes.

Arguments

const MDesCArray& aFindWords

An array of words to find.

MIdleFindObserver *aObserver

Implements the callback function IdleFindCallback(). May be NULL if no observer is needed.

const TCallBack& aWordParserCallback

A function to break the text in the contact down into a list of words.

const CContactTextDef* aTextDef

If specified, the text definition.

Return value

CIdleFinder*

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.


Retrieve contacts


ContactsChangedSinceL() — Get contacts changed since time

CContactIdArray* ContactsChangedSinceL(const TTime& aTime);

Description

Retrieve an array of contacts changed since the specified date/time.

Arguments

const TTime& aTime

The date/time of interest.

Return value

CContactIdArray*

Pointer to the array of contacts modified since the specified time.


DeletedContactsLC() — Get deleted contacts

CContactIdArray* DeletedContactsLC();

Description

Retrieve an array of contact 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 still have a non-zero access count.

Return value

CContactIdArray*

Pointer to the array of contacts marked as deleted.


Sorting


SortL() — Sort the whole database

void SortL(CArrayFix<TSortPref>* aSortOrder);

Description

Use this function to sort all the contact items in the database. The CContactDatabase object takes ownership of the array of TSortPref objects passed in. Contacts are sorted using the first TSortPref in the array. Any identical matches are then sorted using the next TSortPref and so on. When there are no more TSortPrefs to use, any remaining unsorted contacts, they are left in the natural database order.

Arguments

CArrayFix<TSortPref>* aSortOrder

Sort order array. If the array's count is zero, no sorting takes place.

Notes

After calling this function, use CContactDatabase::SortedItemsL() to retrieve the sorted array of contact IDs.


SortArrayL() — Sort subset of contact IDs

CContactIdArray* SortArrayL(const CContactIdArray* aIdArray, const CArrayFix<TSortPref>* aSortOrder)

Description

This function sorts an array of contact IDs. The sort uses the same logic as SortL().

Arguments

const CContactIdArray* aIdArray

Pointer to array of contact IDs to sort.

const CArrayFix<TSortPref>* aSortOrder

Sort order array.

Return value

CContactIdArray*

Pointer to sorted array of contact IDs.


SortedItemsL() — Get sorted array of contact IDs

const CContactIdArray* SortedItemsL();

Description

Return a pointer to the array of sorted items. This pointer is valid until a change is made to the database or until the database’s active object is allowed to run. If the array is required after one of the above two events has occurred, a copy of the array must first be made.

Return value

CContactIdArray*

A pointer to the array of sorted items.


Compression


CompressRequired() — Is compress recommended ?

TBool CompressRequired();

Description

Check whether a compress is recommended. This function does not provide the definitive answer to whether the database should be compressed or not, it just provides a quick and easy way of testing whether the database is being used efficiently.

Return value

TBool

ETrue if a compress is recommended, EFalse if not or if an error occurred.


CompactL() — Compact the database synchronously

void CompactL();

Description

Compact the database to its minimum size synchronously.


CompressL() — Compact the database asynchronously

void CompressL();

Description

Compact the database using an active compressor. Essentially, this function is identical to CompactL(), except that it is asynchronous.


CreateCompressorLC() — Create active compressor

CContactActiveCompress* CreateCompressorLC();

Description

Create an active compressor to compress the database with an active object.

An observer set up on the active compressor can be used to provide a progress dialog.

Return value

CContactActiveCompress*

Pointer to an active compressor.


Recovery


IsDamaged() — Is database damaged ?

TBool IsDamaged() const;

Description

Test whether the database is damaged and needs to be recovered.

Return value

TBool

ETrue if the database is damaged and needs recovery, EFalse otherwise.


RecoverL() — Recover the database

void RecoverL();

Description

Recover the database from a rollback.

This function first closes all tables and then reopens them after the recover.


CreateRecoverLC() — Create active recoverer

CContactActiveRecover* CreateRecoverLC();

Description

Create an active recoverer object to recover the database using an active object.

Return value

CContactActiveRecover*

Pointer to an active recoverer.


CloseTables() — Close all database tables

void CloseTables();

Description

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


OpenTablesL() — Open all database tables

void OpenTablesL();

Description

Open all database tables. After a rollback and recover all tables need to be closed and re-opened before the database can be accessed again. This function calls CloseTables() first to ensure that all tables are closed before opening them.


Phone number matching


InitLoadPhoneMatchesL() — Initialize phone number matching

TInt InitLoadPhoneMatchesL();

Description

Initializes the phone number matching process. Returns the total number of contacts to be indexed.

Return value

TInt

The total number of contacts to be indexed.


LoadPhoneMatchesL() — Index a batch of contacts

TInt LoadPhoneMatchesL();

Description

Indexes the next set of contact items for phone number matching.

Indexing involves reading a batch of contact items. For all items which contain a telephone number field, the number is extracted and is added to a list of telephone numbers stored internally by the contacts model.

Return value

TInt

The number of contact items whch have not yet been indexed. Zero when all contacts have been indexed.

Notes

This function handles any changes which occur during the indexing to the number of contact items. The function returns zero on completion or remains fixed at one until all the contacts are indexed.


PhoneMatchListL() — Get matching contacts

CContactIdArray *PhoneMatchListL(const TDesC& aNumber) const;

Description

Returns an array of contacts that might match the specified phone number. The algorithm doesn’t check for an exact match (if aNumber consists of more than nine digits, only the last nine digits are matched) but provides a fast way of finding contacts that probably match the number.

All fields in the specified contacts should be checked for a match.

Arguments

const TDesC& aNumber

Descriptor specifying the number to find.

Return value

CContactIdArray

Array of contact IDs which identify contact items containing phone numbers matching aNumber.

Note

These three functions could be used as follows: —

In the following code, phoneNumber is a descriptor containing a phone number to match as text.

    TInt todo=database->InitLoadPhoneMatchesL();
    while(todo>0)
          todo=database->LoadPhoneMatchesL();
    CContactIdArray *matchArray=database->PhoneMatchListL(phoneNumber);

Templates


TemplateId() — Get system template ID

TContactItemId TemplateId() const;

Description

Return the ID of the system template. This can then be read, opened and committed like any other contact item.

Return value

TContactItemId

ID of the system template.


TemplateContentType() — Get content type of field

const CContentType& TemplateContentType(const CContactItemField& aField) const;

Description

For a field in a contact item, this function returns the content type of the field in the template it maps onto. If the field does not map onto a field in the template, then its own content type is returned.

Arguments

const CContactItemField& aField

The field of interest.

Return value

CContentType

The content type of the field.


Database enquiry


CountL() — Get number of records in database

TInt CountL();

Description

Return the number of CContactItems in the database. The count does not include template or deleted items.

Return value

TInt

The number of contact items in the database.


FileUid() — Get database UID

TPtrC FileUid();

Description

Retrieve 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.

Return value

TPtrC

Descriptor containing the database UID.


FileSize() — Get file size

TInt FileSize() const;

Description

Return the size of the contact database file in bytes.

Return value

TInt

The size of the contacts file.


ConnectionId() — Get ID of connection to lock server

TUint ConnectionId() const;

Description

Return the ID of the connection to the lock server.

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

Return value

TUint

The ID of the connection to the lock server.


Version() — Get the version number

TVersion Version() const;

Description

Return the contact model's version number.

Return value

TVersion

The version number of the contacts model.


Enumerations


TOptions enum — Options when importing and exporting contacts

Contacts can be imported into or exported from the contact database. Imported or exported contacts must be in the vCard format.

The following options are available during import and export.

EIncludeX

Handle Symbian’s extended vCard format options.

ETTFormat

Support non-standard extensions requried by Symbian PC connectivity software and Microsoft amongst others.

EExcludeUid

Don’t export the contact ID (for exporting only).

EDecreaseAccessCount

Decrease the contact's access count when importing and exporting.

EIncreaseAccessCount

Increase the contact's access count when importing and exporting.

EImportSingleContact

Only import the first contact in the read stream (for importing only).


CContactDatabase::TSortPref class — Sort preferences

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Deirvation

Not applicable.

Defined in

cntdb.h

Link against

cntmodel.lib

Description

The TSortPref class is nested within the CContactDatabase class. It is used when sorting the items in the contacts database — see CContactDatabase::SortL() and CContactDatabase::SortArrayL().

A TSortPref object specifies a field type and an order. The first field in a contact item matching the field type is used for the text to sort on. The order can either be ascending or descending.


Construction


TSortPref() — Trivial default C++ constructor

TSortPref();

Description

The default C++ constructor constructs a TSortPref object.

The order is initialized to EAsc and the field type to KNullUid.


TSortPref() — C++ constructor with a field type and an order

TSortPref(TFieldType aFieldType,TOrder aOrder=EAsc);

Description

The C++ constructor is used to construct the TSortPref object with a field type and an order.

Arguments

TFieldType aFieldType

Specifies the field type to sort on.

TOrder aOrder=EAsc

Specifies the sort order.


Enumerations


TOrder enum — Sort order

EAsc

Ascending sort order.

EDesc

Descending sort order.


Data members

TOrder iOrder

Specifies whether the sort should be ascending or descending.

TFieldType iFieldType

The first field matching this field type is used for the text to sort on.

EPOC       SDK Home Glossary Indexes Previous Next Up