Hello!
I've started working on some in-vehicle infotainment (IVI) use cases.
This will combine work done in SyncEvolution, in particular the PBAP
caching, EDS, and libfolks into a building block for an IVI head unit,
the computer which is built into the car.
The building block is meant to be used via an IPC mechanism like D-Bus,
without having to link against glue libraries. Conceptually, the block
is sitting above SyncEvolution and could be implemented separately. The
D-Bus API is defined such that an independent implementation would be
possible. I reserved a D-Bus name space by creating a "PIM" project on
OTC's
01.org site (not live yet).
In practice, the implementation is done as part of SyncEvolution's
syncevo-dbus-server. That simplifies the interaction with SyncEvolution
and avoids having to start and run too many separate processes. Unless
someone has a better idea and place, I'll use the SyncEvolution mailing
list to discuss also this new aspect of SyncEvolution.
I have some partial implementation of the API ready and will push it
shortly to the new SyncEvolution git repo on
freedesktop.org (will
announce that repo separately).
More important than the implementation is the API itself. It would be
good if someone could review it with an eye towards bad D-Bus practices,
usability, documentation, etc. Therefore let me finish the email with a
complete dump of the current API description:
-----------------------------------------------------------------
Preamble
========
This text describes a D-Bus API. It might get copied into XML API definitions
in future revisions.
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.
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, hyphen and colon. No other
assumptions about its content are made. For example, the phone's
Bluetooth MAC address could be used.
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 the following keys:
- "protocol" - defines how to access the address book. Currently
only "PBAP" is implemented. "SyncML", "CardDAV" are
documented
to illustrate how the API would work for them.
- "transport" - defines how to establish
the connection. Currently only "Bluetooth" is allowed
(for protocol=PBAP or SyncML) and taken as default when
"transport" is not set.
- "address" - the Bluetooth MAC address in the aa:bb:cc:dd:ee:ff
format (for transport=Bluetooth)
- "database" - empty or unset for the internal address book
(protocol=PBAP), the URI (protocol=SyncML)
Address books
-------------
Address books which mirror data from a specific peer use the string
"peer-<uid>" as ID, where <uid> 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!)
Property values which are large (like photos) are not sent via
D-Bus. Instead a link to a local file is sent.
TODO: document all properties and their types.
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. To
support requesting data in batches, 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).
- Data for contacts #5 to #19 gets requested, five contacts #5 to #9
are returned. It's okay to ask for more contacts than exist,
because the caller cannot be sure anyway how many contacts
still exist at the time when the request gets processed.
- 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 could be defined
and returned 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.
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 "first/last", "last/first",
"full name".
"first/last" sorts based on the first name stored in the
"name"
property, with the last name used to break ties between equal first
names. "last/first" reverts that comparison. "full name"
sorts based on
the full name chosen for the contact if there is such a string, otherwise
it uses "<last name>" and "<first name>" as sort
strings.
The sort order is stored persistently. The default is "last/first".
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 SetPeer(string uid, dict properties)
Adds or modifies a peer. Modifying a peer does *not* affect
any contact data which might be cached for it.
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(dict 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.
An empty filter matches all contacts. TODO: define other
searches.
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 contact dicts ReadContacts(int start, int count)
Requests at most "count" contacts in the view, starting
with the one at "start" (numbered starting with 1). May
return less (or no) contacts if the request range is
beyond the end of the view at the time when the call is
processed.
Note that the caller must process the call response
after all events via the ViewAgent interface if it wants
to keep in sync with the view. 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(dict 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).
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, int count)
Contacts #start till #start + count (inclusive) have
changed. Data that the recipient of the call might have
cached became invalid and should be reloaded. In cases
where changing a contact changes its position in the
sorted list, "contact removed" and "contact added"
notifications will be triggered instead of a "contact
changed".
void ContactsAdded(object view, int start, int count)
New contacts were added to the view.
The contact which previously had index #start now
has index #start + count, etc.
void ContactsRemoved(object view, int start, int count)
Some contacts were removed from the view.
The contact which previous had index #start + count
(if there was one) now has index #start, etc.
-----------------------------------------------------------------
--
Best Regards, Patrick Ohly
The content of this message is my personal opinion only and although
I am an employee of Intel, the statements I make here in no way
represent Intel's position on the issue, nor am I authorized to speak
on behalf of Intel on this matter.