Bug 29486 - API requires clients to hard-code "well-known" string identifiers
Summary: API requires clients to hard-code "well-known" string identifiers
Status: RESOLVED FIXED
Alias: None
Product: Telepathy
Classification: Unclassified
Component: tp-qt (show other bugs)
Version: git master
Hardware: All All
: medium normal
Assignee: Telepathy bugs list
QA Contact: Telepathy bugs list
URL:
Whiteboard:
Keywords:
Depends on: 29479 29481 29484
Blocks:
  Show dependency treegraph
 
Reported: 2010-08-10 08:19 UTC by Olli Salli
Modified: 2010-11-05 01:00 UTC (History)
0 users

See Also:
i915 platform:
i915 features:


Attachments

Description Olli Salli 2010-08-10 08:19:30 UTC
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)
Comment 1 Olli Salli 2010-11-05 01:00:23 UTC
Fixed for the parts in which we found it to make sense to do so in 0.3.13/0.3.14/0.5.0.


Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.