Merge branch 'master' into next, and update to merged spec

Conflicts:
	configure.ac
	docs/reference/telepathy-glib-sections.txt
	examples/cm/Makefile.am
	examples/cm/call/example_call.manager
	examples/future/call-cm/call-channel.c
	examples/future/call-cm/call-content.c
	extensions/call-content.xml
	spec/Account_Manager.xml
	spec/Call_Content.xml
	spec/Call_Content_Interface_Audio_Control.xml
	spec/Call_Content_Interface_Media.xml
	spec/Call_Content_Interface_Video_Control.xml
	spec/Call_Content_Media_Description.xml
	spec/Call_Content_Media_Description_Interface_RTCP_Extended_Reports.xml
	spec/Call_Content_Media_Description_Interface_RTCP_Feedback.xml
	spec/Call_Content_Media_Description_Interface_RTP_Header_Extensions.xml
	spec/Call_Interface_Mute.xml
	spec/Call_Stream.xml
	spec/Call_Stream_Endpoint.xml
	spec/Call_Stream_Interface_Media.xml
	spec/Channel.xml
	spec/Channel_Interface_Addressing.xml
	spec/Channel_Interface_DTMF.xml
	spec/Channel_Type_Call.xml
	spec/Connection_Interface_Addressing.xml
	spec/Connection_Interface_Contact_List.xml
	spec/Connection_Manager.xml
	spec/Makefile.am
	spec/Protocol.xml
	spec/Protocol_Interface_Addressing.xml
	spec/all.xml
	telepathy-glib/abi.am
	telepathy-glib/channel-factory-iface.c
	telepathy-glib/channel-request.c
	telepathy-glib/channel.c
	telepathy-glib/channel.xml
	telepathy-glib/signals-marshal.list
	tests/dbus/Makefile.am
	tests/dbus/call-example.c
	tests/lib/bug16307-conn.c
	tests/lib/echo-channel-manager-conn.c
	tests/lib/echo-conn.c
	tests/lib/simple-conn.c
Acked-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

1 files changed, 621 insertions, 0 deletions

diff --git a/spec/Connection_Interface_Presence1.xml b/spec/Connection_Interface_Presence1.xml
new file mode 100644
index 000000000..1e27cc2ea
--- /dev/null
+++ b/spec/Connection_Interface_Presence1.xml
@@ -0,0 +1,621 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Presence1" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>This library is free software; you can redistribute it and/or modify it
+      under the terms of the GNU Lesser General Public License as published by
+      the Free Software Foundation; either version 2.1 of the License, or (at
+      your option) any later version.</p>
+
+    <p>This library is distributed in the hope that it will be useful, but
+      WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
+      General Public License for more details.</p>
+
+    <p>You should have received a copy of the GNU Lesser General Public License
+      along with this library; if not, write to the Free Software Foundation,
+      Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+  </tp:license>
+
+  <interface name="im.telepathy1.Connection.Interface.Presence1">
+    <tp:requires interface="im.telepathy1.Connection"/>
+
+    <tp:struct name="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="Contact_Presence_Map">
+      <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="Presence" name="Presence">
+        <tp:docstring>
+          The contact's presence
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <tp:struct name="Status_Spec">
+      <tp:docstring>
+        A struct containing information about a status.
+      </tp:docstring>
+      <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
+        <tp:docstring>
+          The type of a presence. This SHOULD NOT be used as a way to set
+          statuses that the client does not recognise (as explained in
+          <tp:member-ref>SetPresence</tp:member-ref>), but MAY be used to check
+          that the client's assumptions about a particular status name
+          match the connection manager's.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="b" name="May_Set_On_Self">
+        <tp:docstring>
+          If true, the user can set this status on themselves using
+          <tp:member-ref>SetPresence</tp:member-ref>.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="b" name="Can_Have_Message">
+        <tp:docstring>
+          If true, a non-empty message can be set for this status. Otherwise,
+          the empty string is the only acceptable message.
+
+          <tp:rationale>
+            On IRC you can be Away with a status message, but if you are
+            available you cannot set a status message.
+          </tp:rationale>
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:mapping name="Status_Spec_Map">
+      <tp:docstring>
+        A mapping describing possible statuses.
+      </tp:docstring>
+
+      <tp:member type="s" name="Identifier">
+        <tp:docstring>
+          The string identifier of this status.
+        </tp:docstring>
+      </tp:member>
+      <tp:member type="(ubb)" tp:type="Status_Spec" name="Spec">
+        <tp:docstring>
+          Details of this status.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <method name="SetPresence" tp:name-for-bindings="Set_Presence">
+      <arg direction="in" name="Status" type="s">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The string identifier of the desired status. Possible status
+            identifiers are defined in the
+            <tp:member-ref>Statuses</tp:member-ref> property.</p>
+
+          <p>Clients MUST NOT set a status whose string value they do not
+            recognise, even if its presence type in Statuses
+            matches what the user requested.</p>
+
+          <tp:rationale>
+            <p>Suppose a protocol has statuses that include 'phone' (of type
+              BUSY) and 'in-a-meeting' (of type BUSY), but there is no
+              generic 'busy' status.</p>
+
+            <p>If the user requests "Busy" status from a menu, a
+              client author might be tempted to pick an arbitrary status
+              that has type BUSY. However, on this protocol, neither of
+              the choices would be appropriate, and incorrect information
+              about the user would be conveyed.</p>
+          </tp:rationale>
+
+          <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+            is Offline, Error or Unknown MUST NOT be passed to this
+            function. Connection managers SHOULD reject these statuses.</p>
+
+          <tp:rationale>
+            <p>To go offline, call <tp:dbus-ref
+                namespace="im.telepathy1.Connection">Disconnect</tp:dbus-ref>
+            instead. The "error" and "unknown" statuses make no sense.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </arg>
+      <arg direction="in" name="Status_Message" type="s">
+        <tp:docstring>
+          The status message associated with the current status.
+        </tp:docstring>
+      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the presence status and status message are published for
+          the connection.  Changes will be indicated by
+          <tp:member-ref>PresencesChanged</tp:member-ref>
+          signals being emitted.</p>
+
+        <p>This method may be called on a newly-created connection while it
+          is still in the DISCONNECTED state, to request that when the
+          connection connects, it will do so with the selected status.</p>
+
+        <p>In DISCONNECTED state the
+          <tp:member-ref>Statuses</tp:member-ref>
+          property will indicate which statuses are allowed to be set
+          while DISCONNECTED (none, if the Connection Manager doesn't allow
+          this). This value MUST NOT be cached, as the set of allowed
+          presences might change upon connecting.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="im.telepathy1.Error.NetworkError"/>
+        <tp:error name="im.telepathy1.Error.InvalidArgument">
+          <tp:docstring>
+            Either the specified status is not supported, the specified
+            status cannot be set on the user themselves, or a non-empty
+            message was supplied for a status that does not
+            accept a message.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+
+    <method name="GetPresences" tp:name-for-bindings="Get_Presences">
+      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          An array of the contacts whose presence should be obtained.
+        </tp:docstring>
+      </arg>
+      <arg direction="out" name="Presence" type="a{u(uss)}"
+        tp:type="Contact_Presence_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Presence information in the same format as for the
+            <tp:member-ref>PresencesChanged</tp:member-ref> signal.
+            The returned mapping MUST include an entry for each contact
+            in the method's argument.</p>
+
+          <p>The definition of the connection presence types Unknown
+            and Offline means that if a connection manager will return
+            Unknown for contacts not on the subscribe list, it MUST delay
+            the reply to this method call until it has found out which
+            contacts are, in fact, on the subscribe list.</p>
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        Get presence previously emitted by
+        <tp:member-ref>PresencesChanged</tp:member-ref> for the given
+        contacts. Data is returned in the same structure as the
+        PresencesChanged signal; no additional network requests are made.
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="im.telepathy1.Error.Disconnected"/>
+        <tp:error name="im.telepathy1.Error.InvalidHandle"/>
+        <tp:error name="im.telepathy1.Error.NetworkError">
+          <tp:docstring>
+            While discovering the subscribe list in order to distinguish
+            between Unknown and Offline statuses, a network error occurred.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="im.telepathy1.Error.NotAvailable"/>
+      </tp:possible-errors>
+    </method>
+
+    <property name="Statuses" tp:name-for-bindings="Statuses" access="read"
+      type="a{s(ubb)}" tp:type="Status_Spec_Map">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A dictionary where the keys are the presence statuses that are
+          available on this connection, and the values are the corresponding
+          presence types.</p>
+
+        <p>While the connection is in the DISCONNECTED state, it contains
+          the set of presence statuses allowed to be set before connecting.
+          The connection manager will attempt to set the appropriate status
+          when the connection becomes connected, but cannot necessarily
+          guarantee it. The available statuses cannot change until the
+          connection status changes, so there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTED state, this property
+          contains the set of presence statuses which are actually available
+          on this protocol. This set is constant for the remaining lifetime
+          of the connection, so again, there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTING state, the value of
+          this property is undefined and SHOULD NOT be used. It can change
+          at any time without notification (in particular, any cached values
+          from when the connection was in the DISCONNECTED or CONNECTING
+          state MUST NOT be assumed to still be correct when the state has
+          become CONNECTED).</p>
+
+        <p>This property MUST include the special statuses "unknown" and
+          "error" if and only if the connection manager can emit them
+          as a contact's status.</p>
+
+        <tp:rationale>
+          For instance, connection managers for local-xmpp (XEP-0174) would
+          omit "unknown" since there is no such concept.
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <property name="MaximumStatusMessageLength"
+      tp:name-for-bindings="Maximum_Status_Message_Length" access="read"
+      type="u">
+      <tp:added version="0.22.2"/>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The maximum length in characters for any individual status
+          message, or 0 if there is no limit.</p>
+
+        <p>While the connection is in the DISCONNECTED state, this property will
+          be 0. The connection manager will attempt to set the appropriate value
+          when the connection becomes connected, but cannot necessarily
+          guarantee it. The maximum length cannot change until the
+          connection status changes, so there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTED state, this property
+          contains the maximum length in characters for any individual status
+          message which is actually allowed on this protocol.
+          This value is constant for the remaining lifetime
+          of the connection, so again, there is no change notification.</p>
+
+        <p>While the connection is in the CONNECTING state, the value of
+          this property is undefined and SHOULD NOT be used. It can change
+          at any time without notification (in particular, any cached values
+          from when the connection was in the DISCONNECTED or CONNECTING
+          state MUST NOT be assumed to still be correct when the state has
+          become CONNECTED).</p>
+
+        <p>If a message passed to <tp:member-ref>SetPresence</tp:member-ref> is
+          longer than allowed by this property, the connection manager MUST
+          truncate the supplied message; when emitting
+          <tp:member-ref>PresencesChanged</tp:member-ref>, the truncated version
+          of the message MUST be used.</p>
+
+        <tp:rationale>
+          <p>Some XMPP servers, like Google Talk, define a maximum length for
+          status messages. Whether the user's server is one of
+          these cannot be detected until quite late in the connection
+          process.</p>
+        </tp:rationale>
+
+      </tp:docstring>
+    </property>
+
+    <signal name="PresencesChanged" tp:name-for-bindings="Presences_Changed">
+      <arg name="Presence" type="a{u(uss)}" tp:type="Contact_Presence_Map">
+        <tp:docstring>
+          A dictionary of contact handles mapped to the status,
+          presence type and status message.
+        </tp:docstring>
+      </arg>
+      <tp:docstring>
+        This signal should be emitted when your own presence has been changed,
+        or the presence of the member of any of the connection's channels has
+        been changed.
+      </tp:docstring>
+    </signal>
+
+    <tp:enum name="Connection_Presence_Type" type="u">
+      <tp:enumvalue suffix="Unset" value="0">
+        <tp:docstring>
+          An invalid presence type used as a null value. This value MUST NOT
+          appear in the <tp:member-ref>Statuses</tp:member-ref> property.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Offline" value="1">
+        <tp:docstring>
+          Offline
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Available" value="2">
+        <tp:docstring>
+          Available
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Away" value="3">
+        <tp:docstring>
+          Away
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Extended_Away" value="4">
+        <tp:docstring>
+          Away for an extended time
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Hidden" value="5">
+        <tp:docstring>
+          Hidden (invisible)
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Busy" value="6">
+        <tp:added version="0.17.0"/>
+        <tp:docstring>
+          Busy, Do Not Disturb.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Unknown" value="7">
+        <tp:added version="0.17.8"/>
+        <tp:docstring>
+          Unknown, unable to determine presence for this contact, for example
+          if the protocol only allows presence of subscribed contacts.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Error" value="8">
+        <tp:added version="0.17.8"/>
+        <tp:docstring>
+          Error, an error occurred while trying to determine presence.  The
+          message, if set, is an error from the server.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:enum name="Access_Control_Type" type="u"
+             array-name="Access_Control_Type_List">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>A type for communication access control. These control
+          policies are used in
+          <tp:dbus-ref namespace="imt1.Connection.Interface">CommunicationPolicy1</tp:dbus-ref>
+          and in rich presence interfaces such as
+          <tp:dbus-ref namespace="imt1.Connection.Interface">Location1</tp:dbus-ref>.</p>
+      </tp:docstring>
+      <tp:enumvalue suffix="Whitelist" value="0">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Only allow contacts that are in a certain whitelist.</p>
+
+          <p>The associated variant
+            in <tp:type>Access_Control</tp:type> is a list of
+            <tp:type>Contact_Handle</tp:type> representing
+            the whitelist, with signature <code>au</code>.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Publish_List" value="1">
+        <tp:docstring>
+          Allow contacts whose
+          <tp:token-ref namespace="imt1.Connection.Interface.ContactList1">publish</tp:token-ref>
+          state is Yes, i.e. those who can normally see the local user's presence.
+          The associated variant in <tp:type>Access_Control</tp:type> is ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Group" value="2">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Only allow contacts that are in a certain user-defined group, as
+            configured by the <tp:dbus-ref
+              namespace="imt1.Connection.Interface">ContactGroups1</tp:dbus-ref>
+            interface.</p>
+
+          <p>The associated variant in <tp:type>Access_Control</tp:type> is
+            a string (D-Bus type 's'), the name of a contact group.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Open" value="3">
+        <tp:docstring>
+          Allow all contacts.  The associated
+          variant in <tp:type>Access_Control</tp:type> is ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Subscribe_Or_Publish_List" value="4">
+        <tp:docstring>
+          Allow contacts whose
+          <tp:token-ref namespace="imt1.Connection.Interface.ContactList1">subscribe</tp:token-ref>
+          and/or <tp:token-ref namespace="imt1.Connection.Interface.ContactList1">publish</tp:token-ref>
+          state is Yes, i.e. those whose presence can normally be seen by the
+          local user, and those who can normally see the local user's presence.
+          The associated variant in <tp:type>Access_Control</tp:type> is ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Closed" value="5">
+        <tp:docstring>
+          Forbid all contacts. The associated variant in
+          <tp:type>Access_Control</tp:type> is ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Not_Understood" value="6">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>The access control rule is too complex to be represented
+            in the current Telepathy API. The associated variant is
+            meaningless. Setting this mode is never valid; the
+            connection manager MUST raise an error if this is attempted.</p>
+
+          <tp:rationale>
+            XEP-0016 Privacy Lists can easily produce access control
+            mechanisms that can't be expressed in a simpler API. We
+            need to be able to at least indicate that fact.
+          </tp:rationale>
+
+          <p>The associated variant in <tp:type>Access_Control</tp:type> is
+            ignored.</p>
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:struct name="Access_Control">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>An access control mode for extended presence items like geolocation.
+          This type isn't actually used by the Presence interface, but
+          it's included here so it can be referenced by rich presence
+          interfaces.</p>
+      </tp:docstring>
+
+      <tp:member name="Type" type="u" tp:type="Access_Control_Type">
+        <tp:docstring>
+          The type of access control to apply.
+        </tp:docstring>
+      </tp:member>
+      <tp:member name="Detail" type="v">
+        <tp:docstring>
+          Any additional information required by the Type. The required
+          type and semantics are defined for each
+          <tp:type>Access_Control_Type</tp:type>.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
+    <tp:contact-attribute name="presence"
+      type="(uss)" tp:type="Presence">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The same struct that would be returned by
+          <tp:member-ref>GetPresences</tp:member-ref>
+          (always present with some value if information from the
+          Presence interface was requested)</p>
+      </tp:docstring>
+    </tp:contact-attribute>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>This interface is for services which have a concept of presence which
+        can be published for yourself and monitored on your contacts.</p>
+
+      <p>Presence on an individual (yourself or one of your contacts) is
+        modelled as a status and a status message. Valid statuses are defined
+        per connection, and a list of those that can be set on youself
+        can be obtained from the
+        <tp:member-ref>Statuses</tp:member-ref>
+        property.</p>
+
+      <p>Each status has an arbitrary string identifier which should have an
+        agreed meaning between the connection manager and any client which is
+        expected to make use of it. The following well-known values should be
+        used where possible to allow clients to identify common choices:</p>
+
+      <table>
+        <tr>
+          <th>Status identifier</th>
+          <th><tp:type>Connection_Presence_Type</tp:type></th>
+          <th>Remarks</th>
+        </tr>
+        <tr>
+          <td><code>"available"</code></td>
+          <td>Available</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td><code>"chat"</code></td>
+          <td>Available</td>
+          <td>Actively interested in chatting, as opposed to merely
+            available.</td>
+        </tr>
+        <tr>
+          <td><code>"pstn"</code></td>
+          <td>Available</td>
+          <td>This contact is actually a phone number, not an IM account. As
+            such, the contact is conceptually always available, but not in the
+            same way that a contact can set their IM status to “available”.
+            It does not make sense to allow the user to set this status on
+            herself; hence, on protocols where this status is supported, its
+            entry in <tp:member-ref>Statuses</tp:member-ref> SHOULD have
+            <var>May_Set_On_Self</var> set to <code>False</code>.</td>
+        </tr>
+        <tr>
+          <td><code>"away"</code></td>
+          <td>Away</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td><code>"brb"</code></td>
+          <td>Away</td>
+          <td>Be Right Back (a more specific form of Away)</td>
+        </tr>
+        <tr>
+          <td><code>"busy"</code></td>
+          <td>Busy</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td><code>"dnd"</code></td>
+          <td>Busy</td>
+          <td>Do Not Disturb (a more specific form of Busy)</td>
+        </tr>
+        <tr>
+          <td><code>"xa"</code></td>
+          <td>Extended_Away</td>
+          <td>Extended Away</td>
+        </tr>
+        <tr>
+          <td><code>"hidden"</code></td>
+          <td>Hidden</td>
+          <td>Also known as "Invisible" or "Appear Offline"</td>
+        </tr>
+        <tr>
+          <td><code>"offline"</code></td>
+          <td>Offline</td>
+          <td></td>
+        </tr>
+        <tr>
+          <td><code>"unknown"</code></td>
+          <td>Unknown</td>
+          <td>special, see below</td>
+        </tr>
+        <tr>
+          <td><code>"error"</code></td>
+          <td>Error</td>
+          <td>special, see below</td>
+        </tr>
+      </table>
+
+      <p>As well as these well-known status identifiers, every status also has
+        a numerical type value chosen from
+        <tp:type>Connection_Presence_Type</tp:type> which can be
+        used by the client to classify even unknown statuses into different
+        fundamental types.</p>
+
+      <p>These numerical types exist so that even if a client does not
+        understand the string identifier being used, and hence cannot present
+        the presence to the user to set on themselves, it may display an
+        approximation of the presence if it is set on a contact.</p>
+
+      <p>As well as the normal status identifiers, there are two special ones
+        that may be present: 'unknown' with type Unknown and 'error' with type
+        Error. 'unknown' indicates that it is impossible to determine the
+        presence of a contact at this time, for example because it's not on the
+        'subscribe' list and the protocol only allows one to determine the
+        presence of contacts you're subscribed to. 'error' indicates that there
+        was a failure in determining the status of a contact.</p>
+
+      <p>If the connection has a 'subscribe' contact list,
+        <tp:member-ref>PresencesChanged</tp:member-ref>
+        signals should be emitted to indicate changes of contacts on this list,
+        and should also be emitted for changes in your own presence. Depending
+        on the protocol, the signal may also be emitted for others such as
+        people with whom you are communicating, and any user interface should
+        be updated accordingly.</p>
+    </tp:docstring>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->