![[Index]](../../../../_stock/btn_index.gif){kind=small}
![[Glossary]](../../../../_stock/btn_glossary.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev.gif){kind=small}
![[Next]](../../../../_stock/btn_next.gif){kind=small}
|
|
|
|
|
Location:
cntdb.h
Link against: cntmodel.lib
CContactDatabase
Supported from 5.0
A database of contact items.
Contact items can be added to and removed from the database and
items in the database can be opened or read. To edit an item, the item must
first be opened. Changes to the item can then be committed to the database
using CommitContactL(). Committing can only take place to an open
item. Reading an item provides read only access to it.
When deleting a contact item, note that each item has an access count. The item cannot be fully deleted unless its access count is zero. This is to prevent contact items which have been synchronised with a PC scheduler application for example from being deleted. Also, if the item is a template, it cannot be deleted if other items are based on it.
More than one contact database can exist on a phone, 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.
The CContactDatabase class implements searching and
sorting. 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 database server. Index creation is
started by a call to InitLoadPhoneMatchesL(). Then it is updated
using calls to LoadPhoneMatchesL().
The database owns speed dial information. This is a mapping between a single digit integer and a telephone number. There may be up to 9 speed dial telephone numbers; each of them belongs to a contact item in the database — if a contact item is deleted, its speed dial mapping is removed.
The following functions defined in class
CContactDatabase are not currently supported. If called, they
leave with KErrNotSupported.
ReplacePrefL()
ReadPrefL()
CreatePrefL()
|
Defined in CContactDatabase:
AddContactToGroupL(), AddNewContactL(), CloseContactL(), CloseTables(), CommitContactL(), CompactL(), CompressL(), CompressRequired(), ConnectionId(), ContactsChangedSinceL(), CountL(), CreateCompressorLC(), CreateContactCardTemplateL(), CreateContactCardTemplateLC(), CreateContactGroupL(), CreateContactGroupLC(), CreateL(), CreateL(), CreateOwnCardL(), CreateOwnCardLC(), CreateRecoverLC(), DatabaseDrive(), DeleteContactL(), DeleteContactsL(), DeleteDefaultFileL(), DeletedContactsLC(), EDecreaseAccessCount, EExcludeUid, EImportSingleContact, EIncludeX, EIncreaseAccessCount, EMultiThread, ESingleThread, ETTFormat, ExportSelectedContactsL(), FileSize(), FileUid(), FilterDatabaseL(), FindAsyncL(), FindContactFile(), FindInTextDefAsyncL(), FindInTextDefLC(), FindLC(), GetCardTemplateIdListL(), GetCurrentDatabase(), GetCurrentItem(), GetDbViewContactType(), GetDefaultNameL(), GetGroupIdListL(), GetLastSyncDateL(), GetSpeedDialFieldL(), GroupCount(), ICCTemplateIdL(), ImportContactsL(), InitLoadPhoneMatchesL(), IsDamaged(), LoadPhoneMatchesL(), MachineId(), MatchPhoneNumberL(), NullUidValue(), OpenContactL(), OpenContactLX(), OpenL(), OpenL(), OpenTablesL(), OwnCardId(), PhoneMatchListL(), PrefTemplateId(), ReadContactAndAgentL(), ReadContactL(), ReadContactLC(), ReadContactTextDefL(), ReadContactTextDefL(), ReadMinimalContactL(), ReadMinimalContactLC(), RecoverL(), RemoveContactFromGroupL(), RemoveSpeedDialFieldL(), ReplaceL(), ReplaceL(), SetCurrentDatabase(), SetCurrentItem(), SetDatabaseDriveL(), SetDateFormatTextL(), SetDbViewContactType(), SetFieldAsSpeedDialL(), SetLastSyncDateL(), SetOwnCardL(), SetPrefTemplateL(), SetTextDefinitionL(), SetViewDefinitionL(), SortArrayL(), SortArrayLC(), SortByTypeL(), SortL(), SortedItemsL(), TOptions, TSortPref, TThreadAccess, TemplateContentType(), TemplateCount(), TemplateId(), TextDefinition(), TextToPhoneMatchNumber(), Version(), ~CContactDatabase()
Inherited from CBase:
operator new()
static CContactDatabase* OpenL();
static CContactDatabase* OpenL(const TDesC& aFileName);
Withdrawn in 6.0
Opens a contact database. The database may be named, or, if no name is specified, the default database is opened.
The name of the default 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.
Note:
Clients should not assume any knowledge of the default database name or location — they may be changed in future releases.
|
|
|
static CContactDatabase* OpenL(TThreadAccess aAccess=ESingleThread);
static CContactDatabase* OpenL(const TDesC& aFileName,TThreadAccess aAccess=ESingleThread);
Supported from 6.0
Opens a contact database. The database may be named, or, if no name is specified, the default database is opened.
The name of the default 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.
Note:
Clients should not assume any knowledge of the default database name or location — they may be changed in future releases.
|
|
|
static CContactDatabase* CreateL();
static CContactDatabase* CreateL(const TDesC& aFileName);
Withdrawn in 6.0
Creates and opens an empty contact database. The new database may be assigned a name, or if no name is specified, a database with the default name is created.
|
|
|
static CContactDatabase* CreateL(TThreadAccess aAccess=ESingleThread);
static CContactDatabase* CreateL(const TDesC& aFileName,TThreadAccess aAccess=ESingleThread);
Supported from 6.0
Creates and opens an empty contact database. The new database may be assigned a name, or if no name is specified, a database with the default name is created.
|
|
|
static CContactDatabase* ReplaceL();
static CContactDatabase* ReplaceL(const TDesC& aFileName);
Withdrawn in 6.0
Creates and opens an empty contact database, replacing any existing file with the same name. The name may be specified, or if not, the function replaces the default database.
|
|
static CContactDatabase* ReplaceL(TThreadAccess aAccess=ESingleThread);
static CContactDatabase* ReplaceL(const TDesC& aFileName,TThreadAccess aAccess=ESingleThread);
Supported from 6.0
Creates and opens an empty contact database, replacing any existing file with the same name. The name may be specified, or if not, the function replaces the default database.
|
|
|
~CContactDatabase()
The destructor frees all resources owned by the contact database, prior to its destruction.
|
static TBool DatabaseDrive(TDriveUnit& aDriveUnit);
Gets the currently set database drive. The database drive is the drive on which the default contact database is located.
|
|
static void SetDatabaseDriveL(TDriveUnit aDriveUnit, TBool aCopy=ETrue);
Sets the contact database drive and optionally moves 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.
|
|
static TBool FindContactFile(TDes& aFileName);
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.
|
|
static void GetDefaultNameL(TDes& aDes);
Gets 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.
|
|
void SetViewDefinitionL(CContactViewDef* aView);
Sets the default view definition. The contact database takes
ownership of the view definition specified. The default view definition is used
in calls to ReadContactL(), ReadContactLC() and
ReadContactAndAgentL() when no view definition is explicitly
specified.
|
void SetTextDefinitionL(CContactTextDef* aView);
Sets the current text definition. The contact database takes ownership of the text definition specified.
|
const CContactTextDef* TextDefinition() const;
Gets a pointer to the current text definition.
|
|
CContactItem* CreateContactGroupL(TBool aInTransaction=EFalse);
CContactItem* CreateContactGroupL(const TDesC& aGroupLabel,TBool aInTransaction=EFalse);
Supported from 6.0
Creates a new contact group and adds it to the database — overloaded function. The group label may be specified, or if not, the default string "Group Label" is assigned as the label for the group. The caller takes ownership of the returned object.
|
|
CContactItem* CreateContactGroupLC(TBool aInTransaction=EFalse);
CContactItem* CreateContactGroupLC(const TDesC& aGroupLabel,TBool aInTransaction=EFalse);
Supported from 6.0
Creates a new contact group and adds it to the database — overloaded function. The group label may be specified, or if not, the default string "Group Label" is assigned as the label for the group. The pointer to the group is left on the cleanup stack. The caller takes ownership of the returned object.
|
|
CContactIdArray* GetGroupIdListL() const;
Supported from 6.0
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.
|
void AddContactToGroupL(TContactItemId aItemId, TContactItemId aGroupId);
void AddContactToGroupL(TContactItemId aItemId, TContactItemId aGroupId, TBool aInTransaction);
void AddContactToGroupL(CContactItem& aItem, CContactItem& aGroup);
Supported from 6.0
Sets a contact item which already exists in the database to be a member of a contact group — overloaded function. Specify a reference to the item and group, or their contact item IDs.
|
|
void RemoveContactFromGroupL(CContactItem& aItem, CContactItem& aGroup);
void RemoveContactFromGroupL(TContactItemId aItemId, TContactItemId aGroupId);
Supported from 6.0
Removes the association between a contact item and a group — overloaded function.
A panic is raised if:
aItem or aGroup is NULL
the item is not a member of the group
the group is not of type
KUidContactGroup
|
TInt GroupCount() const;
Supported from 6.0
Returns the number of groups that currently exist in the database.
|
|
CContactItem* OpenContactL(TContactItemId aContactId);
CContactItem* OpenContactL(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
Opens a contact item for editing — overloaded
function. The returned contact item 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.
Notes:
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.
|
|
|
CContactItem* OpenContactLX(TContactItemId aContactId);
CContactItem* OpenContactLX(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
Opens the contact item for editing — overloaded
function. The returned item 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.
Notes:
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.
|
|
|
void CloseContactL(TContactItemId 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.
|
void CommitContactL(const CContactItem& aContact);
Overwrites a contact item with the values contained in
aContact. The contact item is also closed by this call.
|
|
|
CContactItem* ReadContactL(TContactItemId aContactId);
CContactItem* ReadContactL(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
Reads a contact item — overloaded function.
Unlike OpenContactL(), these functions do not lock the
contact.
The variant of the function which does not take a view
definition parameter uses the default view definition (as set by
SetViewDefinitionL()). The caller takes ownership of the returned
object.
|
|
|
CContactItem* ReadContactLC(TContactItemId aContactId);
CContactItem* ReadContactLC(TContactItemId aContactId,const CContactItemViewDef& aViewDef);
Reads a contact item — overloaded
function. Unlike OpenContactL(), this function does not lock the
contact.
The variant of the function which does not take a view
definition parameter uses the default view definition (as set by
SetViewDefinitionL()). The caller takes ownership of the returned
object.
|
|
|
CContactItem* ReadMinimalContactL(TContactItemId aContactId);
Supported from 6.0
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 the following information
is 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.
|
|
|
CContactItem* ReadMinimalContactLC(TContactItemId aContactId);
Supported from 6.0
Reads a contact item (contact card, own card, template, or
contact group), but does not read the group or template information. The object
is left on the cleanup stack. This function is identical to the variant of
ReadContactL() which uses the database's default view definition,
except that the following information is 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.
|
|
|
void ReadContactTextDefL(const CContactItem& aItem, TDes& aResult);
void ReadContactTextDefL(const CContactItem& aItem, TDes& aResult,CContactTextDef* aTextDef);
Reads text into a descriptor from a pre-loaded contact item, using a text definition — overloaded function.
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()).
|
void ReadContactTextDefL(TContactItemId aContactId, TDes& aResult);
void ReadContactTextDefL(TContactItemId aContactId, TDes& aResult,CContactTextDef* aTextDef);
Reads text from a contact item stored in the database into a
descriptor — overloaded function. It uses 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.
|
|
CArrayPtr<CContactItem>* ReadContactAndAgentL(TContactItemId 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.
|
|
|
|
TContactItemId AddNewContactL(CContactItem& aContact);
Adds a new contact item to the database and returns its contact item ID.
|
|
void DeleteContactL(TContactItemId 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.
|
|
void DeleteContactsL(const CContactIdArray& aContactIds);
Deletes 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 all the contacts have been deleted and the changes committed.
|
|
|
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.
|
|
|
void ExportSelectedContactsL(const TUid& aFormat,const CContactIdArray& aSelectedContactIds,RWriteStream& aWriteStream,TInt aOption,TBool aExportPrivateFields=ETrue);
void ExportSelectedContactsL(const TUid& aFormat,const CContactIdArray& aSelectedContactIds,RWriteStream& aWriteStream,TInt aOption,const CVersitParser::TVersitCharSet aCharSet, TBool aExportPrivateFields=ETrue);
Supported from 6.0
Exports an array of contact items to a write stream — overloaded function. The items are converted into vCards before being written to the stream.
|
|
|
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.
|
|
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.
|
|
CContactIdArray* FindInTextDefLC(const MDesCArray& aFindWords, const TCallBack& aWordParserCallback);
CContactIdArray* FindInTextDefLC(const MDesCArray& aFindWords,CContactTextDef* aTextDef, const TCallBack& aWordParserCallback);
Allows the user to search the database for a string containing text which is stored in one or more fields — overloaded function. 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 text
definition aTextDef, if specified. If not specified, the function
uses the currently set text definition.
The caller takes ownership of the returned object.
|
|
CIdleFinder* FindInTextDefAsyncL(const MDesCArray& aFindWords, MIdleFindObserver *aObserver, const TCallBack& aWordParserCallback);
CIdleFinder* FindInTextDefAsyncL(const MDesCArray& aFindWords,const CContactTextDef* aTextDef, MIdleFindObserver *aObserver, const TCallBack& aWordParserCallback);
Searches the database for an array of words — overloaded function.
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. The caller takes ownership of the returned
object.
|
|
|
void SortL(CArrayFix<TSortPref>* aSortOrder);
Sorts the database. The sort only includes items of the type
set by SetDbViewContactType(). The database takes ownership of the
sort order array 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 are left in the
natural database order.
Note:
After calling this function, use
CContactDatabase::SortedItemsL() to retrieve the sorted array of
contact IDs.
|
CContactIdArray* SortArrayL(const CContactIdArray* aIdArray, const CArrayFix<TSortPref>* aSortOrder)
Sorts an array of contact IDs. The sort uses the same logic as
SortL(). The caller takes ownership of the returned object.
|
|
CContactIdArray* SortArrayLC(const CContactIdArray* aIdArray, const CArrayFix<TSortPref>* aSortOrder);
Supported from 6.0
Sorts an array of contact IDs. The sort uses the same logic as
SortL(). The returned array is left on the cleanup stack. The
caller takes ownership of the returned object.
|
|
void SetDbViewContactType(const TUid aUid);
Supported from 6.0
Sets the type of contact items to be included in sorted views
of the database. See also SortL() and
SortByTypeL().
This value is initialised to KUidContactItem when
the database is opened. This means that all CContactItem-derived
types (cards, non-system templates, groups, own cards) are included in database
views.
|
TUid GetDbViewContactType() const;
Supported from 6.0
Gets the type of contact items which are included in sorted
views of the database, as set by SetDbViewContactType().
|
void SortByTypeL(CArrayFix<TSortPref>* aSortOrder);
Supported from 6.0
Sorts the database using the view type value set by
SetDbViewContactType(). The database takes ownership of the sort
order array passed in.
The sort uses the same logic as
SortL() — the two functions have the same
effect.
After calling this function, use
CContactDatabase::SortedItemsL() to retrieve the sorted array of
contact IDs.
|
const CContactIdArray* SortedItemsL();
Returns a pointer to the array of contact items which have been
sorted by either SortByTypeL() or SortL(). 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.
|
|
CContactItem* CreateOwnCardL();
Supported from 6.0
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.
|
CContactItem* CreateOwnCardLC();
Supported from 6.0
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.
|
TContactItemId OwnCardId() const;
Supported from 6.0
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()).
|
void SetOwnCardL(const CContactItem& aContact);
Supported from 6.0
Sets an existing contact item to be the database's current own card.
|
|
|
void SetCurrentItem(const TContactItemId aContactId);
Supported from 6.0
Sets the ID of the current item and persists it in the database. The current item is provided for use by clients who want to identify one contact item in the database as the currently selected item.
|
const TContactItemId GetCurrentItem() const;
Supported from 6.0
Gets the ID of the current item, as set by
SetCurrentItem(). The current item ID is initialised to
KNullContactId when the database is opened.
|
TInt SetCurrentDatabase(const TDesC& aDatabase) const;
Supported from 6.0
Where there are multiple contact databases on a device, this function can be used to set a database as the current one.
Note:
This function simply updates a file name which is stored by the contacts server and its use is optional. It is 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.
|
|
TInt GetCurrentDatabase(TDes& aDatabase) const;
Supported from 6.0
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.
|
|
|
void FilterDatabaseL(CCntFilter& aFilter);
Supported from 6.0
Filters the database. On return, aFilter contains
an array of filtered contact item IDs.
|
TContactSyncId SetLastSyncDateL(const TTime& aSyncDate);
void SetLastSyncDateL(TContactSyncId aSyncId, const TTime& aSyncDate);
Supported from 6.0
Sets the date/time the database was last synchronised e.g. with a PC scheduler application. The first overload sets the last synchronised date/time where the sync ID is not known, and returns the sync ID that was created (a sync ID identifies a machine with which the database has been synchronised). The se
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}