[Telepathy] The XMPP implementation of Tubes

Simon McVittie simon.mcvittie at collabora.co.uk
Mon Aug 13 09:49:46 PDT 2007

As part of the review process for the telepathy-gabble-tubes branch,
I've been looking at the XMPP protocol we use to implement Telepathy
Tubes. I think it needs documenting, and it also needs some changes - at
the moment it's a bit of an abuse of IBB.

To start with, I'll just document the current protocol. I'll reply to this
mail with criticisms and proposed changes.

                            The Tubes protocol

The draft of the Tubes specification that's implemented in the -tubes
branch can be found at

In this document, NS_SI_TUBES, NS_SI_TUBES_OLD and NS_TUBES mean
"http://jabber.org/protocol/si/profile/tubes" and
"http://telepathy.freedesktop.org/xmpp/tubes" respectively.
The use of NS_SI_TUBES_OLD was a mistake (it's not in a namespace we
control, so we shouldn't use it) - wherever this is used, we need
to change it to NS_SI_TUBES.

Tubes can be used in a 1-1 context (for CONTACT tubes channels) or in a MUC
context (for ROOM tubes channels).

Usage in 1-1 context

Opening the channel

A 1-1 Tubes channel is opened by request, or when a Stream Initiation
request with profile NS_SI_TUBES or NS_SI_TUBES_OLD is received.

Offering a tube

To offer a tube, send a Stream Initiation request with profile
NS_SI_TUBES or NS_SI_TUBES_OLD (currently, the latter is sent). As per
XEP-0095_, the SI request must be sent to a full-JID. The resource
chosen is one that has NS_SI_TUBES or NS_SI_TUBES_OLD advertised as a
capability in its presence.

It's somewhat vague whether we support opening a 1-1 tubes channel with
a MUC contact - there is code to support it, but I don't think we put
capabilities in MUC presence. We should probably rule that it's

We currently support only IBB as a transport.

Accepting a tube

Responding to a tube offer is as usual for SI. Once the other end has
agreed to do IBB, we consider the tube to be open.

Sending and receiving data

The messages are sent as specified by IBB.

In the case of D-Bus tubes, each <message> contains (a) an entire
D-Bus message, and (b) no more than one D-Bus message.

In the case of stream tubes, <message> boundaries are arbitrary.

Usage in MUCs

The <tubes> element with namespace NS_TUBES may be added to MUC presence.
Its children are <tube> elements representing those tubes which, in
the Telepathy Tubes spec, are in state Tube_State_Open. This is everyone's
tubes, not just ones we initiated.

Opening a channel

A Tubes channel is opened on request, or when a <tubes> is seen in MUC

Offering a tube

Put it in your presence.

I still need to investigate how stream tubes work here.

Accepting a tube

No D-Bus tubes are remote-pending or local-pending at any time - the tube is
considered to be already open as soon as it appears in someone's presence,
so no accepting is ever needed.

I still need to investigate how stream tubes work here.

Sending data

The messages are sent in <message>s as specified by IBB (XEP-0047_), except
that the sequence number @seq is meaningless on output, must be ignored
on input, and no <open> or <close> ever occurs.

The <tube> element


    <tube stream-id="stream1" type="dbus" initiator="room at conf.example.com/me"
          service="com.example.TextEditor" offering="true" id="1343"
            <parameter name="filename" type="str">README.txt</parameter>

    stream-id : string
        In SI tubes, the stream ID that will be used when the IBB
        stream is eventually opened. In MUC tubes, an arbitrary string
        which is repeated on the pseudo-IBB messages.
    type : "stream" or "dbus"
        Required. The type of tube.
    initiator : MUC member JID (MUC) / bare JID (SI)
        Required. The initiator of the tube.
    service : D-Bus well-known name
        Required. The D-Bus service name.
    offering : "true" or "false"
        In SI context, OfferTube maps to offering="true". I'm not quite
        sure how it can ever have offering="false" or why this is

        In MUC context, omitted.
    id : decimal in range 0 to (2**31)-1
        The per-channel stream ID. Generated randomly in an attempt to
        avoid collisions.
    dbus-name : D-Bus unique name
        Required for D-Bus tubes. The unique name the contact whose
        announcement this is will use in the tube.

        Tube parameters. Children are named "parameter" and have attributes
        "name" (user-specified) and "type" ("str", "bytes", "int" or "uint").
        Character content is UTF-8 (str), Base64 (bytes), ASCII decimal
        (int, uint).

        .. Note:: FIXME
            This encoding can't support ASCII control codes in UTF-8
            strings, because XML can't. Do we care?

        .. Note:: Proposed change:
            Children are either named after either basic D-Bus types, or 'ay'.
            For example::

                    <s name="foo">Hello, world!</s>
                    <ay name="icon">Base64Base64Base64</ay>
                    <d name="quality">1.0</d>

        .. Note:: Alternative:
            The <parameters> element has character content, which is the
            D-Bus serialization of the a{sv} in Base64. The encoding can be
            obtained with libdbus by marshalling a dummy message containing
            the a{sv}, then taking the body part of the message by doing
            trivial parsing.

.. _XEP-0047: http://www.xmpp.org/extensions/xep-0047.html
.. _XEP-0095: http://www.xmpp.org/extensions/xep-0095.html

.. vim:set sw=4 sts=4 et ft=rst:

More information about the Telepathy mailing list