[Bug 29486] New: API requires clients to hard-code "well-known" string identifiers

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=29486

           Summary: API requires clients to hard-code "well-known" string
                    identifiers
           Product: Telepathy
           Version: git master
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: medium
         Component: tp-qt4
        AssignedTo: telepathy-bugs at lists.freedesktop.org
        ReportedBy: ollisal at gmail.com
         QAContact: telepathy-bugs at lists.freedesktop.org
        Depends on: 29479,29481,29484


Strings with "well-known" values (as, mostly, described by the specification)
are used in Telepathy at the D-Bus level for struct members, method and signal
arguments and keys for "dynamic class"-type mappings in many places where an
enum could otherwise do, but allowing greater flexibility for extensions and
future spec additions. However, it shouldn't be necessary for applications to
hard-code knowledge about these well-known string values in their code when
using tp-qt4!

Some examples, from a quick grep:
 - the SimplePresence status string identifier, exposed in:
Account::setRequestedPresence(), Connection::setSelfPresence() and
Contact::presenceStatus() (bug #29479)
 - Connection parameter names: ConnectionManager::ProtocolParameter::name(),
Account::parameters(), AccountManager::createAccount() (bug #29481)
 - MessagePart, essentially a QVariantMap: Message::part(index) and
Message::parts() (however, Message itself provides some convenience access to
the values for some well-known keys, so I'm not sure if this is actually a
problem case - let's file a bug afterwards if it, indeed, is one)
 - Account::connectionErrorDetails is a bare variant map
 - RequestableChannelClass contains a bare variant map and a string list of
well-known parameter ids:
{Connection,Contact}Capabilities::requestableChannelClasses(), the stuff that's
added in Andre's account filtering branch for bug #29090, our future plans for
filtering contacts by capabilities -> bug #29484
 - Channel request immutable properties, when you're not using the
ensureTextChat() etc methods (similar to the RCC actually, so added as a note
to bug #29484)

Add more when identified, please! (As dependencies if bigger issues).

Variant maps can be represented by something like
Channel::GroupMemberChangeDetails or ContactLocation, with accessors for the
well-known keys. However, I think access to the bare variant map should still
be offered (like GroupMemberChangeDetails::allDetails()) to allow for
extensions, if appropriate.

Wrapper classes could be useful for representing other string + data bunches
besides the "dynamic class" type variant maps, instead of just supplying the
string constants, the classes being more self-documenting (ie. no need to look
up the method documentation for which string constants to use and their
semantics, as this can be self-evident from the class type expected for the
parameter).

Thus, the fixes in general are likely to be of one of the following forms
 - add string constants corresponding to the well-known values (shouldn't the
spec itself, in fact, expose them as constants such that we could auto-generate
them?), and document their usage wherever they might appear
 - add a small class wrapping the string and any associated data akin to
Channel::GroupMemberChangeDetails (might be useful for other string id + data
combinations besides just the variant maps)

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.