QtContacts.ContactModel

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

Properties

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

Signals

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

Methods

• void exportContacts(url url, list<string> profiles, list<variant> declarativeContacts)
• int fetchContacts(list<string> contactIds)
• void importContacts(url url, list<string> profiles)
• removeContact(string contactId)
• removeContacts(list<string> contactIds)
• saveContact(Contact contact, StorageLocation storageLocation)

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

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.

Defines the different storage locations for saving contacts and model population purposes.

• ContactModel::UserDataStorage A storage location where user data is stored.
• ContactModel::SystemStorage A storage location where system files are stored.

Depending on the backend implementation, the access rights for different storage locations might vary.

See also ContactModel::storageLocations and ContactModel::saveContact.

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

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

This property holds the list of contacts.

See also Contact.

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

This property is read only.

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

See also FetchHint.

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

See also Filter.

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

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

See also SortOrder.

This property indicates which storage location is used to populate the model.

Only one storage location can be used for each model.

Storage location is a backend specific feature. Some backends support it and some might just ignore it. If backend is having some specific requirements and they're not met, backend returns StorageLocationsNotExistingError.

See also ContactModel::StorageLocation and ContactModel::saveContact.

Signal Documentation

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

See also ContactModel::fetchContacts.

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.

See also ContactModel::importContacts.

This signal is emitted, when ContactModel::storageLocations property changes.

See also ContactModel::storageLocations.

Method Documentation

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

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.

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

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.

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

See also Contact::contactId.

Save the given contact into the contacts backend.

The location for storing the contact can be defined with storageLocation for new contacts. When the contact is updated, ie saved again, storageLocation is ignored and the contact is saved to the same location as it were before.

Once saved successfully, the dirty flags of this contact will be reset.

See also Contact::modified.