CContactDatabase Class Reference

#include <app/cntdb.h>

Link against: cntmodel.lib

class CContactDatabase : public CBase

Inherits from

  • CContactDatabase

    Nested Classes and Structures

    Public Member Type Definitions
    typedef TBuf< KTextFieldMinimalLength > TTextFieldMinimal
    Public Member Enumerations
    enumTContactViewFilter { EUnfiltered, EMailable, ESmsable, ELandLine, ..., ECustomFilter4 }
    enumTDbConnState { EDbConnectionOpen, EDbConnectionNotReady, EDbConnectionFailed, EDbConnectionRecoverRequired, ..., EDbConnectionNeedToCloseForRestore }
    enumTDirection { EAsc, EDesc }
    enumTOptions { EDefault, EIncludeX, ETTFormat, EExcludeUid, ..., EConverterReserved16 }
    enumTSortDataSource { ENoOrder, EUsesIdentityTableOnly, EUsesAllTables, EIdentityTableNotUsed }
    enumTThreadAccess { ESingleThread, EMultiThread }
    Public Member Functions
    ~CContactDatabase()
    IMPORT_C voidAddContactToGroupL(TContactItemId, TContactItemId)
    IMPORT_C voidAddContactToGroupL(CContactItem &, CContactItem &)
    IMPORT_C voidAddContactToGroupL(TContactItemId, TContactItemId, TBool)
    IMPORT_C TContactItemIdAddNewContactL(CContactItem &)
    voidAddObserverL(MContactDbObserver &)
    IMPORT_C CContactItemViewDef *AllFieldsView()
    IMPORT_C voidCancelAsyncSort()
    voidCancelNotifyRequestL()
    voidCleanupLastLockedContact(TAny *)
    voidCleanupTableCancel(TAny *)
    IMPORT_C voidCloseContactL(TContactItemId)
    IMPORT_C voidCloseTables()
    IMPORT_C TIntCntServerResourceCount()
    IMPORT_C voidCommitContactL(const CContactItem &)
    IMPORT_C voidCompactL()
    IMPORT_C TBoolCompressRequired()
    IMPORT_C TUintConnectionId()
    IMPORT_C TBoolContactDatabaseExistsL(const TDesC &)
    IMPORT_C TContactItemIdContactIdByGuidL(const TDesC &)
    IMPORT_C TBoolContactMatchesHintFieldL(TInt, TContactItemId)
    IMPORT_C CContactIdArray *ContactsChangedSinceL(const TTime &)
    IMPORT_C TIntCountL()
    IMPORT_C CContactActiveCompress *CreateCompressorLC()
    IMPORT_C CContactItem *CreateContactCardTemplateL(const TDesC &, TBool)
    IMPORT_C CContactItem *CreateContactCardTemplateL(const CContactItem *, const TDesC &, TBool)
    IMPORT_C CContactItem *CreateContactCardTemplateLC(const TDesC &, TBool)
    IMPORT_C CContactItem *CreateContactCardTemplateLC(const CContactItem *, const TDesC &, TBool)
    IMPORT_C CContactItem *CreateContactGroupL(TBool)
    IMPORT_C CContactItem *CreateContactGroupL(const TDesC &, TBool)
    IMPORT_C CContactItem *CreateContactGroupLC(TBool)
    IMPORT_C CContactItem *CreateContactGroupLC(const TDesC &, TBool)
    IMPORT_C CContactDatabase *CreateL(TThreadAccess)
    IMPORT_C CContactDatabase *CreateL(const TDesC &, TThreadAccess)
    IMPORT_C CContactItem *CreateOwnCardL()
    IMPORT_C CContactItem *CreateOwnCardLC()
    IMPORT_C CContactActiveRecover *CreateRecoverLC()
    IMPORT_C voidDamageDatabaseL(TInt)
    IMPORT_C voidDatabaseBeginL(TBool)
    IMPORT_C voidDatabaseBeginLC(TBool)
    IMPORT_C voidDatabaseCommitL(TBool)
    IMPORT_C voidDatabaseCommitLP(TBool)
    IMPORT_C TBoolDatabaseDrive(TDriveUnit &)
    IMPORT_C voidDatabaseRollback()
    IMPORT_C TBoolDefaultContactDatabaseExistsL()
    IMPORT_C voidDeleteContactL(TContactItemId)
    IMPORT_C voidDeleteContactsL(const CContactIdArray &)
    IMPORT_C voidDeleteDatabaseL(const TDesC &)
    IMPORT_C voidDeleteDefaultFileL()
    IMPORT_C CContactIdArray *DeletedContactsLC()
    IMPORT_C voidExportSelectedContactsL(const TUid &, const CContactIdArray &, RWriteStream &, TInt, TBool)
    IMPORT_C voidExportSelectedContactsL(const TUid &, const CContactIdArray &, RWriteStream &, TInt, const Versit::TVersitCharSet, TBool)
    IMPORT_C voidExportSelectedContactsL(const TUid &, const CContactIdArray &, RWriteStream &, TInt, const TInt64, MConverterCallBack *, const TVCardVersion, const TBool, Versit::TVersitCharSet, TBool)
    IMPORT_C TIntFileSize()
    IMPORT_C TPtrCFileUid()
    IMPORT_C voidFilterDatabaseL(CCntFilter &)
    IMPORT_C CIdleFinder *FindAsyncL(const TDesC &, const CContactItemFieldDef *, MIdleFindObserver *)
    IMPORT_C CIdleFinder *FindInTextDefAsyncL(const MDesCArray &, MIdleFindObserver *, const TCallBack &)
    IMPORT_C CIdleFinder *FindInTextDefAsyncL(const MDesCArray &, const CContactTextDef *, MIdleFindObserver *, const TCallBack &)
    IMPORT_C CContactIdArray *FindInTextDefLC(const MDesCArray &, const TCallBack &)
    IMPORT_C CContactIdArray *FindInTextDefLC(const MDesCArray &, CContactTextDef *, const TCallBack &)
    IMPORT_C CContactIdArray *FindLC(const TDesC &, const CContactItemFieldDef *)
    IMPORT_C CContactIdArray *GetCardTemplateIdListL()
    IMPORT_C TIntGetCurrentDatabase(TDes &)
    IMPORT_C TContactItemIdGetCurrentItem()
    IMPORT_C TUidGetDbViewContactType()
    IMPORT_C voidGetDefaultNameL(TDes &)
    IMPORT_C CContactIdArray *GetGroupIdListL()
    IMPORT_C voidGetLastSyncDateL(TContactSyncId, TTime &)
    IMPORT_C TContactItemIdGetSpeedDialFieldL(TInt, TDes &)
    TInt GroupCount()
    voidHandleDatabaseEventL(RDbNotifier::TEvent)
    IMPORT_C voidHandleDatabaseEventL(const TContactDbObserverEvent &)
    voidHandleDiskSpaceEvent(TInt)
    IMPORT_C TContactItemIdICCTemplateIdL()
    IMPORT_C TContactItemIdICCTemplateIdL(TUid)
    IMPORT_C CArrayPtr< CContactItem > *ImportContactsL(const TUid &, RReadStream &, TBool &, TInt)
    IMPORT_C TBoolIsDamaged()
    TBool IsICCSynchronisedL()
    IMPORT_C CDesCArray *ListDatabasesL()
    IMPORT_C CDesCArray *ListDatabasesL(TDriveUnit)
    IMPORT_C TIntLockServerCallBackL(TUint)
    IMPORT_C voidLockServerCleanup()
    IMPORT_C CContactDatabase *LockServerConnectL(const TDesC &)
    IMPORT_C CContactDatabase *LockServerConnectL(const TDesC &, TInt)
    IMPORT_C TInt64MachineId()
    IMPORT_C CContactIdArray *MatchPhoneNumberL(const TDesC &, TInt)
    TInt NullUidValue()
    IMPORT_C CContactOpenOperation *Open(TRequestStatus &, TThreadAccess)
    IMPORT_C CContactOpenOperation *Open(const TDesC &, TRequestStatus &, TThreadAccess)
    IMPORT_C CContactItem *OpenContactL(TContactItemId)
    IMPORT_C CContactItem *OpenContactL(TContactItemId, const CContactItemViewDef &)
    IMPORT_C CContactItem *OpenContactLX(TContactItemId)
    IMPORT_C CContactItem *OpenContactLX(TContactItemId, const CContactItemViewDef &)
    voidOpenDatabaseAsyncL(TRequestStatus &, const TDesC &)
    IMPORT_C CContactDatabase *OpenL(TThreadAccess)
    IMPORT_C CContactDatabase *OpenL(const TDesC &, TThreadAccess)
    IMPORT_C voidOpenTablesL()
    IMPORT_C voidOverrideMachineUniqueId(TInt64)
    IMPORT_C TContactItemIdOwnCardId()
    IMPORT_C TContactItemIdPhonebookGroupIdL()
    IMPORT_C TContactItemIdPrefTemplateId()
    IMPORT_C CArrayPtr< CContactItem > *ReadContactAndAgentL(TContactItemId)
    IMPORT_C CContactItem *ReadContactL(TContactItemId)
    IMPORT_C CContactItem *ReadContactL(TContactItemId, const CContactItemViewDef &)
    IMPORT_C CContactItem *ReadContactLC(TContactItemId)
    IMPORT_C CContactItem *ReadContactLC(TContactItemId, const CContactItemViewDef &)
    IMPORT_C voidReadContactTextDefL(const CContactItem &, TDes &)
    IMPORT_C voidReadContactTextDefL(const CContactItem &, TDes &, CContactTextDef *)
    IMPORT_C voidReadContactTextDefL(TContactItemId, TDes &)
    IMPORT_C voidReadContactTextDefL(TContactItemId, TDes &, CContactTextDef *)
    IMPORT_C CContactItem *ReadMinimalContactL(TContactItemId)
    IMPORT_C CContactItem *ReadMinimalContactLC(TContactItemId)
    IMPORT_C voidRecoverL()
    IMPORT_C voidRecreateSystemTemplateL(const TDesC &)
    IMPORT_C voidRemoveContactFromGroupL(CContactItem &, CContactItem &)
    IMPORT_C voidRemoveContactFromGroupL(TContactItemId, TContactItemId)
    voidRemoveObserver(const MContactDbObserver &)
    IMPORT_C voidRemoveSpeedDialFieldL(TContactItemId, TInt)
    IMPORT_C CContactDatabase *ReplaceL(TThreadAccess)
    IMPORT_C CContactDatabase *ReplaceL(const TDesC &, TThreadAccess)
    IMPORT_C voidResetServerSpeedDialsL()
    IMPORT_C voidRestoreSortOrderL()
    IMPORT_C voidSetCntServerHeapFailure(TInt, TInt)
    IMPORT_C TIntSetCurrentDatabase(const TDesC &)
    IMPORT_C voidSetCurrentItem(const TContactItemId)
    IMPORT_C voidSetDatabaseDriveL(TDriveUnit, TBool)
    IMPORT_C voidSetDateFormatTextL(const TDesC &)
    voidSetDbConnectionState(TDbConnState)
    IMPORT_C voidSetDbViewContactType(const TUid)
    IMPORT_C voidSetFieldAsSpeedDialL(CContactItem &, TInt, TInt)
    IMPORT_C TContactSyncIdSetLastSyncDateL(const TTime &)
    IMPORT_C voidSetLastSyncDateL(TContactSyncId, const TTime &)
    IMPORT_C voidSetOperationTimeOutL(const TInt)
    IMPORT_C voidSetOwnCardL(const CContactItem &)
    IMPORT_C voidSetPrefTemplateL(const CContactItem &)
    IMPORT_C voidSetSortedItemsList(CContactIdArray *, CArrayFix< TSortPref > *)
    IMPORT_C voidSetTextDefinitionL(CContactTextDef *)
    IMPORT_C voidSetViewDefinitionL(CContactViewDef *)
    IMPORT_C CContactIdArray *SortArrayL(const CContactIdArray *, const CArrayFix< TSortPref > *)
    IMPORT_C CContactIdArray *SortArrayLC(const CContactIdArray *, const CArrayFix< TSortPref > *)
    IMPORT_C voidSortAsyncL(CArrayFix< TSortPref > *, TRequestStatus &)
    IMPORT_C voidSortAsyncL(CArrayFix< TSortPref > *, TRequestStatus &, MContactSortObserver &)
    IMPORT_C voidSortByTypeL(CArrayFix< TSortPref > *)
    IMPORT_C voidSortL(CArrayFix< TSortPref > *)
    IMPORT_C const CArrayFix< TSortPref > *SortOrder()
    IMPORT_C const CContactIdArray *SortedItemsL()
    TUid SpeedDialFieldUidFromSpeedDialPosition(TInt)
    IMPORT_C voidStoreSortOrderL()
    IMPORT_C const CContentType &TemplateContentType(const CContactItemField &)
    TInt TemplateCount()
    IMPORT_C TContactItemIdTemplateId()
    IMPORT_C const CContactTextDef *TextDefinition()
    IMPORT_C CContactIdArray *UnfiledContactsL()
    IMPORT_C CContactItem *UpdateContactLC(TContactItemId, CContactItem *)
    IMPORT_C TVersionVersion()
    IMPORT_C TIntWastedSpaceInBytes()
    IMPORT_C TContactItemIddoAddNewContactL(CContactItem &, TBool, TBool)
    IMPORT_C voiddoCommitContactL(const CContactItem &, TBool, TBool)
    IMPORT_C voiddoDeleteContactL(TContactItemId, TBool, TBool, TBool)
    Inherited Functions
    CBase::CBase()
    CBase::Delete(CBase *)
    CBase::Extension_(TUint,TAny *&,TAny *)
    CBase::operator new(TUint)
    CBase::operator new(TUint,TAny *)
    CBase::operator new(TUint,TLeave)
    CBase::operator new(TUint,TLeave,TUint)
    CBase::operator new(TUint,TUint)
    CBase::~CBase()

    Detailed 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()

    Member Type Definition Documentation

    Typedef TTextFieldMinimal

    typedef TBuf< KTextFieldMinimalLength >TTextFieldMinimal

    A text buffer of KTextFieldMinimalLength used during sorting and searching of contacts

    Member Enumeration Documentation

    Enum TContactViewFilter

    Contact view filter flags.

    These flags define the bits that can be set in filtered views (CContactFilteredView) and in the filter passed to CContactDatabase::ContactMatchesHintFieldL() for comparing against contact view items (CViewContact).

    If the item's bit field and the view's filter have the same settings for the CContactDatabase::EHome and CContactDatabase::EWork flags and any of the other flags are set in both, a match occurs and the item is included in the view.

    Filters only apply to non-hidden contact fields with content.

    EnumeratorValueDescription
    EUnfiltered0x00000000

    The view is unfiltered; it includes all contact items.

    EMailable0x00000001

    The filter includes items that have an email address.

    ESmsable0x00000002

    The filter includes items that have a mobile telephone number.

    ELandLine0x00000004

    The filter includes items that have a landline telephone number.

    EFaxable0x00000008

    The filter includes items that have a fax number.

    EPhonable0x00000010

    The filter includes items that are phonable. (All items with any of the above three flags set also have this flag set).

    EWork0x00000020

    The filter excludes items without a work telephone number or email address.

    EHome0x00000040

    The filter excludes items without a home telephone number or email address.

    ERingTone0x00000080

    The filter includes items that have a non-empty ring tone field (a ring tone that is associated with the item).

    EVoiceDial0x00000100

    The filter includes items that have a non-empty voice dial field (a voice recording associated with a telephone number field in the item).

    EIMAddress0x00000200

    The filter includes items that have any non empty instant messaging address field.

    EWirelessVillage0x00000400

    The filter includes items that have a non empty Wireless Village ID field. An item with this flag set will also have the EIMAddress flag set.

    ECustomFilter10x00000800

    Reserved filters for future use.

    ECustomFilter20x00001000

    Reserved filters for future use.

    ECustomFilter30x00002000

    Reserved filters for future use.

    ECustomFilter40x00004000

    Reserved filters for future use.

    Enum TDbConnState

    State of database connection

    EnumeratorValueDescription
    EDbConnectionOpen0

    Database is open, connection is available for use.

    EDbConnectionNotReady

    Initial state.

    EDbConnectionFailed

    Asynchronous Open failed.

    EDbConnectionRecoverRequired

    A Rollback has occurred and a Recover is required now.

    EDbConnectionWriteLockedForBackup

    Write access is locked during backup.

    EDbConnectionClosedForRestore

    The database has been closed whilst a Restore is in progress.

    EDbConnectionNeedToCloseForRestore

    Restore is in progress need to close after current transaction.

    Enum TDirection

    Currently unused

    EnumeratorValueDescription
    EAsc
    EDesc

    Enum TOptions

    Import and export format flags. Contacts can be imported into or exported from the contact database as vCards.

    The following options are available during import and export.

    DeprecatedThis enum is deprecated. It has been replaced by the TOptions enum in the plugin convertor class CContactVCardConverter, so that each plugin converter can define its own options.

    EnumeratorValueDescription
    EDefault0x0000
    EIncludeX0x0001

    Handle Symbian's extended vCard format options.

    ETTFormat0x0002

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

    EExcludeUid0x0004

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

    EDecreaseAccessCount0x0008

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

    EImportSingleContact0x0010

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

    EIncreaseAccessCount0x0020

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

    ELocalTime0x0040

    Sets a contact item to the local time when importing.

    ENullTemplateId0x0080

    Allows you to set a template to a contact item that does not exist.

    EConverterDefined10x0100

    For use by implementor of converter plug-in.

    EConverterDefined20x0200

    For use by implementor of converter plug-in.

    EConverterDefined30x0400

    For use by implementor of converter plug-in.

    EConverterDefined40x0800

    For use by implementor of converter plug-in.

    EConverterDefined50x1000

    For use by implementor of converter plug-in.

    EConverterDefined60x2000

    For use by implementor of converter plug-in.

    EConverterDefined70x4000

    For use by implementor of converter plug-in.

    EConverterDefined80x8000

    For use by implementor of converter plug-in.

    EConverterReserved10x00010000

    Reserved for use by Symbian.

    EConverterReserved20x00020000

    Reserved for use by Symbian.

    EConverterReserved30x00040000

    Reserved for use by Symbian.

    EConverterReserved40x00080000

    Reserved for use by Symbian.

    EConverterReserved50x00100000

    Reserved for use by Symbian.

    EConverterReserved60x00200000

    Reserved for use by Symbian.

    EConverterReserved70x00400000

    Reserved for use by Symbian.

    EConverterReserved80x00800000

    Reserved for use by Symbian.

    EConverterReserved90x01000000

    Reserved for use by Symbian.

    EConverterReserved100x02000000

    Reserved for use by Symbian.

    EConverterReserved110x04000000

    Reserved for use by Symbian.

    EConverterReserved120x08000000

    Reserved for use by Symbian.

    EConverterReserved130x10000000

    Reserved for use by Symbian.

    EConverterReserved140x20000000

    Reserved for use by Symbian.

    EConverterReserved150x40000000

    Reserved for use by Symbian.

    EConverterReserved160x80000000

    Reserved for use by Symbian.

    Enum TSortDataSource

    Enum TThreadAccess

    Specifies whether the database can be accessed from single or multiple threads.

    EnumeratorValueDescription
    ESingleThread

    Allows access to the contacts database from a single thread only.

    EMultiThread

    Allows for a multi-threaded program to access the contact database from multiple threads but note that the contacts model provides no synchronisation support for such use.

    Constructor & Destructor Documentation

    ~CContactDatabase ( )

    IMPORT_C~CContactDatabase()

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

    Member Function Documentation

    AddContactToGroupL ( TContactItemId, TContactItemId )

    IMPORT_C voidAddContactToGroupL(TContactItemIdaItemId,
    TContactItemIdaGroupId
    )

    Sets a contact item in the database to be a member of a contact group.

    The item and group are identified by their IDs.

    capability
    WriteUserData
    leave
    KErrNotFound Either the group or the item does not exist.
    leave
    KErrNotSupported The group is not of type KUidContactGroup.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemIdThe ID of the item to add to the group.
    aGroupIdThe ID of the group to which the item should be added.

    AddContactToGroupL ( CContactItem &, CContactItem & )

    IMPORT_C voidAddContactToGroupL(CContactItem &aItem,
    CContactItem &aGroup
    )

    Sets a contact item in the database to be a member of a contact group.

    capability
    WriteUserData
    leave
    KErrNotFound Either the group or the item does not exist in the database.
    leave
    KErrNotSupported The group is not of type KUidContactGroup.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemThe item to add to the group.
    aGroupThe group to which the item should be added.

    AddContactToGroupL ( TContactItemId, TContactItemId, TBool )

    IMPORT_C voidAddContactToGroupL(TContactItemIdaItemId,
    TContactItemIdaGroupId,
    TBoolaInTransaction
    )

    Sets a contact item in the database to be a member of a contact group.

    The item and group are identified by their IDs.

    capability
    WriteUserData
    leave
    KErrNotFound Either the group or the item does not exist.
    leave
    KErrNotSupported The group is not of type KUidContactGroup.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemIdThe ID of the item to add to the group.
    aGroupIdThe ID of the group to which the item should be added.
    aInTransactionThis argument should be ignored by developers.

    AddNewContactL ( CContactItem & )

    IMPORT_C TContactItemIdAddNewContactL(CContactItem &aContact)

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

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactThe contact item to add to the database.

    Returns: The ID of the new contact item.

    AddObserverL ( MContactDbObserver & )

    voidAddObserverL(MContactDbObserver &aChangeNotifier)

    AllFieldsView ( )

    IMPORT_C CContactItemViewDef *AllFieldsView()

    Returns the full view definition, that loads every field, the returned pointer is owned by the CContactDatabase object.

    capability
    None

    Returns: The definition for a full view with all the contact item fields.

    CancelAsyncSort ( )

    IMPORT_C voidCancelAsyncSort()

    Cancel the CCntIdleSorter object and clean up resources.

    Deprecated

    CancelNotifyRequestL ( )

    voidCancelNotifyRequestL()

    CleanupLastLockedContact ( TAny * )

    voidCleanupLastLockedContact(TAny *aDatabase)[static]

    CleanupTableCancel ( TAny * )

    voidCleanupTableCancel(TAny *aTable)[static]

    CloseContactL ( TContactItemId )

    IMPORT_C voidCloseContactL(TContactItemIdaContactId)

    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.

    capability
    None
    ParameterDescription
    aContactIdThe ID of the contact to close.

    CloseTables ( )

    IMPORT_C voidCloseTables()

    This method is no longer required and should not be called.

    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.

    capability
    WriteUserData
    Deprecated

    CntServerResourceCount ( )

    IMPORT_C TIntCntServerResourceCount()

    Debug only.

    capability
    None

    Returns: return the heap size usage of the server in debug mode, 0 in release mode.

    CommitContactL ( const CContactItem & )

    IMPORT_C voidCommitContactL(const CContactItem &aContact)

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

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrAccessDenied The contact item is not locked by the caller.
    leave
    KErrNotFound The contact item's ID is not present in the database.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    leave
    KErrNotSupported The contact item cannot be committed because it contains invalid data.
    ParameterDescription
    aContactContains the new values for the contact item.

    CompactL ( )

    IMPORT_C voidCompactL()

    This function does nothing and has been deprecated.

    capability
    WriteUserData
    Deprecated

    CompressRequired ( )

    IMPORT_C TBoolCompressRequired()

    This function is deprecated. It always returns EFalse.

    capability
    None
    Deprecated

    Returns: EFalse

    ConnectionId ( )

    IMPORT_C TUintConnectionId()const

    Gets the ID of the connection to the Contacts server.

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

    capability
    None

    Returns: The ID of the connection to the Contacts server.

    ContactDatabaseExistsL ( const TDesC & )

    IMPORT_C TBoolContactDatabaseExistsL(const TDesC &aFileName)[static]

    A 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 190 characters.

    capability
    None
    leave
    KErrNotReady There is no media present in the drive.
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing.
    leave
    KErrNotFound The database file was not found or it did not have the correct UIDs.
    leave
    KErrCorrupt The file is not a valid database
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.

    See also: CContactDatabase::DefaultContactDatabaseExistsL() CContactDatabase::ListDatabasesL()

    ParameterDescription
    aFileNameThe contact database to search for.

    Returns: ETrue if the file is found, EFalse otherwise.

    ContactIdByGuidL ( const TDesC & )

    IMPORT_C TContactItemIdContactIdByGuidL(const TDesC &aGuid)

    Searches the contact tables for the contact described by aGuid.

    capability
    ReadUserData
    leave
    KErrNotReady The database is not yet ready to read from, could be because an asynchronous open is in progress or because a recover is required after a rollback.
    leave
    KErrBadHandle An asynchronous open either failed or was cancelled.
    leave
    KErrLocked The database has been closed for a restore.
    ParameterDescription
    aGuidDescribes the contact item to be found.

    Returns: The unique id of the contact item within the database.

    ContactMatchesHintFieldL ( TInt, TContactItemId )

    IMPORT_C TBoolContactMatchesHintFieldL(TIntaBitWiseFilter,
    TContactItemIdaContactId
    )

    Tests whether a contact item's hint bit field matches a filter.

    For a match to occur, the item must be of the correct type for inclusion in the database (as returned by GetDbViewContactType()) and its hint bit field (which indicates whether the item contains a work or home telephone number, fax number or email address) must match the filter, according to the rules described in TContactViewFilter.

    capability
    None
    ParameterDescription
    aBitWiseFilterThe filter to compare the item against. This is a combination of TContactViewFilter values.
    aContactIdThe ID of the item in the database.

    Returns: ETrue if the item is of the correct type for inclusion in the database, and its hint bit field matches the specified filter, EFalse if either of these conditions are not met.

    ContactsChangedSinceL ( const TTime & )

    IMPORT_C CContactIdArray *ContactsChangedSinceL(const TTime &aTime)

    Gets an array of contacts modified since the specified date/time. The array includes those contacts that have changed since the beginning of the specified micro-second. The caller takes ownership of the returned object.

    capability
    ReadUserData
    ParameterDescription
    aTimeThe date/time of interest.

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

    CountL ( )

    IMPORT_C TIntCountL()

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

    Deprecated
    capability
    None

    Returns: The number of contact items in the database.

    CreateCompressorLC ( )

    IMPORT_C CContactActiveCompress *CreateCompressorLC()

    This function is deprecated. It returns an object whose functions do nothing.

    capability
    WriteUserData
    Deprecated

    Returns: Pointer to an active compressor.

    CreateContactCardTemplateL ( const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactCardTemplateL(const TDesC &aTemplateLabel,
    TBoolaInTransaction = EFalse
    )

    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.

    capability
    WriteUserData
    ParameterDescription
    aTemplateLabelThe string to set as the template label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the contact card template.

    CreateContactCardTemplateL ( const CContactItem *, const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactCardTemplateL(const CContactItem *aTemplate,
    const TDesC &aTemplateLabel,
    TBoolaInTransaction = EFalse
    )

    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.

    capability
    WriteUserData
    ParameterDescription
    aTemplatePointer to an instance of a CContactItem-derived class. This is used to initialise the new template's field set.
    aTemplateLabelThe string to set as the template label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the contact card template.

    CreateContactCardTemplateLC ( const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactCardTemplateLC(const TDesC &aTemplateLabel,
    TBoolaInTransaction = EFalse
    )

    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.

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aTemplateLabelThe string to set as the template label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the contact card template.

    CreateContactCardTemplateLC ( const CContactItem *, const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactCardTemplateLC(const CContactItem *aTemplate,
    const TDesC &aTemplateLabel,
    TBoolaInTransaction = EFalse
    )

    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.

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aTemplatePointer to an instance of a CContactItem-derived class. This is used to initialise the new template's field set.
    aTemplateLabelThe string to set as the template label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the contact card template.

    CreateContactGroupL ( TBool )

    IMPORT_C CContactItem *CreateContactGroupL(TBoolaInTransaction = EFalse)

    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.

    capability
    WriteUserData
    ParameterDescription
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the newly created contact group.

    CreateContactGroupL ( const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactGroupL(const TDesC &aGroupLabel,
    TBoolaInTransaction = EFalse
    )

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

    The caller takes ownership of the returned object.

    capability
    WriteUserData
    ParameterDescription
    aGroupLabelThe string to set as the group label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the newly created contact group.

    CreateContactGroupLC ( TBool )

    IMPORT_C CContactItem *CreateContactGroupLC(TBoolaInTransaction = EFalse)

    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.

    capability
    WriteUserData
    ParameterDescription
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the newly created contact group.

    CreateContactGroupLC ( const TDesC &, TBool )

    IMPORT_C CContactItem *CreateContactGroupLC(const TDesC &aGroupLabel,
    TBoolaInTransaction = EFalse
    )

    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.

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aGroupLabelThe string to set as the group label.
    aInTransactionThis argument should be ignored by developers.

    Returns: Pointer to the newly created contact group.

    CreateL ( TThreadAccess )

    IMPORT_C CContactDatabase *CreateL(TThreadAccessaAccess = ESingleThread)[static]

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

    capability
    WriteUserData
    leave
    KErrAlreadyExists The database already exists.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aAccessThe 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

    Returns: A pointer to the new contact database.

    CreateL ( const TDesC &, TThreadAccess )

    IMPORT_C CContactDatabase *CreateL(const TDesC &aFileName,
    TThreadAccessaAccess = ESingleThread
    )[static]

    Creates and opens a named contact database.

    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 190 characters.

    capability
    WriteUserData
    leave
    KErrAlreadyExists The database already exists.
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive letter is missing.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.
    ParameterDescription
    aFileNameThe filename of the database to create.
    aAccessThe 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

    Returns: A pointer to the new contact database.

    CreateOwnCardL ( )

    IMPORT_C CContactItem *CreateOwnCardL()

    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.

    capability
    WriteUserData

    Returns: Pointer to the new default own card.

    CreateOwnCardLC ( )

    IMPORT_C CContactItem *CreateOwnCardLC()

    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.

    capability
    WriteUserData

    Returns: Pointer to the new default own card. The pointer is left on the cleanup stack.

    CreateRecoverLC ( )

    IMPORT_C CContactActiveRecover *CreateRecoverLC()

    This function is deprecated. It returns an object whose functions do nothing.

    capability
    WriteUserData
    Deprecated

    Returns: Pointer to an active recoverer.

    DamageDatabaseL ( TInt )

    IMPORT_C voidDamageDatabaseL(TIntaSecretCode)

    Debug Only

    capability
    WriteUserData

    DatabaseBeginL ( TBool )

    IMPORT_C voidDatabaseBeginL(TBoolaIsInTransaction)

    Starts a new transaction, without placing a cleanup item to rollback the database onto the cleanupstack. This is to enable clients to call contacts methods from an active object.

    capability
    WriteUserData
    leave
    KErrDiskFull if used storage space above threshold
    ParameterDescription
    aIsInTransactionETrue if transaction already started

    DatabaseBeginLC ( TBool )

    IMPORT_C voidDatabaseBeginLC(TBoolaIsInTransaction)

    Starts a new transaction. Places and leaves a cleanup item to rollback the database on the cleanupstack.

    leave
    KErrDiskFull There is insufficient disk space.
    ParameterDescription
    aIsInTransactionUsed to determine whether or not to start the transaction depending on if a transaction is currently in progress.

    DatabaseCommitL ( TBool )

    IMPORT_C voidDatabaseCommitL(TBoolaIsInTransaction)

    Commits an existing transaction, without popping a cleanup item.

    capability
    WriteUserData
    ParameterDescription
    aIsInTransactionETrue if transaction already started

    DatabaseCommitLP ( TBool )

    IMPORT_C voidDatabaseCommitLP(TBoolaIsInTransaction)

    Commits an existing transaction, pops the rollback cleanup item off the CleanupStack. Closes the database if the connection state is EDbConnectionNeedToCloseForRestore.

    ParameterDescription
    aIsInTransactionUsed to determine whether or not to commit the transaction depending on whether a transaction is currently in progress.

    DatabaseDrive ( TDriveUnit & )

    IMPORT_C TBoolDatabaseDrive(TDriveUnit &aDriveUnit)[static]

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

    capability
    None
    leave
    KErrNoMemory Out of memory.

    See also: CContactDatabase::SetDatabaseDrive() CContactDatabase::GetDefaultNameL()

    ParameterDescription
    aDriveUnitOn return, contains the database drive.

    Returns: 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.

    DatabaseRollback ( )

    IMPORT_C voidDatabaseRollback()

    Force a rollback of the database.

    capability
    WriteUserData

    DefaultContactDatabaseExistsL ( )

    IMPORT_C TBoolDefaultContactDatabaseExistsL()[static]

    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.

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

    See also: CContactDatabase::ContactDatabaseExistsL()

    Returns: ETrue if the file is found, EFalse otherwise.

    DeleteContactL ( TContactItemId )

    IMPORT_C voidDeleteContactL(TContactItemIdaContactId)

    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.

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrNotFound aContactId is not present in the database.
    leave
    KErrInUse The contact item is open.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactIdThe contact item ID of the contact to delete.

    DeleteContactsL ( const CContactIdArray & )

    IMPORT_C voidDeleteContactsL(const CContactIdArray &aContactIds)

    Deletes an array of contacts.

    The function commits the changes for every 32 (for 9.5 onwards it commits after every 50) 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.

    capability
    WriteUserData
    capability
    ReadUserData
    leave
    KErrNotFound A contact item ID contained in the array is not present in the database.
    leave
    KErrInUse One or more of the contact items is open.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactIdsAn array of contacts to delete.

    DeleteDatabaseL ( const TDesC & )

    IMPORT_C voidDeleteDatabaseL(const TDesC &aFileName)[static]

    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 190 characters.

    capability
    WriteUserData
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing.
    leave
    KErrInUse Another client has the database open.
    leave
    KErrNotFound The database file was not found or it did not have the correct UIDs.
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.

    See also: CContactDatabase::DeleteDefaultFileL()

    ParameterDescription
    aFileNameThe contact database file to delete.

    DeleteDefaultFileL ( )

    IMPORT_C voidDeleteDefaultFileL()[static]

    Deletes the default contact database.

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

    See also: CContactDatabase::DeleteDatabaseL() CContactDatabase::GetDefaultNameL() CContactDatabase::DefaultContactDatabaseExistsL()

    DeletedContactsLC ( )

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

    Debug only.

    capability
    ReadUserData

    Returns: Pointer to the array of contacts marked as deleted.

    ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, TBool )

    IMPORT_C voidExportSelectedContactsL(const TUid &aFormat,
    const CContactIdArray &aSelectedContactIds,
    RWriteStream &aWriteStream,
    TIntaOption,
    TBoolaExportPrivateFields = ETrue
    )

    Converts an array of contact items to vCards and exports them to a write stream.

    The default character set CVersitParser::EUTF8CharSet is used to convert into. If you need a different character set, use the other overload of this function.

    capability
    ReadUserData
    leave
    KErrNotSupported aFormat.iUid is not KUidVCardConvDefaultImpl.
    leave
    KErrNotFound One or more of the contact items does not exist in the database.
    ParameterDescription
    aFormatIndicates the format for imported and exported contacts. Must have a value of KUidVCardConvDefaultImpl.
    aSelectedContactIdsArray of contact IDs to export.
    aWriteStreamThe stream to write to.
    aOptionIndicates the options for import and export. See the TOptions enum.
    aExportPrivateFieldsETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

    ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, const Versit::TVersitCharSet, TBool )

    IMPORT_C voidExportSelectedContactsL(const TUid &aFormat,
    const CContactIdArray &aSelectedContactIds,
    RWriteStream &aWriteStream,
    TIntaOption,
    const Versit::TVersitCharSetaCharSet,
    TBoolaExportPrivateFields = ETrue
    )

    Converts an array of contact items to vCards and exports them to a write stream using the specified character set.

    capability
    ReadUserData
    leave
    KErrNotSupported aFormat.iUid is not KUidVCardConvDefaultImpl.
    leave
    KErrNotFound One or more of the contact items does not exist in the database.
    ParameterDescription
    aFormatIndicates the format for imported and exported contacts. Must have a value of KUidVCardConvDefaultImpl.
    aSelectedContactIdsArray of contact IDs to export.
    aWriteStreamThe stream to write to.
    aOptionIndicates the options for import and export. See the TOptions enum.
    aCharSetThe character set to convert into.
    aExportPrivateFieldsETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

    ExportSelectedContactsL ( const TUid &, const CContactIdArray &, RWriteStream &, TInt, const TInt64, MConverterCallBack *, const TVCardVersion, const TBool, Versit::TVersitCharSet, TBool )

    IMPORT_C voidExportSelectedContactsL(const TUid &aFormat,
    const CContactIdArray &aSelectedContactIds,
    RWriteStream &aWriteStream,
    TIntaOption,
    const TInt64aContactFieldFilter,
    MConverterCallBack *aCallback,
    const TVCardVersionaVersion,
    const TBoolaExportTel,
    Versit::TVersitCharSetaCharSet = Versit::EUTF8CharSet,
    TBoolaExportPrivateFields = ETrue
    )

    Converts an array of contact items to PBAP compliant vCards following vCard2.1 and vCard3.0 specifications and exports them to a write stream using UTF-8 as the character set. It also provides support for exporting contacts as standard vCard2.1.

    capability
    ReadUserData
    leave
    KErrNotSupported aFormat.iUid is not KUidPBAPVCardConvImpl for PBAP export.
    leave
    KErrNotSupported aFormat.iUid is not KUidVCardConvDefaultImpl for standard vCard2.1 export.
    leave
    KErrNotSupported aCharSet is other than UTF-8 for PBAP export.
    leave
    KErrNotFound One or more of the contact items does not exist in the database.
    ParameterDescription
    aFormatIndicates the format for imported and exported contacts. It should have a value of KUidPBAPVCardConvImpl if user wants to export contacts as PBAP specific vCards and KUidVCardConvDefaultImpl for standard vCard2.1.
    aSelectedContactIdsArray of contact IDs to export.
    aWriteStreamThe stream to write to.
    aOptionIndicates the options for import and export. See the TOptions enum.
    aContactFieldFilter64-bit filter,specifies the contact fields to export, argument value not considered for standard vCard2.1 export.
    aCallbackCalls client which has to implement class MConverterCallBack, used to add intra-contact properties, argument value not considered for standard vCard2.1 export.
    aVersionTVCardVersion specifies vCard version to which contacts should be exported.
    aExportTelIf TEL property should be exported, it should be set to ETrue, argument value not considered for standard vCard2.1 export.
    aCharSetThe character set to convert into.Must be UTF-8 for PBAP export, provided as default value.
    aExportPrivateFieldsETrue exports fields marked as private. EFalse does not export fields marked as private. See CContactItemField::SetPrivate().

    FileSize ( )

    IMPORT_C TIntFileSize()const

    Gets the size of the database file in bytes.

    capability
    None

    Returns: The size of the contact database.

    FileUid ( )

    IMPORT_C TPtrCFileUid()

    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.

    Note: This method can leave.

    capability
    None

    Returns: Descriptor containing the database UID.

    FilterDatabaseL ( CCntFilter & )

    IMPORT_C voidFilterDatabaseL(CCntFilter &aFilter)

    Filters the database. On return, aFilter contains an array of filtered contact item IDs.

    capability
    ReadUserData
    ParameterDescription
    aFilterThe filter to use. On return, contains a filtered array of contact item IDs.

    FindAsyncL ( const TDesC &, const CContactItemFieldDef *, MIdleFindObserver * )

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

    ParameterDescription
    aTextThe text to search for.
    aFieldDefSpecifies the fields to search.
    aObserverImplements the callback function IdleFindCallback(). NULL if no observer is needed.

    Returns: A CIdle-derived object which provides information about the progress of the operation, and which can be used to retrieve an array of contact IDs.

    FindInTextDefAsyncL ( const MDesCArray &, MIdleFindObserver *, const TCallBack & )

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

    FindInTextDefAsyncL ( const MDesCArray &, const CContactTextDef *, MIdleFindObserver *, const TCallBack & )

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

    FindInTextDefLC ( const MDesCArray &, const TCallBack & )

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

    FindInTextDefLC ( const MDesCArray &, CContactTextDef *, const TCallBack & )

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

    FindLC ( const TDesC &, const CContactItemFieldDef * )

    IMPORT_C 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. There is a limit of 255 characters on the search string length, due to the implementation of the DBMS API, which also has a search string length restriction of 255 chars. If the search string passed in is over 255 characters this method will leave with KErrArgument.

    ParameterDescription
    aTextThe text to search for.
    aFieldDefSpecifies the fields to search.

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

    GetCardTemplateIdListL ( )

    IMPORT_C CContactIdArray *GetCardTemplateIdListL()const

    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.

    Returns: 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.

    GetCurrentDatabase ( TDes & )

    IMPORT_C TIntGetCurrentDatabase(TDes &aDatabase)const

    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.

    Deprecated
    capability
    None
    ParameterDescription
    aDatabaseThe path and filename of the current database. KNullDesC if no current database has been set.

    Returns: KErrNone if the function completed successfully, otherwise one of the standard error codes.

    GetCurrentItem ( )

    IMPORT_C TContactItemIdGetCurrentItem()const

    Gets the ID of the current item, as set by SetCurrentItem(). The current item ID is initialised to KNullContactId when the database is opened.

    capability
    None

    Returns: The ID of the current item.

    GetDbViewContactType ( )

    IMPORT_C TUidGetDbViewContactType()const

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

    Deprecated

    Returns: 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)

    GetDefaultNameL ( TDes & )

    IMPORT_C voidGetDefaultNameL(TDes &aDes)[static]

    Gets the file name of the default contact database.

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

    capability
    None

    See also: CContactDatabase::SetDatabaseDriveL() CContactDatabase::DatabaseDrive() CContactDatabase::DefaultContactDatabaseExistsL()

    ParameterDescription
    aDesOn 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.

    GetGroupIdListL ( )

    IMPORT_C CContactIdArray *GetGroupIdListL()const

    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.

    Returns: Pointer to an array containing the contact item IDs for each group in the database. NULL if there are no groups in the database.

    GetLastSyncDateL ( TContactSyncId, TTime & )

    IMPORT_C voidGetLastSyncDateL(TContactSyncIdaSyncId,
    TTime &aSyncDate
    )

    Gets the date/time the database was last synchronised with a particular sync ID, as set by SetLastSyncDateL().

    Deprecated

    leave
    KErrNotFound The ID cannot be found in the database.
    ParameterDescription
    aSyncIdThis argument should be ignored by developers.
    aSyncDateOn return contains the date/time the database was last synchronised with the sync ID specified.

    GetSpeedDialFieldL ( TInt, TDes & )

    IMPORT_C TContactItemIdGetSpeedDialFieldL(TIntaSpeedDialPosition,
    TDes &aPhoneNumber
    )

    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.

    capability
    ReadUserData
    ParameterDescription
    aSpeedDialPositionThe speed dial position. This is an integer in the range 1 to 9 inclusive. If outside this range, the function leaves with KErrArgument.
    aPhoneNumberOn return, contains the telephone number which is mapped to the speed dial position specified. Returns KNullDesC if the speed dial position requested has not been set.

    Returns: The ID of the contact item for which the speed dial has been set.

    GroupCount ( )

    TInt GroupCount()const [inline]

    Gets the number of groups that exist in the database. Deprecated

    Returns: The number of groups that exist in the database.

    HandleDatabaseEventL ( RDbNotifier::TEvent )

    voidHandleDatabaseEventL(RDbNotifier::TEvent)[inline]

    HandleDatabaseEventL ( const TContactDbObserverEvent & )

    IMPORT_C voidHandleDatabaseEventL(const TContactDbObserverEvent &aEvent)

    Handle the Database event

    ParameterDescription
    aEventDatabase change event

    HandleDiskSpaceEvent ( TInt )

    voidHandleDiskSpaceEvent(TIntaDrive)

    Default behaviour for handling a low disk event - This function is unimplemented.

    ICCTemplateIdL ( )

    IMPORT_C TContactItemIdICCTemplateIdL()

    Returns the ID of the template that should be used with CContactICCEntry items.

    capability
    None

    Returns: A template ID.

    ICCTemplateIdL ( TUid )

    IMPORT_C TContactItemIdICCTemplateIdL(TUidaPhonebookUid)

    Returns the ID of the template that should be used with CContactICCEntry items belonging to the phonebook with TUid aPhonebookUid.

    capability
    None
    ParameterDescription
    aPhonebookUidThe phonebook ID.

    Returns: A template ID.

    ImportContactsL ( const TUid &, RReadStream &, TBool &, TInt )

    IMPORT_C CArrayPtr< CContactItem > *ImportContactsL(const TUid &aFormat,
    RReadStream &aReadStream,
    TBool &aImportSuccessful,
    TIntaOption
    )

    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.

    capability
    WriteUserData
    leave
    KErrNotSupported aFormat.iUid is not KUidVCardConvDefaultImpl.
    ParameterDescription
    aFormatIndicates the format for imported and exported contacts. Its value must be KUidVCardConvDefaultImpl.
    aReadStreamThe stream to read from.
    aImportSuccessfulOn return, ETrue if at least one contact was successfully imported. EFalse if not.
    aOptionIndicates the options for import and export. See the TOptions enum.

    Returns: The array of contact items imported.

    IsDamaged ( )

    IMPORT_C TBoolIsDamaged()const

    This function is deprecated. It always returns EFalse.

    capability
    None
    Deprecated

    Returns: EFalse

    IsICCSynchronisedL ( )

    TBool IsICCSynchronisedL()

    ListDatabasesL ( )

    IMPORT_C CDesCArray *ListDatabasesL()[static]

    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 190 characters.

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

    capability
    ReadUserData
    leave
    KErrNoMemory Out of memory.

    Returns: An array containing zero or more contact database names.

    ListDatabasesL ( TDriveUnit )

    IMPORT_C CDesCArray *ListDatabasesL(TDriveUnitaDriveUnit)[static]

    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 190 characters.

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

    capability
    ReadUserData
    leave
    KErrNoMemory Out of memory.
    ParameterDescription
    aDriveUnitThe drive unit to search for contact databases.

    Returns: An array containing zero or more contact database names.

    LockServerCallBackL ( TUint )

    IMPORT_C TIntLockServerCallBackL(TUintaServerOperation)

    For BC.

    LockServerCleanup ( )

    IMPORT_C voidLockServerCleanup()

    For BC.

    LockServerConnectL ( const TDesC & )

    IMPORT_C CContactDatabase *LockServerConnectL(const TDesC &aFileName)[static]

    For BC.

    LockServerConnectL ( const TDesC &, TInt )

    IMPORT_C CContactDatabase *LockServerConnectL(const TDesC &aFileName,
    TIntaOperation
    )[static]

    For BC.

    MachineId ( )

    IMPORT_C TInt64MachineId()const

    Returns a number unique to the contacts database. This value may be passed to CContactItem::UidStringL().

    capability
    None

    Returns: The database's unique ID.

    MatchPhoneNumberL ( const TDesC &, TInt )

    IMPORT_C CContactIdArray *MatchPhoneNumberL(const TDesC &aNumber,
    TIntaMatchLengthFromRight
    )

    Returns an array of contact item IDs for all the contact items which may contain the specified telephone number in a telephone, fax or SMS type field.

    The comparison method used is not exact. The number is compared starting from the right side of the number and the method returns an array of candidate matches. Punctuation (eg. spaces) and other alphabetic characters are ignored when comparing.

    Additionally, if the contacts model phone parser (CNTPHONE.DLL) is available, then any DTMF digits are also excluded from the comparision.

    Notes: Due to the way numbers are stored in the database, it is recommended that at least 7 match digits are specified even when matching a number containing fewer digits. Failure to follow this guideline may (depending on the database contents) mean that the function will not return the expected Contacts Id set.

    capability
    ReadUserData
    ParameterDescription
    aNumberPhone number string. If the length of phone number string is greater than KCntMaxTextFieldLength then only the first KCntMaxTextFieldLength characters are used in the match.
    aMatchLengthFromRightNumber of digits from the right of the phone number to use Up to 15 digits can be specified, and it is recommended that at least 7 match digits are specified.

    Returns: CContactIdArray of candidate matches

    NullUidValue ( )

    TInt NullUidValue()[static, inline]

    Gets the NULL contact ID value.

    Returns: KNullContactId.

    Open ( TRequestStatus &, TThreadAccess )

    IMPORT_C CContactOpenOperation *Open(TRequestStatus &aStatus,
    TThreadAccessaAccess = ESingleThread
    )[static]

    Opens the default contact database asynchronously.

    The Contacts 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.

    capability
    ReadUserData

    See also: CContactOpenOperation

    ParameterDescription
    aStatusOn 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.
    aAccessThis argument should be ignored by developers.

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

    Open ( const TDesC &, TRequestStatus &, TThreadAccess )

    IMPORT_C CContactOpenOperation *Open(const TDesC &aFileName,
    TRequestStatus &aStatus,
    TThreadAccessaAccess = ESingleThread
    )[static]

    Opens a named contact database asynchronously.

    The Contacts 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 190 characters.

    If an empty path is entered, it will be treated as a request to open the default contact database.

    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.

    capability
    ReadUserData

    See also: CContactOpenOperation

    ParameterDescription
    aFileNameThe filename of the database to open.
    aStatusOn 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.
    aAccessThis argument should be ignored by developers.

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

    OpenContactL ( TContactItemId )

    IMPORT_C CContactItem *OpenContactL(TContactItemIdaContactId)

    Opens a contact item for editing.

    The returned contact item is locked and left open until either CommitContactL() or CloseContactL() is called.

    This function uses a view definition that loads every field. If you need to specify your own view definition use the other overload of this function.

    The caller takes ownership of the returned object.

    capability
    WriteUserData
    leave
    KErrInUse The contact item is already open.
    leave
    KErrNotFound The contact item is not present in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to open.

    Returns: The open, locked contact.

    OpenContactL ( TContactItemId, const CContactItemViewDef & )

    IMPORT_C CContactItem *OpenContactL(TContactItemIdaContactId,
    const CContactItemViewDef &aViewDef
    )

    Opens a contact item for editing, leaving the lock record on the cleanup stack.

    The returned item is locked and left open until either CommitContactL() or CloseContactL() is called.

    This function uses the specified view definition. Note: 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.

    Deprecated
    capability
    WriteUserData
    leave
    KErrInUse The contact item is already open
    leave
    KErrNotFound The contact item is not present in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to open.
    aViewDefThe view definition.

    Returns: The open, locked contact item.

    OpenContactLX ( TContactItemId )

    IMPORT_C CContactItem *OpenContactLX(TContactItemIdaContactId)

    Opens a contact item for editing using a specified view definition.

    The returned contact item is locked and left open until either CommitContactL() or CloseContactL() is called.

    Note: 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.

    Deprecated
    capability
    WriteUserData
    leave
    KErrInUse The contact item is already open.
    leave
    KErrNotFound The contact item is not present in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to open.

    Returns: The open, locked contact.

    OpenContactLX ( TContactItemId, const CContactItemViewDef & )

    IMPORT_C CContactItem *OpenContactLX(TContactItemIdaContactId,
    const CContactItemViewDef &aViewDef
    )

    Opens a contact item for editing, leaving the lock record on the cleanup stack.

    The returned item is locked and left open until either CommitContactL() or CloseContactL() is called.

    This function uses the specified view definition. Note: 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.

    Deprecated
    capability
    WriteUserData
    leave
    KErrInUse The contact item is already open
    leave
    KErrNotFound The contact item is not present in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to open.
    aViewDefThe view definition.

    Returns: The open, locked contact item.

    OpenDatabaseAsyncL ( TRequestStatus &, const TDesC & )

    voidOpenDatabaseAsyncL(TRequestStatus &aStatus,
    const TDesC &aFileName =  KNullDesC
    )

    OpenL ( TThreadAccess )

    IMPORT_C CContactDatabase *OpenL(TThreadAccessaAccess = ESingleThread)[static]

    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.

    capability
    ReadUserData
    leave
    KErrNotFound The database file was not found or it did not have the correct UIDs.
    leave
    KErrLocked Another client is writing to the database.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aAccessThe 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

    Returns: Pointer to the open contact database.

    OpenL ( const TDesC &, TThreadAccess )

    IMPORT_C CContactDatabase *OpenL(const TDesC &aFileName,
    TThreadAccessaAccess = ESingleThread
    )[static]

    Opens a named contact database.

    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 190 characters, and empty string is not accepted.

    capability
    ReadUserData
    leave
    KErrNotFound The database file was not found or it did not have the correct UIDs.
    leave
    KErrLocked Another client is writing to the database.
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive is missing.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.
    ParameterDescription
    aFileNameThe filename of the database to open.
    aAccessThe 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

    Returns: A pointer to the open contact database.

    OpenTablesL ( )

    IMPORT_C voidOpenTablesL()

    This method is no longer required and should not be called.

    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.

    capability
    ReadUserData
    Deprecated

    OverrideMachineUniqueId ( TInt64 )

    IMPORT_C voidOverrideMachineUniqueId(TInt64aMachineUniqueId)

    Debug only.

    capability
    None
    ParameterDescription
    aMachineUniqueIdThe Machine ID to set.

    OwnCardId ( )

    IMPORT_C TContactItemIdOwnCardId()const

    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()).

    capability
    None

    Returns: The ID of the database's current own card. KNullContactId if the own card has been deleted or has not yet been set.

    PhonebookGroupIdL ( )

    IMPORT_C TContactItemIdPhonebookGroupIdL()

    Returns the ID of the contacts model group which represents the ADN phonebook.

    capability
    None

    Returns: Group ID.

    PrefTemplateId ( )

    IMPORT_C TContactItemIdPrefTemplateId()const

    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.

    capability
    None

    Returns: The ID of the database's current preferred template.

    ReadContactAndAgentL ( TContactItemId )

    IMPORT_C CArrayPtr< CContactItem > *ReadContactAndAgentL(TContactItemIdaContactId)

    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.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item cannot be found in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to read.

    Returns: Pointer to an array containing the contact item and agent, if present.

    ReadContactL ( TContactItemId )

    IMPORT_C CContactItem *ReadContactL(TContactItemIdaContactId)

    Reads a contact item without locking it.

    This function uses the default view definition (as set by SetViewDefinitionL()). The caller takes ownership of the returned object.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item does not exist in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to read.

    Returns: Pointer to the contact item.

    ReadContactL ( TContactItemId, const CContactItemViewDef & )

    IMPORT_C CContactItem *ReadContactL(TContactItemIdaContactId,
    const CContactItemViewDef &aViewDef
    )

    Reads a contact item without locking it.

    This function uses the view definition specified. The caller takes ownership of the returned object.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item does not exist in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to read.
    aViewDefThe view definition to use.

    Returns: Pointer to the contact item.

    ReadContactLC ( TContactItemId )

    IMPORT_C CContactItem *ReadContactLC(TContactItemIdaContactId)

    Reads a contact item without locking it.

    This function uses the default view definition (as set by SetViewDefinitionL()). The caller takes ownership of the returned object.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item does not exist in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to read.

    Returns: Pointer to the contact item. This is left on the cleanup stack.

    ReadContactLC ( TContactItemId, const CContactItemViewDef & )

    IMPORT_C CContactItem *ReadContactLC(TContactItemIdaContactId,
    const CContactItemViewDef &aViewDef
    )

    Reads a contact item without locking it.

    This function uses the view definition specified. The caller takes ownership of the returned object.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item does not exist in the database.
    ParameterDescription
    aContactIdThe ID of the contact item to read.
    aViewDefThe view definition to use.

    Returns: Pointer to the contact item. This is left on the cleanup stack.

    ReadContactTextDefL ( const CContactItem &, TDes & )

    IMPORT_C voidReadContactTextDefL(const CContactItem &aItem,
    TDes &aResult
    )

    Reads text into a descriptor from a pre-loaded contact item.

    This function uses the database's current text definition (as set using CContactDatabase::SetTextDefinitionL()).

    capability
    ReadUserData
    ParameterDescription
    aItemThe contact item to read.
    aResultOn return, contains the text read from the contact item aItem, using the database's current text definition.

    ReadContactTextDefL ( const CContactItem &, TDes &, CContactTextDef * )

    IMPORT_C voidReadContactTextDefL(const CContactItem &aItem,
    TDes &aResult,
    CContactTextDef *aTextDef
    )

    Reads text into a descriptor from a pre-loaded contact item, using the specified text definition.

    capability
    ReadUserData
    ParameterDescription
    aItemThe contact item to read.
    aResultOn return, contains the text read from the contact item aItem, using the text definition specified in aTextDef.
    aTextDefThe text definition to use.

    ReadContactTextDefL ( TContactItemId, TDes & )

    IMPORT_C voidReadContactTextDefL(TContactItemIdaContactId,
    TDes &aResult
    )

    Reads text from a contact item stored in the database into a descriptor.

    This function uses the database's currently set text definition (as set using CContactDatabase::SetTextDefinitionL()).

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item cannot be found in the database.
    ParameterDescription
    aContactIdThe ID of the contact to read.
    aResultOn return, contains the text read from the contact item identified by aContactId, using the database's current text definition.

    ReadContactTextDefL ( TContactItemId, TDes &, CContactTextDef * )

    IMPORT_C voidReadContactTextDefL(TContactItemIdaContactId,
    TDes &aResult,
    CContactTextDef *aTextDef
    )

    Reads text from a contact item stored in the database into a descriptor using the specified text definition.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item cannot be found in the database.
    ParameterDescription
    aContactIdThe ID of the contact to read.
    aResultOn return, contains the text read from the contact item identified by aContactId, using the text definition specified in aTextDef.
    aTextDefThe text definition to use.

    ReadMinimalContactL ( TContactItemId )

    IMPORT_C CContactItem *ReadMinimalContactL(TContactItemIdaContactId)

    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 this function does 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.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item cannot be found in the database.
    ParameterDescription
    aContactIdThe ID of the contact to read.

    Returns: Pointer to the contact whose ID is aContactId.

    ReadMinimalContactLC ( TContactItemId )

    IMPORT_C CContactItem *ReadMinimalContactLC(TContactItemIdaContactId)

    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 ReadContactLC() which uses the server's default view definition, except that this function does 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.

    capability
    ReadUserData
    leave
    KErrNotFound The specified contact item cannot be found in the database.
    ParameterDescription
    aContactIdThe ID of the contact to read.

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

    RecoverL ( )

    IMPORT_C voidRecoverL()

    Recovers the database from a rollback. It first closes all tables and then reopens them after the recover.

    capability
    WriteUserData

    RecreateSystemTemplateL ( const TDesC & )

    IMPORT_C voidRecreateSystemTemplateL(const TDesC &aFileName)[static]

    A static method to recreate the system template.

    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 190 characters.

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive letter is missing.
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.
    ParameterDescription
    aFileNameThe contact database filename.

    RemoveContactFromGroupL ( CContactItem &, CContactItem & )

    IMPORT_C voidRemoveContactFromGroupL(CContactItem &aItem,
    CContactItem &aGroup
    )

    Removes the association between a contact item and a group.

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemThe item to remove.
    aGroupThe group from which the item should be removed.

    RemoveContactFromGroupL ( TContactItemId, TContactItemId )

    IMPORT_C voidRemoveContactFromGroupL(TContactItemIdaItemId,
    TContactItemIdaGroupId
    )

    Removes the association between a contact item and a group.

    The item and group are identified by their IDs.

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemIdThe ID of the item to remove.
    aGroupIdThe ID of the group from which the item should be removed.

    RemoveObserver ( const MContactDbObserver & )

    voidRemoveObserver(const MContactDbObserver &aChangeNotifier)

    RemoveSpeedDialFieldL ( TContactItemId, TInt )

    IMPORT_C voidRemoveSpeedDialFieldL(TContactItemIdaContactId,
    TIntaSpeedDialPosition
    )

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

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactIdThe ID of the contact item containing the speed dial field.
    aSpeedDialPositionThe speed dial position. This is an integer in the range 1 to 9 inclusive. If outside this range, the function leaves with KErrArgument.

    ReplaceL ( TThreadAccess )

    IMPORT_C CContactDatabase *ReplaceL(TThreadAccessaAccess = ESingleThread)[static]

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

    capability
    WriteUserData
    leave
    KErrInUse Another client has an open connection to the database.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    leave
    KErrNoMemory There is no memory to perform the operation.
    ParameterDescription
    aAccessThe 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

    Returns: Pointer to the new contact database.

    ReplaceL ( const TDesC &, TThreadAccess )

    IMPORT_C CContactDatabase *ReplaceL(const TDesC &aFileName,
    TThreadAccessaAccess = ESingleThread
    )[static]

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

    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 190 characters.

    capability
    WriteUserData
    leave
    KErrBadName The filename is invalid; for example it contains wildcard characters or the drive letter is missing.
    leave
    KErrInUse Another client has an open connection to the database.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    leave
    KErrNoMemory There is no memory to perform the operation.
    leave
    KErrArgument if the given descriptor contains more than the maximum length of 190 characters.
    ParameterDescription
    aFileNameThe filename of the database to replace.
    aAccessThe 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

    Returns: A pointer to the new contact database.

    ResetServerSpeedDialsL ( )

    IMPORT_C voidResetServerSpeedDialsL()

    Requests that the server reset all its speed dials to a NULL state. Needed so that T_NOMACH works (since deleting the db no longer resets the speed dials)

    Debug only.

    capability
    WriteUserData

    RestoreSortOrderL ( )

    IMPORT_C voidRestoreSortOrderL()

    This function is not currently supported. Deprecated

    SetCntServerHeapFailure ( TInt, TInt )

    IMPORT_C voidSetCntServerHeapFailure(TIntaTAllocFailType,
    TIntaRate
    )

    Debug only.

    capability
    None

    SetCurrentDatabase ( const TDesC & )

    IMPORT_C TIntSetCurrentDatabase(const TDesC &aDatabase)const

    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.

    Deprecated
    capability
    WriteUserData
    ParameterDescription
    aDatabaseThe path and filename of the current database.

    Returns: KErrNone if the function completed successfully, otherwise one of the standard error codes.

    SetCurrentItem ( const TContactItemId )

    IMPORT_C voidSetCurrentItem(const TContactItemIdaContactId)

    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.

    capability
    WriteUserData
    ParameterDescription
    aContactIdThe ID of the current item.

    SetDatabaseDriveL ( TDriveUnit, TBool )

    IMPORT_C voidSetDatabaseDriveL(TDriveUnitaDriveUnit,
    TBoolaCopy = ETrue
    )[static]

    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.

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

    See also: CContactdatabase::DatabaseDrive() CContactDatabase::GetDefaultNameL() CContactDatabase::DefaultContactDatabaseExistsL()

    ParameterDescription
    aDriveUnitThe drive to which to move the database.
    aCopyETrue 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.

    SetDateFormatTextL ( const TDesC & )

    IMPORT_C voidSetDateFormatTextL(const TDesC &aFormat)

    This function is not currently supported. Deprecated

    ParameterDescription
    aFormatThis parameter should be ignored.

    SetDbConnectionState ( TDbConnState )

    voidSetDbConnectionState(TDbConnStateaDbConnectionState)

    SetDbViewContactType ( const TUid )

    IMPORT_C voidSetDbViewContactType(const TUidaUid)

    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.

    Deprecated
    capability
    None
    ParameterDescription
    aUidSpecifies 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)

    SetFieldAsSpeedDialL ( CContactItem &, TInt, TInt )

    IMPORT_C voidSetFieldAsSpeedDialL(CContactItem &aItem,
    TIntaFieldIndex,
    TIntaSpeedDialPosition
    )

    Sets a field containing a telephone number as a speed dial field. The field is identified by aFieldIndex 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.

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aItemThe contact item containing the field to set as a speed dial field.
    aFieldIndexIndex of a field in aItem's field set to set as a speed dial field.
    aSpeedDialPositionThe speed dial position. This is an integer in the range 1 to 9 inclusive. If outside this range, the function leaves with KErrArgument.

    SetLastSyncDateL ( const TTime & )

    IMPORT_C TContactSyncIdSetLastSyncDateL(const TTime &aSyncDate)

    Sets the date/time the database was last synchronised.

    This 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).

    Deprecated

    ParameterDescription
    aSyncDateThe database's new last synchronised date/time.

    Returns: The sync ID created by the function.

    SetLastSyncDateL ( TContactSyncId, const TTime & )

    IMPORT_C voidSetLastSyncDateL(TContactSyncIdaSyncId,
    const TTime &aSyncDate
    )

    Sets the date/time the database was last synchronised.

    This overload is for a known sync ID and updates the database's last synchronised date/time for that ID.

    Deprecated

    leave
    KErrNotFound The specified sync ID is not found.
    ParameterDescription
    aSyncIdThis argument should be ignored by developers.
    aSyncDateThe database's new last synchronised date/time.

    SetOperationTimeOutL ( const TInt )

    IMPORT_C voidSetOperationTimeOutL(const TIntaMicroSeconds)const

    Sets the time out of operations on the database server.

    This API allows the behaviour of the Contacts Model to be tuned for scenarios where clients either expect to encounter or know they will encounter operations failing primarily due to the database being locked.

    Not all clients will find they need to use this API. By default the operation timeout is 1 second.

    The timeout only needs to be set once per session. Multiple clients using the same database can specify independent values for the operation timeout.

    capability
    None
    leave
    KErrArgument If aMicroSeconds is less than 0 or is greater than 300000000 (equivalent to 5 minutes).
    ParameterDescription
    aMicroSecondsThe operation timeout in microseconds. This timeout will only be applied to requests sent by clients of this database after this point in time.

    SetOwnCardL ( const CContactItem & )

    IMPORT_C voidSetOwnCardL(const CContactItem &aContact)

    Sets an existing contact item to be the database's current own card.

    capability
    WriteUserData
    leave
    KErrNotFound aContact does not exist in the database.
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactThe contact item to set as the database's current own card. It must already exist in the database. It cannot be a group or a template.

    SetPrefTemplateL ( const CContactItem & )

    IMPORT_C voidSetPrefTemplateL(const CContactItem &aContact)

    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.

    capability
    WriteUserData
    leave
    KErrNotSupported The item is not a template (of type KUidContactCardTemplate).
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactThe contact card template to set as the database's preferred template.

    SetSortedItemsList ( CContactIdArray *, CArrayFix< TSortPref > * )

    IMPORT_C voidSetSortedItemsList(CContactIdArray *aSortedItems,
    CArrayFix< TSortPref > *aSortOrder
    )

    This method allows clients of contacts model to set the sorted item list and sort order from a default sort order server as proposed for Crystal 6.0

    Note: This method can leave.

    Deprecated
    capability
    None
    ParameterDescription
    aSortedItemsSpecifies an array sorted items
    aSortOrderSpecifies the sort order

    SetTextDefinitionL ( CContactTextDef * )

    IMPORT_C voidSetTextDefinitionL(CContactTextDef *aView)

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

    ParameterDescription
    aViewThe new text definition.

    SetViewDefinitionL ( CContactViewDef * )

    IMPORT_C voidSetViewDefinitionL(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.

    capability
    WriteUserData
    ParameterDescription
    aViewThe view definition. This method does nothing if this is null.

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

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

    Deprecated
    capability
    None
    ParameterDescription
    aIdArrayPointer to array of contact IDs to sort.
    aSortOrderSort order array.

    Returns: Pointer to sorted array of contact IDs.

    SortArrayLC ( const CContactIdArray *, const CArrayFix< TSortPref > * )

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

    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.

    Deprecated
    capability
    None
    ParameterDescription
    aIdArrayPointer to array of contact IDs to sort.
    aSortOrderSort order array.

    Returns: Pointer to sorted array of contact IDs.

    SortAsyncL ( CArrayFix< TSortPref > *, TRequestStatus & )

    IMPORT_C voidSortAsyncL(CArrayFix< TSortPref > *aSortOrder,
    TRequestStatus &aStatus
    )

    aSortOrder is owned by the idle sorter. Deprecated

    ParameterDescription
    aSortOrderSpecifies the sort order
    aStatusThe request status for the asynchronous phase request.

    SortAsyncL ( CArrayFix< TSortPref > *, TRequestStatus &, MContactSortObserver & )

    IMPORT_C voidSortAsyncL(CArrayFix< TSortPref > *aSortOrder,
    TRequestStatus &aStatus,
    MContactSortObserver &aObserver
    )

    aSortOrder is owned by the idle sorter. Deprecated

    ParameterDescription
    aSortOrderSpecifies the sort order
    aStatusThe request status for the asynchronous phase request.

    SortByTypeL ( CArrayFix< TSortPref > * )

    IMPORT_C voidSortByTypeL(CArrayFix< TSortPref > *aSortOrder)

    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.

    Deprecated
    capability
    None
    ParameterDescription
    aSortOrderSort order array.

    SortL ( CArrayFix< TSortPref > * )

    IMPORT_C voidSortL(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 original database order.

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

    Deprecated
    capability
    None
    ParameterDescription
    aSortOrderSort order array. If the array's count is zero, no sorting takes place.

    SortOrder ( )

    IMPORT_C const CArrayFix< TSortPref > *SortOrder()const

    Gets the array of sort preferences.

    Note: This method can leave.

    Deprecated
    capability
    None

    Returns: A pointer to an array of sort preferences of the contact database.

    SortedItemsL ( )

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

    Deprecated
    capability
    None

    Returns: A pointer to the array of sorted items. The caller does not take ownership of this object.

    SpeedDialFieldUidFromSpeedDialPosition ( TInt )

    TUid SpeedDialFieldUidFromSpeedDialPosition(TIntaSpeedDialPosition)[static]

    Returns the field UID for the given speed dial position. This method is copied from CCntServerSpeedDialManager::SpeedDialFieldUidFromSpeedDialPosition() rather than export this method for use here and on the server. Once the BC break referred to in SetFieldAsSpeedDialL() has been made this method should be removed.

    ParameterDescription
    aSpeedDialPositionThe speed dial position for which we want the field UID.

    Returns: The field UID corresponding to aSpeedDialPosition.

    StoreSortOrderL ( )

    IMPORT_C voidStoreSortOrderL()

    This function is not currently supported. Deprecated

    TemplateContentType ( const CContactItemField & )

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

    Note: this function can leave.

    ParameterDescription
    aFieldThe field of interest.

    Returns: The content type of the field.

    TemplateCount ( )

    TInt TemplateCount()const [inline]

    Gets the number of contact card templates that exist in the database. This does not include the system template. Deprecated

    Returns: The number of contact card templates that exist in the database.

    TemplateId ( )

    IMPORT_C TContactItemIdTemplateId()const

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

    Returns: ID of the system template.

    TextDefinition ( )

    IMPORT_C const CContactTextDef *TextDefinition()const

    Gets a pointer to the text definition.

    Returns: A pointer to the text definition.

    UnfiledContactsL ( )

    IMPORT_C CContactIdArray *UnfiledContactsL()

    Returns a list of 'unfiled' contacts. These are contacts which do not belong to any group.

    capability
    ReadUserData

    Returns: The list of 'unfiled' contacts.

    UpdateContactLC ( TContactItemId, CContactItem * )

    IMPORT_C CContactItem *UpdateContactLC(TContactItemIdaContactId,
    CContactItem *aNewContact
    )

    Updates a contact identified by aContactId with the data in aNewContact. All empty fields are deleted.

    Deprecated

    capability
    WriteUserData
    capability
    ReadUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactIdThis argument should be ignored by developers.
    aNewContactThe contact item to replace it with.

    Returns: The contact item after the update.

    Version ( )

    IMPORT_C TVersionVersion()const

    Gets the contact model's version number.

    Returns: The version number of the contacts model.

    WastedSpaceInBytes ( )

    IMPORT_C TIntWastedSpaceInBytes()const

    This function is deprecated and always returns 0.

    capability
    None
    Deprecated

    Returns: The wasted space in the contacts database.

    doAddNewContactL ( CContactItem &, TBool, TBool )

    IMPORT_C TContactItemIddoAddNewContactL(CContactItem &aContact,
    TBoolaIsTemplate,
    TBoolaIsInTransaction
    )

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

    capability
    WriteUserData
    leave
    KErrDiskFull The disk does not have enough free space to perform the operation.
    ParameterDescription
    aContactThe contact item to add to the database.
    aIsTemplateThis argument should be ignored by developers.
    aIsInTransactionThis argument should be ignored by developers.

    Returns: The ID of the new contact item.

    doCommitContactL ( const CContactItem &, TBool, TBool )

    IMPORT_C voiddoCommitContactL(const CContactItem &aContact,
    TBoolaIsInTransaction,
    TBoolaSendChangedEvent
    )

    Updates the existing contact information.

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrAccessDenied The contact item is not locked by the caller.
    leave
    KErrNotFound The contact item's ID is not present in the database.
    leave
    KErrNotSupported The contact item cannot be committed because it contains invalid data.
    ParameterDescription
    aContactContains the new values for the contact item.
    aIsInTransactionThis argument should be ignored by developers.
    aSendChangedEventThis argument should be ignored by developers.

    doDeleteContactL ( TContactItemId, TBool, TBool, TBool )

    IMPORT_C voiddoDeleteContactL(TContactItemIdaContactId,
    TBoolaIsInTransaction,
    TBoolaSendChangedEvent,
    TBoolaDecAccessCount = EFalse
    )

    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.

    capability
    ReadUserData
    capability
    WriteUserData
    leave
    KErrNotSupported An attempt has been made to delete the system template.
    leave
    KErrNotFound aContactId is not present in the database.
    leave
    KErrInUse The contact item is open.
    ParameterDescription
    aContactIdThe contact item ID of the contact to delete.
    aIsInTransactionThis argument should be ignored by developers.
    aSendChangedEventThis argument should be ignored by developers.
    aDecAccessCountThis argument should be ignored by developers.