summaryrefslogtreecommitdiff
path: root/spec
diff options
context:
space:
mode:
authorSimon McVittie <simon.mcvittie@collabora.co.uk>2010-07-02 10:53:47 +0100
committerSimon McVittie <simon.mcvittie@collabora.co.uk>2010-07-02 10:53:47 +0100
commit28173ee563e2a93e25649aa47c48f12212a42d16 (patch)
tree6a614d43207abfa8e9ac7a8272255f4243b580f6 /spec
parent34d2b6b53b61ec0b8fe956b9b0d60e18d2cd0a96 (diff)
downloadtelepathy-glib-28173ee563e2a93e25649aa47c48f12212a42d16.tar.gz
Update to telepathy-spec 0.19.8
- generate code for Account.Service property - generate code for ConnectionManager.Protocols property and Protocol_Properties_Map type, although the properties they contain are still in draft - Capabilities is deprecated, CMs implementing it must also implement ContactCapabilities - Account.I.Storage, Conn.I.Cellular are stable but do not have generated code yet
Diffstat (limited to 'spec')
-rw-r--r--spec/Account.xml58
-rw-r--r--spec/Account_Interface_Storage.xml169
-rw-r--r--spec/Channel_Interface_Messages.xml654
-rw-r--r--spec/Channel_Type_Text.xml8
-rw-r--r--spec/Connection_Interface_Capabilities.xml7
-rw-r--r--spec/Connection_Interface_Cellular.xml31
-rw-r--r--spec/Connection_Interface_Contact_Groups.xml71
-rw-r--r--spec/Connection_Interface_Contact_List.xml58
-rw-r--r--spec/Connection_Interface_Requests.xml10
-rw-r--r--spec/Connection_Manager.xml77
-rw-r--r--spec/Makefile.am4
-rw-r--r--spec/Protocol.xml370
-rw-r--r--spec/Protocol_Interface_Avatars.xml158
-rw-r--r--spec/Protocol_Interface_Presence.xml114
-rw-r--r--spec/all.xml28
15 files changed, 1453 insertions, 364 deletions
diff --git a/spec/Account.xml b/spec/Account.xml
index dfc37bc58..2bce393ee 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -261,6 +261,53 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
+ <property name="Service" tp:name-for-bindings="Service" type="s"
+ access="readwrite">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some protocols, like XMPP and SIP, are used by various different
+ user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by
+ Nokia</i>. On accounts for such services, this property SHOULD be
+ set to a string describing the service, which MUST consist only of
+ ASCII letters, numbers and hyphen/minus signs, and start with a
+ letter (matching the requirements for <tp:type>Protocol</tp:type>).
+ For the <tt>jabber</tt> protocol, one of the following service names
+ should be used if possible:</p>
+
+ <ul>
+ <li><tt>google-talk</tt> (for <a
+ href="http://www.google.com/talk/">Google's IM service</a>)</li>
+ <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM
+ service)</li>
+ <li><tt>facebook</tt> (for <a
+ href="http://www.facebook.com/sitetour/chat.php">Facebook's IM
+ service</a>)</li>
+ <li><tt>lj-talk</tt> (for <a
+ href="http://www.livejournal.com/chat/">LiveJournal's IM
+ service</a>)</li>
+
+ </ul>
+
+ <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a
+ corresponding brand-specific icon name, if possible. In the future,
+ this property may be used as an index into additional
+ service-specific customizations. If this property is the empty string
+ (or missing), the service is determined by the protocol name (either
+ because this is a single-service protocol like <tt>msn</tt>, or
+ because this is just a generic <tt>jabber</tt> or <tt>sip</tt>
+ account without specific branding).</p>
+
+ <p>This property MAY be set, if appropriate, when calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager"
+ >CreateAccount</tp:dbus-ref>. Updating this property will fail on
+ externally-stored accounts whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Storage"
+ >StorageRestrictions</tp:dbus-ref> include
+ <code>Cannot_Set_Service</code>.</p>
+ </tp:docstring>
+ </property>
+
<property name="Parameters" tp:name-for-bindings="Parameters"
type="a{sv}" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -273,10 +320,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</p>
<p>This property cannot be altered using Set() - use
<tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
-
- <tp:rationale>
- This avoids NMC being tied to gconf as a matter of API.
- </tp:rationale>
</tp:docstring>
</property>
@@ -405,8 +448,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
- <property name="ConnectionStatus" type="u" access="read"
- tp:name-for-bindings="Connection_Status">
+ <property name="ConnectionStatus" type="u" tp:type="Connection_Status"
+ access="read" tp:name-for-bindings="Connection_Status">
<tp:docstring>
If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
the status of that connection.
@@ -426,7 +469,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
- <property name="ConnectionStatusReason" type="u" access="read"
+ <property name="ConnectionStatusReason" type="u"
+ tp:type="Connection_Status_Reason" access="read"
tp:name-for-bindings="Connection_Status_Reason">
<tp:docstring>
The reason for the last change to
diff --git a/spec/Account_Interface_Storage.xml b/spec/Account_Interface_Storage.xml
new file mode 100644
index 000000000..4e3ba5dca
--- /dev/null
+++ b/spec/Account_Interface_Storage.xml
@@ -0,0 +1,169 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Storage"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2010 Collabora Ltd.</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="org.freedesktop.Telepathy.Account.Interface.Storage">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ This interface extends the core Account interface to specify details
+ regarding the storage of this account.
+ </p>
+
+ <tp:rationale>
+ <p>
+ Single-sign-on systems do not generally have directly user-editable
+ properties for Accounts, and require the user to visit a specific UI
+ to alter their account properties. User interfaces should know not to
+ expose these account properties as user-editable, and instead
+ redirect the user to the appropriate interface.
+ </p>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.19.8"/>
+
+ <property name="StorageProvider" tp:name-for-bindings="Storage_Provider"
+ type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The name of the account storage implementation, which SHOULD start
+ with a reversed domain name in the same way as D-Bus interface names.
+ When this is the empty string the account is internally stored.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageIdentifier"
+ tp:name-for-bindings="Storage_Identifier" type="v" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Unique identification of the account within the storage backend.
+ The contents of the variant are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ <tp:rationale>
+ <p>
+ Different storage systems will have their own way of uniquely
+ identifying an account, typically an integer or a string.
+ Given that all users of this property should have direct knowledge
+ of the backend they should know what types to expect and how to
+ handle it.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageSpecificInformation"
+ tp:name-for-bindings="Storage_Specific_Information" type="a{sv}"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Map containing information specific to the storage backend. The keys
+ and the types of their values are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>, and are not
+ interpreted by the AccountManager implementation.
+ </p>
+ <p>
+ As the values in this map may change at any time (due to an external
+ application manipulating the storage provider directly), this
+ property should not be cached; it should instead be retrieved each
+ time it is needed.
+ </p>
+
+ <tp:rationale>
+ <p>
+ This can be used to provide additional hints to user interfaces
+ aware of a specific storage provider, without requiring those user
+ interfaces to use the
+ <tp:member-ref>StorageIdentifier</tp:member-ref> to query the
+ storage provider directly.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageRestrictions"
+ tp:name-for-bindings="Storage_Restrictions" type="u"
+ tp:type="Storage_Restriction_Flags"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Bitfield which defines what restrictions this Storage method has.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Storage_Restriction_Flags"
+ value-prefix="Storage_Restriction_Flag" type="u">
+ <tp:docstring>
+ Flags indicating restrictions imposed on an Account by its storage
+ method.
+ </tp:docstring>
+
+ <tp:flag suffix="Cannot_Set_Parameters" value="1">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Parameters</tp:dbus-ref> property can't be changed by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account"
+ >UpdateParameters</tp:dbus-ref>.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Enabled" value="2">
+ <tp:docstring>
+ The account can't be enabled/disabled by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Enabled</tp:dbus-ref> property.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Presence" value="4">
+ <tp:docstring>
+ The account's presence can't be changed by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >AutomaticPresence</tp:dbus-ref> properties.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Service" value="8">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref>
+ property cannot be changed.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index b33633543..7bd225dfe 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Messages"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008–2010 Nokia Corporation</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
@@ -25,40 +25,47 @@ USA.</p>
<tp:added version="0.17.16">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface extends the Text interface to support more general
- messages, including:</p>
+ <p>This interface extends the <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref>
+ interface to support more general messages, including:</p>
<ul>
<li>messages with attachments (like MIME multipart/mixed)</li>
<li>groups of alternatives (like MIME multipart/alternative)</li>
- <li>delivery reports</li>
+ <li>delivery reports (which replace <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>),
+ addding support for protocols where the message content is not echoed
+ back to the sender on failure and for receiving positive
+ acknowledgements, as well as ensuring that incoming delivery reports
+ are not lost if no client is handling the channel yet;</li>
<li>any extra types of message we need in future</li>
</ul>
- <p>Although this specification supports formatted (rich-text)
- messages with unformatted alternatives, implementations SHOULD NOT
- attempt to send formatted messages until the Telepathy specification
- has also been extended to cover capability discovery for message
- formatting.</p>
+ <p>Incoming messages, outgoing messages, and delivery reports are all
+ represented as lists of <tp:type>Message_Part</tp:type> structures,
+ with a format reminiscent of e-mail. Messages are sent by calling
+ <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are
+ announced to other clients which may be interested in the channel by
+ the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming
+ messages and delivery reports are signalled by
+ <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the
+ the <tp:member-ref>PendingMessages</tp:member-ref> property until
+ acknowledged by calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.
+ Only the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ for a channel should acknowledge messages; <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s
+ (such as loggers) and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
+ for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p>
<tp:rationale>
- We intend to expose all rich-text messages as XHTML-IM, but on some
- protocols, formatting is an extremely limited subset of that format
- (e.g. there are protocols where foreground/background colours, font
- and size can be set, but only for entire messages).
- Until we can tell UIs what controls to offer to the user, it's
- unfriendly to offer the user controls that may have no effect.
+ <p>If observers were allowed to acknowledge messages, then messages
+ might have been acknowledged before the handler even got to see the
+ channel, and hence could not be shown to the user.</p>
</tp:rationale>
- <p>This interface also replaces <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>,
- adding support for
- protocols where the message content is not echoed back to the sender on
- failure, adding support for receiving positive acknowledgements,
- and using the Messages queue for state-recovery
- (ensuring that incoming delivery reports are not lost if there is not
- currently a process handling them).</p>
-
<p>If this interface is present, clients that support it SHOULD
listen for the <tp:member-ref>MessageSent</tp:member-ref> and
<tp:member-ref>MessageReceived</tp:member-ref> signals, and
@@ -70,6 +77,21 @@ USA.</p>
namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
signals on the Text interface (which are guaranteed to duplicate
signals from this interface).</p>
+
+ <p>Although this specification supports formatted (rich-text)
+ messages with unformatted alternatives, implementations SHOULD NOT
+ attempt to send formatted messages until the Telepathy specification
+ has also been extended to cover capability discovery for message
+ formatting.</p>
+
+ <tp:rationale>
+ We intend to expose all rich-text messages as XHTML-IM, but on some
+ protocols, formatting is an extremely limited subset of that format
+ (e.g. there are protocols where foreground/background colours, font
+ and size can be set, but only for entire messages).
+ Until we can tell UIs what controls to offer to the user, it's
+ unfriendly to offer the user controls that may have no effect.
+ </tp:rationale>
</tp:docstring>
<property name="SupportedContentTypes" type="as" access="read"
@@ -182,11 +204,93 @@ USA.</p>
array-depth="2">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Part of a message's content. In practice, this mapping never
- appears in isolation - messages are represented by a list of
- <tp:type>Message_Part</tp:type> mappings.</p>
+ appears in isolation: incoming messages are represented by a list of
+ <tp:type>Message_Part</tp:type> mappings in the
+ <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing
+ messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as
+ a list of these mappings.</p>
+
+ <p>The first part of the message contains "headers", which refer
+ to the entire message. The second and subsequent parts contain the
+ message's content, including plain text, formatted text and/or
+ attached files. Well-known keys for the header and body parts are
+ defined by the <tp:type>Message_Header_Key</tp:type> and
+ <tp:type>Message_Body_Key</tp:type> types, respectively. It is an
+ error for a connection manager to put keys referring to the message
+ as a whole in the second or subsequent Message_Part, or keys intended
+ for body parts in the first Message_Part; clients MUST recover from
+ this error by ignoring these mis-placed keys.</p>
+
+ <tp:rationale>
+ <p>Instead of representing messages as aa{sv} where the first
+ dictionary is special (a dictionary of headers), we could have
+ used a signature like (a{sv}aa{sv}) to separate out the headers
+ and the body parts.</p>
+
+ <p>However, this would make access to the messages more awkward.
+ In Python, the syntax for access to a header field would remain
+ <code>message[0]['message-type']</code>, but access to a body
+ field in the second body part would change from
+ <code>message[2]['content'] to message[1][1]['content']</code>. In
+ GLib, the message would change from being a
+ <code>GPtrArray(GHashTable)</code> to being a
+ <code>GValueArray(GHashTable, GPtrArray(GHashTable))</code> which
+ is rather inconvenient to dereference.</p>
+ </tp:rationale>
+
+ <p>In any group of parts with the same non-empty value for the
+ <tt>alternative</tt> key (which represent alternative versions of the
+ same content), more faithful versions of the intended message MUST
+ come before less faithful versions (note that this order is the
+ opposite of MIME <tt>multipart/alternative</tt> parts). Clients
+ SHOULD display the first alternative that they understand.</p>
+
+ <tp:rationale>
+ <p>Specifying the preference order means that if the underlying
+ protocol doesn't support alternatives, the CM can safely delete
+ everything apart from the first supported alternative when
+ sending messages.</p>
+
+ <p>The order is the reverse of MIME because MIME's rationale for
+ placing the "plainest" part first (legibility in pre-MIME UAs)
+ does not apply to us, and placing the most preferred part
+ first simplifies display (a client can iterate the message
+ in order, display the first alternative that it understands,
+ and skip displaying all subsequent parts with the same
+ "alternative" key).</p>
+ </tp:rationale>
+
+ <p>Clients SHOULD present all parts that are not redundant
+ alternatives in the order they appear in this array, possibly
+ excluding parts that are referenced by another displayed part.
+ It is implementation-specific how the parts are presented to the
+ user.</p>
- <p>An example of how a rich-text message, with an embedded image, might
- look, in a Python-like syntax:</p>
+ <tp:rationale>
+ <p>This allows CMs to assume that all parts are actually shown to
+ the user, even if they are not explicitly referenced - we do
+ not yet recommend formatted text, and there is no way for
+ plain text to reference an attachment since it has no concept of
+ markup or references. This also forces clients to do something
+ sensible with messages that consist entirely of "attachments",
+ with no "body" at all.</p>
+
+ <p>For instance, when displaying the above example, a client that
+ understands the HTML part should display the JPEG image once,
+ between the two lines "Here is a photo of my cat:" and
+ "Isn't it cute?"; it may additionally present the image in some
+ way for a second time, after "Isn't it cute?", or may choose
+ not to.</p>
+
+ <p>A client that does not understand HTML, displaying the same
+ message, should display the plain-text part, followed by the JPEG
+ image.</p>
+ </tp:rationale>
+
+ <h4>Example messages</h4>
+
+ <p>A rich-text message, with an embedded image, might be represented
+ as:</p>
<pre>
[
@@ -215,9 +319,8 @@ USA.</p>
},
]</pre>
- <p>An example of how a non-text message — in particular, a vCard sent
- via SMS as implemented by telepathy-ring on Nokia's Maemo 5 —
- looks:</p>
+ <p>telepathy-ring, Nokia's GSM connection manager, represents vCards
+ sent via SMS as:</p>
<pre>
[
@@ -234,34 +337,164 @@ USA.</p>
},
]</pre>
+ <h3>Delivery reports</h3>
+
<div>
- <p>The first part of the message contains "headers" which refer
- to the entire message.</p>
+ <p>Delivery reports are also represented as messages with the
+ <tt>message-type</tt> header mapping to
+ <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report.
+ Delivery reports SHOULD contain the <tt>message-sender</tt> header,
+ mapping to the intended recipient of the original message, if
+ possible; other headers specific to delivery reports are defined by
+ the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second
+ and subsequent parts, if present, are a human-readable report from
+ the IM service.</p>
+
+ <p>For backwards- and forwards-compatibility, whenever a delivery
+ error report is signalled—that is, with <tt>delivery-status</tt>
+ mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or
+ Permanently_Failed—<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ SHOULD also be emitted; whenever <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ is emitted, a delivery report MUST also be signalled.
+ Delivery report messages on this interface MUST be represented in
+ emissions of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
+ as messages with the Non_Text_Content
+ <tp:type>Channel_Text_Message_Flags</tp:type>; clients which
+ understand this interface SHOULD ignore the SendError signal in
+ favour of listening for delivery reports, as mentioned in the
+ introduction.</p>
+
+ <p>The result of attempting to send delivery reports using
+ <tp:member-ref>SendMessage</tp:member-ref> is currently
+ undefined.</p>
+
+ <h4>Example delivery reports</h4>
- <p>It is an error for a connection manager to put keys referring
- to the message as a whole in the second or subsequent
- Message_Part, but clients MUST recover from this error by ignoring
- these keys in the second and subsequent parts.</p>
+ <dl>
+ <dt>A minimal delivery report indicating permanent failure of the
+ sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
+ reason</dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]</pre></dd>
- <tp:rationale>
- <p>Instead of representing messages as aa{sv} where the first
- dictionary is special (a dictionary of headers), we could have
- used a signature like (a{sv}aa{sv}) to separate out the headers
- and the body parts.</p>
-
- <p>However, this would make access to the messages more awkward.
- In Python, the syntax for access to a header field would remain
- <code>message[0]['message-type']</code>, but access to a body
- field in the second body part would change from
- message[2]['content'] to message[1][1]['content']. In GLib,
- the message would change from being a
- GPtrArray(GHashTable) to being a
- GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather
- inconvenient to dereference.</p>
- </tp:rationale>
+ <dt>A delivery report where the failed message is echoed back to the
+ sender rather than being referenced by ID, and the failure reason
+ is that this protocol cannot send messages to offline contacts
+ such as the contact with handle 123</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Temporarily_Failed,
+'delivery-error': Channel_Text_Send_Error_Offline,
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+
+# no body
+]</pre></dd>
+
+ <dt>A maximally complex delivery report: the server reports a
+ bilingual human-readable failure message because the user sent
+ a message "Hello, world!" with token
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
+ with handle 123, but that handle represents a contact who does not
+ actually exist</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+},
+{ # message from server (alternative in English)
+'alternative': '404',
+'content-type': 'text/plain',
+'lang': 'en',
+'content': 'I have no contact with that name',
+},
+{ # message from server (alternative in German)
+'alternative': '404'.
+'content-type': 'text/plain',
+'lang': 'de',
+'content', 'Ich habe keinen Kontakt mit diesem Namen',
+}
+]</pre></dd>
+
+ <dt>A minimal delivery report indicating successful delivery
+ of the sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Delivered,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]</pre></dd>
+
+ </dl>
+
+ </div>
+ </tp:docstring>
+
+ <tp:member name="Key" type="s">
+ <tp:docstring>
+ A key, which SHOULD be one of the well-known keys specified by
+ <tp:type>Message_Header_Key</tp:type>,
+ <tp:type>Message_Body_Key</tp:type> or
+ <tp:type>Delivery_Report_Header_Key</tp:type> if possible.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Value" type="v">
+ <tp:docstring>
+ The value corresponding to the given key, which SHOULD be one of the
+ specified types for well-known keys.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
- <p>Well-known keys for the message as a whole, and the corresponding
- value types, include:</p>
+ <tp:simple-type type="s" name="Message_Header_Key">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a
+ message, which contains metadata about the message as a whole, along
+ with the corresponding value types. Some keys make sense for both
+ incoming and outgoing messages, while others are only meaningful for
+ one or the other.</p>
<dl>
<dt>message-token (s)</dt>
@@ -354,72 +587,19 @@ USA.</p>
does not make sense on outgoing messages, and SHOULD NOT
appear there.</dd>
</dl>
- </div>
-
- <div>
- <p>The second and subsequent parts contain the message's
- content, including plain text, formatted text and/or attached
- files.</p>
-
- <p>It is an error for a connection manager to put keys referring
- to the message body in the first Message_Part;
- clients MUST recover from this error by ignoring
- these keys in first part.</p>
-
- <p>In any group of parts with the same non-empty value for the
- "alternative" key (which represent alternative versions of the
- same content), more faithful versions of the intended message MUST
- come before less faithful versions (note that this order is the
- opposite of MIME "multipart/alternative" parts). Clients SHOULD
- display the first alternative that they understand.</p>
-
- <tp:rationale>
- <p>Specifying the preference order means that if the underlying
- protocol doesn't support alternatives, the CM can safely delete
- everything apart from the first supported alternative when
- sending messages.</p>
-
- <p>The order is the reverse of MIME because MIME's rationale for
- placing the "plainest" part first (legibility in pre-MIME UAs)
- does not apply to us, and placing the most preferred part
- first simplifies display (a client can iterate the message
- in order, display the first alternative that it understands,
- and skip displaying all subsequent parts with the same
- "alternative" key).</p>
- </tp:rationale>
-
- <p>Clients SHOULD present all parts that are not redundant
- alternatives in the order they appear in this array, possibly
- excluding parts that are referenced by another displayed part.
- It is implementation-specific how the parts are presented to the
- user.</p>
-
- <tp:rationale>
- <p>This allows CMs to assume that all parts are actually shown to
- the user, even if they are not explicitly referenced - we do
- not yet recommend formatted text, and there is no way for
- plain text to reference an attachment since it has no concept of
- markup or references. This also forces clients to do something
- sensible with messages that consist entirely of "attachments",
- with no "body" at all.</p>
-
- <p>For instance, when displaying the above example, a client that
- understands the HTML part should display the JPEG image once,
- between the two lines "Here is a photo of my cat:" and
- "Isn't it cute?"; it may additionally present the image in some
- way for a second time, after "Isn't it cute?", or may choose
- not to.</p>
-
- <p>A client that does not understand HTML, displaying the same
- message, should display the plain-text part, followed by the JPEG
- image.</p>
- </tp:rationale>
+ </tp:docstring>
+ </tp:simple-type>
- <p>Well-known keys for the second and subsequent parts, and the
- corresponding value types, include:</p>
+ <tp:simple-type type="s" name="Message_Body_Key">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the second and subsequent
+ <tp:type>Message_Part</tp:type>s of a message, which contain the
+ message content, along with the corresponding value types.</p>
<dl>
- <dt>identifier (s)</dt>
+ <dt>identifier (s —
+ <tp:type>Protocol_Content_Identifier</tp:type>)</dt>
<dd>An opaque identifier for this part.
Parts of a message MAY reference other parts by treating
this identifier as if it were a MIME Content-ID and using
@@ -502,8 +682,7 @@ USA.</p>
'content': [0xFF, 0xD8, ... 0xFF 0xD9],
},
...
-]
- </pre>
+]</pre>
</dd>
<dt>needs-retrieval (b)</dt>
@@ -547,38 +726,30 @@ USA.</p>
can also appear on the first part, where it indicates that the
entire message should be ignored if unsupported.)</dd>
</dl>
+ </tp:docstring>
+ </tp:simple-type>
- </div>
-
-
- <div>
- <p>Delivery reports are also represented as messages, of type
- Channel_Text_Message_Type_Delivery_Report, with the
- Non_Text_Content flag in the Text interface.</p>
-
- <p>Whenever a message of type
- Channel_Text_Message_Type_Delivery_Report is signalled for a
- delivery error report, Channel.Type.Text.SendError SHOULD also
- be emitted; whenever Channel.Type.Text.SendError is emitted by a
- channel which supports this interface, a message of type
- Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>
-
- <p>The corresponding message in the Messages interface MUST contain
- "headers" for the delivery report, as specified below, in its
- first Message_Part.</p>
+ <tp:simple-type type="s" name="Delivery_Report_Header_Key">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a
+ delivery report, along with the corresponding value types. Some of
+ these are special-cases of headers defined by
+ <tp:type>Message_Header_Key</tp:type>.</p>
<dl>
- <dt>message-sender (u - Contact_Handle as defined above)</dt>
+ <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>, as
+ defined by <tp:type>Message_Header_Key</tp:type>)</dt>
<dd>MUST be the intended recipient of the original message, if
available (zero or omitted if the intended recipient is
unavailable or is not a contact, e.g. a chatroom), even if the
delivery report actually came from an intermediate server.</dd>
- <dt>message-type (u - Channel_Text_Message_Type as defined
- above)</dt>
+ <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>,
+ as defined by <tp:type>Message_Header_Key</tp:type>)</dt>
<dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
- <dt>delivery-status (u - Delivery_Status)</dt>
+ <dt>delivery-status (u - <tp:type>Delivery_Status</tp:type>)</dt>
<dd>The status of the message. All delivery reports MUST contain
this key in the first Message_Part.</dd>
@@ -603,14 +774,16 @@ USA.</p>
</tp:rationale>
</dd>
- <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
+ <dt>delivery-error (u -
+ <tp:type>Channel_Text_Send_Error</tp:type>)</dt>
<dd>
The reason for the failure. MUST be omitted if this was a
successful delivery; SHOULD be omitted if it would be
Channel_Text_Send_Error_Unknown.
</dd>
- <dt>delivery-dbus-error (s - DBus_Error_Name)</dt>
+ <dt>delivery-dbus-error (s -
+ <tp:type>DBus_Error_Name</tp:type>)</dt>
<dd>
The reason for the failure, specified as a (possibly
implementation-specific) D-Bus error. MUST be omitted if this was
@@ -625,7 +798,7 @@ USA.</p>
omitted.
</dd>
- <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
+ <dt>delivery-echo (aa{sv} - <tp:type>Message_Part[]</tp:type>)</dt>
<dd>
<p>The message content, as defined by the Messages interface.
Omitted if no content is available. Content MAY have been
@@ -655,134 +828,8 @@ USA.</p>
</dd>
</dl>
-
- <p>The second and subsequent Message_Part dictionaries, if present,
- are a human-readable report from the IM service.</p>
-
- <p>Clients MUST NOT attempt to send delivery reports using the
- SendMessage method in the Messages API, and connection managers
- MUST NOT allow this to be done. If support for sending delivery
- reports is later added, it will be part of this interface.</p>
-
- <p>Some example delivery reports in a Python-like syntax (in which
- arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
- follow.</p>
-
- <dl>
- <dt>A minimal delivery report indicating permanent failure of the
- sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
- reason</dt>
- <dd><pre>
-[{
-# header
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- <dt>A delivery report where the failed message is echoed back to the
- sender rather than being referenced by ID, and the failure reason
- is that this protocol cannot send messages to offline contacts
- such as the contact with handle 123</dt>
- <dd><pre>
-[{ # header
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Temporarily_Failed,
-'delivery-error': Channel_Text_Send_Error_Offline,
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'content-type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-
-# no body
-]
-</pre></dd>
-
- <dt>A maximally complex delivery report: the server reports a
- bilingual human-readable failure message because the user sent
- a message "Hello, world!" with token
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
- with handle 123, but that handle represents a contact who does not
- actually exist</dt>
- <dd><pre>
-[{ # header
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'content-type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-},
-{ # message from server (alternative in English)
-'alternative': '404',
-'content-type': 'text/plain',
-'lang': 'en',
-'content': 'I have no contact with that name',
-},
-{ # message from server (alternative in German)
-'alternative': '404'.
-'content-type': 'text/plain',
-'lang': 'de',
-'content', 'Ich habe keinen Kontakt mit diesem Namen',
-}
-]
-</pre></dd>
-
- <dt>A minimal delivery report indicating successful delivery
- of the sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
- <dd><pre>
-[{
-# header
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Delivered,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- </dl>
-
- </div>
</tp:docstring>
-
- <tp:member name="Key" type="s">
- <tp:docstring>
- A key, which SHOULD be one of the well-known keys specified, if
- possible.
- </tp:docstring>
- </tp:member>
-
- <tp:member name="Value" type="v">
- <tp:docstring>
- The value corresponding to the given key, which must be of one of
- the types indicated.
- </tp:docstring>
- </tp:member>
- </tp:mapping>
+ </tp:simple-type>
<tp:simple-type type="u" name="Message_Part_Index"
array-name="Message_Part_Index_List">
@@ -818,7 +865,8 @@ USA.</p>
</tp:member>
</tp:mapping>
- <tp:simple-type type="s" name="Protocol_Message_Token">
+ <tp:simple-type type="s" name="Protocol_Message_Token"
+ array-name="Protocol_Message_Token_List">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An opaque token used to identify messages in the underlying.
protocol. As a special case, the empty string indicates that there
@@ -842,6 +890,23 @@ USA.</p>
</tp:docstring>
</tp:simple-type>
+ <tp:simple-type name="Protocol_Content_Identifier" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A protocol-specific identifier for a blob of content, as used for
+ the <tt>identifier</tt> key in a <tp:type>Message_Part</tp:type>. The
+ same identifier MAY be re-used if the same content, byte-for-byte,
+ appears as a part of several messages.</p>
+
+ <tp:rationale>
+ <p>On XMPP, these identifiers might be Content-IDs for custom
+ smileys implemented using <a
+ href="http://xmpp.org/extensions/xep-0231.html">XEP-0232 Bits of
+ Binary</a>; the same smiley might well appear in multiple
+ messages.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:simple-type>
+
<method name="SendMessage" tp:name-for-bindings="Send_Message">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Submit a message to the server for sending.
@@ -933,28 +998,29 @@ USA.</p>
<p>Signals that a message has been submitted for sending. This
MUST be emitted exactly once per emission of the <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
- signal on the Text interface. This SHOULD be emitted as soon as
- the CM determines it's theoretically possible to send the message
- (e.g. the parameters are supported and correct).</p>
+ signal on the Text interface, for backwards-compatibility; clients
+ SHOULD ignore the latter if this interface is present, as mentioned
+ in the introduction.</p>
+
+ <p>This SHOULD be emitted as soon as the CM determines it's
+ theoretically possible to send the message (e.g. the parameters are
+ supported and correct).</p>
<tp:rationale>
<p>This signal allows a process that is not the caller of
- SendMessage to log sent messages. The double signal-emission
- provides compatibility with older clients. Clients supporting
- Messages should listen for Messages.MessageSent only (if the
- channel has the Messages interface) or Text.Sent only
- (otherwise).</p>
+ SendMessage to log sent messages.</p>
</tp:rationale>
</tp:docstring>
<arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The message content (see <tp:type>Message_Part</tp:type> for full
- details). If the message that was passed to SendMessage has a
- formatted text part that the connection manager recognises, but no
- text/plain alternative, the CM MUST use the formatted text part to
- generate a text/plain alternative which is also included in this
- signal argument.</p>
+ details). If the message that was passed to
+ <tp:member-ref>SendMessage</tp:member-ref> has a formatted text
+ part that the connection manager recognises, but no
+ <tt>text/plain</tt> alternative, the CM MUST use the formatted text
+ part to generate a <tt>text/plain</tt> alternative which is also
+ included in this signal argument.</p>
<p>If the connection manager can predict that the message will be
altered during transmission, this argument SHOULD reflect what
@@ -1078,14 +1144,9 @@ USA.</p>
messages queue. This MUST be emitted exactly once per emission of the
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
- signal on the Text interface.
-
- <tp:rationale>
- The double signal-emission provides compatibility with older
- clients. Clients supporting Messages should listen for
- Messages.MessageReceived only (if the channel has the Messages
- interface) or Text.Received only (otherwise).
- </tp:rationale>
+ signal on the Text interface, for backwards-compatibility; clients
+ SHOULD ignore the latter in favour of this signal if this interface is
+ present, as mentioned in the introduction.
</tp:docstring>
<arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
@@ -1105,7 +1166,8 @@ USA.</p>
should still be signalled as either Temporarily_Failed
or Permanently_Failed). If additional detail is required (e.g.
distinguishing between the various types of permanent failure) this
- will be done using additional keys in the Message_Part.</p>
+ will be done using additional
+ <tp:type>Delivery_Report_Header_Key</tp:type>s.</p>
</tp:docstring>
<tp:enumvalue suffix="Unknown" value="0">
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5315a5503..e3cd6b98a 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -325,9 +325,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enumvalue suffix="Delivery_Report" value="4">
<tp:docstring>
- This message type MUST NOT appear unless the channel supports the
- DeliveryReporting interface. The message MUST be as defined by
- the DeliveryReporting interface.
+ A delivery report. This message type MUST NOT appear unless the
+ channel supports the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref>
+ interface; see <tp:type>Message_Part</tp:type> for the format that
+ delivery reports must take.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index 56f923170..8e5eb3357 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for connections where it is possible to know what channel
@@ -56,6 +57,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
well-defined or consistent, and as far as we know it was never
implemented correctly. This usage is now deprecated.</tp:changed>
+ <tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
+ instead.</tp:deprecated>
+ <tp:changed version="0.19.8">Connection managers implementing
+ Capabilities MUST implement ContactCapabilities too.</tp:changed>
+
<tp:flags name="Connection_Capability_Flags"
value-prefix="Connection_Capability_Flag" type="u">
<tp:flag suffix="Create" value="1">
diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml
index cd5141f8e..f6427806a 100644
--- a/spec/Connection_Interface_Cellular.xml
+++ b/spec/Connection_Interface_Cellular.xml
@@ -21,9 +21,8 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular">
+ <tp:added version="0.19.8">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface is for various cellular things (GSM and/or CDMA) that
@@ -105,6 +104,32 @@
</arg>
</signal>
+ <property name="MessageReducedCharacterSet"
+ tp:name-for-bindings="Message_Reduced_Character_Set"
+ type="b" access="readwrite">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Determines whether SMSes containing characters that do not fit into
+ a 7‐bit GSM character set should be sent as UCS‐2, or lossily
+ recoded. If <code>False</code> (which SHOULD be the default),
+ messages will be sent with no loss of fidelity (at the potential
+ financial cost of using twice as many SMSes); if <code>True</code>,
+ the message will be recoded in an implementation‐specific way to fit
+ into a country‐specific GSM reduced character set.</p>
+
+ <p>Connections with this interface SHOULD provide this property as a
+ parameter for <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager.RequestConnection</tp:dbus-ref>, with the
+ <code>DBus_Property</code> flag.</p>
+
+ <p>For connections managed by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>,
+ this property SHOULD be set via the Account Manager, by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Account.UpdateParameters</tp:dbus-ref>; the AccountManager
+ provides change‐notification, as long as all other clients cooperate
+ by using it instead of setting this property directly.</p>
+ </tp:docstring>
+ </property>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml
index 35465a76f..87ab7528c 100644
--- a/spec/Connection_Interface_Contact_Groups.xml
+++ b/spec/Connection_Interface_Contact_Groups.xml
@@ -21,7 +21,7 @@
<interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT"
tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2"/>
<tp:added version="0.19.6">(draft 1)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -58,7 +58,8 @@
<p>The names of groups of which a contact is a member.</p>
<p>Change notification is via
- <tp:member-ref>GroupsChanged</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref>; clients can also
+ get extra context for group membership changes by receiving
<tp:member-ref>GroupRenamed</tp:member-ref> and
<tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
</tp:docstring>
@@ -73,9 +74,16 @@
empty.</p>
<p>Change notification is via
- <tp:member-ref>GroupsCreated</tp:member-ref>,
- <tp:member-ref>GroupRenamed</tp:member-ref> and
- <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+ <tp:member-ref>GroupsCreated</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref>; clients can also
+ distinguish between a create/remove pair and a renamed group by
+ receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p>
+
+ <p>This property's value is not meaningful until the initial contact
+ list has been received, in protocols where this is applicable.
+ Clients MAY wait for this property to be meaningful by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2"
+ >RequestContactList</tp:dbus-ref>.</p>
</tp:docstring>
</property>
@@ -93,17 +101,32 @@
<signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Emitted when a group is renamed. If the group was not empty,
- immediately after this signal is emitted,
- <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ <p>Emitted when a group is renamed.</p>
+
+ <p>Immediately after this signal is emitted,
+ <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the
+ creation of a group with the new name, and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> MUST signal the
+ removal of a group with the old name.</p>
+
+ <tp:rationale>
+ <p>Emitting these extra signals, in this order, means that clients
+ that are interested in the set of groups that exist (but treat a
+ rename and a create/remove pair identically) to ignore the
+ GroupRenamed signal entirely.</p>
+ </tp:rationale>
+
+ <p>If the group was not empty, immediately after those signals are
+ emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
that the members of that group were removed from the old name
and added to the new name.</p>
- <p>On connection managers where groups behave like tags, this signal
- will probably only be emitted when
- <tp:member-ref>RenameGroup</tp:member-ref> is called, and renaming a
- group from another client MAY be signalled as a
- <tp:member-ref>GroupsChanged</tp:member-ref> signal instead.</p>
+ <p>On connection managers where groups behave like tags, renaming a
+ group MAY be signalled as a set of
+ <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsRemoved</tp:member-ref> and
+ <tp:member-ref>GroupsChanged</tp:member-ref> signals, instead of
+ emitting this signal.</p>
<tp:rationale>
<p>On protocols like XMPP, another resource "renaming a group" is
@@ -121,11 +144,23 @@
</signal>
<signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed">
- <tp:docstring>
- Emitted when one or more groups are removed. If they had members at
- the time that they were removed, then immediately after this signal is
- emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
- that their members were removed.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when one or more groups are removed. If they had members at
+ the time that they were removed, then immediately after this signal
+ is emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ that their members were removed.</p>
+
+ <tp:rationale>
+ <p>Emitting the signals in this order allows for two modes of
+ operation. A client interested only in a contact's set of groups
+ can ignore <tp:member-ref>GroupsRemoved</tp:member-ref> and rely
+ on the <tp:member-ref>GroupsChanged</tp:member-ref> signal that
+ will follow; a more elaborate client wishing to distinguish between
+ all of a group's members being removed, and the group itself
+ being removed, can additionally watch for
+ <tp:member-ref>GroupsRemoved</tp:member-ref> and use it to
+ disambiguate.</p>
+ </tp:rationale>
</tp:docstring>
<arg name="Names" type="as">
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
index 3ded87083..9db86aa2c 100644
--- a/spec/Connection_Interface_Contact_List.xml
+++ b/spec/Connection_Interface_Contact_List.xml
@@ -18,10 +18,10 @@
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2"
tp:causes-havoc="experimental">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:added version="0.19.6">(draft 1)</tp:added>
+ <tp:added version="0.19.8">(draft 2)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for connections that have any concept of a list of
@@ -46,21 +46,23 @@
</tp:rationale>
<p>The list of contacts is not exposed as a D-Bus property; it can be
- fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ fetched using <tp:member-ref>RequestContactList</tp:member-ref>.
</p>
<tp:rationale>
<p>In some protocols, such as XMPP, the contact list may not be
available immediately. The
- <tp:member-ref>GetContactListAttributes</tp:member-ref> method
+ <tp:member-ref>RequestContactList</tp:member-ref> method
will wait until the contact list is available before returning.
Using a method also allows extra attributes to be retrieved at
the same time.</p>
</tp:rationale>
</tp:docstring>
- <method name="GetContactListAttributes"
- tp:name-for-bindings="Get_Contact_List_Attributes">
+ <method name="RequestContactList"
+ tp:name-for-bindings="Request_Contact_List">
+ <tp:changed version="0.19.8">(in draft: renamed from
+ GetContactListAttributes)</tp:changed>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Return some contact attributes for a list of contacts somehow
associated with the user.</p>
@@ -133,16 +135,19 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of strings indicating which D-Bus interfaces the calling
process is interested in. Equivalent to the corresponding argument
- to <tp:dbus-ref
+ to <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
- >GetContactAttributes</tp:dbus-ref>.</p>
+ >GetContactAttributes</tp:dbus-ref>,
+ except that if this list does not contain the ContactList
+ interface itself, it is treated as though that interface was also
+ requested.</p>
</tp:docstring>
</arg>
<arg direction="in" name="Hold" type="b">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Whether to hold the handles on behalf of the calling process.
- Equivalent to the corresponding argument to <tp:dbus-ref
+ Equivalent to the corresponding argument to <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
>GetContactAttributes</tp:dbus-ref>.</p>
@@ -158,7 +163,7 @@
tp:type="Contact_Attributes_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A dictionary mapping the contact handles to contact attributes,
- equivalent to the result of <tp:dbus-ref
+ equivalent to the result of <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
>GetContactAttributes</tp:dbus-ref>.</p>
@@ -223,6 +228,14 @@
indefinitely. On other protocols, only contacts who have been
asked during the current session will ever have Ask status.</p>
</tp:rationale>
+
+ <p>This attribute SHOULD be omitted from the
+ <tp:type>Contact_Attributes_Map</tp:type> returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref> until the initial contact
+ list has been received, in protocols where this is applicable.
+ Clients MAY wait for this by calling
+ <tp:member-ref>RequestContactList</tp:member-ref>.</p>
</tp:docstring>
</tp:contact-attribute>
@@ -256,6 +269,14 @@
indefinitely. On other protocols, only contacts who have asked
during the current session will ever have Ask status.</p>
</tp:rationale>
+
+ <p>This attribute SHOULD be omitted from the
+ <tp:type>Contact_Attributes_Map</tp:type> returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref> until the initial contact
+ list has been received, in protocols where this is applicable.
+ Clients MAY wait for this by calling
+ <tp:member-ref>RequestContactList</tp:member-ref>.</p>
</tp:docstring>
</tp:contact-attribute>
@@ -272,6 +293,13 @@
</tp:rationale>
<p>Otherwise, this SHOULD be omitted.</p>
+
+ <p>This attribute SHOULD be omitted from the
+ <tp:type>Contact_Attributes_Map</tp:type> returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref> until the initial contact
+ list has been received. Clients MAY wait for this by calling
+ <tp:member-ref>RequestContactList</tp:member-ref>.</p>
</tp:docstring>
</tp:contact-attribute>
@@ -472,8 +500,8 @@
<p>Emitted when the contact list becomes available, when contacts'
basic stored properties change, when new contacts are added to the
list that would be returned by
- <tp:member-ref>GetContactListAttributes</tp:member-ref>,
- or when contact are removed from that list.</p>
+ <tp:member-ref>RequestContactList</tp:member-ref>,
+ or when contacts are removed from that list.</p>
<tp:rationale>
<p>This provides change notification for that list, and for
@@ -494,7 +522,7 @@
<tp:docstring>
The contacts that have been removed from the list that would be
returned by
- <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ <tp:member-ref>RequestContactList</tp:member-ref>.
This also implies that they have subscribe = No and publish = No;
contacts MUST NOT be listed both here and in Changes.
</tp:docstring>
@@ -538,7 +566,7 @@
identify the contact in future, and store it using <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
>SetAliases</tp:dbus-ref>.
-
+
The user MAY be
prompted using the contact's current self-assigned nickname, or
something derived from the contact's (presumably self-assigned)
@@ -717,7 +745,7 @@
<p>If possible, this method SHOULD set the contacts' subscribe and
publish attributes to No, remove any stored aliases for those
contacts, and remove the contacts from the result of
- <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ <tp:member-ref>RequestContactList</tp:member-ref>.</p>
<p>This method SHOULD succeed even if it was not possible to carry out
the request entirely or for all contacts (for instance, if there is an
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index d8239e589..2f233fa53 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -550,6 +550,16 @@
available to old or minimal clients SHOULD have a channel class
with the minimum number of Fixed_Properties, and MAY additionally
have channel classes with extra Fixed_Properties.</p>
+
+ <p>Interface designers SHOULD avoid introducing fixed properties
+ whose types are not serializable in a <code>.manager</code>
+ file.</p>
+
+ <tp:rationale>
+ <p>Connection managers with a fixed property that is not
+ serializable cannot have a complete <code>.manager</code>
+ file.</p>
+ </tp:rationale>
</tp:docstring>
</tp:member>
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index c4fecd6fa..0d0bbecb4 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -80,8 +80,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<li>sip - Session Initiation Protocol (SIP), with or without
SIMPLE support</li>
<li>skype - Skype</li>
- <li>tel - telephony (the PSTN, including GSM, CDMA and fixed-line
- telephony)</li>
+ <li>tel - telephony (the
+ <abbr title="Public Switched Telephone Network">PSTN</abbr>,
+ including GSM, CDMA and fixed-line telephony)</li>
<li>trepia - Trepia</li>
<li>yahoo - YMSG (Yahoo! Messenger)</li>
<li>yahoojp - Japanese version of YMSG</li>
@@ -186,10 +187,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
+ <tp:mapping name="Protocol_Properties_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from protocol identifiers supported by a connection
+ manager to the immutable properties of the corresponding
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Protocol.DRAFT</tp:dbus-ref> objects.</p>
+ </tp:docstring>
+
+ <tp:member name="Protocol" type="s" tp:type="Protocol">
+ <tp:docstring>A protocol name</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>The immutable properties of the corresponding
+ Protocol object</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="Protocols" tp:name-for-bindings="Protocols"
+ access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from protocol identifiers supported by this connection
+ manager to the immutable properties of the corresponding
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Protocol.DRAFT</tp:dbus-ref> objects.</p>
+
+ <tp:rationale>
+ <p>Providing the immutable properties here means that
+ when the API of Protocol objects has been finalized,
+ most clients will only need one D-Bus round trip to interrogate
+ the ConnectionManager about all its protocols.</p>
+ </tp:rationale>
+
+ <p>If this map is empty or missing, clients SHOULD fall back to
+ calling <tp:member-ref>ListProtocols</tp:member-ref> and
+ <tp:member-ref>GetParameters</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
<method name="ListProtocols" tp:name-for-bindings="List_Protocols">
<arg direction="out" type="as" tp:type="Protocol[]" name="Protocols">
<tp:docstring>
- A array of string protocol identifiers supported by this manager
+ The keys of the <tp:member-ref>Protocols</tp:member-ref> map.
</tp:docstring>
</arg>
<tp:docstring>
@@ -369,17 +410,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>To be compatible with older connection managers, if retrieving
this property fails, clients SHOULD assume that its value is
an empty list.</p>
+
+ <p>Connection managers with a non-empty list of Interfaces MUST
+ represent them in the <code>.manager</code> file, if they have one,
+ as an <code>Interfaces</code> key in the
+ group headed <code>[ConnectionManager]</code>, whose value is a list
+ of strings each followed by a semicolon.</p>
</tp:docstring>
<tp:added version="0.17.8"/>
</property>
- <!-- FIXME: One thing we could perhaps use Interfaces for would be a
- ConnectionManager.Interface.Capabilities that can give hints regarding
- the capabilities (in the sense of
- Connection.Interface.Requests.AvailableChannelClasses and/or
- Connection.GetInterfaces()) that a Connection from this CM is likely
- to have -->
-
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A D-Bus service which allows connections to be created. The manager
processes are intended to be started by D-Bus service activation.</p>
@@ -436,6 +476,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
a plugin architecture) should not install a <code>.manager</code>
file.</p>
+ <p>The <code>.manager</code> file SHOULD have a group headed
+ <code>[ConnectionManager]</code>, containing a key
+ <code>Interfaces</code> representing
+ <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings
+ each followed by a semicolon (the "localestrings" type from the Desktop
+ Entry Specification).</p>
+
+ <p>The <code>[ConnectionManager]</code> group SHOULD NOT contain keys
+ <code>ObjectPath</code> or <code>BusName</code>. If it does, they MUST
+ be ignored.</p>
+
+ <tp:rationale>
+ <p>The object path and bus name are derivable from the connection
+ manager's name, which is part of the filename, so these keys are
+ redundant. They were required in very old versions of Telepathy.</p>
+ </tp:rationale>
+
<p>For each protocol name <em>proto</em> that would be returned by
ListProtocols, the .manager file contains a group
headed <code>[Protocol <em>proto</em>]</code>. For each parameter
diff --git a/spec/Makefile.am b/spec/Makefile.am
index a1d08d293..fb767e089 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -1,5 +1,6 @@
EXTRA_DIST = \
Account_Interface_Avatar.xml \
+ Account_Interface_Storage.xml \
Account_Manager.xml \
Account.xml \
all.xml \
@@ -79,4 +80,7 @@ EXTRA_DIST = \
Media_Session_Handler.xml \
Media_Stream_Handler.xml \
Properties_Interface.xml \
+ Protocol.xml \
+ Protocol_Interface_Avatars.xml \
+ Protocol_Interface_Presence.xml \
template.xml
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
new file mode 100644
index 000000000..55585b20b
--- /dev/null
+++ b/spec/Protocol.xml
@@ -0,0 +1,370 @@
+<?xml version="1.0" ?>
+<node name="/Protocol"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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="org.freedesktop.Telepathy.Protocol.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.8">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An object representing a protocol for which this <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+ can create <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s.</p>
+
+ <p>Each Protocol object has the same well-known bus name as its parent
+ ConnectionManager. Its object path is formed by taking the
+ ConnectionManager's object path and appending '/', followed by the
+ <tp:type>Protocol</tp:type> name with any hyphen/minus '-' converted
+ to underscores '_'.</p>
+
+ <tp:rationale>
+ <p>This is the same as the representation of protocol names
+ in Account object paths, and in Connection object paths and bus
+ names. For instance, telepathy-gabble and telepathy-salut would
+ implement objects at
+ <code>/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber</code>
+ and
+ <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>,
+ respectively.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ access="read" type="as" tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of interfaces supported by this Protocol object.</p>
+
+ <p>This property is immutable, and should not be confused with
+ <tp:member-ref>ConnectionInterfaces</tp:member-ref>,
+ which refers to the interfaces of <em>connections</em> to this
+ protocol.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ (as described as part of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface) MUST cache this
+ property in the protocol's section of the <code>.manager</code>
+ file, using the key <code>Interfaces</code>. The corresponding value
+ is a list of D-Bus interface names, each followed by a semicolon.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Parameters" tp:name-for-bindings="Parameters"
+ access="read" type="a(susv)" tp:type="Param_Spec[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The parameters which must or may be provided to the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
+ >RequestConnection</tp:dbus-ref> method when connecting to the
+ given protocol. This property is immutable.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ (as described as part of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface) MUST cache this
+ property in the protocol's section of the <code>.manager</code>
+ file via keys of the form <code>param-<em>p</em></code> and
+ <code>default-<em>p</em></code>, as documented in the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionInterfaces"
+ tp:name-for-bindings="Connection_Interfaces"
+ access="read" type="as" tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of interface names which might be in the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection"
+ >Interfaces</tp:dbus-ref> property of a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref> to this protocol. Whether a Connection
+ will have all, some or none of these interfaces depends on server
+ capabilities.</p>
+
+ <p>This property is immutable, and should not be confused with
+ <tp:member-ref>Interfaces</tp:member-ref>.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file, using the key
+ <code>ConnectionInterfaces</code>. The corresponding value
+ is a list of D-Bus interface names, each followed by a semicolon.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RequestableChannelClasses"
+ tp:name-for-bindings="Requestable_Channel_Classes"
+ access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of channel classes which might be requestable from a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref> to this protocol (i.e. they will,
+ or might, appear in the Connection's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref> property).</p>
+
+ <p>Whether a Connection will have all, some or none of these
+ requestable channel classes depends on server capabilities;
+ similarly, individual contacts are not guaranteed to support
+ all of these channel classes.</p>
+
+ <p>This property is immutable.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file, using the key
+ <code>RequestableChannelClasses</code>. The corresponding value
+ is a list of opaque strings, each followed by a semicolon; each
+ of those strings is the name of a group in the <code>.manager</code>
+ file which represents a channel class.</p>
+
+ <p>Each group representing a channel class has a key
+ <code>allowed</code> which is a list of D-Bus property names
+ representing allowed parameters. Any other keys that do not contain
+ a space MUST be ignored. Any key containing a space represents
+ a fixed property; the key has the form
+ "<code><em>propertyname</em> <em>type</em></code>", and the value
+ is encoded in the same way as for the <code>default-<em>p</em></code>
+ keys described in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> documentation.</p>
+
+ <p>Connection managers that have channel classes whose fixed
+ properties are not representable in this form SHOULD NOT have
+ <code>.manager</code> files.</p>
+
+ <p>For instance, this <code>.manager</code> file could represent
+ a simple Text-only connection manager:</p>
+
+<pre>[Protocol jabber]
+param-account=s required
+param-password=s required
+RequestableChannelClasses=text
+
+[text]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+</pre>
+ </tp:docstring>
+ </property>
+
+ <property name="VCardField" tp:name-for-bindings="VCard_Field"
+ access="read" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the most common vCard field used for this protocol's
+ contact identifiers, normalized to lower case, or the empty string
+ if there is no such field.</p>
+
+ <p>For example, this would be <code>x-jabber</code> for
+ Jabber/XMPP (including Google Talk), or <code>tel</code> for
+ the <abbr title="Public Switched Telephone Network">PSTN</abbr>.</p>
+
+ <tp:rationale>
+ <p>This is taken from Mission Control profiles as used on Maemo 5.
+ One valid use of this field is to answer the question: given a
+ contact's vCard containing an X-JABBER field, how can you
+ communicate with the contact? By iterating through protocols
+ looking for an x-jabber VCardField, one can build up a list of
+ protocols that handle x-jabber, then offer the user a list of
+ accounts for those protocols and/or the option to create a new
+ account for one of those protocols.</p>
+
+ <p>It is not necessarily valid to interpret contacts' identifiers
+ as values of this vCard field. For instance, telepathy-sofiasip
+ supports contacts whose identifiers are of the form
+ sip:jenny@example.com or tel:8675309, which would not normally
+ both be represented by any single vCard field. Representing
+ arbitrary handles/identifiers as vCard fields is a topic for
+ future work.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="EnglishName" tp:name-for-bindings="English_Name"
+ access="read" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the protocol in a form suitable for display to users,
+ such as "AIM" or "Yahoo!", or the empty string if none is
+ available.</p>
+
+ <p>This is effectively in the C locale (international English);
+ user interfaces requiring a localized protocol name SHOULD look
+ one up in their own message catalog based on either the Telepathy
+ <tp:type>Protocol</tp:type> name or this property, but SHOULD use
+ this English version as a fallback if no translated version can be
+ found.</p>
+
+ <tp:rationale>
+ <p>Many protocols are named after a company or product which isn't
+ translated in non-English locales. This also provides a fallback
+ display name, for UIs with no prior knowledge of a particular
+ protocol.</p>
+ </tp:rationale>
+
+ <p>If this property's value is empty, clients MAY fall back to using
+ the Telepathy <tp:type>Protocol</tp:type> name, possibly with its
+ capitalization adjusted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Icon" tp:name-for-bindings="Icon"
+ access="read" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of an icon in the system's icon theme, such as "im-msn", or
+ the empty string.</p>
+
+ <tp:rationale>
+ <p>This can be used as a default if the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>
+ property is not set on an Account, or used by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>
+ to choose a default icon if none is set during account
+ creation.</p>
+ </tp:rationale>
+
+ <p>If this property's value is empty, clients MAY fall back to
+ generating a name based on the <tp:type>Protocol</tp:type> name.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="IdentifyAccount"
+ tp:name-for-bindings="Identify_Account">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Return a string which uniquely identifies the account to which the
+ given parameters would connect.</p>
+
+ <tp:rationale>
+ <p>For many protocols, this would return the well-known 'account'
+ parameter. However, for IRC the returned string would be composed
+ from the 'account' (i.e. nickname) and 'server' parameters.
+ AccountManager implementations can use this to form the
+ account-specific part of an Account's object path.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Parameters"
+ type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring>
+ A set of parameters as would be provided to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager"
+ >RequestConnection</tp:dbus-ref>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Account_ID" type="s">
+ <tp:docstring>
+ <p>An opaque string suitable for use as the account-specific part of
+ an <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Account</tp:dbus-ref>'s object path. This is not necessarily
+ globally unique, but should represent a "best-effort"
+ identification of the account.</p>
+
+ <tp:rationale>
+ <p>For a pathological case, consider a user signing in as
+ 'me@example.com' with 'server' set to either jabber1.example.com
+ or jabber2.example.com. Both of these should result in
+ me@example.com being returned from this method, even if the user
+ can actually be signed in to those two servers
+ simultaneously.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The IdentifyAccount method is not supported by this connection
+ manager. The caller SHOULD fall back to deriving identification
+ from the parameters.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="NormalizeContact"
+ tp:name-for-bindings="Normalize_Contact">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to normalize the given contact ID. Where possible, this
+ SHOULD return the same thing that would be returned by
+ InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref>.</p>
+
+ <p>If full normalization requires network activity or is otherwise
+ impossible to do without a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>,
+ this method SHOULD perform a best-effort normalization.</p>
+
+ <tp:rationale>
+ <p>One common example of a best-effort offline normalization
+ differing from the ideal normalization is XMPP.</p>
+
+ <p>On XMPP, contacts' JIDs should normally have the resource removed
+ during normalization, but for contacts in a MUC (chatroom), the
+ resource is an integral part of the JID - so the contact JID
+ alice@example.com/Empathy should normalize to alice@example.com,
+ but the in-MUC JID wonderland@conference.example.com/Alice should
+ normalize to itself.</p>
+
+ <p>While online, the connection manager has enough context to know
+ which chatrooms the user is in, and can infer from that whether
+ to remove resources, but the best-effort normalization performed
+ while offline does not have this context, so the best that can be
+ done is to remove the resource from all JIDs.</p>
+ </tp:rationale>
+
+ <p>This method MAY simply raise NotImplemented on some protocols.</p>
+
+ <tp:rationale>
+ <p>In link-local XMPP, you can't talk to someone who isn't present
+ on your local network, so normalizing identifiers in advance is
+ meaningless.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contact_ID" type="s">
+ <tp:docstring>
+ The identifier of a contact in this protocol
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Normalized_Contact_ID" type="s">
+ <tp:docstring>
+ The identifier of a contact in this protocol, normalized as much
+ as possible
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The NormalizeContact method is not supported by this connection
+ manager. The caller MAY recover by using the contact ID as-is.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml
new file mode 100644
index 000000000..9dc630800
--- /dev/null
+++ b/spec/Protocol_Interface_Avatars.xml
@@ -0,0 +1,158 @@
+<?xml version="1.0" ?>
+<node name="/Protocol_Interface_Avatars"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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="org.freedesktop.Telepathy.Protocol.Interface.Avatars.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.8">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Protocol.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for protocols where it might be possible to set the
+ user's avatar, and the expected size limits and supported MIME types
+ are known before connecting.</p>
+
+ <tp:rationale>
+ <p>If the avatar requirements cannot be discovered while offline,
+ it's impossible to avoid setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Account</tp:dbus-ref>'s <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Avatar"
+ >Avatar</tp:dbus-ref> property to an unsupported avatar.</p>
+ </tp:rationale>
+
+ <p>Each property on this interface SHOULD be cached in the
+ <code>.manager</code> file, using a key of the same name as the
+ property in the <code>[Protocol <em>proto</em>]</code>
+ group. All properties are encoded in ASCII decimal in the obvious
+ way, except for
+ <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is
+ encoded as a sequence of strings each followed by a semicolon
+ (as for the "localestrings" type in the Desktop Entry
+ Specification).</p>
+
+ <p>For instance, an XMPP connection manager might have this
+ <code>.manager</code> file:</p>
+
+<pre>[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars;
+param-account=s required
+param-password=s required
+SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif;
+MinimumAvatarHeight=32
+RecommendedAvatarHeight=64
+MaximumAvatarHeight=96
+MinimumAvatarWidth=32
+RecommendedAvatarWidth=64
+MaximumAvatarWidth=96
+MaximumAvatarBytes=8192
+</pre>
+ </tp:docstring>
+
+ <property name="SupportedAvatarMIMETypes"
+ tp:name-for-bindings="Supported_Avatar_MIME_Types"
+ type="as" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarHeight"
+ tp:name-for-bindings="Minimum_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+</tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarWidth"
+ tp:name-for-bindings="Minimum_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarHeight"
+ tp:name-for-bindings="Recommended_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarWidth"
+ tp:name-for-bindings="Recommended_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarHeight"
+ tp:name-for-bindings="Maximum_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarWidth"
+ tp:name-for-bindings="Maximum_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarBytes"
+ tp:name-for-bindings="Maximum_Avatar_Bytes"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml
new file mode 100644
index 000000000..1ae3cfb6a
--- /dev/null
+++ b/spec/Protocol_Interface_Presence.xml
@@ -0,0 +1,114 @@
+<?xml version="1.0" ?>
+<node name="/Protocol_Interface_Presence"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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="org.freedesktop.Telepathy.Protocol.Interface.Presence.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.8">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Protocol.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for protocols where it might be possible to set the
+ user's presence, and the supported presence types can be predicted
+ before connecting.</p>
+
+ <tp:rationale>
+ <p>This allows UIs to show or hide presence types that aren't
+ always supported, such as "invisible", while not online.</p>
+ </tp:rationale>
+
+ <p>The properties on this interface SHOULD be cached in the
+ <code>.manager</code> file, in the
+ <code>[Protocol <em>proto</em>]</code>
+ group. For each status <em>s</em> in
+ <tp:member-ref>Statuses</tp:member-ref>, that group should
+ contain a key of the form <code>status-<em>s</em></code> whose value
+ is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII
+ decimal integer, followed by a space-separated sequence of tokens
+ from the following set:</p>
+
+ <dl>
+ <dt>settable</dt>
+ <dd>If present, the user can set this status on themselves using
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"
+ >SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self
+ in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd>
+
+ <dt>message</dt>
+ <dd>If present, the user can set a non-empty message for this status;
+ this corresponds to Can_Have_Message in the
+ <tp:type>Simple_Status_Spec</tp:type> struct.</dd>
+ </dl>
+
+ <p>Unrecognised tokens MUST be ignored.</p>
+
+ <p>For instance, an XMPP connection manager might have this
+ <code>.manager</code> file:</p>
+
+<pre>[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence;
+param-account=s required
+param-password=s required
+status-offline=1
+status-unknown=7
+status-error=8
+status-hidden=5 settable message
+status-xa=4 settable message
+status-away=3 settable message
+status-dnd=6 settable message
+status-available=2 settable message
+status-chat=2 settable message
+</pre>
+
+ <p>which corresponds to these property values (using a Python-like
+ syntax):</p>
+
+<pre>Statuses = {
+ 'offline': (OFFLINE, False, False),
+ 'unknown': (UNKNOWN, False, False),
+ 'error': (ERROR, False, False),
+ 'hidden': (HIDDEN, True, True),
+ 'xa': (EXTENDED_AWAY, True, True),
+ 'away': (AWAY, True, True),
+ 'dnd': (BUSY, True, True),
+ 'available': (AVAILABLE, True, True),
+ 'chat': (AVAILABLE, True, True),
+}
+</pre>
+ </tp:docstring>
+
+ <property name="Statuses"
+ tp:name-for-bindings="Statuses"
+ type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read">
+ <tp:docstring>
+ <p>The statuses that might appear in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.SimplePresence.Statuses</tp:dbus-ref>
+ property on a connection to this protocol that supports
+ SimplePresence. This property is immutable.</p>
+
+ <p>Depending on server capabilities, it is possible that not all
+ of these will actually appear on the Connection.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
diff --git a/spec/all.xml b/spec/all.xml
index 700c132ce..44d65347b 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.19.7</tp:version>
+<tp:version>0.19.8</tp:version>
<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
@@ -32,6 +32,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</p>
</tp:docstring>
<xi:include href="Connection_Manager.xml"/>
+ <xi:include href="Protocol.xml"/>
+ <xi:include href="Protocol_Interface_Avatars.xml"/>
+ <xi:include href="Protocol_Interface_Presence.xml"/>
<tp:section name="Connection Object">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -54,11 +57,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Connection_Interface_Contacts.xml"/>
<xi:include href="Connection_Interface_Forwarding.xml"/>
<xi:include href="Connection_Interface_Location.xml"/>
- <xi:include href="Connection_Interface_Service_Point.xml"/>
<xi:include href="Connection_Interface_Mail_Notification.xml"/>
<xi:include href="Connection_Interface_Presence.xml"/>
<xi:include href="Connection_Interface_Renaming.xml"/>
<xi:include href="Connection_Interface_Requests.xml"/>
+ <xi:include href="Connection_Interface_Service_Point.xml"/>
<xi:include href="Connection_Interface_Simple_Presence.xml"/>
</tp:section>
@@ -86,16 +89,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Each Channel implements one of the following types:
</p>
</tp:docstring>
+ <xi:include href="Channel_Type_Call.xml"/>
<xi:include href="Channel_Type_Contact_List.xml"/>
- <xi:include href="Channel_Type_Streamed_Media.xml"/>
+ <xi:include href="Channel_Type_Contact_Search.xml"/>
+ <xi:include href="Channel_Type_DBus_Tube.xml"/>
+ <xi:include href="Channel_Type_File_Transfer.xml"/>
<xi:include href="Channel_Type_Room_List.xml"/>
+ <xi:include href="Channel_Type_Stream_Tube.xml"/>
+ <xi:include href="Channel_Type_Streamed_Media.xml"/>
<xi:include href="Channel_Type_Text.xml"/>
<xi:include href="Channel_Type_Tubes.xml"/>
- <xi:include href="Channel_Type_Stream_Tube.xml"/>
- <xi:include href="Channel_Type_DBus_Tube.xml"/>
- <xi:include href="Channel_Type_File_Transfer.xml"/>
- <xi:include href="Channel_Type_Contact_Search.xml"/>
- <xi:include href="Channel_Type_Call.xml"/>
</tp:section>
<tp:section name="Channel Interfaces">
@@ -109,16 +112,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_Call_State.xml"/>
<xi:include href="Channel_Interface_Chat_State.xml"/>
<xi:include href="Channel_Interface_Conference.xml"/>
- <xi:include href="Channel_Interface_Destroyable.xml"/>
<xi:include href="Channel_Interface_DTMF.xml"/>
+ <xi:include href="Channel_Interface_Destroyable.xml"/>
<xi:include href="Channel_Interface_Group.xml"/>
- <xi:include href="Channel_Interface_Hold.xml"/>
<xi:include href="Channel_Interface_HTML.xml"/>
- <xi:include href="Channel_Interface_Service_Point.xml"/>
- <xi:include href="Channel_Interface_Password.xml"/>
+ <xi:include href="Channel_Interface_Hold.xml"/>
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
<xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
<xi:include href="Channel_Interface_Messages.xml"/>
+ <xi:include href="Channel_Interface_Password.xml"/>
+ <xi:include href="Channel_Interface_Service_Point.xml"/>
<xi:include href="Channel_Interface_Splittable.xml"/>
<xi:include href="Channel_Interface_Tube.xml"/>
</tp:section>
@@ -156,6 +159,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Account_Manager.xml"/>
<xi:include href="Account.xml"/>
<xi:include href="Account_Interface_Avatar.xml"/>
+ <xi:include href="Account_Interface_Storage.xml"/>
</tp:section>
<tp:section name="The Channel Dispatcher">
View Lorry Controller Status