XEP-proto-tubes: Tubes over XMPP

A protocol for extensible collaboration over XMPP, designed specifically to implement Telepathy Tubes.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Document Information

Series: XEP
Number: proto-tubes
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: External extension
Version: 0.0.1
Last Updated: 2007-09-07
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0045, XEP-0047, XEP-0095, XEP-proto-muc-bytestream
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED

Author Information

Simon McVittie

Email: simon.mcvittie@collabora.co.uk
JabberID: simon.mcvittie@collabora.co.uk

Legal Notice

This document is copyright 2007 Collabora Ltd. and may be distributed under the same terms as the Telepathy specification.

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.


Table of Contents


1. Introduction
2. Requirements
3. Use Cases
    3.1. In a multi-user chat
    3.2. Peer to peer
    3.3. In a link-local multi-user chat
4. Business Rules
    4.1. D-Bus unique names in a MUC context
    4.2. D-Bus unique names in a link-local MUC context
    4.3. Definition of the tubes SI profile
    4.4. Parameter types
    4.5. TODO
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
8. XML Schema
9. Appendix: test data for D-Bus unique name algorithm
Notes
Revision History


1. Introduction

The XML namespace defined here is http://telepathy.freedesktop.org/xmpp/tubes (NS_TUBES in the telepathy-gabble source code).

2. Requirements

The Telepathy project defines an API called Tubes to be used by arbitrary collaborative applications to communicate with instant messaging contacts. This API is intended to be the same for several IM protocols.

Tubes can be used in two types of context, referred to in Telepathy as Tubes channels:

Each tube has a service name, used to dispatch it to an appropriate client application, and some essentially arbitrary parameters understood by that client application. The tube's initiator (the contact who started it) must also be tracked.

The following tube types are currently supported:

As well as sending and receiving data, the following operations are supported:

3. Use Cases

3.1 In a multi-user chat

Example 1. Offering a new D-Bus tube

      
      <!-- The first witch offers a D-Bus tube to the service
      lit.macbeth.BubblingCauldron.

      The tube parameters provided via the Telepathy API are (in dbus-python
      notation):

      {
        's': 'hello',                     # string
        'ay': dbus.ByteArray('hello'),    # byte-array
        'u': dbus.UInt32(123),            # unsigned Int32
        'i': dbus.Int32(-123),            # signed Int32
      }

      See below for how the dbus-name is generated.
      -->
      <presence to='darkcave@conf.macbeth.lit'
          from='darkcave@conf.macbeth.lit/FirstWitch'>
        <x xmlns='http://jabber.org/protocol/muc'>
        </x>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='darkcave@conf.macbeth.lit/FirstWitch'
            service='lit.macbeth.BubblingCauldron' stream-id='12345'
            id='54321' dbus-name=':2.Rmlyc3RXaXRjaAAA'>
            <parameters>
              <parameter name='s' type='str'>hello</parameter>
              <parameter name='ay' type='bytes'>aGVsbG8=</parameter>
              <parameter name='u' type='uint'>123</parameter>
              <parameter name='i' type='int'>-123</parameter>
            </parameters>
          </tube>
        </tubes>
      </presence>
      
    

Example 2. Accepting (joining) a D-Bus tube

      
      <!-- The second witch accepts the tube by copying it into her own
      MUC presence, changing the dbus-name to an arbitrary value
      that nobody else is using. -->
      <presence to='darkcave@conf.macbeth.lit'
          from='darkcave@conf.macbeth.lit/Second witch'>
        <x xmlns='http://jabber.org/protocol/muc'>
        </x>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='darkcave@conf.macbeth.lit/FirstWitch'
            service='lit.macbeth.BubblingCauldron' stream-id='12345'
            id='54321' dbus-name=':2.U2Vjb25kIHdpdGNo'>
            <parameters>
              <parameter name='s' type='str'>hello</parameter>
              <parameter name='ay' type='bytes'>aGVsbG8=</parameter>
              <parameter name='u' type='uint'>123</parameter>
              <parameter name='i' type='int'>-123</parameter>
            </parameters>
          </tube>
        </tubes>
      </presence>
      
    

Example 3. Sending data in a MUC D-Bus tube

      
      <!-- The second witch sends a D-Bus signal to everyone.
      MUC D-Bus tubes always use MUC Bytestreams (XEP-proto-muc-bytestream).

      Messages can also go to a particular participant (for method calls and
      replies), and can be split up if too big - see the MUC Bytestreams
      document for details.

      In the serialized D-Bus message, the sender field will be
      ":2.U2Vjb25kIHdpdGNo". If the message was being sent to the first witch only
      rather than to all participants, its destination field would be
      ":2.Rmlyc3RXaXRjaAAA".

      The 'sid' here is the same as the 'stream-id' in the <tube> announcement.
      -->
      <message to='darkcave@conf.macbeth.lit'
          from='darkcave@conf.macbeth.lit/Second witch'>
          <data xmlns='http://telepathy.freedesktop.org/xmpp/protocol/muc-bytestreams'
            sid="12345">base64base64...</data>
      </message>
      
    

Example 4. Offering a new stream tube

      
      <!-- The second witch also offers a stream tube to her WebDAV server. -->
      <presence to='darkcave@conf.macbeth.lit'
          from='darkcave@conf.macbeth.lit/Second witch'>
        <x xmlns='http://jabber.org/protocol/muc'>
        </x>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <!-- This D-Bus tube is still here from the first example -
            it's not part of the stream tube -->
          <tube type='dbus' initiator='darkcave@conf.macbeth.lit/FirstWitch'
            service='lit.macbeth.BubblingCauldron' stream-id='12345'
            id='54321' dbus-name=':2.U2Vjb25kIHdpdGNo'>
            <parameters>
              <parameter name='s' type='str'>hello</parameter>
              <parameter name='ay' type='bytes'>aGVsbG8=</parameter>
              <parameter name='u' type='uint'>123</parameter>
              <parameter name='i' type='int'>-123</parameter>
            </parameters>
          </tube>

          <!-- This is the new stream tube. There is no initiator attribute
          because the initiator is implicitly the participant whose presence
          it's seen in -->
          <tube type='stream' service='webdav' id='666'>
            <parameters>
              <parameter name='u' type='str'>anonymous</parameter>
              <parameter name='p' type='str'>password</parameter>
              <parameter name='path' type='str'>/plots/macbeth</parameter>
            </parameters>
          </tube>
        </tubes>
      </presence>
      
    

Example 5. Accepting (joining) a stream tube

      
      <!-- The first witch makes a connection to the second witch to
      open the stream. Data transfer proceeds as usual according to
      Stream Initiation - in this case, they'll use IBB.

      The child element is <muc-stream> and not <stream> in order to
      disambiguate between SI-based streams in a MUC Tubes channel, and
      SI-based streams in a 1-1 channel between two members of a MUC.

      The first witch MUST NOT copy the tube into her own presence
      in this case - only the initiator should put stream tubes in their
      presence, since stream tubes cannot continue after the initiator leaves.
      -->
      <iq from='darkcave@conf.macbeth.lit/FirstWitch'
          to='darkcave@conf.macbeth.lit/Second witch' type='set'>
        <si xmlns='http://jabber.org/protocol/si' id='55555'
          profile='http://telepathy.freedesktop.org/xmpp/tubes'>
          <muc-stream
            xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
            tube='666' />
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns="jabber:x:data" type="form">
              <field var='stream-method' type='list-single'>
                <option>
                  <value>http://jabber.org/protocol/ibb</value>
                </option>
              </field>
            </x>
          </feature>
        </si>
      </iq>

      <!-- The second witch acknowledges the IQ and data transfer proceeds
      using stream ID 55555 (not shown here, but it's the same as for normal
      IBB-over-SI). -->
      
    

Example 6. Leaving a tube explicitly

      
      <!-- The second witch stops offering the stream tube.
      She SHOULD close the stream first, if possible - assume this has
      already been done. -->
      <presence to='darkcave@conf.macbeth.lit'
          from='darkcave@conf.macbeth.lit/Second witch'>
        <x xmlns='http://jabber.org/protocol/muc'>
        </x>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='darkcave@conf.macbeth.lit/FirstWitch'
            service='lit.macbeth.BubblingCauldron' stream-id='12345'
            id='54321' dbus-name=':2.Rmlyc3RXaXRjaAAA'>
            <parameters>
              <parameter name='s' type='str'>hello</parameter>
              <parameter name='ay' type='bytes'>aGVsbG8=</parameter>
              <parameter name='u' type='uint'>123</parameter>
              <parameter name='i' type='int'>-123</parameter>
            </parameters>
          </tube>
        </tubes>
      </presence>
      
    

Leaving the MUC also implicitly implies leaving all tubes.

3.2 Peer to peer

Example 7. Offering a new D-Bus tube

      
      <!-- Romeo offers Tybalt a D-Bus tube to the (hypothetical) service
      com.example.Chess.

      The tube parameters provided via the Telepathy API are (in dbus-python
      notation):

      {
        'theme': 'montagues-vs-capulets.conf'   # string
      }
      -->
      <iq to='tybalt@capulet.lit/Work'
          from='romeo@montague.lit/Home' type='set'>
        <si xmlns='http://jabber.org/protocol/si' id='chess-stream-1'
            profile='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
              type='dbus' service='com.example.Chess' id='333'>
            <parameters>
              <parameter name='theme'
                type='str'>montagues-vs-capulets.conf</parameter>
            </parameters>
          </tube>
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns="jabber:x:data" type="form">
              <field var='stream-method' type='list-single'>
                <option>
                  <value>http://jabber.org/protocol/ibb</value>
                </option>
              </field>
            </x>
          </feature>
        </si>
      </iq>
      
    

Example 8. Accepting (joining) a D-Bus tube

      
      <!-- Tybalt accepts the tube by accepting the SI -->
      <iq to='romeo@montague.lit/Home'
          from='tybalt@capulet.lit/Work' type='result'>
        <si xmlns='http://jabber.org/protocol/si'>
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns='jabber:x:data' type='submit'>
              <field var='stream=method'>
                <value>http://jabber.org/protocol/ibb</value>
              </field>
            </x>
          </feature>
        </si>
      </iq>

      <!-- Messages are now sent using whatever stream protocol was
      negotiated, in this case IBB. Implementations MUST NOT assume that
      message boundaries are preserved. Implementations MAY preserve message
      boundaries.
      -->
      
    

Example 9. Offering a new stream tube

      
      <!-- Romeo offers Juliet a D-Bus tube to a private web server

      The tube parameters provided via the Telepathy API are (in dbus-python
      notation):

      {
        'path': '/poetry/for-juliet/'   # string
      }
      -->
      <message to='juliet@capulet.lit/Balcony'
          from='romeo@montague.lit/Home'>
        <tube xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
            type='stream' service='http' id='1402'>
          <parameters>
            <parameter name='path' type='str'>/poetry/for-juliet/</parameter>
          </parameters>
        </tube>
      </message>
      
    

Example 10. Accepting (joining) a stream tube

      
      <!-- Juliet's web browser connects to Juliet's XMPP implementation,
      causing a stream to be opened -->
      <iq to='romeo@montague.lit/Home'
          from='juliet@capulet.lit/Balcony' type='set'>
        <si xmlns='http://jabber.org/protocol/si' id='http-stream-1a'
            profile='http://telepathy.freedesktop.org/xmpp/tubes'>
          <stream xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
            tube='1402'/>
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns="jabber:x:data" type="form">
              <field var='stream-method' type='list-single'>
                <option>
                  <value>http://jabber.org/protocol/ibb</value>
                </option>
              </field>
            </x>
          </feature>
        </si>
      </iq>
      <!-- Romeo's XMPP implementation accepts the incoming connection
      and routes it to his web server -->
      <iq to='juliet@capulet.lit/Balcony'
          from='romeo@montague.lit/Home' type='result'>
          <si xmlns='http://jabber.org/protocol/si'>
            <feature xmlns='http://jabber.org/protocol/feature-neg'>
              <x xmlns='jabber:x:data' type='submit'>
                <field var='stream=method'>
                  <value>http://jabber.org/protocol/ibb</value>
                </field>
              </x>
            </feature>
        </si>
      </iq>

      <!-- Messages are now sent using whatever stream protocol was
      negotiated, in this case IBB. -->
      
    

If Juliet's web browser opens multiple parallel connections to her XMPP implementation, the implementation will open multiple parallel SI streams as shown above, and Romeo's XMPP implementation will open multiple parallel connections to his web server. This MUST be supported by implementations.

Example 11. Leaving a tube (initiator)

      
      <!-- Romeo stops offering the stream tube.
      He SHOULD close all streams first. If not, Juliet SHOULD
      close all streams when this message is received. -->
      <message to='juliet@capulet.lit/Balcony'
          from='romeo@montague.lit/Home'>
        <close xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
          tube='1402'/>
      </message>
      
    

Example 12. Leaving a tube (non-initiator)

      
      <!-- Alternatively, Juliet could reject the stream tube.
      She SHOULD close all streams first. If not, Romeo SHOULD close all
      streams in response to this message. -->
      <message from='juliet@capulet.lit/Balcony'
          to='romeo@montague.lit/Home'>
        <close xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
          tube='1402'/>
      </message>
      
    

3.3 In a link-local multi-user chat

Example 13. Offering a new D-Bus tube

      
      <!-- Suppose Mercutio and Tybalt are in a link-local chatroom,
      with their mDNS presence records being
      mercutio@mab._presence._tcp.local. and
      Tybalt@feline._presence._tcp.local.

      Mercutio offers a D-Bus tube to the service lit.verona.Duel.

      This time one Tube parameter was provided by the Telepathy API,
      a string called 'weapon' with value "swords".

      See below for how the dbus-name is generated.
      -->
      <!-- Sent by mercutio@mab -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.verona.Duel' stream-id='8'
            id='54321' dbus-name=':2.bWVyY3V0aW9AbWFi'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>
        </tubes>
      </message>
      
    

Example 14. Accepting (joining) a D-Bus tube

      
      <!-- Tybalt joins the D-Bus tube, changing the dbus-name appropriately.
      In the implementation of Tubes on link-local MUC he may also have a
      different stream-id. -->
      <!-- Sent by Tybalt@feline -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.macbeth.BubblingCauldron' stream-id='6'
            id='54321' dbus-name=':2.VHliYWx0QGZlbGluZQAA'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>
        </tubes>
      </message>
      
    

Example 15. Sending data in a link-local MUC D-Bus tube

      
      <!-- Tybalt sends a D-Bus message and Mercutio responds.

      Link-local MUC D-Bus tubes always use the rMulticast streams 1 to 255;
      in this case, because Tybalt has stream-id='6' in his announcement
      message, all messages from Tybalt in stream 6 MUST be interpreted as
      part of tube 54321. Similarly, all messages from Mercutio in stream 8
      MUST be interpreted as part of tube 54321. Messages from Tybalt in
      stream 8 are NOT part of tube 54321.
      -->
      <!-- (a binary rMulticast message is sent by Tybalt with stream ID 6;
      its payload is a raw D-Bus message) -->
      <!-- (a binary rMulticast message is sent by Mercutio with stream ID 8;
      its payload is also a raw D-Bus message) -->
      
    

Example 16. Joining and being notified about link-local MUC tubes

      
      <!-- An rMulticast join event occurs, in which Romeo and Benvolio
      join the chatroom. Their mDNS presence records are:

      romeo@angstbook._presence._tcp.local.
      benvolio@peacemaker._presence._tcp.local.

      Mercutio and Tybalt must both respond by re-sending
      their tube announcements to the chatroom, once. They SHOULD NOT
      send their tube announcements twice when two participants join
      in a single join event. -->

      <!-- rMulticast protocol indicates that romeo@angstbook and
      benvolio@peacemaker have joined the room -->

      <!-- Sent by mercutio@mab -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.verona.Duel' stream-id='8'
            id='54321' dbus-name=':2.bWVyY3V0aW9AbWFi'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>
        </tubes>
      </message>

      <!-- Sent by Tybalt@feline -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.verona.Duel' stream-id='6'
            id='54321' dbus-name=':2.VHliYWx0QGZlbGluZQAA'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>
        </tubes>
      </message>
      
    

Example 17. Offering a new stream tube

      
      <!-- Mercutio offers a stream tube to his WebDAV server. This message
      would also be re-sent if another rMulticast join event occurred. -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <!-- This D-Bus tube is still here from the first example -
            it's not part of the stream tube -->
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.verona.Duel' stream-id='8'
            id='54321' dbus-name=':2.bWVyY3V0aW9AbWFi'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>

          <!-- This is the new stream tube. There is no initiator attribute
          because the initiator is implicitly the participant whose message
          it's seen in -->
          <tube type='stream' service='webdav' id='666'>
            <parameters>
              <parameter name='path' type='str'>/warez</parameter>
            </parameters>
          </tube>
        </tubes>
      </presence>
      
    

Example 18. Accepting (joining) a stream tube

      
      <!-- Romeo joins the stream tube to download some MP3s from
      Mercutio's server.

      The child element is, again, <muc-stream> and not <stream>.

      Romeo MUST NOT copy the tube into his own tube announcements
      in this case - only the initiator should announce stream tubes,
      since stream tubes cannot continue after the initiator leaves.
      -->
      <!-- Sent by romeo@angstbook -->
      <iq to='mercutio@mab' type='set'>
        <si xmlns='http://jabber.org/protocol/si' id='55555'
          profile='http://telepathy.freedesktop.org/xmpp/tubes'>
          <muc-stream
            xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
            tube='666' />
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns="jabber:x:data" type="form">
              <field var='stream-method' type='list-single'>
                <option>
                  <value>jabber:iq:oob</value>
                </option>
              </field>
            </x>
          </feature>
        </si>
      </iq>

      <!-- Sent by mercutio@mab -->
      <iq to='romeo@angstbook' type='result'>
        <si xmlns='http://jabber.org/protocol/si' id='55555'
          profile='http://telepathy.freedesktop.org/xmpp/tubes'>
          <muc-stream xmlns='http://telepathy.freedesktop.org/xmpp/tubes'
            tube='666'/>
          <feature xmlns='http://jabber.org/protocol/feature-neg'>
            <x xmlns='jabber:x:data' type='submit'>
              <field var='stream-method'>
                <value>jabber:iq:oob</value>
              </field>
            </x>
          </feature>
        </si>
      </iq>

      <!-- Sent by romeo@angstbook -->
      <iq to='mercutio@mab' type='set'>
        <query xmlns='jabber:iq:oob' sid='55555'>
          <url>x-tcp://angstbook.local:1234</url>
        </query>
      </iq>

      <!-- Mercutio resolves the IP address of angstbook.local and connects
      to port 1234, and out-of-band transfer proceeds -->

      <!-- FIXME: this has too many steps and it ends up with a TCP
      connection flowing "the wrong way" -->
      
    

Example 19. Leaving a tube explicitly

      
      <!-- Mercutio stops offering the stream tube.
      He SHOULD close the OOB stream first, if possible - assume this has
      already been done. -->
      <message type='groupchat'>
        <tubes xmlns='http://telepathy.freedesktop.org/xmpp/tubes'>
          <!-- This D-Bus tube is still here from the first example -
            it's now the only one, because the stream tube has been
            removed -->
          <tube type='dbus' initiator='mercutio@mab'
            service='lit.verona.Duel' stream-id='8'
            id='54321' dbus-name=':2.bWVyY3V0aW9AbWFi'>
            <parameters>
              <parameter name='weapon' type='str'>swords</parameter>
            </parameters>
          </tube>
        </tubes>
      </message>
      
    

Leaving the link-local MUC (a leave or split event from rMulticast) also implicitly implies leaving all tubes.

4. Business Rules

4.1 D-Bus unique names in a MUC context

The D-Bus unique names used in the MUC SHOULD be ":2." followed by the MUC nick (i.e. the resource part of the MUC JID) processed with the following algorithm:

This produces collision-free unique names of length no more than 251 octets (4/3 * 186 + 3) for nicknames no longer than 186 UTF-8 octets (replacing "=" with "A" is harmless here because XMPP resources cannot contain U+0000).

For longer nicknames it makes collisions highly unlikely, and produces 255-octet unique names (4/3 * 189 + 3), which still fit into D-Bus' 255-octet limit.

The choice of 186 and 169 for the magic numbers ensures that these long nicknames can only have unique-name collisions with other long nicknames, and that the Base64 encoding step when applied to long nicknames does not leave any trailing "=" characters.

Implementations MUST NOT use unique names that start with ":2." but are not formed according to the above rules, and SHOULD treat tube elements containing such a dbus-name as if they were invalid.

For backwards compatibility with earlier implementations, the dbus-name MAY also be ":1." followed by an arbitrary unique string of up to 252 characters chosen from A-Z, a-z, 0-9, "-" or "_".

4.2 D-Bus unique names in a link-local MUC context

The D-Bus unique names used in a link-local MUC SHOULD be ":2." followed by the _presence._tcp instance name (e.g. mercutio@mab) processed with the algorithm above.

Again, implementations MUST NOT use unique names that start with ":2." but are not formed according to the above rules, and SHOULD treat tube elements containing such a dbus-name as if they were invalid.

4.3 Definition of the tubes SI profile

The Tubes SI profile is indicated by the profile string http://telepathy.freedesktop.org/xmpp/tubes. A Tubes SI IQ can be classified as follows:

4.4 Parameter types

The allowed parameter types are:

4.5 TODO

FIXME: how big do we want to allow a message to be? In the D-Bus specification the limit is 2**27 bytes, in the default dbus-daemon configuration (as used on the system bus) it's 32M.

FIXME: limit how many messages are queued up somehow (the system bus limits it to 127M in total)

5. Security Considerations

FIXME

6. IANA Considerations

None.

7. XMPP Registrar Considerations

None, this isn't a real XEP (yet?).

8. XML Schema

    <xs:schema
      xmlns:xs='http://www.w3.org/2001/XMLSchema'
      targetNamespace='http://telepathy.freedesktop.org/xmpp/protocol/tubes'
      xmlns='http://telepathy.freedesktop.org/xmpp/protocol/tubes'
      elementFormDefault='qualified'>

      <!-- Container for <tube> elements in MUC <presence> -->
      <xs:element name='tubes'>
        <xs:complexType>
          <xs:sequence minOccurs='0'>
            <xs:element ref='tube' minOccurs='0' maxOccurs='unbounded'/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <!-- A tube offer -->
      <xs:element name='tube'>
        <xs:complexType>
          <!-- Required attributes -->
          <xs:attribute name='id' type='xs:unsignedInt' use='required'/>
          <xs:attribute name='type' use='required'>
            <xs:simpleType>
              <xs:restriction base='xs:NCName'>
                <xs:enumeration value='dbus'/>
                <xs:enumeration value='stream'/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name='service' type='xs:string' use='required'/>

          <!-- MUC D-Bus tube attributes -->
          <!-- MUST be present for MUC D-Bus tubes, SHOULD NOT be
          emitted for other types of tube, MUST be ignored for other types
          of tube -->
          <xs:attribute name='initiator' type='xs:string' use='optional'/>
          <xs:attribute name='dbus-name' type='xs:string' use='optional'/>
          <xs:attribute name='stream-id' type='xs:string' use='optional'/>

          <!-- Parameters -->
          <xs:element name='parameters'>
            <xs:sequence minOccurs='0'>
              <xs:element name='parameter' minOccurs='0'
                maxOccurs='unbounded' type='name-value-pair'/>
              </xs:element>
            </xs:sequence>
          </xs:element>
        </xs:complexType>
      </xs:element>

      <!-- A name-value pair -->
      <xs:complexType name='name-value-pair'>
        <xs:simpleContent>
          <xs:extension base='xs:string'>
            <xs:attribute name='name' type='xs:string'/>
            <xs:attribute name='type'>
              <xs:simpleType>
                <xs:restriction base='xs:NCName'>
                  <xs:enumeration value='bool'/>
                  <xs:enumeration value='str'/>
                  <xs:enumeration value='bytes'/>
                  <xs:enumeration value='int'/>
                  <xs:enumeration value='uint'/>
                </xs:restriction>
              </xs:simpleType>
            </xs:attribute>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>

      <xs:complexType name='tube-reference'>
        <xs:simpleContent>
          <xs:extension base='empty'>
            <xs:attribute name='tube' use='required' type='xs:unsignedInt'/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>

      <xs:element name='close' type='tube-reference'/>

      <xs:element name='stream' type='tube-reference'/>

      <!-- only valid in a MUC -->
      <xs:element name='muc-stream' type='tube-reference'/>

      <xs:simpleType name='empty'>
        <xs:restriction base='xs:string'>
          <xs:enumeration value=''/>
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>
  

9. Appendix: test data for D-Bus unique name algorithm

The string "short" produces the unique name ":2.c2hvcnQA".

The string "FirstWitch", as used in the examples, produces the unique name ":2.Rmlyc3RXaXRjaAAA".

The string "Second witch", as used in the examples, produces the unique name ":2.U2Vjb25kIHdpdGNo".

The string consisting of 18 repetitions of "0123456789" followed by "012345" (186 characters) produces a unique name consisting of ":2.", followed by 6 repetitions of the 40-character string "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5", followed by "MDEyMzQ1".

The string consisting of 18 repetitions of "0123456789" followed by "0123456" (187 characters) produces a unique name consisting of ":2.", followed by 5 repetitions of the 40-character string above, followed by "MDEyMzQ1Njc4OTAxMjM0NTY3OEVd9C5NgmmRD6jp1ftG6XUEc11x".

The string consisting of 20 repetitions of "0123456789" (200 characters) produces a unique name consisting of ":2.", followed by 5 repetitions of the 40-character string above, followed by "MDEyMzQ1Njc4OTAxMjM0NTY3OO-utwRnwcoUFhnJVMKg5pm9Hxal".


Notes


Revision History

Version 0.0.1 (2007-09-07)

First draft.

(smcv)

END