![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
CBase |
Abstract: CBase behaviour. |
MContactDbPrivObserver |
Abstract: defines HandleDatabaseEventL() function |
cntdb.h
cntmodel.lib
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.
static CContactDatabase* OpenL();
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.
CContactDatabase* |
The default database. |
The function leaves with KErrNotFound if the default database file does not exist.
Clients should not assume any knowledge of the database name or location they may be changed in future releases.
static CContactDatabase* OpenL(const TDesC& aFileName);
Open the specified contact database.
const TDesC& aFileName |
The path and filename of the database to open. |
CContactDatabase* |
Pointer to the open contact database. |
The function leaves with KErrNotFound if the database file does not exist.
static CContactDatabase* CreateL();
Create and open an empty contact database with the default name.
CContactDatabase* |
Pointer to the new default database. |
This function leaves with KErrAlreadyExists if the database file already exists.
static CContactDatabase* CreateL(const TDesC& aFileName);
Create and open an empty contact database with the specified name.
const TDesC& aFileName |
The path and filename of the database to create. |
CContactDatabase* |
Pointer to the new contact database. |
This function leaves with KErrAlreadyExists if the database file already exists.
static CContactDatabase* ReplaceL();
Create and open an empty contact database with the default name. This replaces any existing file of the same name.
CContactDatabase* |
Pointer to the new contact database. |
static CContactDatabase* ReplaceL(const TDesC& aFileName);
Create and open an empty contact database with the specified filename. This replaces any existing file of the same name.
const TDesC& aFileName |
The path and filename of the database to create. |
CContactDatabase* |
Pointer to the new contact database. |
static void DeleteDefaultFileL();
Delete the default contact database as retrieved by GetDefaultNameL().
static TBool DatabaseDrive(TDriveUnit& aDriveUnit);
Retrieve the currently set database drive.
The database drive is the drive on which the default contact database is located.
TDriveUnit& aDriveUnit |
On return, contains the database drive. |
TBool |
ETrue if the database drive has been set using SetDatabaseDriveL(). Otherwise EFalse and in this case, the function returns drive |
static void SetDatabaseDriveL(TDriveUnit aDriveUnit, TBool aCopy=ETrue);
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.
TDriveUnit aDriveUnit |
The drive to which to move the database. |
TBool aCopy=ETrue |
ETrue to move the existing file to |
If there is no media present in the drive, the function leaves with KErrNotReady.
This function is used for example by the Contacts application; see the Tools|Preferences... menu option to change the disk for the contacts store.
static TBool FindContactFile(TDes& aFileName);
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.
TDes& aFileName |
On return, contains the full path and filename of the default contact database. |
TBool |
EFalse if no file is found. ETrue if a file is found. |
static void GetDefaultNameL(TDes& aDes);
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.
TDes& aDes |
On return, contains the full path and filename of the default contact database. |
void SetViewDefinitionL(CContactViewDef* aView);
Set the current view definition. The contact database takes ownership of the view definition specified.
CContactViewDef* aView |
The view definition. |
void SetTextDefinitionL(CContactTextDef* aView);
Set the current text definition. The contact database takes ownership of the text definition specified.
CContactTextDef* aView |
The new text definition. |
const CContactTextDef* TextDefinition() const;
Return a pointer to the current text definition.
CContactTextDef* |
A pointer to the current text definition. |
CContactItem* OpenContactL(TContactItemId aContactId);
CContactItem* OpenContactL(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
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.
TContactItemId aContactId |
The ID of the contact to open. |
const CContactItemViewDef& aViewDef |
If specified, the view definition. |
CContactItem* |
The open, locked contact. |
This function leaves with KErrInUse if the contact is already locked or KErrNotFound if the contact is not present in the database.
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.
CContactItem* OpenContactLX(TContactItemId aContactId);
CContactItem* OpenContactLX(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
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.
TContactItemId aContactId |
The ID of the contact to open. |
const CContactItemViewDef& aViewDef |
The view definition. |
CContactItem* |
The open, locked contact. |
This function leaves with KErrInUse if the contact is already locked or KErrNotFound if the contact is not present in the database.
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.
void CloseContactL(TContactItemId aContactId);
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.
TContactItemId aContactId |
The ID of the contact to close. |
void CommitContactL(const CContactItem& aContact);
Overwrite a contact item with the values contained in aContact. The contact item is also closed by this call.
const CContactItem& aContact |
Contains the new values for the contact item. |
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.
CContactItem* ReadContactL(TContactItemId aContactId);
CContactItem* ReadContactL(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
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.
TContactItemId aContactId |
The ID of the contact item to read. |
const CContactItemViewDef& aViewDef |
If specified, the view definition to use. |
CContactItem* |
Pointer to the contact item read. |
If the specified contact item does not exist in the database, these functions leave with KErrNotFound.
CContactItem* ReadContactLC(TContactItemId aContactId);
CContactItem* ReadContactLC(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
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.
TContactItemId aContactId |
The ID of the contact to read. |
const CContactItemViewDef& aViewDef |
If specified, the view definition to use. |
CContactItem* |
Pointer to the contact whose ID is aContactId. The contact is left on the cleanup stack. |
If the specified contact does not exist in the database, these functions leave with KErrNotFound.
void ReadContactTextDefL(const CContactItem& aItem, TDes& aResult);
void ReadContactTextDefL(const CContactItem& aItem, TDes& aResult,CContactTextDef* aTextDef);
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()).
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. |
void ReadContactTextDefL(TContactItemId aContactId, TDes& aResult);
void ReadContactTextDefL(TContactItemId aContactId, TDes& aResult,CContactTextDef* aTextDef);
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.
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. |
If the contact identified by aContactId does not exist in the database, these functions leave with KErrNotFound.
TContactItemId AddNewContactL(CContactItem& aContact);
Add a new contact item to the database and return its contact ID.
CContactItem& aContact |
The contact item to add to the database. |
The ID of the new contact item. |
void DeleteContactL(TContactItemId aContactId);
Delete the specified contact item.
TContactItemId aContactId |
The ID of the contact to delete. |
If the contacts 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.
Leaves with KErrNotFound if aContactId is not present in the database.
Leaves with KErrInUse if the contact is open.
void DeleteContactsL(const CContactIdArray& aContactIds);
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.
const CContactIdArray& aContactIds |
An array of contacts to delete. |
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.
CArrayPtr<CContactItem>* ImportContactsL(const TUid& aFormat,RReadStream& aReadStream,TBool& aImportSuccessful,TInt aOption);
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.
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. |
CArrayPtr<CContactItem>* |
The array of contacts imported. |
This function leaves with KErrNotSupported if aFormat.iUid is not KVersitEntityUidVCard.
void ExportSelectedContactsL(const TUid& aFormat,const CContactIdArray& aSelectedContactIds,RWriteStream& aWriteStream,TInt aOption);
Export the specified array of contacts to the write stream.
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. |
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.
CContactIdArray* FindLC(const TDesC& aText,const CContactItemFieldDef *aFieldDef);
Search the database for the specified text in all of the fields identified by a field definition.
const TDesC& aText |
The text to search for. |
const CContactItemFieldDef *aFieldDef |
Specifies the fields to search. |
CContactIdArray* |
Array of contact IDs identifying the contact items which contain the specified text. |
CIdleFinder* FindAsyncL(const TDesC& aText,const CContactItemFieldDef *aFieldDef, MIdleFindObserver *aObserver);
Search the database for the specified text in all of the fields identified by aFieldDef.
Works asynchronously using the MIdleFindObserver and CIdleFinder classes.
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. |
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. |
CContactIdArray* FindInTextDefLC(const MDesCArray& aFindWords, const TCallBack& aWordParserCallback);
CContactIdArray* FindInTextDefLC(const MDesCArray& aFindWords,CContactTextDef* aTextDef, const TCallBack& aWordParserCallback);
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.
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. |
CContactIdArray* |
Array of contact IDs. |
CIdleFinder* FindInTextDefAsyncL(const MDesCArray& aFindWords, MIdleFindObserver *aObserver, const TCallBack& aWordParserCallback);
CIdleFinder* FindInTextDefAsyncL(const MDesCArray& aFindWords,const CContactTextDef* aTextDef, MIdleFindObserver *aObserver, const TCallBack& aWordParserCallback);
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.
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. |
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. |
CContactIdArray* ContactsChangedSinceL(const TTime& aTime);
Retrieve an array of contacts changed since the specified date/time.
const TTime& aTime |
The date/time of interest. |
CContactIdArray* |
Pointer to the array of contacts modified since the specified time. |
CContactIdArray* DeletedContactsLC();
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.
CContactIdArray* |
Pointer to the array of contacts marked as deleted. |
void SortL(CArrayFix<TSortPref>* aSortOrder);
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.
CArrayFix<TSortPref>* aSortOrder |
Sort order array. If the array's count is zero, no sorting takes place. |
After calling this function, use CContactDatabase::SortedItemsL() to retrieve the sorted array of contact IDs.
CContactIdArray* SortArrayL(const CContactIdArray* aIdArray, const CArrayFix<TSortPref>* aSortOrder)
This function sorts an array of contact IDs. The sort uses the same logic as SortL().
const CContactIdArray* aIdArray |
Pointer to array of contact IDs to sort. |
const CArrayFix<TSortPref>* aSortOrder |
Sort order array. |
CContactIdArray* |
Pointer to sorted array of contact IDs. |
const CContactIdArray* SortedItemsL();
Return a pointer to the array of sorted items. This pointer is valid until a change is made to the database or until the databases 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.
CContactIdArray* |
A pointer to the array of sorted items. |
TBool CompressRequired();
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.
TBool |
ETrue if a compress is recommended, EFalse if not or if an error occurred. |
void CompactL();
Compact the database to its minimum size synchronously.
void CompressL();
Compact the database using an active compressor. Essentially, this function is identical to CompactL(), except that it is asynchronous.
CContactActiveCompress* CreateCompressorLC();
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.
CContactActiveCompress* |
Pointer to an active compressor. |
TBool IsDamaged() const;
Test whether the database is damaged and needs to be recovered.
TBool |
ETrue if the database is damaged and needs recovery, EFalse otherwise. |
void RecoverL();
Recover the database from a rollback.
This function first closes all tables and then reopens them after the recover.
CContactActiveRecover* CreateRecoverLC();
Create an active recoverer object to recover the database using an active object.
CContactActiveRecover* |
Pointer to an active recoverer. |
void CloseTables();
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.
void OpenTablesL();
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.
TInt InitLoadPhoneMatchesL();
Initializes the phone number matching process. Returns the total number of contacts to be indexed.
TInt |
The total number of contacts to be indexed. |
TInt LoadPhoneMatchesL();
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.
TInt |
The number of contact items whch have not yet been indexed. Zero when all contacts have been indexed. |
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.
CContactIdArray *PhoneMatchListL(const TDesC& aNumber) const;
Returns an array of contacts that might match the specified phone number. The algorithm doesnt 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.
const TDesC& aNumber |
Descriptor specifying the number to find. |
CContactIdArray |
Array of contact IDs which identify contact items containing phone numbers matching aNumber. |
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);
TContactItemId TemplateId() const;
Return the ID of the system template. This can then be read, opened and committed like any other contact item.
ID of the system template. |
const CContentType& TemplateContentType(const CContactItemField& aField) const;
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.
const CContactItemField& aField |
The field of interest. |
CContentType |
The content type of the field. |
TInt CountL();
Return the number of CContactItems in the database. The count does not include template or deleted items.
TInt |
The number of contact items in the database. |
TPtrC FileUid();
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.
TPtrC |
Descriptor containing the database UID. |
TInt FileSize() const;
Return the size of the contact database file in bytes.
TInt |
The size of the contacts file. |
TUint ConnectionId() const;
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.
The ID of the connection to the lock server. |
TVersion Version() const;
Return the contact model's version number.
TVersion |
The version number of the contacts model. |
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.
Handle Symbians extended vCard format options. |
|
Support non-standard extensions requried by Symbian PC connectivity software and Microsoft amongst others. |
|
Dont export the contact ID (for exporting only). |
|
Decrease the contact's access count when importing and exporting. |
|
Increase the contact's access count when importing and exporting. |
|
Only import the first contact in the read stream (for importing only). |
Section Contents
Applications that use this class will not work correctly on a version of EPOC earlier than ER5.
Not applicable.
cntdb.h
cntmodel.lib
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.
TSortPref();
The default C++ constructor constructs a TSortPref object.
The order is initialized to EAsc and the field type to KNullUid.
TSortPref(TFieldType aFieldType,TOrder aOrder=EAsc);
The C++ constructor is used to construct the TSortPref object with a field type and an order.
TFieldType aFieldType |
Specifies the field type to sort on. |
TOrder aOrder=EAsc |
Specifies the sort order. |
Ascending sort order. |
|
Descending sort order. |
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. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |