Tp-Qt4 does application-level RAII-powered reference counting on handles, so that the application doesn't have to care about the D-Bus level semantics of HoldHandles/ReleaseHandles. In an initial frenzy of trying to enforce batching of the D-Bus level operations as much as possible, I designed the API as a container of handles. While it is extremely useful to store a single handle in isolation (eg. the handle of a single Contact), this can only be represented as a ReferencedHandles container with size one.
However, it turned out that trying to keep big bunches of ReferencedHandles together wasn't really very practical, and that implementing batch combining logic was sufficiently easy, so in the end, all handles are actually released one-by-one by ReferencedHandles, and the Connection takes care to form a efficient batch of them (actually all handles which lost their references in any container in a given Qt mainloop iteration). This obviously means the API could be ReferencedHandle instead, and plural operations could simply be QList<ReferencedHandle>.
This is obviously an API/ABI break, so we shouldn't consider doing it until 1.0. Some points to consider then, though:
* ReferencedHandles currently also makes sure that all handles within are from the same actual Connection - should we preserve it as a thin means to this end alone?
* Should handles actually be made immortal on the D-Bus level (bug #23155)
- ... or should we <shock> actually just use normalized ID strings (but still with CM-level normalization) wherever we currently use handles (the TargetID, etc, additions from a few spec major versions ago are already half-way there anyway)
We're going to have an API/ABI break really soon now, so let's target this for inclusion too.
The handle concept is low-level enough to make this not much of a problem; we can always wrap handle APIs with overloads taking ContactPtrs and/or IDs to make using handles even more easier (because tp-qt4 does it for you!).