|
|
              
Contacts Synchronous APIIntroductionThe Contacts Synchronous API enables a client to synchronously fetch, update, or remove contact data from a contact manager. A synchronous API is of most use to clients who wish to perform simple requests where performance or user interface responsiveness is not critical. Synchronous calls to a contact manager will block until they are completed, and therefore should not be performed in the GUI thread if the manager is a frontend to an online service or long-latency datastore. The main advantage of the synchronous API is its simplicity and convenience. Most operations which may be performed using the synchronous API may also be performed using the asynchronous API. It is recommended for most applications that the asynchronous API be used where possible. Using The APIThe synchronous API offered by the Contacts module is available through the QContactManager class. It consists of three major sections:
Error ReportingWhen a synchronous operation fails, clients need to be able to retrieve error information associated with that synchronous operation. The QContactManager::error() function provides this information to clients. For some synchronous operations (for example, batch save or remove operations) it is possible that multiple errors may occur during the operation. In those cases, the synchronous function will take a pointer to a map of input index to error, which will be filled by the function as required, and the QContactManager::error() function will report the overall operation error. Error reporting is handled slightly differently in the asynchronous API, in that each instance of an asynchronous request is able to report any overall operation error as well as the finer-grained map of errors, for the operation which it requested. Contact ManipulationThe most common type of operation that clients will perform involves retrieval or modification of contacts. The QContactManager class offers synchronous API to retrieve, create, update and delete contacts. The create and update operations are provided through the same interface. Both singular and batch operations are offered by the API. A contact is identified by its QContactId. This id consists of two parts: a URI which identifies the contact manager which stores the contact, and the local id of the contact in that manager. Some operations which take a pointer to a contact as an argument may modify the contact during the operation; updating the contact id is a common example. The QContactManager class provides API for accessing the IDs of contacts which are stored in the manager:
The contact id retrieval functionality is also provided via asynchronous API through the QContactIdFetchRequest class. The synchronous, singular contact manipulation functions offered by the QContactManager class are:
The (optional) fetch argument to the contact accessor function allows clients to tell the plugin which types of information they wish to retrieve. This argument is a hint only, and may be ignored safely by the plugin, or used by the plugin to optimize the performance of the retrieve operation. The save operation entails a validation step, where the contact's details are checked against the supported schema. If the contact is valid, it will be saved. Note that if the contact already exists in the database (determined by the id of the contact) it will be replaced with the contact contained in the argument. This means that clients should not save any contact which was retrieved with a non-empty fetchHint defined, or data loss may occur. Any error which occurs during such singular contact manipulation functions may be accessed by calling QContactManager::error() directly after the original synchronous call. The synchronous, batch contact manipulation functions offered by the QContactManager class are:
The batch save and remove functions both take an (optional) pointer to a map of errors. If the pointer is non-null, this map will be filled out with any errors which occur. The overall operation error of any batch manipulation operation may be accessed by calling QContactManager::error() directly after the original synchronous call. The contact manipulation functionality is also provided via asynchronous API through the QContactFetchRequest, QContactSaveRequest, and QContactRemoveRequest classes. The "self" contact is a special concept, which has dedicated API. A client may instruct any backend which supports the concept of a self contact that a particular, previously saved contact is the self contact. Any backend which implements this functionality should report that it supports the QContactManager::SelfContact feature. The API which provides the self-contact functionality consists of:
In order to unset the self contact, a client may either delete the contact which is currently set as the self contact, or set the self contact id to be null id (constructed via QContactId()). The self-contact manipulation functionality is only available via the synchronous API. Relationship ManipulationContacts may be related in various ways. The contacts API allows clients to define relationships between contacts if the plugin providing the functionality supports such relationships. Some plugins support arbitrary relationship types. Clients can define custom relationships between contacts saved in such plugins. The API which provides the relationship manipulation functionality consists of:
The relationship manipulation functionality is also provided via asynchronous API through the QContactRelationshipFetchRequest, QContactRelationshipSaveRequest, and QContactRelationshipRemoveRequest classes. Examples Of UsageThe synchronous API provides the simplest way to access or modify the contact information managed by a particular backend. It has the disadvantage that calls block until completion and is therefore most suitable only for applications which interact with local, high-speed datastores. Saving a new contact to the default managerThe client creates a new contact, adds a name and a phone number, and saves it to the default store of the default manager. We assume the existence of a specialized leaf-class that allows simple access to details of the definition identified by the "PhoneNumber" identifier, and another that allows simple access to details of the definition identified by the "Name" identifier. These specialized leaf classes may be written by anyone, and simply wrap the functionality provided by QContactDetail in order to allow simpler access to fields supported by a particular definition. void addContact(QContactManager* cm) { QContact alice; /* Set the contact's name */ QContactName aliceName; aliceName.setFirstName("Alice"); aliceName.setLastName("Jones"); aliceName.setCustomLabel("Ally Jones"); alice.saveDetail(&aliceName); /* Add a phone number */ QContactPhoneNumber number; number.setContexts(QContactDetail::ContextHome); number.setSubTypes(QContactPhoneNumber::SubTypeMobile); number.setNumber("12345678"); alice.saveDetail(&number); alice.setPreferredDetail("DialAction", number); /* Add a second phone number */ QContactPhoneNumber number2; number2.setContexts(QContactDetail::ContextWork); number2.setSubTypes(QContactPhoneNumber::SubTypeLandline); number2.setNumber("555-4444"); alice.saveDetail(&number2); /* Save the contact */ cm->saveContact(&alice) ? qDebug() << "Successfully saved" << aliceName.customLabel() : qDebug() << "Failed to save" << aliceName.customLabel(); qDebug() << "The backend has synthesized a display label for the contact:" << alice.displayLabel(); } Filtering by detail definition and valueThe client utilizes a default manager and asks for any contacts with a particular phone number. The example assumes that the default manager supports the provided QContactPhoneNumber detail leaf class (which implements the default definition for phone number details). void matchCall(QContactManager* cm, const QString& incomingCallNbr) { QContactDetailFilter phoneFilter; phoneFilter.setDetailType(QContactPhoneNumber::Type, QContactPhoneNumber::FieldNumber); phoneFilter.setValue(incomingCallNbr); phoneFilter.setMatchFlags(QContactFilter::MatchExactly); QList<QContactId> matchingContacts = cm->contactIds(phoneFilter); if (matchingContacts.size() == 0) { qDebug() << "Incoming call from unknown contact (" << incomingCallNbr << ")"; } else { QContact match = cm->contact(matchingContacts.at(0)); qDebug() << "Incoming call from" << match.displayLabel() << "(" << incomingCallNbr << ")"; } } Modifying an existing contact and saving the modificationsThe client retrieves a contact, modifies one of its details, adds a new detail, and then saves the contact back to the manager. void editView(QContactManager* cm) { QList<QContactId> contactIds = cm->contactIds(); QContact a = cm->contact(contactIds.first()); qDebug() << "Modifying the details of" << a.displayLabel(); /* Change the first phone number */ QList<QContactDetail> numbers = a.details(QContactPhoneNumber::Type); QContactPhoneNumber phone = numbers.value(0); phone.setNumber("123-4445"); /* Add an email address */ QContactEmailAddress email; email.setEmailAddress("alice.jones@example"); email.setContexts(QContactDetail::ContextHome); email.setValue("Label", "Alice's Work Email Address"); /* Save the updated details to the contact. */ a.saveDetail(&phone); a.saveDetail(&email); /* Now we must save the updated contact back to the database. */ cm->saveContact(&a); viewDetails(cm); } |
