Class CContactDatabase

class CContactDatabase : public CBase, public MContactDbPrivObserver, public MContactStorageObserver;

Description

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, it must first be opened. Changes to the item can then be committed using CommitContactL() (committing can only take place to an open item).

If the available disk space is less than 128 kilobytes then changes to the contact database cannot be started, and methods such as CreateL() or CommitContactL() will leave with a KErrDiskFull error. Less obviously OpenL() can also fail with KErrDiskFull when trying to update the system template.

Each item has an access count. An item cannot be fully deleted unless its access count is zero. This is to prevent items which have been synchronised with another contacts application 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 a default contact database. Its filename is contacts.cdb. It can be moved between drives.

CContactDatabase implements searching and sorting and also provides separate phone number matching functions. These provide a fast way of indexing and looking up phone numbers, e.g. for looking up caller IDs on incoming calls.

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 supported. If called, they leave with KErrNotSupported.

• ReplacePrefL()

• ReadPrefL()

• CreatePrefL()

Derivation

• MContactStorageObserver - Mixin used to observe low disk events
• MContactDbPrivObserver - (No abstract)
• CBase - Base class for all classes to be instantiated on the heap
• CContactDatabase - A database of contact items

Members

Defined in CContactDatabase:
AddContactToGroupL(), AddContactToGroupL(), AddContactToGroupL(), AddNewContactL(), CancelAsyncSort(), CloseContactL(), CloseTables(), CommitContactL(), CompactL(), CompressRequired(), ConnectionId(), ContactDatabaseExistsL(), ContactsChangedSinceL(), CountL(), CreateCompressorLC(), CreateContactCardTemplateL(), CreateContactCardTemplateL(), CreateContactCardTemplateLC(), CreateContactCardTemplateLC(), CreateContactGroupL(), CreateContactGroupL(), CreateContactGroupLC(), CreateContactGroupLC(), CreateL(), CreateL(), CreateOwnCardL(), CreateOwnCardLC(), CreateRecoverLC(), DatabaseDrive(), DefaultContactDatabaseExistsL(), DeleteContactL(), DeleteContactsL(), DeleteDatabaseL(), DeleteDefaultFileL(), EAsc, EConverterDefined1, EConverterDefined2, EConverterDefined3, EConverterDefined4, EConverterDefined5, EConverterDefined6, EConverterDefined7, EConverterDefined8, ECustomFilter1, ECustomFilter2, ECustomFilter3, ECustomFilter4, EDecreaseAccessCount, EDefault, EDesc, EExcludeUid, EFaxable, EHome, EIMAddress, EImportSingleContact, EIncludeX, EIncreaseAccessCount, ELandLine, ELocalTime, EMailable, EMultiThread, ENullTemplateId, EPhonable, ERingTone, ESingleThread, ESmsable, ETTFormat, EUnfiltered, EVoiceDial, EWirelessVillage, EWork, ExportSelectedContactsL(), ExportSelectedContactsL(), FileSize(), FileUid(), FilterDatabaseL(), FindAsyncL(), FindInTextDefAsyncL(), FindInTextDefAsyncL(), FindInTextDefLC(), FindInTextDefLC(), FindLC(), GetCardTemplateIdListL(), GetCurrentDatabase(), GetCurrentItem(), GetDbViewContactType(), GetDefaultNameL(), GetGroupIdListL(), GetLastSyncDateL(), GetSpeedDialFieldL(), GroupCount(), ICCTemplateIdL(), ICCTemplateIdL(), ImportContactsL(), IsDamaged(), ListDatabasesL(), ListDatabasesL(), MachineId(), MatchPhoneNumberL(), NullUidValue(), Open(), Open(), OpenContactL(), OpenContactL(), OpenContactLX(), OpenContactLX(), OpenL(), OpenL(), OpenTablesL(), OwnCardId(), PhonebookGroupIdL(), PrefTemplateId(), ReadContactAndAgentL(), ReadContactL(), ReadContactL(), ReadContactLC(), ReadContactLC(), ReadContactTextDefL(), ReadContactTextDefL(), ReadContactTextDefL(), ReadContactTextDefL(), ReadMinimalContactL(), ReadMinimalContactLC(), RecoverL(), RemoveContactFromGroupL(), RemoveContactFromGroupL(), RemoveSpeedDialFieldL(), ReplaceL(), ReplaceL(), RestoreSortOrderL(), SetCurrentDatabase(), SetCurrentItem(), SetDatabaseDriveL(), SetDateFormatTextL(), SetDbViewContactType(), SetFieldAsSpeedDialL(), SetLastSyncDateL(), SetLastSyncDateL(), SetOwnCardL(), SetPrefTemplateL(), SetSortedItemsList(), SetTextDefinitionL(), SetViewDefinitionL(), SortArrayL(), SortArrayLC(), SortAsyncL(), SortAsyncL(), SortByTypeL(), SortL(), SortOrder(), SortedItemsL(), StoreSortOrderL(), TContactViewFilter, TDirection, TOptions, TSortPref, TTextFieldMinimal, TThreadAccess, TemplateContentType(), TemplateCount(), TemplateId(), TextDefinition(), Version(), WastedSpaceInBytes(), ~CContactDatabase()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from MContactDbPrivObserver:
HandleDatabaseEventL()

Inherited from MContactStorageObserver:
HandleDiskSpaceEvent()

IMPORT_C ~CContactDatabase();

Description

Frees all resources owned by the contact database, prior to its destruction.

Capability:

ReadUserData

static IMPORT_C CContactDatabase *OpenL(TThreadAccess aAccess=ESingleThread);

Description

Opens the default contact database.

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

Parameters

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

Return value

CContactDatabase * Pointer to the open contact database.

Leave codes

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

Capability:

ReadUserData

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

Description

Opens a named contact database.

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

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

Parameters

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

Return value

CContactDatabase * A pointer to the open contact database.

Leave codes

KErrNotFound The database file was not found or it did not have the correct UIDs. KErrLocked Another client is writing to the database. KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing. KErrDiskFull The disk does not have enough free space to perform the operation.

Capability:

WriteUserData

static IMPORT_C CContactDatabase *CreateL(TThreadAccess aAccess=ESingleThread);

Description

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

Parameters

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

Return value

CContactDatabase * A pointer to the new contact database.

Leave codes

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

Capability:

WriteUserData

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

Description

Creates and opens a named contact database.

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

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

Parameters

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

Return value

CContactDatabase * A pointer to the new contact database.

Leave codes

KErrAlreadyExists The database already exists. KErrBadName The filename is invalid; for example it contains wildcard characters or the drive letter is missing. KErrDiskFull The disk does not have enough free space to perform the operation.

Capability:

WriteUserData

static IMPORT_C CContactDatabase *ReplaceL(TThreadAccess aAccess=ESingleThread);

Description

Creates and opens an empty contact database, replacing the existing default database.

Parameters

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

Return value

CContactDatabase * Pointer to the new contact database.

Leave codes

KErrInUse Another client has an open connection to the database. KErrDiskFull The disk does not have enough free space to perform the operation.

Capability:

WriteUserData

static IMPORT_C CContactDatabase *ReplaceL(const TDesC &aFileName, TThreadAccess aAccess=ESingleThread);

Description

Creates and opens an empty contact database, replacing any existing file with the same name.

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

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

Parameters

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

Return value

CContactDatabase * A pointer to the new contact database.

Leave codes

KErrBadName The filename is invalid; for example it contains wildcard characters or the drive letter is missing. KErrInUse Another client has an open connection to the database. KErrDiskFull The disk does not have enough free space to perform the operation.

Capability:

ReadUserData

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

Description

Opens the default contact database asynchronously.

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

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

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

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

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

Parameters

TRequestStatus &aStatus On return, the request status for the asynchronous phase request. The Open() action can fail with one of the system wide error codes. In this case, the CContactDatabase object cannot access the database and must be deleted. TThreadAccess aAccess The default, ESingleThread allows access to the session with the database server from a single client thread only. EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers.

Return value

CContactOpenOperation * NULL if there is an error starting the asynhchronous open, otherwise a pointer to an active object that manages the open operation.

See also:

• CContactOpenOperation

Capability:

ReadUserData

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

Description

Opens a named contact database asynchronously.

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

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

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

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

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

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

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

Parameters

const TDesC &aFileName The filename of the database to open. TRequestStatus &aStatus On return, the request status for the asynchronous phase request. The Open() action can fail with one of the system wide error codes. In this case the CContactDatabase object cannot access the database and must be deleted. TThreadAccess aAccess The default, ESingleThread allows access to the session with the database server from a single client thread only. EMultiThread allows multiple client threads to share the same session with the server. As multi-threaded programs are uncommon in Symbian OS, this argument can be ignored by most C++ developers.

Return value

CContactOpenOperation * NULL if there is an error starting the asynhchronous open, otherwise a pointer to an active object that manages the open operation.

See also:

• CContactOpenOperation

Capability:

ReadUserData

static IMPORT_C TBool DatabaseDrive(TDriveUnit &aDriveUnit);

Description

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

Parameters

TDriveUnit &aDriveUnit On return, contains the database drive.

Return value

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

See also:

• CContactDatabase::SetDatabaseDrive()
• CContactDatabase::GetDefaultNameL()

static inline TInt NullUidValue();

Description

Gets the NULL contact ID value.

Return value

TInt KNullContactId.

Capability:

WriteUserData

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

Description

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.

In v8.1 when copying the file is moved to \system\data on the specified drive, and if the destination file already exists it is replaced.

From v9.0 onwards the file copying goes to the correct data caged directory on the destination drive. If the destination file already exists the copy fails.

Parameters

TDriveUnit aDriveUnit The drive to which to move the database. TBool aCopy ETrue moves the existing file to the specified drive. Deletion of the source file will fail if it is in use. EFalse does not move the file.

Leave codes

KErrNotReady There is no media present in the drive. KErrInUse The destination file for the copy is already open. KErrNotFound The source file for the copy was not found. KErrAlreadyExists The destination file for the copy already exists, (v9.0).

See also:

• CContactdatabase::DatabaseDrive()
• CContactDatabase::GetDefaultNameL()
• CContactDatabase::DefaultContactDatabaseExistsL()

Capability:

ReadUserData

static IMPORT_C void GetDefaultNameL(TDes &aDes);

Description

Gets the file name of the default contact database.

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

Parameters

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

See also:

• CContactDatabase::SetDatabaseDriveL()
• CContactDatabase::DatabaseDrive()
• CContactDatabase::DefaultContactDatabaseExistsL()

Capability:

WriteUserData

static IMPORT_C void DeleteDefaultFileL();

Description

Deletes the default contact database.

Leave codes

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

See also:

• CContactDatabase::DeleteDatabaseL()
• CContactDatabase::GetDefaultNameL()
• CContactDatabase::DefaultContactDatabaseExistsL()

Capability:

WriteUserData

static IMPORT_C void DeleteDatabaseL(const TDesC &aFileName);

Description

A static method to delete a named contact database.

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

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

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

Parameters

const TDesC &aFileName The contact database file to delete.

Leave codes

KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing. KErrInUse Another client has the database open. KErrNotFound The database file was not found or it did not have the correct UIDs.

See also:

• CContactDatabase::DeleteDefaultFileL()

Capability:

ReadUserData

static IMPORT_C CDesCArray *ListDatabasesL();

Description

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

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

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

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

Return value

CDesCArray * An array containing zero or more contact database names.

Leave codes

KErrNoMemory Out of memory.

Capability:

ReadUserData

static IMPORT_C CDesCArray *ListDatabasesL(TDriveUnit aDriveUnit);

Description

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

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

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

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

Parameters

TDriveUnit aDriveUnit The drive unit to search for contact databases.

Return value

CDesCArray * An array containing zero or more contact database names.

Leave codes

KErrNoMemory Out of memory.

Capability:

ReadUserData

static IMPORT_C TBool DefaultContactDatabaseExistsL();

Description

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

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

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

Return value

TBool ETrue if the file is found, EFalse otherwise.

Leave codes

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

See also:

• CContactDatabase::ContactDatabaseExistsL()

Capability:

ReadUserData

static IMPORT_C TBool ContactDatabaseExistsL(const TDesC &aFileName);

Description

A static method to determine if a named contact database exists.

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

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

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

Parameters

const TDesC &aFileName The contact database to search for.

Return value

TBool ETrue if the file is found, EFalse otherwise.

Leave codes

KErrNotReady There is no media present in the drive. KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing. KErrNotFound The database file was not found or it did not have the correct UIDs. KErrCorrupt The file is not a valid database

See also:

• CContactDatabase::DefaultContactDatabaseExistsL()
• CContactDatabase::ListDatabasesL()

IMPORT_C void SetViewDefinitionL(CContactViewDef *aView);

Description

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.

Parameters

CContactViewDef *aView The view definition.

IMPORT_C void SetTextDefinitionL(CContactTextDef *aView);

Description

Sets the text definition. The contact database takes ownership of the text definition specified.

Parameters

CContactTextDef *aView The new text definition.

IMPORT_C const CContactTextDef *TextDefinition() const;

Description

Gets a pointer to the text definition.

Return value

const CContactTextDef * A pointer to the text definition.

Interface status:

deprecated

IMPORT_C TInt CountL();

Description

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

Return value

TInt The number of contact items in the database.

Interface status:

deprecated

IMPORT_C void SetDbViewContactType(const TUid aUid);

Description

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.

Parameters

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

Interface status:

deprecated

IMPORT_C TUid GetDbViewContactType() const;

Description

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

Return value

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

Capability:

None

IMPORT_C TContactItemId AddNewContactL(CContactItem &aContact);

Description

Adds a new contact item to the database and returns its ID.

Parameters

CContactItem &aContact The contact item to add to the database.

Return value

TContactItemId The ID of the new contact item.

Leave codes

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

Capability:

None

IMPORT_C CContactItem *CreateContactGroupL(TBool aInTransaction=EFalse);

Description

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

The caller takes ownership of the returned object.

Parameters

TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the newly created contact group.

Capability:

None

IMPORT_C CContactItem *CreateContactGroupLC(TBool aInTransaction=EFalse);

Description

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

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

Parameters

TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the newly created contact group.

Leave codes

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

Capability:

None

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

Description

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

The caller takes ownership of the returned object.

Parameters

const TDesC &aGroupLabel The string to set as the group label. TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the newly created contact group.

Capability:

None

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

Description

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

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

Parameters

const TDesC &aGroupLabel The string to set as the group label. TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the newly created contact group.

Leave codes

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

Capability:

None

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

Description

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

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

The caller takes ownership of the returned object.

Parameters

const TDesC &aTemplateLabel The string to set as the template label. TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the contact card template.

Capability:

None

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

Description

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

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

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

Parameters

const TDesC &aTemplateLabel The string to set as the template label. TBool aInTransaction This argument should be ignored by developers.

Return value

CContactItem * Pointer to the contact card template.

Leave codes

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

Capability:

None

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

Description

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

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

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

The caller takes ownership of the returned object.

Parameters

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

Return value

CContactItem * Pointer to the contact card template.

Capability:

None

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

Description

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

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

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

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

Parameters

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

Return value

CContactItem * Pointer to the contact card template.

Leave codes

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

IMPORT_C CContactIdArray *GetCardTemplateIdListL() const;

Description

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

Return value

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