The latest draft specification can be found at http://telepathy.freedesktop.org/spec/. Older stable versions of the specification available at:

Specification D-Bus introspect format extensions, version 0

As of version 0.14 the spec is written in an embraced-and-extended form of the D-Bus introspection format.

The spec consists of a main XML all.xml file which incorporates other files using XInclude.

Document structure

<!-- all.xml -->
<tp:spec xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
  <tp:title>The Telepathy specification</tp:title>
  <tp:version>a.b.c</tp:version>

  <!-- each node is actually in a separate document, using XInclude -->
  <node><interface>...</interface></node>

  <!-- tp:errors is actually in a separate document errors.xml, using XInclude -->
  <tp:errors namespace="org.freedesktop.Telepathy.Error">
    <tp:error name="...">...</tp:error>
  </tp:errors>
</tp:spec>

XHTML

Some elements are noted below as containing XHTML. These may either contain a single paragraph of plain text, or some XHTML - in the latter case you need an xmlns="http://www.w3.org/1999/xhtml" attribute on the element. Some spec processing tools may just ignore the tags and write out the plain text, so bear that in mind when you format it.

Copyright and stuff

tp:copyright elements may appear anywhere, to describe the copyright of nodes below that point. They contain character data like "Copyright (C) 2005, 2006, 2007 Collabora Limited". If there is more than one copyright holder there must be multiple tp:copyright elements.

tp:license elements may appear anywhere. They contain XHTML.

(FIXME: it would be somewhat saner to have the license and copyright holders only appear in one place, or something.)

Docstrings

Many elements can contain a tp:docstring. This is the text of the spec; it may contain XHTML.

Any interface, method or signal can contain something like which has the obvious meaning.

Interface definitions

Each interface is wrapped in a separate node element: this is to make it easier to generate ordinary D-Bus introspection XML for tools that need that. It's also in a separate XML file, which is XIncluded into all.xml.

The node's name is required to be in the format "/Some_API_Name". This is mangled in various ways to make constants, class names, etc.:

for camel-case names like Python and GLib classes, remove the "/" and the underscores: SomeAPIName
for upper- or lower-case underscore-separated names like C constants and functions, remove the "/" and translate to upper- or lower-case: SOME_API_NAME, some_api_name The filename is the same as the node name, without the leading '/'.

The interface element has a tp:docstring and some D-Bus method and signal elements.

The interface element can also include tp:requires elements whose interface attribute is the full D-Bus name of an interface which must be implemented as a prerequisite.

The method and signal elements, and their arg elements, are extended to contain a tp:docstring too. Also, methods can contain a tp:possible-errors element.

The tp:possible-errors element contains tp:error elements whose name attribute is the full D-Bus name of an error. Each of these may optionally contain a tp:docstring specifying when the error is raised. If it doesn't, the generic docstring from the error definition will be used in documentation instead.

For example, here's the definition of the Connection.?InspectHandles method, which illustrates errors with custom reasons as well as an error using the default description:

<method name="InspectHandles" tp:name-for-bindings="Inspect_Handles">
  <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
    <tp:docstring>
      The type of handle to be inspected
    </tp:docstring>
  </arg>

  <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
    <tp:docstring>
      An array of integer handles of this type
    </tp:docstring>
  </arg>

  <arg direction="out" type="as" name="Identifiers">
    <tp:docstring>
      An array of identifiers corresponding to the given handles, in the same order.
    </tp:docstring>
  </arg>

  <tp:docstring>
    Return a string representation for a number of handles of a given
    type.
  </tp:docstring>

  <tp:possible-errors>
    <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
    <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
      The handle type is invalid
    </tp:error>
    <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
      One of the given handles is not valid
    </tp:error>
  </tp:possible-errors>
</method>

Simple type synonyms

You can declare and document semantically-relevant synonyms for simple types using the tp:simple-type elemnt, as follows:

<tp:simple-type name="Handle" type="u" array-name="Handle_List">
  <tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring>
</tp:simple-type>

This example also illustrates the array-name attribute, which suggests a sensible name for arrays or lists of this type to binding generators.

Flags and enumerations

Enumerations are represented by a tp:enum element with a name attribute; sets of flags which are to be bitwise-OR'd together are represented by a tp:flags element with a name attribute. The name must be in mixed case with underscores between words: this will be mangled into various formats in the same way the node names are. Either may contain an optional tp:docstring.

There may also be a value-prefix attribute which sets the string used for the beginning of a value's name, as described below; if omitted, the name is used.

Typically, enums don't need a value-prefix, and for a flag set Foo_Flags the value-prefix is Foo_Flag.

Enums may have a plural attribute giving the plural form of the name. If not given, it may be assumed to be the name with "s" appended (we assume that any specification in this format is likely to be in English :-))

(FIXME: We should replace @value-prefix and @name with @singular and @plural)

tp:enum elements contain tp:enumvalue elements, and tp:flags elements contain tp:flag elements. Both have attributes suffix and value, and may contain a tp:docstring.

(FIXME: Alp suggests we should replace @suffix with @name)

The suffix is in mixed case with underscores between words, and is mangled into the appropriate format (in practice, usually upper-case with underscores) and appended to the value-prefix of the enumeration (separated by an underscore if appropriate; the name is used if there is no value-prefix). The value is the numeric value, typically 0, 1, ... for enumerations and 1, 2, 4, ... for sets of flags.

In enumerations, the tp:enumvalue elements must appear in ascending numeric order, so tools can generate a constant for "highest value" in a straightforward way.

Structs and Maps

Aliases for D-Bus structs and dictionaries are represented by tp:struct and tp:mapping elements, respectively. They are identical, except that the latter must contain exactly two tp:member children, documenting the key and value types of the dictionary. The members may be annotated with tp:type attributes if appropriate. Here are a pair of examples from the ?SimplePresence interface:

<tp:struct name="Simple_Presence">
  <tp:docstring>
    A struct representing the presence of a contact.
  </tp:docstring>
  <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
    <tp:docstring>
      The presence type, e.g. Connection_Presence_Type_Away.
    </tp:docstring>
  </tp:member>
  <tp:member type="s" name="Status">
    <tp:docstring>
      The string identifier of the status, e.g. "brb", as defined in the
      <tp:member-ref>Statuses</tp:member-ref> property.
    </tp:docstring>
  </tp:member>
  <tp:member type="s" name="Status_Message">
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
      <p>The user-defined status message, e.g. "Back soon!".</p>

      <p>Clients SHOULD set the status message for the local
        user to the empty string, unless the user has actually provided
        a specific message (i.e. one that conveys more information than the
        Status).</p>

      <p>User interfaces SHOULD regard an empty status message as unset,
        and MAY replace it with a localized string corresponding to the
        Status or Type.</p>

      <tp:rationale>
        Use case: Daf sets his status in Empathy by choosing the Welsh
        translation of "Available" from a menu.
        It is more informative for his English-speaking colleagues
        to see the English translation of "Available" (as localized
        by their own clients) than to see "Ar Gael" (which they don't
        understand anyway).
      </tp:rationale>
    </tp:docstring>
  </tp:member>
</tp:struct>

<tp:mapping name="Simple_Contact_Presences">
  <tp:docstring>
    Mapping returned by <tp:member-ref>GetPresences</tp:member-ref>
    and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
    indicating the presence of a number of contacts.
  </tp:docstring>
  <tp:member type="u" tp:type="Contact_Handle" name="Contact">
    <tp:docstring>
      A contact
    </tp:docstring>
  </tp:member>
  <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence">
    <tp:docstring>
      The contact's presence
    </tp:docstring>
  </tp:member>
</tp:mapping>

Properties

The tp:property elements document the name and meaning of properties which can be accessed on the org.freedesktop.Telepathy.Properties interface of the object implementing the documented interface. This is primarily intended to associate certain named properties with particular channel types. The name attribute is the string name of the property as found in the ?ListProperties method, and the type attribute is the single complete D-Bus type of this property. Each tp:property element should have a tp:docstring element associated.

(FIXME: we should probably provide a Camel_Case_With_Underscores name for each property, as well or instead)

Error definitions

The tp:errors element has a namespace attribute and contains a number of tp:error-def elements, each with a tp:docstring and a name attribute.

The namespace attribute is the part of the namespace that's assumed for all errors - this won't appear in class names etc. since the language's namespacing (modules in Python, prefixes like TP_ in C, etc.) is used instead.

The name attribute on each error-def is written like "Example ?SubNamespace.Sample Error". This is mangled in various ways to generate names:

for D-Bus error names, the spaces are removed and it's appended to the assumed namespace after a dot: e.g. org.freedesktop.Telepathy.Error.?ExampleSubNamespace.?SampleError
for "camel-case" names, like classes in Python, the spaces and dots are removed: e.g. ?ExampleSubNamespaceSampleError
for UPPER_CASE or lower_case names, like constants and functions in C, the spaces and dots are converted to underscores, and the case is normalized: e.g. EXAMPLE_SUBNAMESPACE_SAMPLE_ERROR or the lower-case equivalent