- Qt 5.0
- Qt 5.0.0 Reference Documentation

# ContactModel QML Type

The ContactModel element provides access to contacts from the contacts store. More...

Import Statement: | import QtContacts 5.0

- List of all members, including inherited members

## Properties

- ImportError : enumeration
- autoUpdate : bool
- availableManagers : list<string>
- contacts : list<Contact>
- error : string
- fetchHint : FetchHint
- filter : Filter
- manager : string
- sortOrders : list<SortOrder>

## Signals

- contactsFetched(int requestId, list<Contact> fetchedContacts)
- onImportCompleted(ImportError error, URL url, list<string> ids)

## Methods

- cancelUpdate()
- void exportContacts(url url, list<string> profiles, list<variant> declarativeContacts)
- int fetchContacts(list<string> contactIds)
- void importContacts(url url, list<string> profiles)
- removeCollection(string collectionId)
- removeContact(string contactId)
- removeContacts(list<string> contactIds)
- saveContact(Contact contact)
- updateCollections()
- updateContacts()

## Detailed Description

This element is part of the QtContacts module.

ContactModel provides a model of contacts from the contacts store. The contents of the model can be specified with filter, sortOrders and fetchHint properties. Whether the model is automatically updated when the store or contacts changes, can be controlled with ContactModel::autoUpdate property.

There are two ways of accessing the contact data: via model by using views and delegates, or alternatively via contacts list property. Of the two, the model access is preferred. Direct list access (i.e. non-model) is not guaranteed to be in order set by sortOrder.

At the moment the model roles provided by ContactModel are display, decoration and `contact`. Through the `contact` role can access any data provided by the Contact element.

See also RelationshipModel, Contact, and QContactManager.

## Property Documentation

ImportError : enumeration

Defines the errors cases for ContactModel::importContacts() -function.

- ContactModel::ImportNoError Completed successfully, no error.
- ContactModel::ImportUnspecifiedError Unspecified error.
- ContactModel::ImportIOError Input/output error.
- ContactModel::ImportOutOfMemoryError Out of memory error.
- ContactModel::ImportNotReadyError Not ready for importing. Only one import operation can be active at a time.
- ContactModel::ImportParseError Error during parsing.

autoUpdate : bool

This property indicates whether or not the contact model should be updated automatically, default value is true.

availableManagers : list<string>

This property holds the list of available manager names. This property is read only.

contacts : list<Contact>

This property holds the list of contacts.

See also Contact.

error : string

This property holds the latest error code returned by the contact manager.

This property is read only.

fetchHint : FetchHint

This property holds the fetch hint instance used by the contact model.

See also FetchHint.

filter : Filter

This property holds the filter instance used by the contact model.

See also Filter.

manager : string

This property holds the manager uri of the contact backend engine.

sortOrders : list<SortOrder>

This property holds a list of sort orders used by the contacts model.

See also SortOrder.

## Signal Documentation

contactsFetched(int requestId, list<Contact> fetchedContacts)

This signal is emitted, when a contact fetch request is finished.

Note: The corresponding handler is `onContactsFetched`.

See also ContactModel::fetchContacts.

onImportCompleted(ImportError error, URL url, list<string> ids)

This signal is emitted, when ContactModel::importContacts() completes. The success of operation can be seen on error which is defined in ContactModel::ImportError. url indicates the file, which was imported. ids contains the imported contacts ids.

If the operation was successful, contacts are now imported to backend. If ContactModel::autoUpdate is enabled, ContactModel::modelChanged will be emitted when imported contacts are also visible on ContactModel's data model.

Note: The corresponding handler is `onOnImportCompleted`.

See also ContactModel::importContacts.

## Method Documentation

cancelUpdate()

Cancel the running contact model content update request.

See also ContactModel::autoUpdate and ContactModel::update.

void exportContacts(url url, list<string> profiles, list<variant> declarativeContacts)

Export all contacts of this model into a vcard file to the given url by optional profiles. The optional declarativeContacts list can be used to export an arbitrary list of QDeclarativeContact objects not necessarily belonging to the data set of this model. At the moment only the local file url is supported in export method. Also, only one export operation can be active at a time. Supported profiles are:

- "Sync" exports contacts in sync mode, currently, this is the same as passing in an empty list, and is generally what you want.
- "Backup" exports contacts in backup mode, this will add non-standard properties to the generated vCard to try to save every detail of the contacts. Only use this if the vCard is going to be imported using the backup profile. #include "moc_qdeclarativecontactmodel_p.cpp"

See also QVersitContactHandlerFactory, QVersitContactHandlerFactory::ProfileSync(), and QVersitContactHandlerFactory::ProfileBackup().

int fetchContacts(list<string> contactIds)

Starts a request to fetch contacts by the given contactIds, and returns the unique ID of this request. -1 is returned if the request can't be started.

Note that the contacts fetched won't be added to the model, but can be accessed through the contactsFetched signal handler.

See also ContactModel::contactsFetched.

void importContacts(url url, list<string> profiles)

Import contacts from a vcard by the given url and optional profiles. Only one import operation can be active at a time. Supported profiles are:

- "Sync" Imports contacts in sync mode, currently, this is the same as passing in an empty list, and is generally what you want.
- "Backup" imports contacts in backup mode, use this mode if the vCard was generated by exporting in backup mode.

See also QVersitContactHandlerFactory, QVersitContactHandlerFactory::ProfileSync(), and QVersitContactHandlerFactory::ProfileBackup().

removeCollection(string collectionId)

Removes asynchronously the contact collection with the given collectionId from the backend.

removeContact(string contactId)

Remove the contact from the contacts store by given contactId. After removing a contact it is not possible to save it again.

See also Contact::contactId.

removeContacts(list<string> contactIds)

Remove the list of contacts from the contacts store by given contactIds.

See also Contact::contactId.

saveContact(Contact contact)

Save the given contact into the contacts backend. Once saved successfully, the dirty flags of this contact will be reset.

See also Contact::modified.

updateCollections()

Manually update the contact model collections.

See also ContactModel::update, ContactModel::updateContacts, and ContactModel::autoUpdate.

updateContacts()

Manually update the contact model contacts.

See also ContactModel::update, ContactModel::updateCollections, and ContactModel::autoUpdate.