![[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 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.
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(), 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(), ImportContactsL(), InitLoadPhoneMatchesL(), IsDamaged(), LoadPhoneMatchesL(), MachineId(), MatchPhoneNumberL(), NullUidValue(), OpenContactL(), OpenContactLX(), OpenL(), OpenTablesL(), OwnCardId(), PhoneMatchListL(), PrefTemplateId(), ReadContactAndAgentL(), ReadContactL(), ReadContactLC(), ReadContactTextDefL(), ReadMinimalContactL(), ReadMinimalContactLC(), RecoverL(), RemoveContactFromGroupL(), RemoveSpeedDialFieldL(), 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 second overload is for a particular sync ID and updates the database's last
synchronised date/time for that ID. It leaves with KErrNotFound if
the specified sync ID is not found.
|
|
void GetLastSyncDateL(TContactSyncId aSyncId, TTime& aSyncDate);
Supported from 6.0
Returns the date/time the database was last synchronised with a
particular sync ID, as set by SetLastSyncDateL().
|
|
CContactIdArray* ContactsChangedSinceL(const TTime& aTime);
Gets an array of contacts modified since the specified date/time. The caller takes ownership of the returned object.
|
|
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.
|
|
TInt64 MachineId() const;
Supported from 5.1
Returns a number unique to the contacts database. This value may be
passed to CContactItem::UidStringL().
|
|
TBool CompressRequired();
Tests whether a compress is recommended. This function provides an easy way of testing whether the database is being used efficiently.
ETrue is returned if:
more than 32K of space is wasted and this is more than 50% of the file, or
more than 256K is wasted in the file
|
void CompressL();
Compacts the database using an active compressor. This function is
identical to CompactL(), except that it is asynchronous.
CContactActiveCompress* CreateCompressorLC();
Creates 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. The caller takes ownership of the returned object.
|
|
TBool IsDamaged() const;
Tests whether the database is damaged and needs to be recovered.
|
void RecoverL();
Recovers the database from a rollback. First closes all tables and then reopens them after the recover.
CContactActiveRecover* CreateRecoverLC();
Creates an active recoverer object to recover the database using an active object. The caller takes ownership of the returned object.
|
void CloseTables();
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.
void OpenTablesL();
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. This
function calls CloseTables() first to ensure that all tables are
closed before opening them.
|
TInt InitLoadPhoneMatchesL();
Initialises the phone number matching process. Returns 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.
Note:
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;
Gets an array of contact item IDs that might match the specified phone
number. The algorithm doesn’t check for an exact match (only the last
eight digits of aNumber are compared) but provides a fast way of
finding contacts that probably match the number.
All fields in the contact items returned by this function should be checked for a match. The caller takes ownership of the returned object.
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);
|
|
static TInt TextToPhoneMatchNumber(const TDesC &aText, TInt &aNumDigits, TInt aPhoneMatchLength=8);
Converts a telephone number stored in a text string into numeric format.
The number of digits (counting from the end of the string) to convert can be
specified. By default it is the last eight digits. The return value from this
function can be passed to MatchPhoneNumberL(). The method only
looks at digits in the text string provided, all other characters are ignored.
If the string contains no digits, the function returns zero.
|
|
CContactIdArray* MatchPhoneNumberL(TInt aPhoneNumber);
Supported from 6.0
Returns an array of contact item IDs for all the contact items which contain the specified telephone number in any of their fields.
Notes:
Telephone numbers are automatically stored for recognition as they are
entered into the database. The telephone number can be obtained by passing the
text content of a telephone number field into TextToPhoneMatchNumber().
The caller takes ownership of the returned object.
|
|
|
|
void SetFieldAsSpeedDialL(CContactItem& aItem, TInt aFieldId, TInt aSpeedDialPosition);
Supported from 6.0
Sets a field containing a telephone number as a speed dial field. The
field is identified by aFieldId within the contact item aItem.
It is assigned a speed dial position between 1 and 9 inclusive.
The field's speed dial and user added attributes are set and the
appropriate UID (KUidSpeedDialXxx) is added to the field's content
type. The changes are committed to the database.
Notes:
If an item's telephone number field has already been assigned to
position aSpeedDialPosition, that item is updated so that the speed
dial attribute is removed from its field and the speed dial field type UID is
removed from the field's content type, before the new speed dial field is
set.
The speed dial attribute can be tested for using
the CContactItemField::IsSpeedDial() function.
The contact item passed to this function (aItem) must have
been obtained using one of the variants of CContactDatabase::OpenContactL().
This is because it is modified and committed to the database by this function —
no further commits are necessary.
|
TContactItemId GetSpeedDialFieldL(TInt aSpeedDialPosition, TDes& aPhoneNumber);
Supported from 6.0
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.
|
|
void RemoveSpeedDialFieldL(TContactItemId aContactId, TInt aSpeedDialPosition);
Supported from 6.0
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
contact item.
|
|
TContactItemId TemplateId() const;
Gets the ID of the system template. This can then be read, opened and committed like any other contact item.
|
const CContentType& TemplateContentType(const CContactItemField& aField) const;
Gets the content type of the template field which a specified field maps onto. If the field does not map onto a field in a template, then its own content type is returned.
|
|
CContactItem* CreateContactCardTemplateL(const TDesC& aTemplateLabel,TBool aInTransaction=EFalse);
CContactItem* CreateContactCardTemplateL(const CContactItem* aTemplate,const TDesC& aTemplateLabel,TBool aInTransaction=EFalse);
Supported from 6.0
Creates a contact card template and adds it to the database — overloaded function.
The caller can optionally specify a contact item on which the new template's field set is based. This could be a contact card, an own card, another template or even a group. If this is not specified, then the new template's field set is based on the system template. 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.
|
|
CContactItem* CreateContactCardTemplateLC(const TDesC& aTemplateLabel,TBool aInTransaction=EFalse);
CContactItem* CreateContactCardTemplateLC(const CContactItem* aTemplate,const TDesC& aTemplateLabel,TBool aInTransaction=EFalse);
Supported from 6.0
Creates a contact card template and adds it to the database — overloaded function.
The caller can optionally specify a contact item on which the new template's field set is based. This could be a contact card, an own card, another template or even a group. If this is not specified, then the new template's field set is based on the system template. 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 later be changed
using CContactCardTemplate::SetTemplateLabelL().
The pointer to the template is left on the cleanup stack. The caller takes ownership of the returned object.
|
|
CContactIdArray* GetCardTemplateIdListL() const;
Supported from 6.0
Returns 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.
|
TInt TemplateCount() const;
Supported from 6.0
Returns the number of contact card templates that currently exist in the database. This does not include the system template.
|
TContactItemId PrefTemplateId() const;
Supported from 6.0
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.
|
void SetPrefTemplateL(const CContactItem& aContact);
Supported from 6.0
Sets the database's preferred template.
The preferred template's ID persists when the database is opened and
closed. If the preferred template is subsequently deleted, the preferred template
ID is set to KNullContactId.
|
|
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.
|
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.
|
static TInt NullUidValue();
Supported from 6.0
Returns the NULL contact ID value.
|
TInt FileSize() const;
Gets the size of the contact database file in bytes.
|
TUint ConnectionId() const;
Gets 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.
|
TVersion Version() const;
Gets the contact model's version number.
|
|
TOptions
Import and export contact format option flags. 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.
|
TThreadAccess
Supported from 6.0
Specifies whether the database can be accessed from single or multiple threads.
|
|
TSortPref
Specifies the field type and order preferences used for sorting items in
the contacts database — see CContactDatabase::SortL() and CContactDatabase::SortArrayL().
The contents of the first field in a contact item matching the field type is used
as the data to sort on. The order can either be ascending or descending.
The TSortPref class is nested within
the CContactDatabase class.
Defined in CContactDatabase::TSortPref:
EAsc, EDesc, TOrder, TSortPref(), iFieldType, iOrder
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
TSortPref()TSortPref();
Constructs a TSortPref object. The order is initialised
to EAsc and the field type to KNullUid.
TSortPref()TSortPref(TFieldType aFieldType,TOrder aOrder=EAsc);
Constructs the TSortPref object with a field type and an
order.
|
TOrderTOrder
The sort order.
|
iOrderTOrder iOrder
Specifies whether the sort should be ascending or descending.
iFieldTypeTFieldType iFieldType
The first field matching this field type is used for the text to sort on.
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up.gif){kind=icon}