Preamble ======== This text describes a D-Bus API. The API implements in-vehicle infotainment (IVI) use cases around contacts: - cache address books from peers (primarily phones connected via Bluetooth) in local address books - provide a unified address book that combines a configurable (and changing) subset of the local address books - fast phone number lookup - browsing and searching in the unified address book Tasks that are expected to be done by the user of this API: - identify peers and their capabilities - decide how and when peer data should be cached - define which data goes into the unified address book In other words, the API provides the mechanisms and the user the policy. Several aspects of this API may differ depending on the implementation. For example, searching for contacts and syncing with peers are not described in the API. Consult the documentation of the API implementation to learn what it supports. For SyncEvolution, that documentation is the src/dbus/server/pim/README file. Datatypes ========= Peers ----- A peer is an entity which has exactly one address book that is meant to be cached locally. Typically a peer is a phone connected via Bluetooth and accessed via PBAP, but it could also be a web service that supports CardDAV or a phone with SyncML support. Peers are identified by a unique string ID. That ID needs to be assigned by the user of this API. The string must not be empty and may only contain characters a-z, 0-9 and hyphen. No other assumptions about its content are made. For example, the phone's Bluetooth MAC address could be used after removing or replacing the colon and using lower case hex characters. For an entity that has more than one address book, multiple peers must be configured. For each peer, enough information must be provided to access its address book. That information is passed via D-Bus as a string-to-string dict, with keys and their values being defined by the implementation. Address books ------------- Address books which mirror data from a specific peer use the string "peer-" as ID, where is the unique ID of that peer. In addition, there is a system address book which is independent of any particular phone. Its ID is the empty string. This naming scheme can be extended later on, to support other kinds of address books. Contact ------- A single contact is transferred via D-Bus as a string->variant dict where the keys are predefined property names and the values represent simple values (a string for "full-name") or more complex structures (list of phone numbers for "phone-numbers", with each list entry itself being a combination of type flags and the actual value). [comment: this mirrors the properties of a libfolks Individual: http://telepathy.freedesktop.org/doc/folks/c/FolksIndividual.html] Some properties of a FolksIndividual only make sense locally and are not transmitted, for example the personas it is derived from. Some other properties provide information not found that way in FolksIndividual: - "source" = list of string pairs, where each pair is a combination of address book ID and local contact ID inside that address book (not necessarily the same as the vCard UID of a contact!) - "id" = an opaque string which identifies the contact while it exists inside any PIM Manager view. See ContactsAdded and ReadContacts. Property values which are large (like photos) are not sent via D-Bus. Instead a link to a local file is sent. For a full definition of contact properties see the implementation documentation. Search results -------------- The goal is to support a UI which: - displays an ordered list of the search result, - can show the initial results with minimal delay, - can load actual content for the display as needed (only load the parts which are visible or will be visible soon). The content of the unified address book can change at any time. The API design takes that into account by using a model/view/controller model. The model is the complete list of contacts, sorted according to the currently configured sort order. Sorting is part of the model to simplify generating views. The view is the subset of the data that a user of the API has requested. In the most extreme case, all contacts are part of the view. Therefore contact data has to be requested explicitly. Contacts are numbered 0 to n-1 in each view, where n is the number of contacts in the view. Sort order is the same as in the underlying model. Change notifications with these index numbers are sent as contacts are added, modified or removed. The controller is the part of the API which allows changing contacts in the system address book, changing the sort order, enabling or disabling address books, etc. Note that removing or adding a contact changes the numbers assigned to other contacts. Example: - A view containing 10 contacts is created. - A notification about "contacts #0 to #9 added" is sent (given as pair of first index and count, not list of numbers). - The five contacts starting with #5 to are read via their ID. - Contact #4 gets removed. The user needs to remember that the data that it has now corresponds to contacts #4 to #8. - Contact #5 gets added, before the contact which had that number before. The user now has contacts #4 and #6 to #9. It should request contact #5 if (or once) it is needed to provide a complete list to the user. [comment: using a view could be simplified by including contact data in the change notifications. This is not planned at the moment because it would not work well for large views. When adding it, there should be an API to restrict which properties of a contact get sent.] Error handling ============== D-Bus error messages are not localized. They are meant for debugging, not for displaying to the user. In cases where the caller may be able to do something about an error, specific error codes are defined as part of the API. However, typically errors are generic and the caller simply has to assume that the PIM storage is currently unusable. Unless noted otherwise, calls return when the requested operation is complete. The following errors are defined. In addition to the D-Bus name of the error they provide a textual error description. org._01.pim.contacts.Manager.Aborted Some operation was intentionally aborted instead of letting it complete. Typically not an error. org._01.pim.contacts.Manager.BadStatus A generic error report. The error description is a string which gives further information for debugging. API === PIM Manager ----------- The PIM manager is used to hold the unified address book in memory, create views on it, change configuration and control data transfers from phones. Service: org._01.pim.contacts Interface: org._01.pim.contacts.Manager Object path: /org/01/pim/contacts Methods: void Start() The PIM manager does not start loading contact data right away. That allows setting the options like sort order first and/or delaying the loading until it is needed. After Start(), changing options that affect the unified address book will take effect immediately. Calling Start() is optional, any method asking for data will automatically do that. void Stop() Explicitly tells the PIM manager to discard the unified address book and free up the memory if possible (= not currently in use). Primarily useful for testing. void SetSortOrder(string mode) "mode" must be one of the values supported by the implementation. string GetSortOrder() Returns the current sort order. list of strings GetActiveAddressBooks() Returns the IDs of the address books which currently contribute to the unified address book. void SetActiveAddressBooks(list of strings) Sets the address books which contribute to the unified address book. void CreatePeer(string uid, dict properties) Creates a peer. Will fail with a org._01.pim.contacts.Manager.AlreadyExists error if the uid is already in use. To change the configuration of a peer, remove and recreate it. This ensures that its data gets removed, too. [A ModifyPeer() might get added if there is demand for it and the desired behavior (remove cached data or keep it?) is better understood.] As a backwards compatibility measure this method is also available as SetPeer() with the semantic that the config is created or modified automatically as needed. void RemovePeer(string uid) Removes a peer and all its cached data. If that data was part of the active address books, it will be removed automatically. void SyncPeer(string uid) Retrieve contacts from the peer and ensure that the local cache is identical to the address book of the peer. The call returns once the operation is complete. Only if there was no error can the caller assume that the cache is up-to-date. Otherwise it is in an undefined state. void StopSync(string uid) Stop any running sync for the given peer. The SyncPeer() method which started such a sync will return with an "aborted" error once the sync was stopped. dict of UID to string key/value dict GetAllPeers() Returns information about all currently configured peers. object Search(list filter, object agent) Creates a new view which contains all contacts matching the filter. The call returns the object path of a view object after validating parameters and starting the result gathering, and before completing the search. The view object can be used to control the view via the org._01.pim.contacts.ViewControl interface. The content of the filter is defined by the implementation. Notifications for the view are sent back to the caller by invoking methods from the org._01.pim.contacts.ViewAgent interface on the object whose path is given in the "view" parameter. If any of these method calls fail, the view will automatically be destroyed. In other words, the caller first needs to get ready to process results by registering an object on the bus before calling Search(). [comment: this allows sending results to just one recipient, something that cannot be done easily with the use of signals as in, for example, obexd. In obexd, the initiator of a transfer has to subscribe to org.bluez.obex.Transfer on the object path returned to it when starting the transfer, then check the current status before waiting for signals, because the "Completed" signal might have been sent before it could register for it.] string AddContact(string addressbook, dict contact) Adds a new contact to the given address book. Typically only the system address book is writable. Contact properties which are unknown or cannot be stored are silently ignored. Returns the local ID of the new contact in the address book. Photo data that is sent inline in the dict will be split out into a file that gets associated with the contact. A photo file that gets linked will continue to be owned by the caller; the contact storage may or may not make a copy of it, depending on which storage is used. void ModifyContact(string addressbook, string localid, dict contact) Updates an existing contact. void RemoveContact(string addressbook, string localid) Remove the contact and all of its associated data (like the photo, if the photo file is owned by the contact storage). Service: org._01.pim.contacts Interface: org._01.pim.contacts.ViewControl Object path: [variable prefix]/{view0,view1,....} Methods: list of (int index, contact dicts) pairs ReadContacts(array ids) Requests the data of the contacts idenfified via their IDs. Only the data of contacts that are still part of the view can be returned. The returned list contains the current index of the requested contact plus its data. -1 and an empty dictionary are returned for contacts which can no longer be read, for example because they were removed from the view in the meantime or because the ID was simply invalid. Note that the caller must process the call response after all events via the ViewAgent interface. Otherwise the index numbers are potentially out of sync and thus unreliable. Doing this call asynchronously and dealing with the response as part of the main event loop will do the right thing automatically, because D-Bus guarantees ordering of messages. Making this explicit by returning data via another org._01.pim.contacts.ViewAgent method was considered and rejected a) for the sake of keeping this API simple and b) to allow simple synchronous calls where it makes sense (testing, for example). void Close() Closes the view and all resources associated with it. Pending ReadContacts() calls will return without any data and no error. void RefineSearch(list filter) Replaces the current filter of the view with a new one. The new filter must be stricter than the old one. Contacts which were already filtered out will not be added back to the view when setting a less restrictive filter (simplifies the implementation and improves performance). void ReplaceSearch(list filter, bool refine) Same as RefineSearch() if refine is true. If refine is false, the new filter can be less restrictive and contacts which did not match the old filter will be added back to the list of matching contacts. Service: [user of the PIM Manager] Interface: org._01.pim.contacts.ViewAgent Object path: [as chosen by user of PIM Manager] Methods: void ContactsModified(object view, int start, array ids) Contacts #start till #start + count (inclusive) have changed. Data that the recipient of the call might have cached became invalid and should be reloaded. It is possible that a contact gets replaced by another with a single "contact modified" signal. In other words, the ID at each position may change and thus the IDs are sent as part of the signal. In cases where a contact changes its position in the view, both a combination of "contact removed" + "contact added" (single contact changes) as well as several "contact modified" signals are possible (contacts swap position, for example when reordering). In the later case, a contact will temporarily appear at two different positions. void ContactsAdded(object view, int start, array ids) New contacts were added to the view. The number of new contacts is given via the size of the ids array. The ID of each new contact is guaranteed to be the same in all views. IDs may get reused after their contact got removed from the last view it was contained in. In particular there is no guarantee that it is persistent across restarts of the PIM manager. The contact which previously had index #start now has index #start + count, etc. void ContactsRemoved(object view, int start, array ids) Some contacts were removed from the view. The contact which previous had index #start + count (if there was one) now has index #start, etc. void Quiescent(object view) The current content of the view is complete. No further updates are expected until something changes again (underlying data, ordering, active address books, filter). Changing data (directly or via syncing) can trigger multiple "Quiescent" signals, depending on when these changes are reported by the underlying storage. Changing multiple settings will trigger one "Quiescent" per change. Implementing the Quiescent() method in a ViewAgent is optional.