[Telepathy] Spec discussion notes: advertising running applications, listing calls you could join

[Will Thompson]

== Connection.Interface.Applications; Channel.Interface.Application ==

Tomeu's been working on standardizing some Sugar-specific functionality
to allow the user to see what their contacts are up to (in particular,
what kind of collaborative tasks they're working on using Tubes).
Sjoerd, Simon, he and myself discussed it a bit.

spec branch: http://git.collabora.co.uk/?p=user/tomeu/telepathy-spec.git;a=shortlog;h=refs/heads/application-presence
HTML: http://people.collabora.co.uk/~tomeu/telepathy-spec-application_presence/spec/

=== Minor comments ===

Should probably have a token to use with Connection.Interface.Contacts.

Remove the unneeded String_String_Map re-definition from
Channel.Interface.Application

The method should be AdvertiseApplication (rather than Advertise, which
is too generic). And, Sjoerd thinks the ”Application” moniker is
sub-ideal.)

=== Representation of applications ===

Applications should be represented as an a{sv}, not an (suss), matching
channel properties. So Contact_Application_Map would become a{uaa{sv}}.

  { ChannelType: DBusTube,
    ...,
    Channel.Type.DBusTube.ServiceName: 'org.gnome.AbiWord',
  }

Maybe we want a human-readable name for each application as well? So
that my UI can say “Rob is editing Confidential_Report.odt” even if I
don't have a tube-enabled AbiWord installed. So perhaps applications
should be represented by two a{sv}s: one the set of immutable properties
that you could feed to EnsureChannel to get a channel for that
application (namely, immutable and requestable properties for the
channel), the other a bunch of other metadata about the application
(like the document name) to show to the user. So in fact
Contact_Application_Map would become a{ua(a{sv}a{sv})} — mapping handles
to lists of (properties to feed to EnsureChannel, extra metadata)
tuples.

Having three <code>a{sv}</code>s — one for channel properties, one for
application metadata, one for tube parameters — seemed like a lot to
Will, but he was convinced that it's okay: you never really want to pass
stuff to Offer() anyway. And separating the stuff that you pass to
EnsureChannel() to get involved in the activity from the stuff
describing the activity is good. (Maybe you want to include a screenshot
in the metadata, for instance.)

Simon wonders whether, rather than using a struct ( a{sv}: stuff you
should pass to EnsureChannel, a{sv}: Metadata ), we should just use an
a{sv} of metadata with a key whose value is the stuff you should pass to
EnsureChannel. A tad easier to work with with dbus-glib, but others
reckoned it would be more opaque maybe, and having it be a struct means
apps don't have to deal with it being missing.

Application-specific metadata seems like a good way to go. This allows
each application to deal with the question of “what does it mean to be
the same activity?” in its own way: perhaps the document name, perhaps
some uuid, whatever. On Sugar, this is done by just generating a UUID
for the room name; this breaks down if two different groups of people
  are editing two separate documents in the XMPP MUC
  devel at conference.telepathy.im (which is impossible with the Sugar UI
  but is a reasonably likely situation in a desktop UI).

If an application uses >1 channel for a single activity, it could either
use the metadata dictionary to tie them together, or just Advertise()
one of the channels (if you have 1 control channel and a bunch of data
channels, just advertise the first one).

Do we want to have a well-known metadata key for some kind of
human-readable thing that you can show to the user to say “hey this guy
is playing chess but you don't have chess installed”? But this has
localization issues. An alternative is to hook up the (e.g.) D-Bus tube
service name to PackageKit so your information on a contact could have a
"three other application..." thing which you click and it offers you a
list of apps you could install to get involved. This seems more useful
than “Rob's playing Chess. You can't.”. So we don't need any extra
machinery for this.

But we do want a normal channel property for the subject anyway? And
then we can re-use it on MUCs and be happy.

So perhaps the keys of the metadata should be namespaced, so that they
can include mutable channel properties, unioned with
application-specific keys, so that if there *is* a standard Telepathy
property for a metadatum (is that a word?) it can be exposed with that
name.

In conclusion, we think a Contact_Application_Map dict might look
something like this (for a handle <code>42</code>):

  { 42: [ ( { 'o.fd.T.Channel.ChannelType': 'o.fd.T.C.Type.DBusTube',
              'o.fd.T.Channel.TargetHandleType': Room,
              'o.fd.T.Channel.TargetID': 'devel at conference.telepathy.im',
              'o.fd.T.C.T.DBusTube.ServiceName': 'org.gnome.abiword',
            },
            {
              # standard channel properties which shouldn't be included
              # in the channel request but which provide useful
              # information:
              # (Subject's non-standard, but it should be standard.)
              'o.fd.T.Channel.Subject': 'Hypothetical spec extension',

              # Also application-specific properties:
              'org.gnome.abiword.DocumentID': '0xDEADBEEF',
            }
          ),
          ...
        ],
  }

The above would have been advertised by calling methods on the tube
channel:

  # To set the subject, hypothetical API
  org.fd.DBus.Properties.Set('org.fd.T.Channel', 'Subject',
                             'Hypothetical spec extension')
  # And for application-specific metadata:
  AdvertiseApplication( { 'org.gnome.abiword.DocumentID': '0xDEADBEEF' })

== Other similar issues that need solving ===

Consider:

* I'm invited to a Muji call in foo at conf.bar
* I join, and join the call
* I leave the ''call'' but stay in the ''MUC''

How do we represent that there's a call going on?

Simon suggests: maybe we could represent them as applications with
contact handle 0:

  { 0:  [ ({ 'o.fd.T.Channel.ChannelType': 'o.fd.T.C.Type.Call',
             'o.fd.T.Channel.TargetHandleType': Room,
             'o.fd.T.Channel.TargetID': 'foo at conf.bar',
           },
           { 'o.fd.T.Channel.I.Group.Members': [42, 57, ...],
           }
          )
        ],
    42: [ ... ],
  }

or we could change the type entirely, to a(a{sv}a{sv}) — using an alist
not a dict because we can't use dicts as dict keys:

  [
    ( { 'o.fd.T.Channel.ChannelType': 'o.fd.T.C.Type.DBusTube',
        'o.fd.T.Channel.TargetHandleType': Room,
        'o.fd.T.Channel.TargetID': 'devel at conference.telepathy.im',
        'o.fd.T.C.T.DBusTube.ServiceName': 'org.gnome.abiword',
      },
      { 'org.fd.Telepathy.Channel.Interface.Group.Members':
          [ 42, 45, my cat, ... ]
        # what do we do if different people say different subjects?
        # impl detail
        'o.fd.T.Channel.Subject': 'Hypothetical spec extension',
        'org.gnome.abiword.DocumentID': '0xDEADBEEF',
      }
    )
  ]

This would let us express the calls that are going on in an XMPP MUC you
happen to be in (and also to represent tubes in a MUC that you happen to
be in) even if you aren't auto-invited, or if you were, but you left the
call.

It also neatly solves the problem of trying to tell who's in the same
application session... although it does actually mean Gabble has to know
somehow. And it makes the API a bit harder to use for the “what is John
doing?” case.

A bunch of different use-cases:

* What is Simon doing?
* How can I know that there's a call going on in the MUC that I happen
  to be in?
* Show me all the documents my friends are editing.
** Sugar-style one activity per person based on focus
** elsewhere-style multitasking: everyone's "doing" everything they have
   running
*** could we express the former as a well-known metadata key Focused:
    True?
*** simon thinks we could!
*** metadata churn: republish the entire dict every time.
*** should the interface show updates as a diff?

Left this as something to ponder.

-- 
Will