[Development] More feedback for the Contacts API of the QtPim module

[Friedrich W. H. Kossebau]

Hi,

seems the former Qt Mobility Contacts module is going to be (part of) a normal 
Qt module for version 5, so here is some more feedback from the developers of 
the backend for Qt Mobility Contacts on the N9, the qtcontacts-tracker engine 
[qct]. (You might not have heard of it that much because, hey, we made it just 
stay out of the way and simply work ;) )
[qct] https://gitorious.org/qtcontacts-tracker/qtcontacts-tracker

My co-worker Mathias from Openismus already once gave some short initial 
feedback, e.g. in http://lists.qt-project.org/pipermail/development/2011-
November/000216.html, but that was just a very short comment, while there is 
lots more to say, the scrollbar already tells :)

I have not yet an overview who works on QtPim and where and how, so for a 
start I just dump here the feedback as it is on our mind for now, so we can 
see where to push which part of it, please give us the proper hints.


== The biggest issue: ignoring the shared nature of the db

The API does not honour the fact that the database (as in: storage) can be 
shared and be accessed by different processes at the same time (and this might 
even be the common case).
This issue might be true for some other parts of the QtPim module as well, 
have not checked.

No transactions__:
A client of the API has no way to do transaction-style operations, like 
fetching data, modifying it and storing it again, without having to be afraid 
that some other process could interfere in-between. Chances might be small, 
but still. Unnecessary risk. And Murphy will tell you it will be important 
data you lose.

Change signals don't include info about origin__:
Signals about changes in the contact database do not tell who made the 
modification. So if some client code modifies a contact, when getting a change 
signal with the id of that contact the client code cannot be sure it was it 
who modified that contact and, to have it up-to-date, has to reload it again in 
any case.
Still the current API asks the engine implementation to update the QContact 
object on saving to the current state in the database in any case (which in 
case of masked saving might even involve fetching data from the database to 
check the correctness of the displaylabel). Which is quite useless then, at 
least for the use-cases I can think of.

Conflicts possible on data schema modifications__:
If the engine allows to change the detail definitions, at least in theory and 
by the API every client code can currently do whatever it wants. There is 
nothing preventing conflicts, e.g. no namespacing enforced/pushed for with 
identifiers of additional details or fields or if one process removes some 
detail which another one instead adds a field.
Also is it not obvious if such schema modifications would be permanent.
And it is unclear what to do with data stored on removing some details/fields 
from the schema.

IMHO QtPim should not yet become a normal Qt module, I think this all is a 
really big flaw and should be improved/fixed.
Qt5 API is to stay for some years, no? Would be a shame to have such a broken, 
data loss prone API.

== Smaller issues:

Engine features description not fine-grained enough__:
There is the flag set QContactManager::ManagerFeature [qcmf], but it is too 
coarse. E.g. the tracker database has a selfcontact from the start, which can 
neither be removed, nor can be set to have another id. But there is just the 
flag QContactManager::SelfContact, saying "The manager supports the concept of 
saving a contact which represents the current user".
This feature flag set needs to be changed to something else, perhaps some tree-
structured settings, so engine implementations can define their features to be 
as detailed as possible/needed.
[qcmf] http://doc.qt.nokia.com/qt5/qcontactmanager.html#ManagerFeature-enum

Mutability of detail definition cannot be queried__:
QContactManager::MutableDefinitions just has: "Some built-in definitions may 
still be immutable". [qcmf] But QContactDetailDefinition [qcdd] misses a 
property to query if that definition is mutable, so the client can just go for 
trial-and-error.
[qcmf] http://doc.qt.nokia.com/qt5/qcontactmanager.html#ManagerFeature-enum
[qcdd] http://doc.qt.nokia.com/qt5/qcontactdetaildefinition.html

Detail and Field identifier strings not pure shared .text data__:
There have been some efforts with that QLatin1Constant construct to reduce the 
memory footprint. But in the whole Qt Contacts code/API there are lots of 
places where still conversion to QString incl. copying the data onto each 
process' heap happens again and again, as e.g. QVariantMap is used internally 
by QContactDetail or most API uses QString for the identifier strings.
At least for predefined details it should be considered to use e.g. 
QString::fromRawData(...) or have a look at what Thiago & Co. are cooking with 
the QStringLiteral [QSL].
[QSL] http://www.macieira.org/blog/2011/07/qstring-improved/

Strange QContactChangeLogFilter::EventRemoved__:
To claim that your engine has the feature QContactManager::ChangeLogs ("The 
manager supports reporting of timestamps of changes, and filtering and sorting 
by those timestamps") [qcmf] the engine has to support the filter 
QContactChangeLogFilter, with some QContactChangeLogFilter::EventRemoved that 
shall obviously be used to filter contacts that have been deleted. I have not 
seen any engine which supports that, and cannot imagine a real use case.
[qcmf] http://doc.qt.nokia.com/qt5/qcontactmanager.html#ManagerFeature-enum
[qccf] http://doc.qt.nokia.com/qt5/qcontactchangelogfilter.html#EventType-enum

Missing QContactNotFilter__:
There are special QContactIntersectionFilter and QContactUnionFilter 
subclasses of QContactFilter [qcf] to create more complex filter expressions, 
but a "not" filter is missing. So no way to e.g. ask for "all contacts but not 
the self contact" or "all contacts but those from mfe"
[qcf] http://doc.qt.nokia.com/qt5/qcontactfilter.html


Please also consider dealing with all the open bugs on Qt Mobility Contacts 
and the merge requests [qtmmr], during our work on qtcontacts-tracker most of 
the issues which have been found never got sufficient reaction (due to too few 
resources, too many team changes at Qt Mobility). Would be too bad if that 
work/feedback would be lost for ever. :)
[qtmmr] https://qt.gitorious.org/qt-mobility/qt-mobility/merge_requests

Cheers
Friedrich
-- 
Friedrich W. H. Kossebau  --  Openismus GmbH  --  www.openismus.com