[Telepathy-commits] [telepathy-python/master] Update to spec 0.17.9
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Mon Aug 25 03:49:21 PDT 2008
---
spec/Account.xml | 447 +++++++++++++++++
spec/Account_Interface_Avatar.xml | 65 +++
spec/Account_Manager.xml | 166 +++++++
spec/Channel.xml | 218 ++++++++-
spec/Channel_Bundle.xml | 48 ++
spec/Channel_Future.xml | 184 +++++++
spec/Channel_Handler.xml | 27 +-
spec/Channel_Interface_Call_Merging.xml | 1 +
spec/Channel_Interface_Call_State.xml | 108 +++++
spec/Channel_Interface_DTMF.xml | 9 +-
spec/Channel_Interface_Delivery_Reporting.xml | 442 +++++++++++++++++
spec/Channel_Interface_Group.xml | 260 +++++++++--
spec/Channel_Interface_HTML.xml | 86 ++++
spec/Channel_Interface_Hold.xml | 195 ++++++--
spec/Channel_Interface_Media_Signalling.xml | 26 +-
spec/Channel_Interface_Messages.xml | 635 +++++++++++++++++++++++++
spec/Channel_Type_Contact_List.xml | 6 +-
spec/Channel_Type_Contact_Search.xml | 32 +-
spec/Channel_Type_Room_List.xml | 12 +
spec/Channel_Type_Streamed_Media.xml | 59 ++-
spec/Channel_Type_Text.xml | 154 +++++--
spec/Channel_Type_Tubes.xml | 10 +-
spec/Connection.xml | 181 ++++++-
spec/Connection_Interface_Aliasing.xml | 26 +-
spec/Connection_Interface_Avatars.xml | 24 +-
spec/Connection_Interface_Capabilities.xml | 124 +++--
spec/Connection_Interface_Contacts.xml | 227 +++++++++
spec/Connection_Interface_Presence.xml | 56 ++-
spec/Connection_Interface_Privacy.xml | 2 +-
spec/Connection_Interface_Requests.xml | 400 ++++++++++++++++
spec/Connection_Interface_Simple_Presence.xml | 382 +++++++++++++++
spec/Connection_Manager.xml | 119 ++++-
spec/Media_Stream_Handler.xml | 64 +++-
spec/Properties_Interface.xml | 10 +-
spec/all.xml | 36 +-
spec/generic-types.xml | 59 ++-
36 files changed, 4566 insertions(+), 334 deletions(-)
create mode 100644 spec/Account.xml
create mode 100644 spec/Account_Interface_Avatar.xml
create mode 100644 spec/Account_Manager.xml
create mode 100644 spec/Channel_Bundle.xml
create mode 100644 spec/Channel_Future.xml
create mode 100644 spec/Channel_Interface_Call_State.xml
create mode 100644 spec/Channel_Interface_Delivery_Reporting.xml
create mode 100644 spec/Channel_Interface_HTML.xml
create mode 100644 spec/Channel_Interface_Messages.xml
create mode 100644 spec/Connection_Interface_Contacts.xml
create mode 100644 spec/Connection_Interface_Requests.xml
create mode 100644 spec/Connection_Interface_Simple_Presence.xml
diff --git a/spec/Account.xml b/spec/Account.xml
new file mode 100644
index 0000000..86ff675
--- /dev/null
+++ b/spec/Account.xml
@@ -0,0 +1,447 @@
+<?xml version="1.0" ?>
+<node name="/Account"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An Account object encapsulates the necessary details to make a
+ Telepathy connection.</p>
+
+ <p>Accounts are uniquely identified by object path. The object path
+ of an Account MUST take the form
+ <code>/org/freedesktop/Telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p>
+
+ <ul>
+ <li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type>
+ that appears in the connection manager's well-known bus name and
+ object path</li>
+ <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
+ ConnectionManager.ListProtocols, but with "-" replaced with "_"
+ (i.e. the same as in the object-path of a Connection)</li>
+ <li><em>acct</em> is an arbitrary string of ASCII letters, digits
+ and underscores, starting with a letter or underscore, which
+ uniquely identifies this account</li>
+ <li>Clients SHOULD parse the object path to discover the
+ connection manager and protocol</li>
+ <li>Clients MUST NOT attempt to parse <em>acct</em></li>
+ <li>Clients MUST NOT assume that <em>acct</em> matches
+ the connection-specific part of a Connection's object-path and
+ bus name</li>
+ <li>The account manager SHOULD choose <em>acct</em> such that if
+ an account is deleted, its object path will be re-used if and only
+ if the new account is in some sense "the same"
+ (incorporating the 'account' parameter in some way is
+ recommended)</li>
+ </ul>
+
+ <tp:rationale>
+ <p>This API avoids specifying the "profiles" used in Mission Control
+ 4.x or the "presets" that have been proposed to replace them. An
+ optional interface will be provided for AM implementations
+ that want to provide presets.</p>
+
+ <p>There is deliberately no functionality here for opening channels;
+ we intend to provide that in the channel dispatcher.</p>
+
+ <p>Other missing features which would be better in their own
+ interfaces:</p>
+
+ <ul>
+ <li>dynamic parameter-providing (aka provisioning)</li>
+ <li>saved server capabilities</li>
+ <li>account conditions</li>
+ <li>account grouping</li>
+ </ul>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+ <tp:changed version="0.17.6">moved the Avatar property to a separate
+ interface</tp:changed>
+
+ <!-- Missing functionality compared with NMC 4.x account + profile,
+ apart from as listed above:
+
+ * vCard field, + default profile for each vCard field
+ (vCard field is per protocol and should be chosen by the
+ Telepathy <-> address-book bridge?; default profile is now
+ meaningless)
+
+ * "normalized name" (normalized handle?)
+
+ * branding icon (what's this and how does it differ from the icon?)
+
+ * configuration UI (not our problem - perhaps the UI could special-case
+ by cm,protocol,preset tuples?)
+
+ * default account domain (somewhat meaningless in general; specialized
+ account config UI can hard-code this)
+
+ * SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol,
+ not the profile, and in any case only the account config UI cares)
+
+ Missing functionality compared with Decibel accounts:
+
+ * we don't really know, they take arbitrary key/value pairs...
+ but display name, protocol, presence/message, current, autoreconnect
+ are the ones given special status by the source, and we have all of them
+ -->
+
+ <property name="Interfaces" type="as" access="read">
+ <tp:docstring>
+ A list of the extra interfaces provided by this account.
+ </tp:docstring>
+ </property>
+
+ <method name="Remove">
+ <tp:docstring>Delete the account.</tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Removed">
+ <tp:docstring>
+ This account has been removed.
+
+ <tp:rationale>
+ This is redundant with AccountRemoved, but it's still worth having,
+ to avoid having to bind to AccountManager.AccountRemoved to tell
+ you whether your Account is valid - ideally, an account-editing UI
+ should only care about a single Account.
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ <signal name="AccountPropertyChanged">
+ <tp:docstring>
+ The values of one or more properties on this interface (that do not
+ specify that this signal does not apply to them) may have changed.
+ This does not cover properties of other interfaces, which must
+ provide their own change notification if appropriate.
+ </tp:docstring>
+
+ <arg name="Properties" type="a{sv}">
+ <tp:docstring>
+ A map from property names in this namespace (e.g. Nickname) to
+ values. Properties whose values have not changed SHOULD be
+ omitted, but this need not be done.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="DisplayName" type="s" access="readwrite">
+ <tp:docstring>
+ The user-visible name of this account. This SHOULD be chosen by the
+ user at account creation time. The account creation user interface
+ is responsible for setting a reasonable default value in the user's
+ locale; something like "Jabber (bob at example.com)" would be sensible.
+
+ <tp:rationale>
+ This approximately corresponds to "display name" in NMC 4.x and
+ Decibel.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Icon" type="s" access="readwrite">
+ <tp:docstring>
+ The name of an icon in the system's icon theme, such as "im-msn",
+ or the empty string to not specify an icon. If the icon is set to
+ an empty string, the account manager or any client MAY derive a
+ default icon, for instance from the protocol.
+
+ <tp:rationale>
+ This approximately corresponds to mc_profile_get_icon_name
+ (or possibly mc_profile_get_branding_icon_name) in NMC 4.x.
+ It's accessed via the account rather than the profile because
+ we no longer have profiles as a core concept.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Valid" type="b" access="read">
+ <tp:docstring>
+ If true, this account is considered by the account manager to be
+ complete and usable. If false, user action is required to make it
+ usable, and it will never attempt to connect (for instance, this
+ might be caused by the absence of a required parameter).
+
+ <tp:rationale>
+ For connection managers with a plugin architecture, like
+ telepathy-haze, we have little or no control over the parameters
+ offered; for platforms with package management, we have little or
+ no control over the CMs offered. NMC 4.x would just pretend the
+ account didn't exist in these circumstances, but silent data loss
+ is bad, and UIs with CM-specific knowledge (or a user filling in
+ newly-required parameters) might be able to rescue a broken account.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Enabled" type="b" access="readwrite">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This property gives the users the possibility to prevent an account
+ from being used. This flag does not change the validity of the
+ account.</p>
+
+ <p>A disabled account can never be put online.</p>
+
+ <tp:rationale>
+ <p>Use cases:</p>
+
+ <ul>
+ <li>user has two or more accounts capable of calling contact X, but
+ he doesn't want the UI to prompt him everytime about which one he
+ wants to use for the call. He can then disable all the equivalent
+ accounts but one.</li>
+
+ <li>There is some temporary server error and the user doesn't want
+ to be be bother by error messages, or change the account
+ configuration: temporarily disabling the account is quicker.</li>
+ </ul>
+
+ <p>The AccountManager SHOULD allow this property to be set on invalid
+ accounts, but MUST NOT attempt to put invalid accounts online
+ even if they become Enabled.</p>
+
+ <tp:rationale>
+ <p>There doesn't seem to be any good reason not to allow this.</p>
+ </tp:rationale>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Nickname" type="as" access="readwrite">
+ <tp:docstring>
+ The nickname to set on this account for display to other contacts,
+ as set by the user. When the account becomes connected, the
+ account manager SHOULD set this as the user's alias using SetAliases
+ if appropriate.
+
+ <tp:rationale>
+ In a later specification revision, we plan to separate the concepts
+ of a contact's nickname as set by themselves, and the local
+ name for them in our contact list (a "handle" or "pet name" as
+ described in XEP-0165 and its references). The terminology change
+ from alias to nickname here is a step in that direction.
+ This corresponds to NMC 4.x mc_account_get_alias.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Parameters" type="a{sv}" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from connection manager parameter names (as in the
+ ConnectionManager interface) to their values. This property includes
+ only those parameters that are stored for this account, and SHOULD
+ only include those parameters that the user has explicitly set.
+ </p>
+ <p>This property cannot be altered using Set() - use
+ UpdateParameters instead.</p>
+
+ <tp:rationale>
+ This avoids NMC being tied to gconf as a matter of API.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="UpdateParameters">
+ <tp:docstring>
+ Change the value of the Parameters property. Any changes will not
+ take effect until the next time the account is disconnected and
+ reconnected.
+
+ <tp:rationale>
+ Migration tools that twiddle the settings of all accounts shouldn't
+ cause an automatic disconnect and reconnect, probably. I could be
+ persuaded otherwise, though. Or we could add a Reconnect() method.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Set" type="a{sv}" direction="in">
+ <tp:docstring>
+ A mapping from parameter names to their values. These parameters
+ should be stored for future use.
+ </tp:docstring>
+ </arg>
+ <arg name="Unset" type="as" direction="in">
+ <tp:docstring>
+ A list of the names of parameters to be removed from the set of
+ stored values, allowing the default values to be used.
+ If the given parameters were not, in fact, stored, or even if they
+ do not exist at all, the account manager MUST accept this without
+ error.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="AutomaticPresence" type="(uss)" access="readwrite"
+ tp:type="Simple_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The presence status that this account should have if it is brought
+ online.</p>
+
+ <p>Setting this property MUST NOT actually change the account's
+ status until the next time it is (re)connected for some reason.</p>
+
+ <p>The <tp:type>Connection_Presence_Type</tp:type> in the structure
+ SHOULD NOT be Offline or Unset.</p>
+
+ <tp:rationale>
+ In ITOS2007 and ITOS2008 this is a global preference, not visible
+ on D-Bus (the "default presence"). "Automatic presence" better
+ describes when it is used.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectAutomatically" type="b" access="readwrite">
+ <tp:docstring>
+ If true, the account manager SHOULD attempt to put this account
+ online with the AutomaticPresence whenever possible (in the base
+ Account interface this is deliberately left vague). If false,
+ it MUST NOT put the account online automatically in response to,
+ for instance, connectivity changes, but SHOULD still put the account
+ online with the AutomaticPresence if requested by the user (for
+ instance, if the user tries to start a conversation using this
+ account).
+
+ <tp:rationale>
+ This approximately corresponds to NMC 4.x "enabled" and Decibel
+ "autoreconnect".
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Connection" type="s" access="read">
+ <tp:docstring>
+ Either the well-known bus name of the connection to this account,
+ or the empty string if there is no connection.
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionStatus" type="u" access="read">
+ <tp:docstring>
+ If the Connection property is non-empty, the status of that connection.
+ If the Connection property is the empty string, this property may
+ either be Disconnected (indicating that the account manager is not
+ attempting to bring it online), or Connecting (indicating that the
+ account manager is attempting to connect).
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ If the AM is doing some sort of backoff/delay on reconnection
+ attempts, the account's status is conceptually "Connecting" even
+ though there is no Connection. This vaguely corresponds to
+ GetCurrentStatus in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionStatusReason" type="u" access="read">
+ <tp:docstring>
+ The reason for the last change to ConnectionStatus.
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ If you weren't watching the Connection at the time it failed,
+ you can't tell why - unless the AM can tell you. This is part
+ of GetCurrentStatus in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="CurrentPresence" type="(uss)" access="read"
+ tp:type="Simple_Presence">
+ <tp:docstring>
+ The actual presence. If the connection is not online, this should be
+ (Connection_Presence_Type_Offline, "", "").
+ If the connection is online but does not support the Presence
+ interface, this should be (Connection_Presence_Type_Unset, "", "").
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ This corresponds to GetPresenceActual in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="RequestedPresence" type="(uss)" access="readwrite"
+ tp:type="Simple_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested presence for this account. When this is changed, the
+ account manager should attempt to manipulate the connection manager
+ to make CurrentPresence match RequestedPresence as closely as
+ possible. It should not be saved to any sort of persistent
+ storage.</p>
+
+ <p>When the account manager automatically connects an account,
+ it must signal this by setting the RequestedPresence to the same
+ thing as the AutomaticPresence.</p>
+
+ <tp:rationale>
+ This corresponds to e.g. GetPresence and GetPresenceMessage
+ in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="NormalizedName" type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The normalized user ID of the local user on this account (i.e. the
+ string returned when the InspectHandle method is called on the
+ result of GetSelfHandle() for an active connection).</p>
+
+ <p>It is unspecified whether this user ID is globally unique.</p>
+
+ <tp:rationale>
+ <p>As currently implemented, IRC user IDs are only unique within
+ the same IRCnet. On some saner protocols, the user ID includes a
+ DNS name which provides global uniqueness.</p>
+ </tp:rationale>
+
+ <p>If this value is not known yet (which will always be the case for
+ accounts that have never been online), it will be an empty
+ string.</p>
+
+ <p>It is possible that this value will change if the connection
+ manager's normalization algorithm changes, although this SHOULD
+ be avoided.</p>
+
+ <tp:rationale>
+ <p>It's not always completely clear what normalization algorithm
+ should be used; for instance, in Gabble, we currently use JIDs,
+ but it would also have been reasonable to use xmpp URIs.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml
new file mode 100644
index 0000000..cb58256
--- /dev/null
+++ b/spec/Account_Interface_Avatar.xml
@@ -0,0 +1,65 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Avatar"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.Avatar">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the core Account interface to provide a
+ user-settable avatar image.</p>
+
+ <tp:rationale>
+ <p>The avatar could have been a property on the core Account interface,
+ but was moved to a separate interface because it is likely to be
+ large. This means that clients can safely use GetAll to get
+ properties on the core Account interface without flooding the
+ session bus with large images.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.17.6"/>
+
+ <property name="Avatar" type="(ays)" access="readwrite">
+ <tp:docstring>
+ The avatar to set on this account for display to other contacts,
+ represented as a structure containing the bytes of the avatar,
+ and the MIME type as a string; may be set to an empty byte-array and
+ an empty string to indicate no avatar. When the account becomes
+ connected, the account manager SHOULD set this avatar using SetAvatar
+ if appropriate.
+
+ <tp:rationale>
+ This corresponds to NMC 4.x mc_account_get_avatar.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="AvatarChanged">
+ <tp:docstring>
+ Emitted when the Avatar property changes.
+
+ <tp:rationale>The avatar itself is deliberately not included in this
+ signal, to reduce bus traffic in the (likely common) case where no
+ running application cares about the user's own avatar.</tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
new file mode 100644
index 0000000..a068da3
--- /dev/null
+++ b/spec/Account_Manager.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" ?>
+<node name="/Account_Manager"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.AccountManager">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The account manager is a central service used to store account
+ details.</p>
+
+ <p>The current account manager is defined to be the process that owns
+ the well-known bus name org.freedesktop.Telepathy.AccountManager on
+ the session bus. This process must export an
+ /org/freedesktop/Telepathy/AccountManager object with the
+ AccountManager interface.</p>
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+
+ <!-- Missing functionality compared with NMC 4.x:
+ * look up accounts by conditions (can be done client-side, less
+ efficiently, so not a blocker)
+ * global presence/... changes (can be done client-side, less efficiently -
+ we should add this)
+ * count used channels (what's this for?)
+ * get "average" status (not well-defined, UIs can do this)
+ * request channels (out of scope: Channel Dispatcher will do this)
+ * register filters (completely out of scope: Channel Dispatcher again)
+ -->
+
+ <property name="Interfaces" type="as" access="read">
+ <tp:docstring>
+ A list of the interfaces provided by the account manager object.
+ </tp:docstring>
+ </property>
+
+ <property name="ValidAccounts" type="ao" access="read">
+ <tp:docstring>
+ A list of the valid (complete, usable) accounts. Change notification
+ is via AccountValidityChanged.
+
+ <tp:rationale>
+ This split between valid and invalid accounts makes it easy to
+ ignore the invalid ones. The only things that should be manipulating
+ invalid accounts are account-editing UIs, which might be able to
+ rescue them.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InvalidAccounts" type="ao" access="read">
+ <tp:docstring>
+ A list of incomplete or otherwise unusable accounts. Change
+ notification is via AccountValidityChanged.
+ </tp:docstring>
+ </property>
+
+ <signal name="AccountRemoved">
+ <tp:docstring>
+ The given account has been removed.
+
+ <tp:rationale>
+ This is effectively change notification for the valid and invalid
+ accounts lists.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o">
+ <tp:docstring>
+ An Account, which must not be used any more.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="AccountValidityChanged">
+ <tp:docstring>
+ The validity of the given account has changed. New accounts are
+ also indicated by this signal, as an account validity change
+ (usually to True) on an account that did not previously exist.
+
+ <tp:rationale>
+ This is effectively change notification for the valid and invalid
+ accounts lists.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o">
+ <tp:docstring>
+ An Account.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Valid" type="b">
+ <tp:docstring>
+ True if the account is now valid.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="CreateAccount">
+ <tp:docstring>
+ Request the creation of a new account. The account manager SHOULD NOT
+ allow invalid accounts to be created. Accounts created through this
+ API SHOULD have an empty PresetParameters property.
+ </tp:docstring>
+
+ <arg name="Connection_Manager" direction="in" type="s"
+ tp:type="Connection_Manager_Name">
+ <tp:docstring>
+ The name of the connection manager, e.g. "salut".
+ </tp:docstring>
+ </arg>
+
+ <arg name="Protocol" direction="in" type="s"
+ tp:type="Protocol">
+ <tp:docstring>The protocol, e.g. "local-xmpp".</tp:docstring>
+ </arg>
+
+ <arg name="Display_Name" direction="in" type="s">
+ <tp:docstring>The initial value of the new account's DisplayName
+ property. The account manager MAY modify this to make it unique,
+ for instance by appending a number or the 'account'
+ parameter.</tp:docstring>
+ </arg>
+
+ <arg name="Parameters" direction="in" type="a{sv}">
+ <tp:docstring>Initial parameter values, as would be passed to
+ RequestConnection.</tp:docstring>
+ </arg>
+
+ <arg name="Account" direction="out" type="o">
+ <tp:docstring>The new account.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>The connection manager is not installed or does not
+ implement that protocol.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>The parameters provided omit a required argument
+ or provide unsupported arguments.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 5e8678c..b9b8f3b 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2005, 2006 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2005, 2006 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
@@ -19,6 +19,160 @@ 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.Channel">
+
+ <property name="ChannelType" type="s" tp:type="DBus_Interface"
+ access="read">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel's type. This cannot change once the channel has
+ been created.</p>
+
+ <p>For compatibility between older connection managers and newer
+ clients, if this is unavailable or is an empty string,
+ clients MUST use the result of calling GetChannelType.</p>
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip, which is desirable.
+ </tp:rationale>
+
+ <p>When requesting a channel, the request MUST specify a channel
+ type, and the request MUST fail if the specified channel type
+ cannot be supplied.</p>
+
+ <tp:rationale>
+ Common sense.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Interfaces" type="as" tp:type="DBus_Interface[]"
+ access="read">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this channel. This SHOULD NOT include
+ the channel type and the Channel interface itself, and cannot
+ change once the channel has been created.</p>
+
+ <p>For compatibility between older connection managers and newer
+ clients, if this is unavailable, or if this is an empty list and
+ ChannelType is an empty string, clients MUST use the result of
+ calling GetInterfaces instead. If this is an empty list but
+ ChannelType is non-empty, clients SHOULD NOT call GetInterfaces;
+ this implies that connection managers that implement the
+ ChannelType property MUST also implement the Interfaces property
+ correctly.</p>
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip, which is desirable.
+ </tp:rationale>
+
+ <p>When requesting a channel with a particular value for this
+ property, the request must fail without side-effects unless the
+ connection manager expects to be able to provide a channel whose
+ interfaces include at least the interfaces requested.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetHandle" type="u" access="read" tp:type="Handle">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The handle (a representation for the identifier) of the contact,
+ chatroom, etc. with which this handle communicates. Its type
+ is given by the TargetHandleType property.</p>
+
+ <p>This is fixed for the lifetime of the channel, so channels which
+ could potentially be used to communicate with multiple contacts
+ (such as streamed media calls defined by their members, or ad-hoc
+ chatrooms like MSN switchboards) must have TargetHandleType set
+ to Handle_Type_None and TargetHandle set to 0.</p>
+
+ <p>Unlike in the telepathy-spec 0.16 API, there is no particular
+ uniqueness guarantee - there can be many channels with the same
+ (channel type, handle type, handle) tuple. This is necessary
+ to support conversation threads in XMPP and SIP, for example.</p>
+
+ <p>If this is present in a channel request, it must be nonzero,
+ <tp:member-ref>TargetHandleType</tp:member-ref>
+ MUST be present and not Handle_Type_None, and
+ <tp:member-ref>TargetID</tp:member-ref> MUST NOT be
+ present.</p>
+
+ <p>The channel that satisfies the request MUST either:</p>
+
+ <ul>
+ <li>have the specified TargetHandle property; or</li>
+ <li>have <tp:member-ref>TargetHandleType</tp:member-ref> =
+ Handle_Type_None, TargetHandle = 0, and be configured such that
+ it could communicate with the specified handle in some other way
+ (e.g. have the requested contact handle in its Group
+ interface)</li>
+ </ul>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetID" type="s" access="read">
+ <tp:added version="0.17.9"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the
+ <tp:member-ref>TargetHandle</tp:member-ref>
+ property (i.e. the identifier in the IM protocol of the contact,
+ room, etc. with which this channel communicates), or the empty
+ string if the TargetHandle is 0.</p>
+
+ <tp:rationale>
+ <p>The presence of this property avoids the following race
+ condition:</p>
+
+ <ul>
+ <li>New channel C is signalled with target handle T</li>
+ <li>Client calls InspectHandles(CONTACT, [T])</li>
+ <li>Channel C closes, removing the last reference to handle T</li>
+ <li>InspectHandles(CONTACT, [T]) returns an error</li>
+ </ul>
+ </tp:rationale>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetHandleType</tp:member-ref>
+ MUST be present and not Handle_Type_None, and
+ <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be
+ present. The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested TargetID would not be accepted by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>
+
+ <p>The returned channel must be related to the handle corresponding
+ to the given identifier, in the same way as if TargetHandle
+ had been part of the request instead.</p>
+
+ <tp:rationale>
+ <p>Requesting channels with a string identifier saves a round-trip
+ (the call to RequestHandles). It also allows the channel
+ dispatcher to accept a channel request for an account that is not
+ yet connected (and thus has no valid handles), bring the account
+ online, and pass on the same parameters to the new connection's
+ CreateChannel method.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetHandleType" type="u" access="read"
+ tp:type="Handle_Type">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of TargetHandle.</p>
+
+ <p>If this is omitted from a channel request, connection managers
+ SHOULD treat this as equivalent to Handle_Type_None.</p>
+
+ <p>If this is omitted or is Handle_Type_None,
+ <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the
+ request.</p>
+ </tp:docstring>
+ </property>
+
<method name="Close">
<tp:docstring>
Request that the channel be closed. This is not the case until
@@ -43,6 +197,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<signal name="Closed">
<tp:docstring>
Emitted when the channel has been closed. Method calls on the
@@ -51,34 +206,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
at any point.
</tp:docstring>
</signal>
+
<method name="GetChannelType">
+ <tp:deprecated version="0.17.7">Use the ChannelType
+ property if possible.</tp:deprecated>
<arg direction="out" type="s" tp:type="DBus_Interface">
<tp:docstring>The interface name</tp:docstring>
</arg>
<tp:docstring>
Returns the interface name for the type of this channel.
+ Clients SHOULD use the ChannelType property instead, falling back
+ to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
</tp:docstring>
</method>
+
<method name="GetHandle">
+ <tp:deprecated version="0.17.7">Use the TargetHandleType
+ and TargetHandle properties if possible.</tp:deprecated>
<arg direction="out" type="u" tp:type="Handle_Type">
<tp:docstring>
- The handle type, or zero if this channel does not correspond to any
- particular handle
+ The same as TargetHandleType.
</tp:docstring>
</arg>
<arg direction="out" type="u" tp:type="Handle">
<tp:docstring>
- The handle, or zero if this channel does not correspond to any
- particular handle
+ The same as TargetHandle.
</tp:docstring>
</arg>
<tp:docstring>
Returns the handle type and number if this channel represents a
communication with a particular contact, room or server-stored list, or
- zero if it is transient and defined only by its contents.
+ zero if it is transient and defined only by its contents. Clients
+ SHOULD use the TargetHandle and TargetHandleType properties instead,
+ falling back to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
</tp:docstring>
</method>
+
<method name="GetInterfaces">
+ <tp:deprecated version="0.17.7">Use the Interfaces
+ property if possible.</tp:deprecated>
<arg direction="out" type="as" tp:type="DBus_Interface[]">
<tp:docstring>
An array of the D-Bus interface names
@@ -86,8 +262,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<tp:docstring>
Get the optional interfaces implemented by the channel.
+ Clients SHOULD use the Interfaces property instead, falling back
+ to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
</tp:docstring>
</method>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>All communication in the Telepathy framework is carried out via channel
objects which are created and managed by connections. This interface must
@@ -98,15 +282,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Each channel may have an immutable handle associated with it, which
may be any handle type, such as a contact, room or list handle,
- indicating that the channel is for communicating with that handle.
- There can be at most one channel for each combination of
- (channel type, handle type, handle) with nonzero handle type.</p>
-
- <p>If a channel does not have a handle (an "anonymous channel"), it
+ indicating that the channel is for communicating with that handle.</p>
+
+ <p>If a channel does not have a handle (an "anonymous channel" with
+ Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it
means that the channel is defined by some other terms, such as it
may be a transient group defined only by its members as visible
- through the Channel.Interface.Group interface. There can be any number
- of anonymous channels of the same channel type.</p>
+ through the Channel.Interface.Group interface.</p>
<p>Other optional interfaces can be implemented to indicate other available
functionality, such as Channel.Interface.Group if the channel contains
@@ -126,6 +308,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
methods or signals with conflicting names, the D-Bus interface names should
always be used to invoke methods and bind signals.</p>
</tp:docstring>
+
+ <tp:changed version="0.17.7">Previously we guaranteed that, for
+ any handle type other than Handle_Type_None, and for any channel type
+ and any handle, there would be no more than one channel with that
+ combination of channel type, handle type and handle. This guarantee
+ has now been removed in order to accommodate features like message
+ threads.
+ </tp:changed>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Bundle.xml b/spec/Channel_Bundle.xml
new file mode 100644
index 0000000..0b1a6c1
--- /dev/null
+++ b/spec/Channel_Bundle.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Bundle"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.ChannelBundle.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A group of related channels, which should all be dispatched to the
+ same handler if possible.</p>
+
+ <p>Bundles currently have no functionality of their own, so clients
+ SHOULD NOT examine this interface, but should instead treat the
+ bundle object-path as an opaque identifier. If more functionality is
+ added to bundles in future, this interface will be used for capability
+ discovery.</p>
+
+ <p>The lifetime of a bundle is defined by its component channels -
+ as long as one or more channels whose Bundle property is <em>B</em>
+ exist, the bundle <em>B</em> will also exist.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" type="as" access="read"
+ tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel bundle.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml
new file mode 100644
index 0000000..ad18879
--- /dev/null
+++ b/spec/Channel_Future.xml
@@ -0,0 +1,184 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Future"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.Channel.FUTURE"
+ tp:causes-havoc="a staging area for future Channel functionality">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface contains functionality which we intend to incorporate
+ into the Channel interface in future. It should be considered to
+ be conceptually part of the core Channel interface, but without
+ API or ABI guarantees.</p>
+
+ <tp:rationale>
+ <p>If we add new functionality to the Channel interface, libraries
+ that use generated code (notably telepathy-glib) will have it as
+ part of their ABI forever, meaning we can't make incompatible
+ changes. By using this interface as a staging area for future
+ Channel functionality, we can try out new properties, signals
+ and methods as application-specific extensions, then merge them
+ into the core Channel interface when we have enough implementation
+ experience to declare them to be stable.</p>
+
+ <p>The name is by analogy to Python's <code>__future__</code>
+ pseudo-module.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="Requested" type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel was created in response to a call to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>,
+ or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.DRAFT.CreateChannel</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>The idea of this property is to distinguish between "incoming"
+ and "outgoing" channels, in a way that doesn't break down when
+ considering special cases like contact lists that are automatically
+ created on connection to the server, or chatrooms that an
+ IRC proxy/bouncer like irssi-proxy or bip was already in.</p>
+
+ <p>The reason we want to make that distinction is that UIs for
+ things that the user explicitly requested should start up
+ automatically, whereas for incoming messages and VoIP calls we
+ should first ask the user whether they want to open the messaging
+ UI or accept the call.</p>
+ </tp:rationale>
+
+ <p>If the channel was not explicitly requested (even if it was
+ created as a side-effect of a call to one of those functions,
+ e.g. because joining a Tube in a MUC context on XMPP implies
+ joining that MUC), then this property is false.</p>
+
+ <p>For compatibility with older connection managers, clients SHOULD
+ assume that this property is true if they see a channel announced
+ by the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal with the suppress_handler parameter set to true.</p>
+
+ <tp:rationale>
+ <p>In a correct connection manager, the only way to get such a
+ channel is to request it.</p>
+ </tp:rationale>
+
+ <p>Clients MAY additionally assume that this property is false
+ if they see a channel announced by the NewChannel signal with the
+ suppress_handler parameter set to false.</p>
+
+ <tp:rationale>
+ <p>This is more controversial, since it's possible to get that
+ parameter set to false by requesting a channel. However, there's
+ no good reason to do so, and we've deprecated this practice.</p>
+
+ <p>In the particular case of the channel dispatcher, the only
+ side-effect of wrongly thinking a channel is unrequested
+ is likely to be that the user has to confirm that they want to
+ use it, so it seems fairly harmless to assume in the channel
+ dispatcher that channels with suppress_handler false are
+ indeed unrequested.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
+ access="read">
+ <tp:added version="0.17.7">(in Channel.FUTURE
+ pseudo-interface)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact who initiated the channel. For channels requested by the
+ local user, this MUST be the same thing as would be returned
+ by Connection.GetSelfHandle() at the time the channel was
+ created.</p>
+
+ <tp:rationale>
+ <p>The careful wording about the self-handle is because the Renaming
+ interface can cause the return from Connection.GetSelfHandle to
+ change. It's something of a specification bug that we don't signal
+ this in the Connection interface yet.</p>
+ </tp:rationale>
+
+ <p>For channels requested by a remote user, this MUST be their handle.
+ If unavailable or not applicable, this MUST be 0 (for instance,
+ contact lists are not really initiated by anyone in particular, and
+ it's easy to imagine a protocol where chatroom invitations can be
+ anonymous).</p>
+
+ <p>For channels with the Group interface, this SHOULD be the same
+ contact who is signalled as the "Actor" causing the self-handle
+ to be placed in the local-pending set.</p>
+
+ <p>This SHOULD NOT be a channel-specific handle, if possible.</p>
+
+ <p>It does not make sense for this property to be in channel
+ requests - the initiator will always be the local user - so it
+ MUST NOT be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitiatorID" type="s" access="read">
+ <tp:added version="0.17.7">(in Channel.FUTURE
+ pseudo-interface)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the InitiatorHandle
+ property (i.e. the initiator's identifier in the IM protocol).</p>
+
+ <tp:rationale>
+ <p>The presence of this property avoids the following race
+ condition:</p>
+
+ <ul>
+ <li>New StreamedMedia channel C is signalled with initiator
+ handle I</li>
+ <li>Client calls InspectHandles(CONTACT, [I])</li>
+ <li>Channel C closes, removing the last reference to handle I</li>
+ <li>InspectHandles(CONTACT, [I]) returns an error</li>
+ <li>Client can indicate that a call was missed, but not who
+ called!</li>
+ </ul>
+ </tp:rationale>
+
+ <p>It does not make sense for this property to be in channel
+ requests - the initiator will always be the local user - so it
+ MUST NOT be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Bundle" type="o" access="read">
+ <tp:added version="0.17.9">(in Channel.FUTURE
+ pseudo-interface)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle</tp:dbus-ref>
+ to which this channel belongs.</p>
+
+ <p>A channel's Bundle property can never change.</p>
+
+ <p>Older connection managers might not have this property. Clients
+ (particularly the channel dispatcher) SHOULD recover by considering
+ each channel to be in a bundle containing only that channel,
+ distinct from all other bundles, which has no additional
+ interfaces.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml
index 440ec2a..06b14e8 100644
--- a/spec/Channel_Handler.xml
+++ b/spec/Channel_Handler.xml
@@ -1,6 +1,6 @@
<?xml version="1.0" ?>
<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2007 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2007-2008 Collabora Limited</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
@@ -18,44 +18,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.ChannelHandler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface exported by client applications which are able to
+ handle incoming channels.</p>
+ </tp:docstring>
+ <tp:added version="0.17.0"/>
+
<method name="HandleChannel">
+ <tp:docstring>
+ Called when a channel handler should handle a new channel.
+ </tp:docstring>
+ <tp:added version="0.17.0"/>
+
<arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name">
<tp:docstring>
The bus name of the connection and channel
</tp:docstring>
</arg>
+
<arg direction="in" type="o" name="Connection">
<tp:docstring>
The object-path of the connection that owns the channel
</tp:docstring>
</arg>
+
<arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type">
<tp:docstring>
The channel type
</tp:docstring>
</arg>
+
<arg direction="in" type="o" name="Channel">
<tp:docstring>
The object-path of the channel
</tp:docstring>
</arg>
+
<arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type">
<tp:docstring>The type of the handle that the channel communicates
with, or 0 if there is no associated handle</tp:docstring>
</arg>
+
<arg direction="in" type="u" tp:type="Handle" name="Handle">
<tp:docstring>The handle that the channel communicates with,
or 0 if there is no associated handle</tp:docstring>
</arg>
- <tp:docstring>
- Called when a channel handler should handle a new channel.
- </tp:docstring>
+
<!-- FIXME: possible errors? -->
</method>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>An interface exported by client applications which are able to
- handle incoming channels.</p>
- </tp:docstring>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Call_Merging.xml b/spec/Channel_Interface_Call_Merging.xml
index f34bf99..23f9558 100644
--- a/spec/Channel_Interface_Call_Merging.xml
+++ b/spec/Channel_Interface_Call_Merging.xml
@@ -22,6 +22,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<interface name="org.freedesktop.Telepathy.Channel.Interface.CallMerging"
tp:causes-havoc='not yet API-stable'>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:added version="0.17.1"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Interface for streamed media channels that can be merged and split
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
new file mode 100644
index 0000000..aead16b
--- /dev/null
+++ b/spec/Channel_Interface_Call_State.xml
@@ -0,0 +1,108 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Call_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2008 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
+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.Channel.Interface.CallState">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <tp:docstring>
+ An interface for streamed media channels that can indicate call
+ progress or call states. The presence of this interface is no guarantee
+ that call states will actually be signalled (for instance, SIP
+ implementations are not guaranteed to generate status 180 Ringing,
+ so a call can be accepted without the Ringing flag ever having been set).
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+
+ <method name="GetCallStates">
+ <tp:docstring>
+ Get the current call states for all contacts involved in this call.
+ </tp:docstring>
+
+ <arg tp:type="Channel_Call_State_Map" name="States" direction="out"
+ type="a{uu}">
+ <tp:docstring>
+ The current call states. Participants where the call state flags
+ would be 0 (all unset) may be omitted from this mapping.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="CallStateChanged">
+ <tp:docstring>
+ Emitted when the state of a member of the channel has changed.
+ </tp:docstring>
+
+ <arg name="contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact.
+ </tp:docstring>
+ </arg>
+
+ <arg name="state" type="u" tp:type="Channel_Call_State_Flags">
+ <tp:docstring>
+ The new state for this contact.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:mapping name="Channel_Call_State_Map">
+ <tp:docstring>
+ A map from contacts to call states.
+ </tp:docstring>
+
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact involved in this call.</tp:docstring>
+ </tp:member>
+
+ <tp:member name="State" type="u" tp:type="Channel_Call_State_Flags">
+ <tp:docstring>State flags for the given contact.</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:flags name="Channel_Call_State_Flags" value-prefix="Channel_Call_State" type="u">
+ <tp:docstring>
+ A set of flags representing call states.
+ </tp:docstring>
+
+ <tp:flag suffix="Ringing" value="1">
+ <tp:docstring>
+ The contact has been alerted about the call but has not responded
+ (e.g. 180 Ringing in SIP).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Queued" value="2">
+ <tp:docstring>
+ The contact is temporarily unavailable, and the call has been placed
+ in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Held" value="4">
+ <tp:docstring>
+ The contact has placed the call on hold, and will not receive
+ media from the local user or any other participants until they
+ unhold the call again.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml
index 56ce9c9..c24ec11 100644
--- a/spec/Channel_Interface_DTMF.xml
+++ b/spec/Channel_Interface_DTMF.xml
@@ -20,8 +20,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF">
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
<method name="StartTone">
- <arg direction="in" name="stream_id" type="u">
+ <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID">
<tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
</arg>
<arg direction="in" name="event" type="y" tp:type="DTMF_Event">
@@ -48,8 +49,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="StopTone">
- <arg direction="in" name="stream_id" type="u">
+ <arg direction="in" name="stream_id" type="u" tp:type="Stream_ID">
<tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
</arg>
<tp:docstring>
@@ -70,6 +72,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<tp:enum name="DTMF_Event" type="y">
<tp:enumvalue suffix="Digit_0" value="0">
<tp:docstring>0</tp:docstring>
@@ -120,6 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>D</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An interface that gives a Channel the ability to send DTMF events over
audio streams which have been established using the StreamedMedia channel
@@ -127,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
listed in the DTMF_Event enumeration.
</tp:docstring>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Delivery_Reporting.xml b/spec/Channel_Interface_Delivery_Reporting.xml
new file mode 100644
index 0000000..8d6f797
--- /dev/null
+++ b/spec/Channel_Interface_Delivery_Reporting.xml
@@ -0,0 +1,442 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Delivery_Reporting"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.Channel.Interface.DeliveryReporting.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
+ <tp:added version="0.17.5">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the Text and Messages interfaces with improved
+ sent-message status reporting.</p>
+
+ <p>This interface replaces Text.SendError, adding support for protocols
+ where the message content is not echoed back to the sender on
+ failure. It also adds support for receiving positive
+ acknowledgements, and uses 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 and the Messages interface are both present,
+ clients that support it SHOULD listen for the MessageReceived signal
+ to get delivery reports, and ignore the SendError signal on the Text
+ interface.</p>
+
+ <p>Delivery reports appear as messages of type
+ Channel_Text_Message_Type_Delivery_Report in the Text and Messages
+ interfaces. The message in the Text interface SHOULD have the
+ Non_Text_Content flag.</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>
+
+ <dl>
+ <dt>interface (s - DBus_Interface, as defined in the Messages
+ interface)</dt>
+ <dd>MUST be the name of this interface.</dd>
+
+ <dt>message-sender (u - Contact_Handle, as defined in the Messages
+ interface)</dt>
+ <dd>MUST be the intended recipient of the original message, if
+ available (zero or omitted otherwise), even if the delivery report
+ actually came from an intermediate server.</dd>
+
+ <dt>message-type (u - Channel_Text_Message_Type, as defined in the
+ Messages interface)</dt>
+ <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
+
+ <dt>delivery-status (u - Delivery_Status)</dt>
+ <dd>The status of the message. All delivery reports MUST contain
+ this key in the first Message_Part.</dd>
+
+ <dt>delivery-token (s - Sent_Message_Token)</dt>
+
+ <dd>
+ <p>An identifier for the message to which this delivery report
+ refers. MUST NOT be an empty string. Omitted if not
+ available.</p>
+
+ <p>Clients may match this against the token produced by the
+ SendMessage method and MessageSent signal on the Messages
+ interface. A status report with no token could match any sent
+ message, and a sent message with an empty token could match
+ any status report. If multiple sent messages match, clients
+ SHOULD use some reasonable heuristic.</p>
+
+ <tp:rationale>
+ In an ideal world, we could unambiguously match reports
+ against messages; however, deployed protocols are not ideal,
+ and not all reports and messages can be matched.
+ </tp:rationale>
+ </dd>
+
+ <dt>delivery-error (u - Channel_Text_Send_Error)</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-echo (aa{sv} - Message_Part[])</dt>
+ <dd>
+ <p>The message content, as defined by the Messages interface.
+ Omitted if no content is available. Content MAY have been
+ truncated, message parts MAY have been removed, and message
+ parts MAY have had their content removed (i.e. the message part
+ metadata is present, but the 'content' key is not).</p>
+
+ <tp:rationale>
+ Some protocols, like XMPP, echo the failing message back to
+ the sender. This is sometimes the only way to match it
+ against the sent message, so we include it here.
+ </tp:rationale>
+
+ <p>Unlike in the Messages interface, content not visible
+ in the value for this key cannot be retrieved by another
+ means, so the connection manager SHOULD be more
+ aggressive about including (possibly truncated) message
+ content in the 'content' key.</p>
+
+ <tp:rationale>
+ The Messages interface needs to allow all content to be
+ retrieved, but in this interface, the content we provide is
+ merely a hint; so some is better than none, and it doesn't
+ seem worth providing an API as complex as Messages'
+ GetPendingMessageContent for the echoed message.
+ </tp:rationale>
+ </dd>
+
+ </dl>
+
+ <p>The second and subsequent Message_Part dictionaries, if present,
+ are a human-readable report from the IM service.</p>
+
+ <p>It is an error for this interface to appear on channels of type
+ other than Text, or on Text channels without the Messages interface.
+ Clients MUST recover from this error by ignoring the presence
+ of the DeliveryReporting 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
+'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
+'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
+'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
+'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
+ '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
+'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
+'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
+ 'type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+},
+{ # message from server (alternative in English)
+'alternative': '404',
+'type': 'text/plain',
+'lang': 'en',
+'content': 'I have no contact with that name',
+},
+{ # message from server (alternative in German)
+'alternative': '404'.
+'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
+'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
+'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>
+ </tp:docstring>
+
+ <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" type="u">
+ <tp:docstring>
+ <p>The status of a message as indicated by a delivery report.</p>
+
+ <p>If this enum is extended in future specifications, this should
+ only be to add new, non-overlapping conditions (i.e. all failures
+ 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>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ The message's disposition is unknown.
+ Clients SHOULD consider all messages to have status
+ Delivery_Status_Unknown unless otherwise specified; connection
+ managers SHOULD NOT signal this delivery status explicitly.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Delivered" value="1">
+ <tp:docstring>
+ The message has been delivered to the intended recipient.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Temporarily_Failed" value="2">
+ <tp:docstring>
+ Delivery of the message has failed. Clients SHOULD notify the user,
+ but MAY automatically try sending another copy of the message.
+
+ <tp:rationale>
+ Similar to errors with type="wait" in XMPP; analogous to
+ 4xx errors in SMTP.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Permanently_Failed" value="3">
+ <tp:docstring>
+ Delivery of the message has failed. Clients SHOULD NOT try again
+ unless by specific user action. If the user does not modify the
+ message or alter configuration before re-sending, this error is
+ likely to happen again.
+
+ <tp:rationale>
+ Similar to errors with type="cancel", type="modify"
+ or type="auth" in XMPP; analogous to 5xx errors in SMTP.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:flags name="Delivery_Reporting_Support_Flags"
+ value-prefix="Delivery_Reporting_Support_Flag" type="u">
+ <tp:docstring>
+ Flags indicating the level of support for delivery reporting on this
+ channel. Any future flags added to this set will conform to the
+ convention that the presence of an extra flag implies that
+ more operations will succeed.
+ </tp:docstring>
+
+ <tp:flag suffix="Receive_Failures" value="1">
+ <tp:docstring>
+ Clients MAY expect to receive negative delivery reports if
+ Message_Sending_Flag_Report_Delivery is specified when sending.
+
+ <tp:rationale>
+ If senders want delivery reports, they should ask for them.
+ If they don't want delivery reports, they can just ignore them,
+ so there's no need to have capability discovery for what will
+ happen if a delivery report isn't requested.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Receive_Successes" value="2">
+ <tp:docstring>
+ Clients MAY expect to receive positive delivery reports if
+ Message_Sending_Flag_Report_Delivery is specified when sending.
+
+ <tp:rationale>
+ Same rationale as Receive_Failures.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Send_Failures" value="4">
+ <tp:docstring>
+ Clients MAY expect that sending a negative delivery report will
+ succeed, and will actually get a message to the sender.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Send_Successes" value="8">
+ <tp:docstring>
+ Clients MAY expect that sending a positive delivery report will
+ succeed, and will actually get a message to the sender.
+ </tp:docstring>
+ </tp:flag>
+
+ </tp:flags>
+
+ <property name="DeliveryReportingSupport" access="read"
+ tp:type="Delivery_Reporting_Support_Flags" type="u">
+ <tp:docstring>
+ A bitfield indicating features supported by this channel.
+ </tp:docstring>
+ </property>
+
+ <method name="SendDeliveryReport">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that a delivery report is sent for the specified pending
+ incoming message. Delivery reports cannot currently be sent for
+ messages that have already been acknowledged.</p>
+
+ <tp:rationale>
+ <p>The only use-case I can see for delivery reports on non-pending
+ messages is a "read receipt" like in email's RFC 3798. Delivery
+ reports on non-pending messages will also need a more complex
+ API.</p>
+
+ <p>If they turn out to be needed, we can add a method like
+ SendDeliveryReportByContent(aa{sv}: message) and add a flag to
+ Delivery_Reporting_Support_Flags indicating that this method is
+ implemented.</p>
+ </tp:rationale>
+
+ <p>Clients SHOULD NOT attempt to send delivery reports that are
+ not indicated to be supported using the DeliveryReportingSupport
+ property.</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.</p>
+ </tp:docstring>
+
+ <arg name="Messages" type="au" tp:type="Message_ID[]" direction="in">
+ <tp:docstring>
+ The IDs of one or more unacknowledged messages.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Status" direction="in" type="u" tp:type="Delivery_Status">
+ <tp:docstring>
+ The status to be reported.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reason" direction="in" type="u"
+ tp:type="Channel_Text_Send_Error">
+ <tp:docstring>
+ If the status to be reported is a failure, the reason for that
+ failure. If the status to be reported is not an error, this MUST be
+ Channel_Text_Send_Error_Unknown.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ One of the specified message IDs was invalid. No delivery reports
+ were sent.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested message status could not be reported to the sender
+ (for instance, this will be raised if a positive delivery report
+ is requested on a protocol that only supports negative delivery
+ reports). Clients MUST treat this error as non-fatal.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ This channel cannot report message status back to the sender
+ at all. Do not call this method on this channel again.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 940269a..cab68c5 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -22,15 +22,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List">
- <tp:docstring>A struct (handle to be added, handle of contact
- requesting the change, reason code, optional message)
- representing a contact whose attempt to join a group is to be confirmed
- by the local user, as returned by GetLocalPendingMembersWithInfo
- on the Group interface.</tp:docstring>
- <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added"/>
- <tp:member type="u" tp:type="Contact_Handle" name="Actor"/>
- <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason"/>
- <tp:member type="s" name="Message"/>
+ <tp:docstring>A structure representing a contact whose attempt to
+ join a group is to be confirmed by the local user using
+ AddMembers.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added">
+ <tp:docstring>
+ The contact to be added to the group
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Contact_Handle" name="Actor">
+ <tp:docstring>
+ The contact requesting or causing the change
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason">
+ <tp:docstring>
+ The reason for the change
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Message">
+ <tp:docstring>
+ A human-readable message from the Actor, or an empty string
+ if there is no message
+ </tp:docstring>
+ </tp:member>
</tp:struct>
<method name="AddMembers">
@@ -67,7 +82,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
</tp:possible-errors>
</method>
+
<method name="GetAllMembers">
+ <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
+ Properties D-Bus interface to get properties including Members,
+ RemotePendingMembers and LocalPendingMembers instead, falling back to
+ this method and GetLocalPendingMembers if necessary.</tp:deprecated>
+
<arg direction="out" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
array of handles of current members
@@ -92,6 +113,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
<tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u">
<tp:flag suffix="Can_Add" value="1">
<tp:docstring>
@@ -170,28 +192,115 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:flag suffix="Handle_Owners_Not_Available" value="1024">
<tp:docstring>
In rooms with channel specific handles (ie Channel_Specific_Handles
- flag is set), this flag indicates that none of the handle owners are
- available, and that GetHandleOwners method will always return 0 for
- channel members other than the self handle.
+ flag is set), this flag indicates that no handle owners are
+ available, apart from the owner of the SelfHandle.
+
+ <tp:rationale>
+ This used to be an important optimization to avoid repeated
+ GetHandleOwners calls, before we introduced the HandleOwner
+ property and HandleOwnerChanged signal.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Properties" value="2048">
+ <tp:docstring>
+ This flag indicates that all the properties introduced in
+ specification 0.17.6 are fully supported.
</tp:docstring>
</tp:flag>
</tp:flags>
+
+ <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
+ access="read">
+ <tp:docstring>
+ An integer representing the bitwise-OR of flags on this
+ channel. The user interface can use this to present information about
+ which operations are currently valid. Change notification is via
+ the GroupFlagsChanged signal.
+ </tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetGroupFlags if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+ </property>
+
<method name="GetGroupFlags">
<arg direction="out" type="u" tp:type="Channel_Group_Flags">
<tp:docstring>
- The bitwise OR of zero or more values from ChannelGroupFlags
+ The value of the GroupFlags property
</tp:docstring>
</arg>
<tp:docstring>
- Returns an integer representing the bitwise-OR of flags on this
- channel. The user interface can use this to present information about
- which operations are currently valid.
+ Returns the value of the GroupFlags property.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
+ Properties D-Bus interface to get properties including GroupFlags
+ instead, falling back to this method if necessary.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
+ <tp:mapping name="Handle_Owner_Map">
+ <tp:docstring>
+ A map from channel-specific handles to their owners.
+ </tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetHandleOwners if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+
+ <tp:member type="u" name="Channel_Specific_Handle"
+ tp:type="Contact_Handle">
+ <tp:docstring>
+ A nonzero channel-specific handle
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Global_Handle" tp:type="Contact_Handle">
+ <tp:docstring>
+ The global handle that owns the corresponding channel-specific
+ handle, or 0 if this could not be determined
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map"
+ access="read">
+ <tp:docstring>
+ A map from channel-specific handles to their owners, including
+ at least all of the channel-specific handles in this channel's members,
+ local-pending or remote-pending sets as keys. Any handle not in
+ the keys of this mapping is not channel-specific in this channel.
+ Handles which are channel-specific, but for which the owner is
+ unknown, MUST appear in this mapping with 0 as owner. Change
+ notification is via the HandleOwnersChanged signal.
+ </tp:docstring>
+ <tp:added version="0.17.6"/>
+ </property>
+
+ <signal name="HandleOwnersChanged">
+ <tp:docstring>
+ Emitted whenever the HandleOwners property changes.
+ </tp:docstring>
+ <tp:added version="0.17.6">This signal should not be relied on
+ unless Channel_Group_Flag_Properties is present.</tp:added>
+
+ <arg name="Added" type="a{uu}" tp:type="Handle_Owner_Map">
+ <tp:docstring>
+ A map from channel-specific handles to their owners, in which the
+ keys include all the handles that were added to the keys of the
+ HandleOwners property, and all the handles in that property whose
+ owner has changed
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The channel-specific handles that were removed from the keys of the
+ HandleOwners property, as a result of the contact leaving this group
+ in a previous MembersChanged signal
+ </tp:docstring>
+ </arg>
+ </signal>
+
<method name="GetHandleOwners">
<arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
@@ -213,6 +322,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
the owner of the handle if it can be discovered in this channel,
or 0 if the owner is not available.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Clients should use the
+ HandleOwners property and HandleOwnersChanged signal if
+ Channel_Group_Flag_Properties is present.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -231,24 +343,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="GetLocalPendingMembers">
<arg direction="out" type="au" tp:type="Contact_Handle[]"/>
<tp:docstring>
- Returns an array of handles representing contacts requesting
- channel membership and awaiting local approval with AddMembers.
+ Returns the To_Be_Added handle (only) for each structure in the
+ LocalPendingMembers property.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Use the LocalPendingMembers
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
<method name="GetLocalPendingMembersWithInfo">
<tp:added version="0.15.0" />
<tp:docstring>
- Returns an array of structs containing handles representing contacts
- requesting channel membership and awaiting local approval with
- AddMembers.
+ Returns the LocalPendingMembers property.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Use the LocalPendingMembers
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
<arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]">
<tp:docstring>
An array of structs containing:
@@ -276,42 +392,108 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
+ <property name="LocalPendingMembers" access="read"
+ type="a(uuus)" tp:type="Local_Pending_Info[]">
+ <tp:docstring>
+ An array of structs containing handles representing contacts
+ requesting channel membership and awaiting local approval with
+ AddMembers.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties is
+ not present, clients should fall back to using the
+ deprecated GetLocalPendingMembersWithInfo method, or fall back
+ from that to the deprecated GetAllMembers method.</tp:added>
+ </property>
+
+ <property name="Members" access="read" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The members of this channel.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties
+ is not set, fall back to calling GetAllMembers.</tp:added>
+ </property>
+
<method name="GetMembers">
<arg direction="out" type="au" tp:type="Contact_Handle[]"/>
<tp:docstring>
- Returns an array of handles for the members of this channel.
+ Returns the Members property.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Use the Members
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
+ <property name="RemotePendingMembers" access="read" type="au"
+ tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of handles representing contacts who have been
+ invited to the channel and are awaiting remote approval.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties
+ is not set, fall back to calling GetAllMembers.</tp:added>
+ </property>
+
<method name="GetRemotePendingMembers">
<arg direction="out" type="au" tp:type="Contact_Handle[]"/>
<tp:docstring>
Returns an array of handles representing contacts who have been
invited to the channel and are awaiting remote approval.
</tp:docstring>
+ <tp:deprecated version="0.17.6">Use the RemotePendingMembers
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
- <method name="GetSelfHandle">
- <arg direction="out" type="u" tp:type="Contact_Handle"/>
+
+ <signal name="SelfHandleChanged">
<tp:docstring>
- Returns the handle for the user on this channel (which can also be a
- local or remote pending member) or 0 if the user not a member at all
- (which is likely to be the case, for instance, on Type.ContactList
+ Emitted whenever the SelfHandle property changes.
+ </tp:docstring>
+ <tp:added version="0.17.6">This signal should not be relied on
+ unless Channel_Group_Flag_Properties is present.</tp:added>
+
+ <arg type="u" tp:type="Contact_Handle" name="Self_Handle">
+ <tp:docstring>
+ The new value of the SelfHandle property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SelfHandle" type="u" tp:type="Contact_Handle"
+ access="read">
+ <tp:docstring>
+ The handle for the user on this channel (which can also be a
+ local or remote pending member), or 0 if the user is not a member at
+ all (which is likely to be the case, for instance, on ContactList
channels). Note that this is different from the connection
GetSelfHandle on some protocols, so the value of this handle should
always be used with the methods of this interface.
</tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetSelfHandle if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+ </property>
+
+ <method name="GetSelfHandle">
+ <arg direction="out" type="u" tp:type="Contact_Handle"/>
+ <tp:docstring>
+ Returns the value of the SelfHandle property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Clients should retrieve the
+ SelfHandle property using GetAll instead,
+ if Channel_Group_Flag_Properties is present.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
</tp:possible-errors>
</method>
+
<signal name="GroupFlagsChanged">
<arg name="added" type="u" tp:type="Channel_Group_Flags">
<tp:docstring>
@@ -328,6 +510,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The user interface should be updated as appropriate.
</tp:docstring>
</signal>
+
<tp:enum name="Channel_Group_Change_Reason" type="u">
<tp:enumvalue suffix="None" value="0">
<tp:docstring>
@@ -415,6 +598,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<signal name="MembersChanged">
<arg name="message" type="s">
<tp:docstring>
@@ -453,14 +637,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
ChannelGroupChangeReason
</tp:docstring>
</arg>
- <tp:docstring>
- Emitted when contacts join any of the three lists (members, local
- pending or remote pending). Contacts are listed in the removed
- list when they leave any of the three lists. There may also be
- a message from the server regarding this change, which may be
- displayed to the user if desired.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when contacts join any of the three lists (members, local
+ pending or remote pending) or when they leave any of the three lists.
+ There may also be a message from the server regarding this change,
+ which may be displayed to the user if desired.</p>
+
+ <p>All channel-specific handles that are mentioned in this signal
+ MUST be represented in the value of the HandleOwners property.
+ In practice, this will mean that HandleOwnersChanged is
+ emitted <em>before</em> emitting a MembersChanged signal in which
+ channel-specific handles are added, but that it is emitted
+ <em>after</em> emitting a MembersChanged signal in which
+ channel-specific handles are removed.</p>
</tp:docstring>
</signal>
+
<method name="RemoveMembers">
<arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
@@ -490,6 +682,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
</tp:possible-errors>
</method>
+
<method name="RemoveMembersWithReason">
<arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
@@ -526,6 +719,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Interface for channels which have multiple members, and where the members
of the channel can change during its lifetime. Your presence in the channel
diff --git a/spec/Channel_Interface_HTML.xml b/spec/Channel_Interface_HTML.xml
new file mode 100644
index 0000000..ad86867
--- /dev/null
+++ b/spec/Channel_Interface_HTML.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_HTML"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.Channel.Interface.HTML.DRAFT"
+ tp:causes-havoc="unfinished">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:requires
+ interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
+ <tp:added version="0.17.5">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the Messages interface to support
+ capability discovery, so clients can decide what subset of HTML
+ is supported.</p>
+
+ <p>(However, the capability discovery mechanism has not been written
+ yet, so this interface MUST NOT be used. It exists only to
+ indicate what direction we intend to go in.)</p>
+
+ <tp:rationale>
+ <p>XMPP supports all of XHTML-IM, and SIP (at least theoretically)
+ supports all of XHTML. However, many protocols are more limited -
+ for instance, in MSN you can only set font properties for a
+ whole message at a time. We should not mislead users into thinking
+ they can send MSN messages where individual words are emphasized.</p>
+ </tp:rationale>
+
+ <p>If this interface is present, clients MAY send XHTML formatted text
+ in message parts with type "text/html", and SHOULD interpret
+ "text/html" message parts received in reply.</p>
+
+ <p>Client authors SHOULD pay careful attention to the security
+ considerations in XEP-0071, "XHTML-IM", to avoid exposing client users
+ to security risks. Clients MUST NOT assume that connection managers
+ will filter messages to remove unsafe HTML.</p>
+
+ <tp:rationale>
+ <p>Connection managers are the components in Telepathy that are most
+ likely to be exploitable by a remote attacker to run malicious code
+ (since they are network-facing), so any filtering that the CM does
+ might be subverted.</p>
+ </tp:rationale>
+
+ <p>To avoid misleading users, clients SHOULD only present UI for the
+ subset of HTML that is indicated to be supported by this
+ interface. It follows that clients SHOULD NOT send unsupported
+ markup to the connection manager. However, even if the connection
+ manager cannot send arbitrary XHTML, it MUST cope gracefully
+ with being given arbitrary XHTML by a client.</p>
+
+ <tp:rationale>
+ <p>Connection managers should be lenient in what they receive.</p>
+ </tp:rationale>
+
+ <p>Clients MUST NOT send HTML that is not well-formed XML, but
+ connection managers MAY signal HTML that is malformed or invalid.
+ Clients SHOULD attempt to parse messages as XHTML, but fall back
+ to using a permissive "tag-soup" HTML parser if that fails.
+ (FIXME: or should the presence of this interface imply that the
+ CM fixes up "text/html" to be XHTML? In practice that would result
+ in all the CMs having to link against libxml2 or something... the
+ rationale above no longer applies here, since dropping a malformed
+ message is "safe")</p>
+ </tp:docstring>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml
index 91e72ff..8c5c33b 100644
--- a/spec/Channel_Interface_Hold.xml
+++ b/spec/Channel_Interface_Hold.xml
@@ -19,24 +19,15 @@ License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold"
- tp:causes-havoc='not yet API-stable'>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold">
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:changed version="0.17.4">first API-stable version</tp:changed>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Interface for channels where you or other members may put
- the channel on hold. This only makes sense for channels where
+ <p>Interface for channels where you may put the channel on hold.
+ This only makes sense for channels where
you are streaming media to or from the members.</p>
- <p>If you are placed on hold, this indicates that some or all members
- of the channel will no longer be receiving media streams from you.
- If the channel has the MediaSignalling interface, client applications
- should stop sending media to all members of the channel.</p>
-
- <p>Depending on the protocol, it might not be possible to tell that
- you're on hold, in which case the connection manager should always
- indicate that you're not on hold unless it finds out otherwise.</p>
-
<p>If you place a channel on hold, this indicates that you do not wish
to be sent media streams by any of its members and will be ignoring
any media streams you continue to receive. It also requests that the
@@ -46,76 +37,176 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
another call).</p>
</tp:docstring>
- <tp:enum name="Channel_Hold_State" type="u">
+ <method name="GetHoldState">
<tp:docstring>
- The possible hold states of a call.
+ Return whether the local user has placed the channel on hold.
</tp:docstring>
- <tp:enumvalue suffix="None" value="0">
+
+ <arg name="HoldState" direction="out" type="u"
+ tp:type="Local_Hold_State">
<tp:docstring>
- Neither the local user nor a remote member have placed the call on
- hold.
+ The state of the channel
</tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Local" value="1">
+ </arg>
+
+ <arg name="Reason" direction="out" type="u"
+ tp:type="Local_Hold_State_Reason">
<tp:docstring>
- The local user has put the call on hold.
+ The reason why the channel is in that state
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="HoldStateChanged">
+ <tp:docstring>
+ Emitted to indicate that the hold state has changed for this channel.
+ This may occur as a consequence of you requesting a change with
+ RequestHold, or the state changing as a result of a request from
+ another process.
+ </tp:docstring>
+
+ <arg name="HoldState" type="u" tp:type="Local_Hold_State">
+ <tp:docstring>
+ The state of the channel
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason">
+ <tp:docstring>
+ The reason for the state change
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Local_Hold_State" type="u">
+ <tp:docstring>
+ The hold state of a channel.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="Unheld">
+ <tp:docstring>
+ All streams are unheld (the call is active). New channels SHOULD
+ have this hold state.
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Remote" value="2">
+
+ <tp:enumvalue value="1" suffix="Held">
<tp:docstring>
- The call has been put on hold by a remote member.
+ All streams are held (the call is on hold)
</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="Both" value="3">
+
+ <tp:enumvalue value="2" suffix="Pending_Hold">
<tp:docstring>
- The local user and a remote member have both placed the call
- on hold.
+ The connection manager is attempting to move to state Held, but
+ has not yet completed that operation. It is unspecified whether
+ any, all or none of the streams making up the channel are on hold.
</tp:docstring>
</tp:enumvalue>
- </tp:enum>
- <method name="GetHoldState">
- <arg direction="out" type="u" tp:type="Channel_Hold_State">
+ <tp:enumvalue value="3" suffix="Pending_Unhold">
<tp:docstring>
- The channel's current hold state
+ The connection manager is attempting to move to state Held, but
+ has not yet completed that operation. It is unspecified whether
+ any, all or none of the streams making up the channel are on hold.
</tp:docstring>
- </arg>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Local_Hold_State_Reason" type="u">
<tp:docstring>
- Return the channel's current hold state.
+ The reason for a change to the Local_Hold_State. Clients MUST
+ treat unknown values as equivalent to Local_Hold_State_Reason_None.
</tp:docstring>
- </method>
- <signal name="HoldStateChanged">
- <arg name="state" type="u" tp:type="Channel_Hold_State">
+ <tp:enumvalue value="0" suffix="None">
<tp:docstring>
- An integer representing the new hold state
+ The reason cannot be described by any of the predefined values
+ (connection managers SHOULD avoid this reason, but clients MUST
+ handle it gracefully)
</tp:docstring>
- </arg>
- <tp:docstring>
- Emitted to indicate that the hold state has changed for this channel.
- This may occur as a consequence of you requesting a change with
- RequestHold, or the state changing as a result of a request from a
- remote member or another process.
- </tp:docstring>
- </signal>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Requested">
+ <tp:docstring>
+ The change is in response to a user request
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Resource_Not_Available">
+ <tp:docstring>
+ The change is because some resource was not available
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
<method name="RequestHold">
- <arg direction="in" name="hold" type="b">
+ <arg direction="in" name="Hold" type="b">
<tp:docstring>
A boolean indicating whether or not the channel should be on hold
</tp:docstring>
</arg>
- <tp:docstring>
- Request that the channel be put on hold (be instructed not to send
- any media streams to you) or be taken off hold. Success is indicated
- by the HoldStateChanged signal being emitted and by a successful
- return from this method.
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the channel be put on hold (be instructed not to send
+ any media streams to you) or be taken off hold.</p>
+
+ <p>If the connection manager can immediately tell that the requested
+ state change could not possibly succeed, this method SHOULD
+ return the NotAvailable error. If the requested state is the
+ same as the current state, this method SHOULD return successfully
+ without doing anything.</p>
+
+ <p>Otherwise, this method SHOULD immediately set the hold state to
+ Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold
+ (as appropriate), emitting HoldStateChanged if this is a change,
+ and return successfully.</p>
+
+ <p>The eventual success or failure of the request is indicated by a
+ subsequent HoldStateChanged signal, changing the hold state to
+ Local_Hold_State_Held or Local_Hold_State_Unheld.</p>
+
+ <p>If the channel has multiple streams, and the connection manager
+ succeeds in changing the hold state of one stream but fails to
+ change the hold state of another, it SHOULD attempt to revert
+ all streams to their previous hold states.</p>
+
+ <p>The following state transitions SHOULD be used, where
+ appropriate:</p>
+
+ <ul>
+ <li>Successful hold:
+ (Unheld, any reason) → (Pending_Hold, Requested) →
+ (Held, Requested)
+ </li>
+ <li>Successful unhold:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Unheld, Requested)
+ </li>
+ <li>Attempting to unhold fails at the first attempt to acquire a
+ resource:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Held, Resource_Not_Available)
+ </li>
+ <li>Attempting to unhold acquires one resource, but fails to acquire
+ a second, and takes time to release the first:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Pending_Hold, Resource_Not_Available) →
+ (Held, Resource_Not_Available)
+ </li>
+ </ul>
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested hold state cannot be achieved; for example,
+ if only a limited number of channels can be in the "not on hold"
+ state, attempts to exceed this number will raise NotAvailable.
+ </tp:docstring>
+ </tp:error>
</tp:possible-errors>
</method>
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 6aed7a1..cc7a7a9 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -21,20 +21,39 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <tp:simple-type name="Media_Session_Type" type="s">
+ <tp:docstring>The type of a media session. Currently, the only supported
+ value is "rtp".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="Media_Session_Handler_Info"
+ array-name="Media_Session_Handler_Info_List">
+ <tp:docstring>A struct representing a active session handler.</tp:docstring>
+ <tp:member type="o" name="Session_Handler">
+ <tp:docstring>The object path of the session handler, which is on the
+ same bus name as the channel.</tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type">
+ <tp:docstring>The media session's type</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
<method name="GetSessionHandlers">
- <arg direction="out" type="a(os)"/>
+ <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"/>
<tp:docstring>
Returns all currently active session handlers on this channel
as a list of (session_handler_path, type).
</tp:docstring>
</method>
+
<signal name="NewSessionHandler">
- <arg name="session_handler" type="o">
+ <arg name="Session_Handler" type="o">
<tp:docstring>
Object path of the new MediaSessionHandler object
</tp:docstring>
</arg>
- <arg name="type" type="s">
+ <arg name="Session_Type" tp:type="Media_Session_Type" type="s">
<tp:docstring>
String indicating type of session, eg "rtp"
</tp:docstring>
@@ -81,6 +100,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
server.
</tp:docstring>
</tp:property>
+
<tp:docstring>
An interface for signalling a channel containing synchronised media
sessions which can contain an arbitrary number of streams. The negotiation
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
new file mode 100644
index 0000000..7ba2f8e
--- /dev/null
+++ b/spec/Channel_Interface_Messages.xml
@@ -0,0 +1,635 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Messages"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+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.Channel.Interface.Messages.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:added version="0.17.5">(draft version, not API-stable)</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>
+
+ <ul>
+ <li>messages with attachments (like MIME multipart/mixed)</li>
+ <li>groups of alternatives (like MIME multipart/alternative)</li>
+ <li>delivery reports</li>
+ <li>any extra types of message we need in future</li>
+ </ul>
+
+ <p>It also provides a hook for improved sent
+ message status notification, to be used by the DeliveryReporting
+ 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>
+
+ <p>If this interface is present, clients that support it SHOULD
+ listen for the MessageSent and MessageReceived signals, and
+ ignore the Sent and Received signal on the Text interface
+ (which are guaranteed to duplicate signals from this interface).</p>
+ </tp:docstring>
+
+ <property name="SupportedContentTypes" type="as" access="read">
+ <tp:docstring>
+ A list of MIME types supported by this channel, with more preferred
+ MIME types appearing earlier in the list. The list MAY include "*/*"
+ to indicate that attachments with arbitrary MIME types can be sent.
+ If the list is empty, this indicates that messages may only include
+ a single "text/plain" part.
+ </tp:docstring>
+ </property>
+
+ <property name="MessagePartSupportFlags" type="u"
+ tp:type="Message_Part_Support_Flags"
+ access="read">
+ <tp:docstring>
+ Flags indicating the level of support for message parts on this
+ channel.
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Message_Part_Support_Flags"
+ value-prefix="Message_Part_Support_Flag" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Flags indicating the level of support for message parts on this
+ channel. They are designed such that setting more flags always
+ implies that the channel has more capabilities.</p>
+
+ <p>It is assumed that messages containing a textual message body
+ (only), like the messages the Text interface was designed for, are
+ always supported.</p>
+
+ <p>There is no flag indicating support for alternatives. This is
+ because the SendMessage implementation can always accept messages
+ containing alternatives, even if the underlying protocol does not,
+ by deleting all alternatives except the first (most preferred)
+ that is supported.</p>
+
+ <tp:rationale>
+ Each of the flags 1, 2, 4 implies the previous flag, so we could
+ have used a simple enumeration here; however, we've defined
+ the message-part support indicator as a flag set for future
+ expansion.
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:flag suffix="Data_Only" value="1">
+ <tp:docstring>
+ SendMessage will accept messages containing a single part of any
+ type listed in the SupportedContentTypes property, with no
+ accompanying text.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="One_Attachment" value="2">
+ <tp:docstring>
+ SendMessage will accept messages containing a textual message body,
+ plus a single attachment of any type listed in the
+ SupportedContentTypes property. It does not make sense for this
+ flag to be set if Message_Part_Support_Flag_Data_Only is not also set
+ (because the connection manager can trivially provide an empty text
+ part if necessary).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Multiple_Attachments" value="4">
+ <tp:docstring>
+ SendMessage will accept messages containing a textual message body,
+ plus an arbitrary number of attachments of any type listed in the
+ SupportedContentTypes property. It does not make sense for this
+ flag to be set if Message_Part_Support_Flag_One_Attachment is not
+ also set.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:mapping name="Message_Part" array-name="Message_Part_List">
+ <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>
+
+ <p>An example of how a message might
+ look, in a Python-like syntax:</p>
+
+ <pre>
+[
+ {
+ 'message-sender': 42,
+ 'message-sent': 1210067943,
+ 'message-received': 1210067947,
+ 'message-type': 0,
+ 'pending-message-id': 437,
+ },
+ { 'alternative': 'main',
+ 'type': 'text/html',
+ 'content': 'Here is a photo of my cat:<br />' +
+ '<img src="cid:catphoto" alt="lol!" />' +
+ '<br />Isn't it cute?',
+ },
+ { 'alternative': 'main',
+ 'type': 'text/plain',
+ 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
+ },
+ { 'identifier': 'catphoto',
+ 'type': 'image/jpeg',
+ 'size': 101000,
+ 'needs-retrieval': True,
+ },
+]
+ </pre>
+
+ <div>
+ <p>The first part of the message contains "headers" which refer
+ to the entire message.</p>
+
+ <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>
+
+ <p>Well-known keys for the message as a whole, and the corresponding
+ value types, include:</p>
+
+ <dl>
+ <!-- FIXME: if needed we could add:
+ <dt>message-identifier (s)</dt>
+ <dd>An opaque, globally-unique identifier for the entire message.
+ This MAY be treated as if it were a MIME Message-ID, e.g. for
+ the mid: and cid: URI schemes. If omitted, there is no suitable
+ identifier.</dd>
+ -->
+
+ <dt>message-sent (u - <tp:type>Unix_Timestamp</tp:type>)</dt>
+ <dd>The time the message was sent (if unavailable, the time
+ it arrived at a central server MAY be used). Omitted if no
+ reasonable approximation is available</dd>
+
+ <dt>message-received (u - <tp:type>Unix_Timestamp</tp:type>)</dt>
+ <dd>The time the message was received locally. SHOULD always
+ be present.</dd>
+
+ <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>)</dt>
+ <dd>The contact who sent the message. If 0 or omitted, the contact
+ who sent the message could not be determined.</dd>
+
+ <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>)
+ </dt>
+ <dd>The type of message; if omitted,
+ Channel_Text_Message_Type_Normal MUST be assumed. SHOULD
+ be omitted for normal chat messages.</dd>
+
+ <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt>
+ <dd>The incoming message ID. This MUST NOT be present on outgoing
+ messages. Clients SHOULD NOT store this key - it is only valid
+ for as long as the message remains unacknowledged.</dd>
+
+ <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt>
+ <dd>This message is specific to the given interface, which is
+ neither Text nor Messages. It SHOULD be ignored if that
+ interface is not supported. (Note that an 'interface' key
+ can also appear on the second and subsequent parts, where
+ it indicates that that part (only) should be ignored if
+ unsupported.)</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>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>
+ 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.
+ </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>
+
+ <p>Well-known keys for the second and subsequent parts, and the
+ corresponding value types, include:</p>
+
+ <dl>
+ <dt>identifier (s)</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
+ the cid: URI scheme.</dd>
+
+ <dt>alternative (s)</dt>
+ <dd>
+ <p>If present, this part of the message is an alternative for
+ all other parts with the same value for "alternative".
+ Clients SHOULD only display one of them (this is expected to
+ be used for XHTML messages in a future version of this
+ specification).</p>
+
+ <p>If omitted, this part is not an alternative for any other
+ part.</p>
+
+ <p>Parts of a message MAY reference the group of alternatives
+ as a whole (i.e. a reference to whichever of them is chosen)
+ by treating this identifier as if it were the MIME Content-ID
+ of a multipart/alternative part, and using the cid: URI
+ scheme.</p>
+ </dd>
+
+ <dt>type (s)</dt>
+ <dd>
+ <p>The MIME type of this part. See the documentation
+ for ReceivedMessage for notes on the special status of
+ "text/plain" parts.</p>
+
+ <p>Connection managers MUST NOT signal parts without a 'type'
+ key; if a protocol provides no way to determine the MIME type,
+ the connection manager is responsible for guessing it, but
+ MAY fall back to "text/plain" for text and
+ "application/octet-stream" for non-text.</p>
+
+ <p>Clients MUST ignore parts without a 'type' key, which are
+ reserved for future expansion.</p>
+ </dd>
+
+ <dt>lang (s)</dt>
+ <dd>The natural language of this part, identified by a
+ RFC 3066 language tag.
+
+ <tp:rationale>
+ XMPP allows alternative-selection by language as well as
+ by content-type.
+ </tp:rationale>
+ </dd>
+
+ <dt>size (u)</dt>
+ <dd>The size in bytes (if needs-retrieval is true, this MAY be an
+ estimated or approximate size). SHOULD be omitted if 'content'
+ is provided.
+
+ <tp:rationale>
+ There's no point in providing the size if you're already
+ providing all the content.
+ </tp:rationale>
+ </dd>
+
+ <dt>needs-retrieval (b)</dt>
+ <dd>If false or omitted, the connection
+ manager already holds this part in memory. If present and true,
+ this part will be retrieved on demand (like MIME's
+ message/external-body), so clients should expect retrieval to
+ take time; if this specification is later extended to provide a
+ streaming version of GetPendingMessageContent, clients should
+ use it for parts with this flag.</dd>
+
+ <dt>truncated (b)</dt>
+ <dd>The content available via the 'content' key or
+ GetPendingMessageContent has been truncated by the server
+ or connection manager (equivalent to
+ Channel_Text_Message_Flag_Truncated in the Text interface).
+ </dd>
+
+ <dt>content (s or ay)</dt>
+ <dd>The part's content, if it is available and
+ sufficiently small to include here (implies that
+ 'needs-retrieval' is false or omitted). Otherwise, omitted.
+ If the part is human-readable text or HTML, the value for this
+ key MUST be a UTF-8 string (D-Bus signature 's').
+ If the part is not text, the value MUST be a byte-array
+ (D-Bus signature 'ay'). If the part is a text-based format
+ that is not the main body of the message (e.g. an iCalendar
+ or an attached XML document), the value SHOULD be a UTF-8 string,
+ transcoding from another charset to UTF-8 if necessary, but
+ MAY be a byte-array (of unspecified character set) if
+ transcoding fails or the source charset is not known.</dd>
+
+ <!-- FIXME: "sufficiently small to include" is not currently
+ defined; we should add some API so clients can tell the
+ CM how large a message it should emit in the signal.-->
+
+ <dt>interface (s - <tp:type>DBus_Interface</tp:type>)</dt>
+ <dd>This part is specific to the given interface, which is
+ neither Text nor Messages. It SHOULD be ignored if that
+ interface is not supported. (Note that an 'interface' key
+ can also appear on the first part, where it indicates that the
+ entire message should be ignored if unsupported.)</dd>
+ </dl>
+
+ <p>It is an error for a connection manager to put these keys
+ in the first <tp:type>Message_Part</tp:type>, but clients MUST be
+ able to recover from this error by ignoring these keys in the
+ first part.</p>
+
+ </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 type="s" name="Sent_Message_Token">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An opaque token used to identify sent messages. As a special case,
+ the empty string indicates that there is no particular
+ identification for a message.</p>
+
+ <p>CM implementations SHOULD use an identifier expected to be unique,
+ such as a UUID, if possible.</p>
+
+ <p>Some protocols can only track a limited number of sent messages
+ in a small message-ID space. As a result, clients MUST NOT assume
+ that message tokens will not be re-used, and SHOULD use some
+ reasonable heuristic to assign delivery reports to messages, such
+ as matching on message content or timestamp (if available), or
+ assuming that the delivery report refers to the most recent message
+ with that ID.</p>
+
+ <tp:rationale>
+ <p>This is a hook for the DeliveryReporting interface,
+ to avoid having to introduce a
+ SendMultiPartMessageAndReturnToken method in that interface.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <method name="SendMessage">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Submit a message to the server for sending.
+ If this method returns successfully, the message has been submitted
+ to the server and the MessageSent signal is emitted. A corresponding
+ Sent signal on the Text interface MUST also be emitted.</p>
+
+ <p>If this method fails, message submission to the server has failed
+ and no signal on this interface (or the Text interface) is
+ emitted.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="aa{sv}" tp:type="Message_Part[]"
+ name="Message">
+ <tp:docstring>
+ The message content, including any attachments or alternatives
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Flags" type="u"
+ tp:type="Message_Sending_Flags">
+ <tp:docstring>
+ Flags affecting how the message is sent.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="s" tp:type="Sent_Message_Token">
+ <tp:docstring>
+ An opaque token used to match any incoming delivery or failure
+ reports against this message, or an empty string if the message
+ is not readily identifiable.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The requested message is malformed and cannot be sent.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:flags name="Message_Sending_Flags" value-prefix="Message_Sending_Flag"
+ type="u">
+ <tp:docstring>
+ Flags altering the way a message is sent. The "most usual" action
+ should always be to have these flags unset.
+ </tp:docstring>
+
+ <tp:flag suffix="Report_Delivery" value="1">
+ <tp:docstring>
+ Provide a delivery report via the DeliveryReporting interface, if
+ possible, even if this is not the default for this protocol.
+ Ignored if delivery reports are not possible on this protocol.
+
+ <tp:rationale>
+ In some protocols, like XMPP, it is not conventional to request
+ or send delivery notifications.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <signal name="MessageSent">
+ <tp:docstring>
+ Signals that a message has been submitted for sending. This
+ MUST be emitted exactly once per emission of the Sent signal on the
+ Text interface.
+
+ <tp:rationale>
+ This signal allows a process that is not the caller of
+ SendMessage to log sent messages. The double signal-emission
+ means that clients can safely follow the following rule:
+ if the channel has the Messages interface, listen for
+ Messages.MessageSent only; otherwise, listen for Text.Sent only.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ 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.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message_Token" type="s" tp:type="Sent_Message_Token">
+ <tp:docstring>
+ An opaque token used to match any incoming delivery or failure
+ reports against this message, or an empty string if the message
+ is not readily identifiable.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="PendingMessages" type="aaa{sv}" access="read"
+ tp:type="Message_Part[][]">
+ <tp:docstring>
+ A list of incoming messages that have neither been acknowledged nor
+ rejected. This list is a superset of the one returned by
+ ListPendingMessages on the Text interface; its items can be removed
+ using AcknowledgePendingMessages on that interface.
+ </tp:docstring>
+ </property>
+
+ <signal name="PendingMessagesRemoved">
+ <tp:docstring>
+ The messages with the given IDs have been removed from the
+ PendingMessages list. Clients SHOULD NOT attempt to acknowledge
+ those messages.
+
+ <tp:rationale>
+ This completes change notification for the PendingMessages property
+ (previously, there was change notification when pending messages
+ were added, but not when they were removed).
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Message_IDs" type="au" tp:type="Message_ID[]">
+ <tp:docstring>
+ The messages that have been removed from the pending message list.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="GetPendingMessageContent">
+ <tp:docstring>
+ Retrieve the content of one or more parts of a pending message.
+ Note that this function may take a considerable amount of time
+ to return if the part's 'needs-retrieval' flag is true; consider
+ extending the default D-Bus method call timeout. Additional API is
+ likely to be added in future, to stream large message parts.
+ </tp:docstring>
+
+ <arg name="Message_ID" type="u" tp:type="Message_ID" direction="in">
+ <tp:docstring>
+ The ID of a pending message
+ </tp:docstring>
+ </arg>
+
+ <arg name="Parts" type="au" direction="in">
+ <tp:docstring>
+ The desired entries in the array of message parts, identified by
+ their position. The "headers" part (which is not a valid argument
+ to this method) is considered to be part 0, so the valid part
+ numbers start at 1 (for the second Message_Part).
+ </tp:docstring>
+ </arg>
+
+ <arg name="Content" type="a{uv}" direction="out">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The content of the requested parts. The keys in this mapping
+ are positions in the array of message parts; the values are
+ either of type 's' or 'ay' (UTF-8 text string, or byte array),
+ following the same rules as for the value of the 'content' key in
+ the <tp:type>Message_Part</tp:type> mappings.</p>
+
+ <p>If the one of the requested part numbers was greater than zero
+ but referred to a part that had no content (i.e. it had no 'type'
+ key or no 'content' key), it is simply omitted from this mapping;
+ this is not considered to be an error condition.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Either there is no pending message with the given message ID,
+ or one of the part numbers given was 0 or too large.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="MessageReceived">
+ <tp:docstring>
+ Signals that a message has been received and added to the pending
+ messages queue. This MUST be emitted exactly once per emission of the
+ Received signal on the Text interface.
+
+ <tp:rationale>
+ The double signal-emission means that clients can safely follow
+ the following rule: if the channel has the Messages interface,
+ listen for Messages.MessageReceived only; otherwise, listen for
+ Text.Received only.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The message content, including any attachments or alternatives
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Contact_List.xml b/spec/Channel_Type_Contact_List.xml
index 6e787cc..577f250 100644
--- a/spec/Channel_Type_Contact_List.xml
+++ b/spec/Channel_Type_Contact_List.xml
@@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Type.ContactList">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel type for representing a list of people on the server which is
not used for communication. This is intended for use with the interface
@@ -36,7 +37,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
of this channel type should be created by the connection manager at
connection time if the list exists on the server, or may be requested
by using the appropriate handle. These handles can be obtained using
- RequestHandle with a handle type of HANDLE_TYPE_LIST and
+ RequestHandles with a handle type of HANDLE_TYPE_LIST and
one of the following identifiers:</p>
<ul>
@@ -52,7 +53,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>For user-defined contact groups, instances of this channel type should
be created by the connection manager at connection time for each group
that exists on the server. New, empty groups can be created by calling
- RequestHandle with a handle type of
+ RequestHandles with a handle type of
HANDLE_TYPE_GROUP and with the name set to the
human-readable UTF-8 name of the group.</p>
@@ -64,6 +65,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
server, so disconnecting from the server and reconnecting might cause
empty groups to vanish.</p>
</tp:docstring>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index f3c7fd6..0213ca7 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -21,19 +21,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"
tp:causes-havoc='not well-tested'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:struct name="Search_Key_Info">
+ <tp:docstring>A struct representing details on search strings.</tp:docstring>
+ <tp:member type="b" name="Is_Mandatory">
+ <tp:docstring>Booleans indicating if the search key is mandatory.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="g" name="Type_Signature">
+ <tp:docstring>The type signature of the value for this search key.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Search_Key_Info_Map">
+ <tp:docstring>A dictionary mapping string search key names to its search details.
+ </tp:docstring>
+ <tp:member type="s" name="Term"/>
+ <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
+ </tp:mapping>
+
<method name="GetSearchKeys">
<arg direction="out" type="s">
<tp:docstring>
A string with any instructions from the server
</tp:docstring>
</arg>
- <arg direction="out" type="a{s(bg)}">
+ <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- A dictionary mapping string search key names to an array of:
- <ul>
- <li>booleans indicating if the search key is mandatory</li>
- <li>type signature of the value for this search key</li>
- </ul>
+ A dictionary mapping string search key names to its search details.
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -75,7 +91,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</method>
<method name="Search">
- <arg direction="in" name="terms" type="a{sv}">
+ <arg direction="in" name="terms" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring>
A dictionary mapping search key names to the desired values
</tp:docstring>
@@ -95,7 +111,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<arg name="contact" type="u" tp:type="Contact_Handle">
<tp:docstring>An integer handle for the contact</tp:docstring>
</arg>
- <arg name="values" type="a{sv}">
+ <arg name="values" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
</arg>
<tp:docstring>
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 5b2de13..10261c9 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -27,6 +27,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/>
</tp:struct>
+ <property name="Server" type="s" access="read">
+ <tp:docstring>
+ <p>For protocols with a concept of chatrooms on multiple servers
+ with different DNS names (like XMPP), the DNS name of the server
+ whose rooms are listed by this channel, e.g. "conference.jabber.org".
+ Otherwise, the empty string.</p>
+
+ <p>This property cannot change during the lifetime of the channel.</p>
+ </tp:docstring>
+ </property>
+
<method name="GetListingRooms">
<arg direction="out" type="b">
<tp:docstring>
@@ -38,6 +49,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
on this channel.
</tp:docstring>
</method>
+
<signal name="GotRooms">
<arg name="rooms" type="a(usa{sv})" tp:type="Room_Info[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index d24f37f..0c2eced 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
@@ -21,6 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
+
<tp:enum name="Media_Stream_Type" type="u">
<tp:enumvalue suffix="Audio" value="0">
<tp:docstring>An audio stream</tp:docstring>
@@ -29,6 +30,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>A video stream</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:enum name="Media_Stream_State" type="u">
<tp:enumvalue suffix="Disconnected" value="0">
<tp:docstring>The stream is disconnected.</tp:docstring>
@@ -40,6 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>The stream is connected.</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:enum name="Media_Stream_Direction" type="u">
<tp:enumvalue suffix="None" value="0">
<tp:docstring>Media are not being sent or received</tp:docstring>
@@ -54,6 +57,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>Media are being sent and received</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:flags name="Media_Stream_Pending_Send" value-prefix="Media_Stream_Pending" type="u">
<tp:flag suffix="Local_Send" value="1">
<tp:docstring>
@@ -70,6 +74,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:flag>
</tp:flags>
+
+ <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List">
+ <tp:member type="u" tp:type="Stream_ID" name="Identifier"/>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
+ <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/>
+ <tp:member type="u" tp:type="Media_Stream_State" name="State"/>
+ <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/>
+ <tp:member type="u" tp:type="Media_Stream_Pending_Send"
+ name="Pending_Send_Flags"/>
+ </tp:struct>
+
+ <tp:simple-type name="Stream_ID" type="u"/>
+
<method name="ListStreams">
<arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -91,8 +108,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
which is unique for each stream within the channel.
</tp:docstring>
</method>
+
<method name="RemoveStreams">
- <arg direction="in" name="streams" type="au">
+ <arg direction="in" name="streams" type="au" tp:type="Stream_ID[]">
<tp:docstring>
An array of stream identifiers (as defined in ListStreams)
</tp:docstring>
@@ -106,6 +124,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="RequestStreamDirection">
<arg direction="in" name="stream_id" type="u">
<tp:docstring>
@@ -142,13 +161,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="RequestStreams">
<arg direction="in" name="contact_handle" type="u" tp:type="Contact_Handle">
<tp:docstring>
A contact handle with whom to establish the streams
</tp:docstring>
</arg>
- <arg direction="in" name="types" type="au">
+ <arg direction="in" name="types" type="au" tp:type="Media_Stream_Type[]">
<tp:docstring>
An array of stream types (values of MediaStreamType)
</tp:docstring>
@@ -179,6 +199,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
with the flag cleared when the remote end has replied.</p>
</tp:docstring>
+ <tp:changed version="0.17.2">
+ <p>It is valid to use a handle which is neither
+ a current nor pending member in this channel's Group interface. If
+ so, that handle will be added to the remote-pending set only when
+ an attempt has actually been made to contact them. For further
+ call-state notification, use the CallState interface, if
+ supported. This usage was not allowed in spec versions below
+ 0.17.2.</p>
+ </tp:changed>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
@@ -189,6 +218,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<signal name="StreamAdded">
<arg name="stream_id" type="u">
<tp:docstring>
@@ -210,6 +240,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when a new stream has been added to this channel.
</tp:docstring>
</signal>
+
<signal name="StreamDirectionChanged">
<arg name="stream_id" type="u">
<tp:docstring>
@@ -233,6 +264,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
should be called to indicate whether or not this change is acceptable.
</tp:docstring>
</signal>
+
<signal name="StreamError">
<arg name="stream_id" type="u">
<tp:docstring>
@@ -253,6 +285,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when a stream encounters an error.
</tp:docstring>
</signal>
+
<signal name="StreamRemoved">
<arg name="stream_id" type="u">
<tp:docstring>
@@ -263,6 +296,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when a stream has been removed from this channel.
</tp:docstring>
</signal>
+
<signal name="StreamStateChanged">
<arg name="stream_id" type="u">
<tp:docstring>
@@ -278,6 +312,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when a member's stream's state changes.
</tp:docstring>
</signal>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel that can send and receive streamed media such as audio or video.
Provides a number of methods for listing and requesting new streams, and
@@ -289,8 +324,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
to a contact, clients should request a new, empty streamed media
channel, then call AddMembers to add the contact to the channel.
The local user should be in the group's members, while the contact
- should be in "remote pending" until the call is accepted, then
- move to the group's members.</p>
+ should be absent from the channel until a call is made, appear in
+ "remote pending" from when the call is attempted until the call is
+ accepted, then move to the group's members.</p>
<p>Similarly, incoming calls should be signalled as having handle type 0
and handle 0. The remote contact should be in the group's members,
@@ -306,6 +342,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
connection manager), the signalling interface can be omitted and this
channel type used simply to control the streams.</p>
</tp:docstring>
+
<tp:flags name="Channel_Media_Capabilities" value-prefix="Channel_Media_Capability" type="u">
<tp:docstring>
The channel-type-specific capability flags used for
@@ -335,16 +372,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:flag>
</tp:flags>
- <tp:struct name="Media_Stream_Info" array-name="Media_Stream_Info_List">
- <tp:member type="u" name="Identifier"/>
- <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
- <tp:member type="u" tp:type="Media_Stream_Type" name="Type"/>
- <tp:member type="u" tp:type="Media_Stream_State" name="State"/>
- <tp:member type="u" tp:type="Media_Stream_Direction" name="Direction"/>
- <tp:member type="u" tp:type="Media_Stream_Pending_Send"
- name="Pending_Send_Flags"/>
- </tp:struct>
-
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index b2e0c65..049ed6b 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -21,14 +21,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Type.Text">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:simple-type name="Message_ID" type="u">
+ <tp:docstring>
+ A unique-per-channel identifier for an incoming message. These
+ SHOULD be allocated in a way that minimizes collisions (in particular,
+ message IDs SHOULD NOT be re-used until all of the 32-bit integer
+ space has already been used).
+ </tp:docstring>
+ </tp:simple-type>
+
<tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List">
<tp:docstring>A struct (message ID, timestamp in seconds since
1970-01-01 00:00 UTC, sender's handle, message type, flags, text)
representing a pending text message, as returned by ListPendingMessages
on the Text channel type. The arguments of the Received signal
also match this struct's signature.</tp:docstring>
- <tp:member type="u" name="Message_ID"/>
- <tp:member type="u" name="Unix_Timestamp"/>
+ <tp:member type="u" tp:type="Message_ID" name="Identifier"/>
+ <tp:member type="u" tp:type="Unix_Timestamp" name="Unix_Timestamp"/>
<tp:member type="u" tp:type="Contact_Handle" name="Sender"/>
<tp:member type="u" tp:type="Channel_Text_Message_Type"
name="Message_Type"/>
@@ -37,7 +46,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:struct>
<method name="AcknowledgePendingMessages">
- <arg direction="in" name="ids" type="au">
+ <arg direction="in" name="ids" type="au" tp:type="Message_ID[]">
<tp:docstring>
The IDs of the messages to acknowledge
</tp:docstring>
@@ -48,10 +57,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- A given message ID was not found, so no action was taken
+ <tp:docstring>
+ A given message ID was not found, so no action was taken
+ </tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
+
<method name="GetMessageTypes">
<arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]">
<tp:docstring>
@@ -63,14 +75,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
channel.
</tp:docstring>
</method>
+
<method name="ListPendingMessages">
<arg direction="in" name="clear" type="b">
<tp:docstring>
- If true, remove all messages from the queue
+ If true, behave as if AcknowledgePendingMessages had also been
+ called.
</tp:docstring>
+ <tp:deprecated since="0.17.3">
+ Setting this to true is NOT RECOMMENDED for clients that
+ have some sort of persistent message storage - clients SHOULD only
+ acknowledge messages after they have actually stored them, which is
+ impossible if this flag is true.</tp:deprecated>
</arg>
<arg direction="out" type="a(uuuuus)" tp:type="Pending_Text_Message[]">
- <tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structs representing the pending queue. Each contains:
<ul>
<li>a numeric identifier</li>
@@ -87,6 +106,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
remove then all.
</tp:docstring>
</method>
+
<signal name="LostMessage">
<tp:docstring>
This signal is emitted to indicate that an incoming message was
@@ -94,6 +114,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
due to lack of memory.
</tp:docstring>
</signal>
+
<signal name="Received">
<arg name="id" type="u">
<tp:docstring>
@@ -112,13 +133,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<arg name="type" type="u" tp:type="Channel_Text_Message_Type">
<tp:docstring>
- The type of the message (normal, action, notice, etc), from
- ChannelTextMessageType
+ The type of the message (normal, action, notice, etc.)
</tp:docstring>
</arg>
<arg name="flags" type="u" tp:type="Channel_Text_Message_Flags">
<tp:docstring>
- A bitwise OR of the message flags as defined by ChannelTextMessageFlags
+ A bitwise OR of the message flags
</tp:docstring>
</arg>
<arg name="text" type="s">
@@ -134,11 +154,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
AcknowledgePendingMessage method.
</tp:docstring>
</signal>
+
<method name="Send">
<arg direction="in" name="type" type="u" tp:type="Channel_Text_Message_Type">
<tp:docstring>
- An integer indicating the type of the message, from
- ChannelTextMessageType
+ An integer indicating the type of the message
</tp:docstring>
</arg>
<arg direction="in" name="text" type="s">
@@ -147,8 +167,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</arg>
<tp:docstring>
- Request that a message be sent on this channel. The Sent signal will be
- emitted when the message has been sent, and this method will return.
+ Request that a message be sent on this channel. When the message has
+ been submitted for delivery, this method will return and the Sent
+ signal will be emitted. If the message cannot be submitted for
+ delivery, the method returns an error and no signal is emitted.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -157,6 +179,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
+
<tp:enum name="Channel_Text_Send_Error" type="u">
<tp:enumvalue suffix="Unknown" value="0">
<tp:docstring>
@@ -190,10 +213,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<signal name="SendError">
- <arg name="error" type="u">
+ <arg name="error" type="u" tp:type="Channel_Text_Send_Error">
<tp:docstring>
- One of the values of ChannelTextSendError
+ The error that occurred
</tp:docstring>
</arg>
<arg name="timestamp" type="u" tp:type="Unix_Timestamp">
@@ -203,7 +227,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<arg name="type" type="u" tp:type="Channel_Text_Message_Type">
<tp:docstring>
- The message type from ChannelTextMessageType
+ The message type
</tp:docstring>
</arg>
<arg name="text" type="s">
@@ -211,11 +235,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The text of the message
</tp:docstring>
</arg>
- <tp:docstring>
- Signals that an outgoing message has failed to send. The error
- will be one of the values from ChannelTextSendError.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that an outgoing message has failed to send. The error
+ will be one of the values from ChannelTextSendError.</p>
+
+ <p>This signal should only be emitted for messages for which
+ Sent has already been emitted and Send has already returned
+ success.</p>
</tp:docstring>
+ <tp:changed version="0.17.3">older spec versions claimed that SendError
+ was emitted <em>instead of</em> Sent, rather than <em>in addition
+ to</em> Sent. However, the 0.17.3+ semantics were what we'd always
+ actually implemented.</tp:changed>
</signal>
+
<signal name="Sent">
<arg name="timestamp" type="u" tp:type="Unix_Timestamp">
<tp:docstring>
@@ -234,32 +267,51 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</arg>
<tp:docstring>
- Signals that a message has been sent on this channel.
+ Signals that a message has been submitted for sending.
</tp:docstring>
</signal>
+
<tp:enum name="Channel_Text_Message_Type" type="u">
+ <tp:docstring>
+ The type of message.
+ </tp:docstring>
+
<tp:enumvalue suffix="Normal" value="0">
<tp:docstring>
- A standard message
+ An ordinary chat message. Unknown types SHOULD be treated like this.
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Action" value="1">
<tp:docstring>
An action which might be presented to the user as
- "* <sender> <action>"
+ "* <sender> <action>", such as an IRC CTCP
+ ACTION (typically selected by the "/me" command). For example, the
+ text of the message might be "drinks more coffee".
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Notice" value="2">
<tp:docstring>
A one-off or automated message not necessarily expecting a reply
</tp:docstring>
</tp:enumvalue>
+
<tp:enumvalue suffix="Auto_Reply" value="3">
<tp:docstring>
- An automatically-generated reply message
+ An automatically-generated reply message.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <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.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u">
<tp:flag suffix="Truncated" value="1">
<tp:docstring>
@@ -267,7 +319,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
server or the connection manager.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="Non_Text_Content" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The incoming message contained non-text content which cannot be
+ represented by this interface, but has been signalled
+ in the Messages interface.</p>
+
+ <p>Connection managers SHOULD only set this flag if the non-text
+ content appears to be relatively significant (exactly how
+ significant is up to the implementor). The intention is that
+ if this flag is set, clients using this interface SHOULD inform
+ the user that part of the message was not understood.</p>
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
+
<tp:property name="anonymous" type="b">
<tp:docstring>
True if people may join the channel without other members being made
@@ -343,27 +410,34 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
A unix timestamp indicating when the subject was last modified.
</tp:docstring>
</tp:property>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A channel type for sending and receiving messages in plain text, with no
- formatting.</p>
+ <p>A channel type for sending and receiving messages in plain text,
+ with no formatting. In future specifications, channels for sending
+ and receiving messages that can be reduced to plain text (i.e.
+ formatted text) should also have this type.</p>
- <p>When a message is received, an identifier is assigned and a Received signal
- emitted, and the message placed in a pending queue which can be inspected
- with ListPendingMessages. A client which has handled the message by showing
- it to the user (or equivalent) should acknowledge the receipt using the
- AcknowledgePendingMessage method, and the message will then be removed from
- the pending queue. Numeric identifiers for received messages may be reused
- over the lifetime of the channel.</p>
+ <p>When a message is received, an identifier is assigned and a
+ Received signal emitted, and the message placed in a pending queue
+ which can be inspected with ListPendingMessages. A client which has
+ handled the message by showing it to the user (or equivalent) should
+ acknowledge the receipt using the AcknowledgePendingMessage method,
+ and the message will then be removed from the pending queue. Numeric
+ identifiers for received messages may be reused over the lifetime of
+ the channel.</p>
- <p>Each message has an associated 'type' value, which should be one of the
- values allowed by ChannelTextMessageType.</p>
+ <p>Each message has an associated 'type' value, which should be one
+ of the values allowed by ChannelTextMessageType.</p>
<p>Each message also has a flags value, which is a bitwise OR of the
- flags given in ChannelTextMessageFlags.</p>
+ flags given in ChannelTextMessageFlags.</p>
- <p>Sending messages can be requested using the Send method, which will return
- and cause the Sent signal to be emitted when the message has been delivered
- to the server, or SendError if there is a failure.</p>
+ <p>Sending messages can be requested using the Send method, which will
+ return successfully and emit the Sent signal when the message has
+ been delivered to the server, or return an error with no signal
+ emission if there is a failure. If a message is sent but delivery
+ of the message later fails, this is indicated with the SendError
+ signal.</p>
<p>On protocols where additional contacts cannot be invited into
a one-to-one chat, or where a one-to-one chat is just a series of
@@ -383,7 +457,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>On protocols where a conversation with a user is actually just
a nameless chat room starting with exactly two members, to which
- more members can be invited, calling RequestChannel with type Text
+ more members can be invited, calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
+ with type Text
and handle type CONTACT should continue to succeed, but may return
a channel with handle type 0, handle 0, the group interface,
and the local and remote contacts in its members.</p>
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index c0be619..b187c03 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
- Copyright (C) 2007 Collabora Limited
+ Copyright (C) 2007-2008 Collabora Limited
</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
@@ -47,7 +47,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>A struct (tube ID, initiator handle, tube type,
service name, parameters, state) representing a tube, as returned
by ListTubes on the Tubes channel type.</tp:docstring>
- <tp:member type="u" name="Tube_ID"/>
+ <tp:member type="u" tp:type="Tube_ID" name="Identifier"/>
<tp:member type="u" tp:type="Contact_Handle" name="Initiator"/>
<tp:member type="u" tp:type="Tube_Type" name="Type"/>
<tp:member type="s" name="Service"/>
@@ -350,7 +350,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
D-Bus type, or a byte array 'ay'.
</tp:docstring>
</arg>
- <arg direction="out" type="u">
+ <arg direction="out" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the new tube.
</tp:docstring>
@@ -380,6 +380,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A string representing the service name that will be used over the
tube.
It should be a well-known TCP service name as defined by
+ <a href="http://www.iana.org/assignments/port-numbers">
+ http://www.iana.org/assignments/port-numbers</a> or
<a href="http://www.dns-sd.org/ServiceTypes.html">
http://www.dns-sd.org/ServiceTypes.html</a>, for instance
"rsync" or "daap".
@@ -421,7 +423,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
specified in the documentation for the Socket_Access_Control enum.
</tp:docstring>
</arg>
- <arg direction="out" type="u">
+ <arg direction="out" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the new tube.
</tp:docstring>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index d703ec3..4dac8d0 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -18,7 +18,8 @@ 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>
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+USA.</p>
</tp:license>
<interface name="org.freedesktop.Telepathy.Connection">
@@ -34,7 +35,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
<tp:member type="u" tp:type="Handle_Type" name="Handle_Type">
<tp:docstring>The type of the handle that the channel communicates
- with, or 0 if there is no associated handle</tp:docstring>
+ with, or Handle_Type_None if there is no associated
+ handle</tp:docstring>
</tp:member>
<tp:member type="u" tp:type="Handle" name="Handle">
<tp:docstring>The handle that the channel communicates with,
@@ -48,12 +50,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
asynchronously and errors will be returned by emitting StatusChanged
signals.
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
The connection is already connecting or connected
</tp:error>
</tp:possible-errors>
</method>
+
<method name="Disconnect">
<tp:docstring>
Request that the connection be closed. This closes the connection if
@@ -61,66 +65,106 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
object.
</tp:docstring>
</method>
+
<method name="GetInterfaces">
<arg direction="out" type="as" tp:type="DBus_Interface[]">
<tp:docstring>
An array of D-Bus interface names
</tp:docstring>
</arg>
- <tp:docstring>
- Get the optional interfaces supported by this connection.
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Get the optional interfaces supported by this connection.
+ Before the connection status changes to CONNECTED, the return
+ from this method may change at any time, but it is guaranteed that
+ interfaces will only be added, not removed. After the connection
+ status changes to CONNECTED, the return from this method cannot
+ change further.</p>
+
+ <p>There is no explicit change notification; reasonable behaviour
+ for a client would be to retrieve the interfaces list once
+ initially, and once more when it becomes CONNECTED.</p>
+
+ <tp:rationale>
+ <p>In some connection managers, certain capabilities of a connection
+ are known to be implemented for all connections (e.g. support
+ for SimplePresence), and some interfaces (like SimplePresence) can
+ even be used before connecting. Other capabilities may
+ or may not exist, depending on server functionality; by the time
+ the connection goes CONNECTED, the connection manager is expected
+ to have evaluated the server's functionality and enabled any extra
+ interfaces for the remainder of the Connection's lifetime.</p>
+ </tp:rationale>
</tp:docstring>
+
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
+ <tp:docstring>
+ Before version 0.17.8 calling GetInterfaces while
+ on a connection that is not yet CONNECTED wasn't allowed. If a
+ CM returns this error, its list of interfaces should be regarded
+ as empty until it becomes CONNECTED.
+ </tp:docstring>
+ </tp:error>
</tp:possible-errors>
</method>
+
<method name="GetProtocol">
- <arg direction="out" type="s">
+ <arg direction="out" type="s" tp:type="Protocol">
<tp:docstring>
A string identifier for the protocol
</tp:docstring>
</arg>
+
<tp:docstring>
Get the protocol this connection is using.
</tp:docstring>
</method>
+
<method name="GetSelfHandle">
- <arg direction="out" type="u">
+ <arg direction="out" type="u" tp:type="Contact_Handle">
<tp:docstring>
An integer handle representing the user
</tp:docstring>
</arg>
+
<tp:docstring>
Get the handle which represents the user on this connection, which will
remain valid for the lifetime of this connection, or until a change
in the user's identifier is signalled by the Renamed signal on the
- Renaming interface (if present). This is always a CONTACT type handle.
+ Renaming interface (if present).
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
+
<method name="GetStatus">
<arg direction="out" type="u" tp:type="Connection_Status">
<tp:docstring>
An integer representing the current status
</tp:docstring>
</arg>
+
<tp:docstring>
Get the current status as defined in the StatusChanged signal.
</tp:docstring>
</method>
+
<method name="HoldHandles">
<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle to be held
</tp:docstring>
</arg>
+
<arg direction="in" name="handles" type="au" tp:type="Handle[]">
<tp:docstring>
A array of integer handles to hold
</tp:docstring>
</arg>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Notify the connection manger that your client is holding a copy
of handles which may not be in use in any existing channel or
@@ -138,6 +182,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
ReleaseHandles when none of the cooperating components need the
handle any longer.</p>
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
@@ -148,26 +193,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="InspectHandles">
<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle to be inspected
</tp:docstring>
</arg>
+
<arg direction="in" name="handles" type="au" tp:type="Handle[]">
<tp:docstring>
An array of integer handles of this type
</tp:docstring>
</arg>
+
<arg direction="out" type="as">
<tp:docstring>
An array of handle names in the same order as the given numbers
</tp:docstring>
</arg>
+
<tp:docstring>
Return a string representation for a number of handles of a given
type.
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
@@ -178,99 +228,136 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="ListChannels">
<arg direction="out" type="a(osuu)" tp:type="Channel_Info[]">
<tp:docstring>
An array of structs representing channels.
</tp:docstring>
</arg>
+
<tp:docstring>
List all the channels which currently exist on this connection.
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
+
<signal name="NewChannel">
<arg name="object_path" type="o">
<tp:docstring>
A D-Bus object path for the channel object on this service
</tp:docstring>
</arg>
+
<arg name="channel_type" type="s" tp:type="DBus_Interface">
<tp:docstring>
A D-Bus interface name representing the channel type
</tp:docstring>
</arg>
+
<arg name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
- An integer representing the type of handle this channel communicates with, which is zero if no handle is specified
+ An integer representing the type of handle this channel
+ communicates with, or Handle_Type_None if no handle is specified
</tp:docstring>
</arg>
+
<arg name="handle" type="u" tp:type="Handle">
<tp:docstring>
- A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel
+ A handle indicating the specific contact, room or list this
+ channel communicates with, or zero if no handle is specified
</tp:docstring>
</arg>
+
<arg name="suppress_handler" type="b">
- <tp:docstring>
- A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, the channel was requested by a client that intends to
+ present it to the user itself (i.e. it passed suppress_handler=TRUE
+ to the RequestChannel method), so no other handler should be
+ launched. Clients MAY assume that channels where this is true
+ were created by a user request.</p>
+
+ <p>If false, either the channel was created due to incoming
+ information from the service, or the channel was requested by
+ a local client that does not intend to handle the channel itself
+ (this usage is deprecated).</p>
+
+ <p>Clients MUST NOT assume that only incoming channels will have
+ this flag set to false.</p>
</tp:docstring>
</arg>
+
<tp:docstring>
Emitted when a new Channel object is created, either through user
- request or incoming information from the service. The suppress_handler
- boolean indicates if the channel was requested by an existing client,
- or is an incoming communication and needs to have a handler launched.
+ request or incoming information from the service.
</tp:docstring>
</signal>
+
<method name="ReleaseHandles">
<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
An integer handle type (as defined in RequestHandle)
</tp:docstring>
</arg>
+
<arg direction="in" name="handles" type="au" tp:type="Handle[]">
<tp:docstring>
An array of integer handles being held by the client
</tp:docstring>
</arg>
+
<tp:docstring>
Explicitly notify the connection manager that your client is no
longer holding any references to the given handles, and that they
may be deallocated if they are not held by any other clients or
referenced by any existing channels. See HoldHandles for notes.
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- The handle type is invalid
+ <tp:docstring>
+ The handle type is invalid
+ </tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
- One of the given handles is not valid
+ <tp:docstring>
+ One of the given handles is not valid
+ </tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
- One of the given handles is not held by this client
+ <tp:docstring>
+ One of the given handles is not held by this client
+ </tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
+
<method name="RequestChannel">
<arg direction="in" name="type" type="s" tp:type="DBus_Interface">
<tp:docstring>
A D-Bus interface name representing base channel type
</tp:docstring>
</arg>
+
<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
- An integer representing the handle type, or zero if no handle is being specified
+ An integer representing the handle type, or Handle_Type_None if
+ no handle is specified
</tp:docstring>
</arg>
+
<arg direction="in" name="handle" type="u" tp:type="Handle">
<tp:docstring>
A nonzero integer handle representing a contact, room, list etc.
- according to handle_type, or zero if the handle_type is zero
+ according to handle_type, or zero if the handle_type is
+ Handle_Type_None
</tp:docstring>
</arg>
+
<arg direction="in" name="suppress_handler" type="b">
<tp:docstring>
If true, the requesting client intends to take responsibility for
@@ -278,11 +365,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
be launched
</tp:docstring>
</arg>
+
<arg direction="out" type="o">
<tp:docstring>
The D-Bus object path for the channel created or retrieved
</tp:docstring>
</arg>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Request a channel satisfying the specified type and communicating
with the contact, room, list etc. indicated by the given
@@ -312,6 +401,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>If the request cannot be satisfied, an error is raised and no
channel is created.</p>
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -335,6 +425,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
</tp:possible-errors>
</method>
+
<tp:enum name="Handle_Type" type="u">
<tp:enumvalue suffix="None" value="0">
<tp:docstring>
@@ -364,22 +455,51 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
+ <tp:simple-type name="Handle" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing a
+ handle</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Contact_Handle" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing a handle of type
+ Handle_Type_Contact</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Room_Handle" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing a handle of type
+ Handle_Type_Room</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="List_Handle" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing a handle of type
+ Handle_Type_List</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Group_Handle" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing a handle of type
+ Handle_Type_Group</tp:docstring>
+ </tp:simple-type>
+
<method name="RequestHandles">
<arg direction="in" name="handle_type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle required
</tp:docstring>
</arg>
+
<arg direction="in" name="names" type="as">
<tp:docstring>
An array of names of entities to request handles for
</tp:docstring>
</arg>
+
<arg direction="out" type="au" tp:type="Handle[]">
<tp:docstring>
An array of integer handle numbers in the same order as the given strings
</tp:docstring>
</arg>
+
<tp:docstring>
Request several handles from the connection manager which represent a
number of contacts, rooms or server-stored lists on the service. The
@@ -390,16 +510,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
in this connection manager, this handle should be returned instead.
The handle number 0 must not be returned by the connection manager.
</tp:docstring>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- The handle type is invalid
+ <tp:docstring>
+ The handle type is invalid
+ </tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
- The given name is not a valid entity of the given type
+ <tp:docstring>
+ The given name is not a valid entity of the given type
+ </tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
+
<tp:enum name="Connection_Status" plural="Connection_Statuses" type="u">
<tp:enumvalue suffix="Connected" value="0">
<tp:docstring>
@@ -496,24 +622,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+
<signal name="StatusChanged">
<arg name="status" type="u" tp:type="Connection_Status">
<tp:docstring>
An integer indicating the new status, as defined by ConnectionStatus
</tp:docstring>
</arg>
+
<arg name="reason" type="u" tp:type="Connection_Status_Reason">
<tp:docstring>
An integer indicating the reason for the status change, as defined
by ConnectionStatusReason
</tp:docstring>
</arg>
+
<tp:docstring>
Emitted when the status of the connection changes. All states and
reasons have numerical values, as defined in ConnectionStatus
and ConnectionStatusReason.
</tp:docstring>
</signal>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
@@ -525,9 +655,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
functionality, such as the Connection.Interface.Presence for receiving and
reporting presence information, and Connection.Interface.Aliasing for
connections where contacts may set and change an alias for themselves.
- These interfaces can be discovered using GetInterfaces after the
- connection, has been established and must not change subsequently at
- runtime.</p>
+ These interfaces can be discovered using the
+ <tp:member-ref>GetInterfaces</tp:member-ref> method.</p>
<p>Contacts, rooms, and server-stored lists (such as subscribed contacts,
block lists, or allow lists) on a service are all represented by
@@ -538,7 +667,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Zero as a handle value is sometimes used as a "null" value to mean
the absence of a contact, room, etc.</p>
-
+
<p>Handles have per-type uniqueness, meaning that
every (handle type, handle number) tuple is guaranteed to be unique within
a connection and that a handle alone (without its type) is meaningless or
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
index 900a8b2..5d6eb53 100644
--- a/spec/Connection_Interface_Aliasing.xml
+++ b/spec/Connection_Interface_Aliasing.xml
@@ -103,6 +103,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
</tp:possible-errors>
</method>
+ <method name="GetAliases">
+ <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of handles representing contacts
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a{us}" tp:type="Alias_Map">
+ <tp:docstring>
+ A dictionary mapping contact handles to aliases
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request the value of several contacts' aliases at once. This SHOULD
+ only return cached aliases, falling back on the handle name if none is
+ present. Also if there was no cached alias, a request SHOULD be started
+ of which the result is later signalled by
+ <tp:member-ref>AliasesChanged</tp:member-ref>.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
<method name="SetAliases">
<arg direction="in" name="aliases" type="a{us}" tp:type="Alias_Map">
<tp:docstring>
@@ -112,7 +135,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<tp:docstring>
Request that the alias of the given contact be changed. Success will be
- indicated by emitting an AliasUpdate signal. On connections where the
+ indicated by emitting an AliasesChanged signal. On connections where the
CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only
ever succeed if the contact is the user's own handle (as returned by
GetSelfHandle on the Connection interface).
@@ -122,7 +145,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 33f6f68..53d3108 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:mapping name="Avatar_Token_Map" array-name="">
+ <tp:mapping name="Avatar_Token_Map">
<tp:docstring>A dictionary whose keys are contact handles and whose
values are avatar tokens.</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
@@ -43,7 +43,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when the avatar for a contact has been updated, or first
discovered on this connection. If the token differs from the token
associated with the client's cached avatar for this contact, the new
- avatar should be requested with RequestAvatar.
+ avatar should be requested with RequestAvatars.
</tp:docstring>
</signal>
<signal name="AvatarRetrieved">
@@ -154,11 +154,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>
Get the unique tokens for the given contacts' avatars. These tokens
can be persisted across connections, and should be used by the client
- to check whether the avatars have been updated. A CM must always have
- the tokens for the self handle if one is set (even if it is set to no
- avatar). Otherwise, only tokens that are already known or that can be
- discovered without retrieving the complete avatar are returned. An
- empty token means the given contact has no avatar.
+ to check whether the avatars have been updated. For handles other than
+ the self handle, only tokens that are already known are returned; an
+ empty token means the given contact has no avatar. However, a CM must
+ always have the tokens for the self handle if one is set (even if it is
+ set to no avatar). On protocols where the avatar does not persist
+ between connections, a CM should omit the self handle from the returned
+ map until an avatar is explicitly set or cleared.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -283,8 +285,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
the avatar is persistent, but on others it is transferred via a peer to
peer mechanism, so needs to be set every connection. Hence, on every
connection, clients should inspect the avatar token of the connection's
- self handle, and set the avatar if it is an empty string (and may
- optionally replace it if the token corresponds to a different avatar).</p>
+ self handle using GetKnownAvatarTokens; if the self handle is not in the
+ returned map, the client should re-set the avatar. If the self handle's
+ avatar token is known, but the avatar has been changed locally since the
+ last connection, the client should upload the new avatar; if the avatar has
+ not changed locally, then the client should download the avatar from the
+ server if its token differs from the that of the local avatar.</p>
<p>To remove the published avatar on protocols which have persistent avatars,
a client should use the ClearAvatar method. This method can safely be used
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index 874f07c..95fbaaf 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -21,6 +21,60 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections where it is possible to know what channel
+ types may be requested before the request is made to the connection
+ object. Each capability represents a commitment by the connection
+ manager that it will ordinarily be able to create a channel when given
+ a request with the given type and handle.</p>
+
+ <p>Capabilities pertain to particular contact handles, and represent
+ activities such as having a text chat or a voice call with the user.
+ The activities are represented by the D-Bus interface name of the
+ channel type for that activity.</p>
+
+ <p>The generic capability flags are defined by
+ <tp:type>Connection_Capability_Flags</tp:type>.</p>
+
+ <p>In addition, channel types may have type specific capability flags of
+ their own, which are described in the documentation for each channel
+ type.</p>
+
+ <p>This interface also provides for user interfaces notifying the
+ connection manager of what capabilities to advertise for the user. This
+ is done by using the AdvertiseCapabilities method, and deals with the
+ interface names of channel types and the type specific flags pertaining
+ to them which are implemented by available client processes.</p>
+ </tp:docstring>
+
+ <tp:changed version="0.17.8">Previously, this interface
+ also expressed capabilities of the connection itself, indicating what
+ sorts of channels could be requested (for instance, the ability to
+ open chatroom lists or chatrooms). However, this was never very
+ well-defined or consistent, and as far as we know it was never
+ implemented correctly. This usage is now deprecated.</tp:changed>
+
+ <!-- FIXME: are the type-specific flags sufficient, in a world that has
+ the Requests interface? It'd be nice if we could advertise capabilities
+ that are not defined in terms of a channel type but rather in terms of
+ a property or something, e.g. Channel.Interface.TLS.Secure for
+ individually TLS'd channels. -->
+
+ <tp:flags name="Connection_Capability_Flags"
+ value-prefix="Connection_Capability_Flag" type="u">
+ <tp:flag suffix="Create" value="1">
+ <tp:docstring>
+ The given channel type and handle can be given to RequestChannel to
+ create a new channel of this type.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Invite" value="2">
+ <tp:docstring>
+ The given contact can be invited to an existing channel of this type.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
<tp:struct name="Capability_Pair" array-name="Capability_Pair_List">
<tp:docstring>A pair (channel type, type-specific flags) as passed to
AdvertiseCapabilities on the Capabilities interface.</tp:docstring>
@@ -92,7 +146,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Upon a successful invocation of this method, the CapabilitiesChanged
signal will be emitted for the user's own handle (as returned by
- GetSelfHandle) the by the connection manager to indicate the changes
+ GetSelfHandle) by the connection manager to indicate the changes
that have been made. This signal should also be monitored to ensure
that the set is kept accurate - for example, a client may remove
capabilities or type specific capability flags when it exits
@@ -103,6 +157,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
+
<signal name="CapabilitiesChanged">
<arg name="caps" type="a(usuuuu)" tp:type="Capability_Change[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -117,19 +172,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</ul>
</tp:docstring>
</arg>
- <tp:docstring>
- Announce that there has been a change of capabilities on the
- given handle, or on the connection itself if the handle is zero.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Announce that there has been a change of capabilities on the
+ given handle.</p>
+
+ <p>If the handle is zero, the capabilities refer to the connection
+ itself, in some poorly defined way. This usage is deprecated and
+ clients should ignore it.</p>
</tp:docstring>
</signal>
+
<method name="GetCapabilities">
<arg direction="in" name="handles" type="au" tp:type="Contact_Handle[]">
- <tp:docstring>
- An array of contact handles for this connection, or zero to query capabilities available on the connection itself
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of contact handles for this connection.</p>
+
+ <p>This may include zero, which originally meant a query for
+ capabilities available on the connection itself. This usage
+ is deprecated; clients SHOULD NOT do this, and connection managers
+ SHOULD proceed as though zero had not been present in this
+ list.</p>
</tp:docstring>
</arg>
<arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]">
- <tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structures containing:
<ul>
<li>an integer handle representing the contact</li>
@@ -140,58 +206,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</arg>
<tp:docstring>
- Returns an array of capabilities for the given contact handles, or
- the connection itself (where handle is zero).
+ Returns an array of capabilities for the given contact handles.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
- The handle does not represent a contact
+ The handle does not represent a contact and is not zero
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>An interface for connections where it is possible to know what channel
- types may be requested before the request is made to the connection object.
- Each capability represents a commitment by the connection manager that it
- will ordinarily be able to create a channel when given a request with the
- given type and handle.</p>
-
- <p>Capabilities can pertain to a certain contact handle, representing
- activities such as having a text chat or a voice call with the user, or can
- be on the connection itself (where the handle will be zero), where they
- represent the ability to create channels for chat rooms or activities such
- as searching and room listing. The activities are represented by the D-Bus
- interface name of the channel type for that activity.</p>
-
- <p>The generic capability flags are defined by ConnectionCapabilityFlag.</p>
-
- <p>In addition, channel types may have type specific capability flags of their
- own, which are described in the documentation for each channel type.</p>
-
- <p>This interface also provides for user interfaces notifying the connection
- manager of what capabilities to advertise for the user. This is done by
- using the AdvertiseCapabilities method, and deals with the interface names
- of channel types and the type specific flags pertaining to them which are
- implemented by available client processes.</p>
- </tp:docstring>
+
</interface>
- <tp:flags name="Connection_Capability_Flags" value-prefix="Connection_Capability_Flag" type="u">
- <tp:flag suffix="Create" value="1">
- <tp:docstring>
- The given channel type and handle can be given to RequestChannel to
- create a new channel of this type.
- </tp:docstring>
- </tp:flag>
- <tp:flag suffix="Invite" value="2">
- <tp:docstring>
- The given contact can be invited to an existing channel of this type.
- </tp:docstring>
- </tp:flag>
- </tp:flags>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
new file mode 100644
index 0000000..3f5b5ea
--- /dev/null
+++ b/spec/Connection_Interface_Contacts.xml
@@ -0,0 +1,227 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contacts" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or (at
+ your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+ General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public License
+ along with this library; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Contacts">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.17.9"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface allows many attributes of many contacts to be
+ obtained in a single D-Bus round trip.</p>
+
+ <p>Each contact attribute has an string identifier
+ (<tp:type>Contact_Attribute</tp:type>), which is namespaced
+ by the D-Bus interface which defines it.</p>
+
+ <p>An initial set of contact attributes is defined here:</p>
+
+ <dl>
+ <dt>org.freedesktop.Telepathy.Connection/contact-id
+ (type s)</dt>
+ <dd>The same string that would be returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ (always present in the result)
+ </dd>
+ <dt>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias
+ (type s)</dt>
+ <dd>The same string that would be returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">GetAliases</tp:dbus-ref>
+ (always present with some value, possibly the
+ same as Connection/contact-id, if information from the
+ Aliasing interface was requested)
+ </dd>
+ <dt>org.freedesktop.Telepathy.Connection.Interface.Avatars/token
+ (type s)</dt>
+ <dd>The same string that would be returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
+ (omitted from the result if the contact's avatar token is not known,
+ present as an empty string if the contact is known not to have
+ an avatar). Unlike in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
+ method, the avatar tokens for the self handle aren't required to be
+ present. This attribute should not be used to determine whether or
+ not the Avatar needs to be set.
+ </dd>
+ <dt>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence
+ (type (uss), <tp:type>Simple_Presence</tp:type>)</dt>
+ <dd> The same struct that would be returned by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
+ (always present with some value if information from the
+ SimplePresence interface was requested)
+ </dd>
+ <dt>org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps
+ (type a(usuu), <tp:type>Contact_Capability</tp:type>)</dt>
+ <dd>The same structs that would be returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Capabilities">GetCapabilities</tp:dbus-ref>
+ (all of them will redundantly have the contact's handle as the
+ first member). Omitted from the result if the contact's capabilities
+ are not known; present in the result as an empty array if the
+ contact is known to have no capabilities at all.</dd>
+ </dl>
+ </tp:docstring>
+
+ <tp:simple-type name="Contact_Attribute" type="s">
+ <tp:docstring>
+ A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
+ and an identifier for an attribute defined by that interface. The
+ attribute identifier SHOULD be in lower case.
+
+ <tp:rationale>
+ These aren't D-Bus core Properties, and we want them to look visibly
+ different.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Single_Contact_Attributes_Map">
+ <tp:docstring>
+ Some of the attributes of a single contact.
+ </tp:docstring>
+
+ <tp:member type="s" tp:type="Contact_Attribute" name="Attribute">
+ <tp:docstring>
+ The name of the attribute
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="v" name="Value">
+ <tp:docstring>
+ The value of the attribute
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:mapping name="Contact_Attributes_Map">
+ <tp:docstring>Mapping returned by GetContactAttributes, representing a
+ collection of Contacts and their requested attributes.</tp:docstring>
+
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+ <tp:docstring>
+ A contact
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="a{sv}" tp:type="Single_Contact_Attributes_Map"
+ name="Attributes">
+ <tp:docstring>
+ Attributes of that contact
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="ContactAttributeInterfaces" access="read" type="as"
+ tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of D-Bus interfaces for which
+ <tp:member-ref>GetContactAttributes</tp:member-ref> is expected to work.
+ This cannot change during the lifetime of the Connection.
+ </tp:docstring>
+ </property>
+
+ <method name="GetContactAttributes">
+ <tp:docstring>
+ Return any number of contact attributes for the given handles.
+ </tp:docstring>
+
+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of handles representing contacts.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Interfaces" type="as"
+ tp:type="DBus_Interface[]">
+ <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. All supported attributes from these
+ interfaces, whose values can be obtained without additional network
+ activity, will be in the reply.</p>
+
+ <p>It is an error to request interfaces that are not supported by
+ this Connection (i.e. mentioned in the
+ <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>
+ property).</p>
+
+ <tp:rationale>
+ <p>This makes it possible to distinguish between interfaces for
+ which the Connection has nothing to say (e.g. we don't know the
+ avatar tokens of any of the contacts, so we omitted them all),
+ and interfaces for which this API isn't supported.</p>
+ </tp:rationale>
+
+ <p>Attributes from the interface
+ <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref>
+ are always returned, and need not be requested explicitly.</p>
+
+ <p>As well as returning cached information immediately, the
+ connection MAY start asynchronous requests to obtain better
+ values for the contact attributes. If better values are later
+ obtained by this process, they will be indicated with the usual
+ signals (such as AliasesChanged).</p>
+
+ <tp:rationale>
+ For instance, an XMPP connection manager could download vCards
+ in response to a request for Aliasing attributes.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Hold" type="b">
+ <tp:docstring>
+ If true, all handles in the result have been held on behalf of the
+ calling process, as if by a call to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.HoldHandles</tp:dbus-ref>.
+
+ <tp:rationale>
+ For further round-trip avoidance.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="a{ua{sv}}" name="Attributes"
+ tp:type="Contact_Attributes_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary mapping the contact handles to contact attributes.
+ If any of the requested handles are in fact invalid, they are
+ simply omitted from this mapping. If contact attributes are not
+ immediately known, the behaviour is defined by the interface;
+ the attribute should either be omitted from the result or
+ replaced with a default value.</p>
+
+ <p>Each contact's attributes will always include at least the
+ identifier that would be obtained by inspecting the handle
+ (<code>org.freedesktop.Telepathy.Connection/contact-id</code>).</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ One of the requested interfaces is not supported (mentioned in
+ <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>).
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 37653ee..4ba59b6 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -258,10 +258,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface is for services which have a concept of presence which can
- be published for yourself and monitored on your contacts. Telepathy's
- definition of presence is based on that used by the Galago project
- (see http://www.galago-project.org/).</p>
+ <p>This interface will become deprecated in future versions. New
+ client implementations MAY use
+ org.freedesktop.Telepathy.Connection.Interface.SimplePresence
+ instead; new connection managers SHOULD implement both
+ Presence and SimplePresence.</p>
+
+ <p>This interface is for services which have a concept of presence which
+ can be published for yourself and monitored on your contacts.
+ Telepathy's definition of presence is based on that used by
+ <a href="http://www.galago-project.org/">the Galago
+ project</a>.</p>
<p>Presence on an individual (yourself or one of your contacts) is modelled as
a last activity time along with a set of zero or more statuses, each of
@@ -276,14 +283,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
choices:</p>
<ul>
- <li>available</li>
- <li>away</li>
- <li>brb (Be Right Back)</li>
- <li>busy</li>
- <li>dnd (Do Not Disturb),</li>
- <li>xa (Extended Away)</li>
- <li>hidden (aka Invisible)</li>
- <li>offline</li>
+ <li>available (corresponding to Connection_Presence_Type_Available)</li>
+ <li>away (corresponding to Connection_Presence_Type_Away)</li>
+ <li>brb (Be Right Back) (corresponding to
+ Connection_Presence_Type_Away, but more specific)</li>
+ <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
+ <li>dnd (Do Not Disturb) (corresponding to
+ Connection_Presence_Type_Busy, but more specific)</li>
+ <li>xa (Extended Away) (corresponding to
+ Connection_Presence_Type_Extended_Away)</li>
+ <li>hidden (aka Invisible) (corresponding to
+ Connection_Presence_Type_Hidden)</li>
+ <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
+ <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
+ <li>error (corresponding to Connection_Presence_Type_Error)</li>
</ul>
<p>As well as these well-known status identifiers, every status also has a
@@ -317,7 +330,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enum name="Connection_Presence_Type" type="u">
<tp:enumvalue suffix="Unset" value="0">
<tp:docstring>
- An invalid presence type used as a null value
+ An invalid presence type used as a null value. This value MUST NOT
+ appear in the result of GetStatuses, or in the Statuses property
+ of the SimplePresence interface.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Offline" value="1">
@@ -346,10 +361,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Busy" value="6">
+ <tp:added version="0.17.0"/>
<tp:docstring>
Busy, Do Not Disturb.
</tp:docstring>
</tp:enumvalue>
+ <tp:enumvalue suffix="Unknown" value="7">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Unknown, unable to determine presence for this contact, for example
+ if the protocol only allows presence of subscribed contacts.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="8">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Error, an error occurred while trying to determine presence. The
+ message, if set, is an error from the server.
+ </tp:docstring>
+ </tp:enumvalue>
</tp:enum>
</interface>
</node>
diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml
index 4ada369..8654736 100644
--- a/spec/Connection_Interface_Privacy.xml
+++ b/spec/Connection_Interface_Privacy.xml
@@ -42,7 +42,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
An array of valid privacy modes for this connection
</tp:docstring>
</arg>
- <tp:docstring>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
Returns the privacy modes available on this connection. The following
well-known names should be used where appropriate:
<dl>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
new file mode 100644
index 0000000..ea1eeeb
--- /dev/null
+++ b/spec/Connection_Interface_Requests.xml
@@ -0,0 +1,400 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Requests"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ >
+ <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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
+ 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.Connection.Interface.Requests.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.17.9"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An enhanced version of the Telepathy connection interface, which can
+ represent bundles of channels that should be dispatched together, and
+ does not assume any particular properties by which channels are
+ uniquely identifiable.</p>
+ </tp:docstring>
+
+ <tp:struct name="Channel_Details" array-name="Channel_Details_List">
+ <tp:docstring>
+ Enough details of a channel that clients can work out how to dispatch
+ or handle it.
+ </tp:docstring>
+
+ <tp:member name="Channel" type="o">
+ <tp:docstring>
+ The object path of the channel.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel.</p>
+
+ <p>Connection managers MUST NOT include properties in this mapping
+ if their values can change. Clients MUST ignore properties
+ that appear in this mapping if their values can change.</p>
+
+ <tp:rationale>
+ <p>If properties that could change were included, the following
+ race condition would be likely to exist in some cases:</p>
+
+ <ul>
+ <li>NewChannels or Get("Channels") includes a property P with
+ value V1</li>
+ <li>Client creates a proxy object for the channel</li>
+ <li>The value of P changes to V2</li>
+ <li>Client connects to PChanged signal</li>
+ <li>Client should call Get("P") or GetAll here, to avoid the
+ race, but client's author has forgotten to do so</li>
+ <li>Proxy object thinks P == V1, but actually P == V2</li>
+ </ul>
+
+ <p>We've taken the opportunity to make the API encourage the
+ client author to get it right. Where possible, we intend that
+ properties whose value will be used in channel dispatching
+ or other "early" processing will be defined so that they are
+ immutable (can never change).</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain the keys
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>.
+ </p>
+ <!-- FIXME: maybe also Requested, InitiatorHandle,
+ InitiatorID once they leave the FUTURE pseudo-interface -->
+
+ <tp:rationale>
+ <p>We expect these to be crucial to the channel-dispatching
+ process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="CreateChannel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that channels are created.</p>
+
+ <tp:rationale>
+ <p>There is deliberately no flag corresponding to the
+ suppress_handler argument to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>,
+ because passing a FALSE value for that argument is deprecated.
+ Requests made using this interface always behave as though
+ suppress_handler was TRUE.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+
+ <arg direction="in" name="Request" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. Some properties
+ are defined such that only an exact match makes sense, and
+ connection managers MUST NOT satisfy a request with a channel
+ where that property does not match; some properties are defined
+ such that the connection manager MAY treat the request as merely
+ a hint, and make a best-effort attempt to satisfy it. This is
+ documented separately for each property.</p>
+
+ <p>If this dictionary contains a property whose semantics
+ are not known to the connection manager, this method MUST fail
+ without side-effects (in particular it must not create a new
+ channel).</p>
+
+ <tp:rationale>
+ <p>This is necessary if we want to be able to invent properties
+ in future that, when used in a request, are hard requirements
+ rather than just hints. A connection manager that did not know
+ the semantics of those properties could incorrectly return a
+ new channel that did not satisfy the requirements.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST NOT respond successfully,
+ and SHOULD NOT create a new channel or cause any other
+ side-effects, unless it can create a new channel that satisfies
+ the client's requirements.</p>
+
+ <p>Properties that will be set by this argument need not have write
+ access after the channel has been created - indeed, it is
+ expected that most will be read-only.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel" direction="out" type="o">
+ <tp:docstring>
+ The Channel object, which MUST already have been signalled with
+ <tp:member-ref>NewChannels</tp:member-ref> by the time this method
+ returns.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" direction="out" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel that was produced, equivalent to
+ the properties in <tp:type>Channel_Details</tp:type>.
+ Connection managers MUST NOT include properties here whose
+ values can change, for the same reasons as in
+ <tp:type>Channel_Details</tp:type>.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The channel request was one that can never succeed,
+ such as requesting an unsupported channel type, or requesting
+ a channel type which this connection manager does not support with
+ the given target handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ An invalid handle was requested as the value of a property whose
+ value is a handle (like
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>),
+ or a syntactically invalid identifier was requested as the value
+ of a property whose value is the string corresponding to a handle
+ (like TargetID).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested channel cannot be created, but in
+ principle, a similar request might succeed in future. For instance,
+ this might be because the requested contact is using a client
+ that lacks a particular feature, or because a channel matching the
+ request already exists and the protocol requires that only one
+ such channel can exist at a time.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="NewChannels">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>New channels have been created. The connection manager SHOULD emit
+ a single signal for any group of closely related channels that are
+ created at the same time, so that the channel dispatcher can try to
+ dispatch them to a handler as a unit.</p>
+
+ <p>In particular, if additional channels are created as a side-effect
+ of a call to <tp:member-ref>CreateChannel</tp:member-ref>,
+ these channels SHOULD appear in the same NewChannels signal as
+ the channel that satisfies the request.</p>
+
+ <tp:rationale>
+ <p>Joining a MUC Tube in XMPP requires joining the corresponding
+ MUC (chatroom), so a Text channel can be created as a
+ side-effect.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
+ <tp:docstring>
+ The channels and their details. All channels that are signalled
+ together like this MUST have the same
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+ property, which may
+ either refer to an existing bundle, or establish a new bundle.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Channels" type="a(oa{sv})" access="read"
+ tp:type="Channel_Details[]">
+ <tp:docstring>
+ A list of all the channels which currently exist on this connection.
+ Change notification is via the
+ <tp:member-ref>NewChannels</tp:member-ref> and
+ <tp:member-ref>ChannelClosed</tp:member-ref> signals.
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelClosed">
+ <tp:docstring>
+ Emitted when a channel is closed and hence disappears from the
+ Channels property.
+
+ <tp:rationale>
+ This is redundant with the Close signal on the channel itself, but
+ it does provide full change notification for the Channels property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Removed" type="o">
+ <tp:docstring>
+ The channel which has been removed from the Channels property
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:mapping name="Channel_Class">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Mapping representing a class of channels that can be requested
+ from a connection manager, can be handled by a user interface,
+ are supported by a contact, etc.</p>
+
+ <p>Classes of channel are identified by the fixed values of
+ a subset of their properties.</p>
+
+ <p>Channel classes SHOULD always include the keys
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
+ </p>
+ </tp:docstring>
+
+ <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
+ <tp:docstring>
+ A D-Bus interface name, followed by a dot and a D-Bus property name.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="v" name="Value">
+ <tp:docstring>
+ The value of the property.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Requestable_Channel_Class"
+ array-name="Requestable_Channel_Class_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Structure representing a class of channels that can be requested,
+ identified by a set of properties that identify that class of
+ channel.</p>
+
+ <tp:rationale>
+ <p>This will often just be the channel type and the handle type,
+ but can include other properties of the channel - for instance,
+ encrypted channels might require properties that
+ unencrypted channels do not, like an encryption key.</p>
+ </tp:rationale>
+
+ <p>In some cases, these classes of channel may overlap, in the sense
+ that one class fixes all the properties that another class does,
+ plus some more properties.</p>
+
+ <tp:rationale>
+ <p>For older clients to still be able to understand how to request
+ channels in the presence of a hypothetical "encryption" interface,
+ we'd need to represent it like this:</p>
+
+ <ul>
+ <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li>
+ <li>class 2: Channel.ChannelType = Text,
+ Channel.TargetHandleType = CONTACT,
+ Encryption.Encrypted = TRUE</li>
+ </ul>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:member name="Fixed_Properties" type="a{sv}"
+ tp:type="Channel_Class">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The property values that identify this requestable channel class.
+ These properties MUST be included in requests for a channel of this
+ class, and MUST take these values.</p>
+
+ <p>Clients that do not understand the semantics of all the
+ Fixed_Properties MUST NOT request channels of this class, since
+ they would be unable to avoid making an incorrect request.</p>
+
+ <p>This implies that connection managers wishing to make channels
+ 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>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Allowed_Properties" type="as"
+ tp:type="DBus_Qualified_Member[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties that MAY be set when requesting a channel of this
+ channel type and handle type.</p>
+
+ <p>This array MUST NOT include properties that are in the
+ Fixed_Properties mapping.</p>
+
+ <p>Properties in this array may either be required or optional,
+ according to their documented semantics.</p>
+
+ <tp:rationale>
+ <p>For instance, if
+ TargetHandleType takes a value that is not Handle_Type_None,
+ one or the other of TargetHandle and TargetID is required.
+ Clients are expected to understand the documented relationship
+ between the properties, so we do not have separate arrays
+ of required and optional properties.</p>
+ </tp:rationale>
+
+ <p>If this array contains the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref>
+ property, then this class of channel can be combined with other
+ channels with that property in a request, or added to an existing
+ bundle. If not, this signifies that the connection manager is
+ unable to mark channels of this class as part of a bundle - this
+ means that to the remote contact they are likely to be
+ indistinguishable from channels requested separately.</p>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="RequestableChannelClasses" access="read"
+ type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The classes of channel that are expected to be available on this
+ connection, i.e. those for which
+ <tp:member-ref>CreateChannel</tp:member-ref> can reasonably
+ be expected to succeed. User interfaces can use this information
+ to show or hide UI components.</p>
+
+ <p>This property cannot change after the connection has gone to
+ state Connection_Status_Connected, so there is no change
+ notification (if the connection has context-dependent capabilities,
+ it SHOULD advertise support for all classes of channel that it might
+ support during its lifetime). Before this state has been reached,
+ the value of this property is undefined.</p>
+
+ <tp:rationale>
+ <p>This is not on an optional interface, because connection
+ managers can always offer some sort of clue about the channel
+ classes they expect to support (at worst, they can announce
+ support for everything for which they have code).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
new file mode 100644
index 0000000..56ac9d3
--- /dev/null
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -0,0 +1,382 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Simple_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or (at
+ your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+ General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public License
+ along with this library; if not, write to the Free Software Foundation,
+ Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:struct name="Simple_Presence">
+ <tp:docstring>
+ A struct representing the presence of a contact.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
+ <tp:docstring>
+ The presence type, e.g. Connection_Presence_Type_Away.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Status">
+ <tp:docstring>
+ The string identifier of the status, e.g. "brb", as defined in the
+ <tp:member-ref>Statuses</tp:member-ref> property.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Status_Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The user-defined status message, e.g. "Back soon!".</p>
+
+ <p>Clients SHOULD set the status message for the local
+ user to the empty string, unless the user has actually provided
+ a specific message (i.e. one that conveys more information than the
+ Status).</p>
+
+ <p>User interfaces SHOULD regard an empty status message as unset,
+ and MAY replace it with a localized string corresponding to the
+ Status or Type.</p>
+
+ <tp:rationale>
+ Use case: Daf sets his status in Empathy by choosing the Welsh
+ translation of "Available" from a menu.
+ It is more informative for his English-speaking colleagues
+ to see the English translation of "Available" (as localized
+ by their own clients) than to see the Welsh version (which they
+ don't understand anyway).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Simple_Contact_Presences">
+ <tp:docstring>
+ Mapping returned by <tp:member-ref>GetPresences</tp:member-ref>
+ and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
+ indicating the presence of a number of contacts.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+ <tp:docstring>
+ A contact
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence">
+ <tp:docstring>
+ The contact's presence
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Simple_Status_Spec">
+ <tp:docstring>
+ A struct containing information about a status.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Connection_Presence_Type" name="Type">
+ <tp:docstring>
+ The type of a presence. This SHOULD NOT be used as a way to set
+ statuses that the client does not recognise (as explained in
+ <tp:member-ref>SetPresence</tp:member-ref>), but MAY be used to check
+ that the client's assumptions about a particular status name
+ match the connection manager's.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="b" name="May_Set_On_Self">
+ <tp:docstring>
+ If true, the user can set this status on themselves using
+ <tp:member-ref>SetPresence</tp:member-ref>.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="b" name="Can_Have_Message">
+ <tp:docstring>
+ If true, a non-empty message can be set for this status. Otherwise,
+ the empty string is the only acceptable message.
+
+ <tp:rationale>
+ On IRC you can be Away with a status message, but if you are
+ available you cannot set a status message.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Simple_Status_Spec_Map">
+ <tp:docstring>
+ A mapping describing possible statuses.
+ </tp:docstring>
+
+ <tp:member type="s" name="Identifier">
+ <tp:docstring>
+ The string identifier of this status.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="(ubb)" tp:type="Simple_Status_Spec" name="Spec">
+ <tp:docstring>
+ Details of this status.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="SetPresence">
+ <arg direction="in" name="status" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string identifier of the desired status. Possible status
+ identifiers are defined in the
+ <tp:member-ref>Statuses</tp:member-ref> property.</p>
+
+ <p>Clients MUST NOT set a status whose string value they do not
+ recognise, even if its presence type in Statuses
+ matches what the user requested.</p>
+
+ <tp:rationale>
+ <p>Suppose a protocol has statuses that include 'phone' (of type
+ BUSY) and 'in-a-meeting' (of type BUSY), but there is no
+ generic 'busy' status.</p>
+
+ <p>If the user requests "Busy" status from a menu, a
+ client author might be tempted to pick an arbitrary status
+ that has type BUSY. However, on this protocol, neither of
+ the choices would be appropriate, and incorrect information
+ about the user would be conveyed.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="status_message" type="s">
+ <tp:docstring>
+ The status message associated with the current status.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the presence status and status message are published for
+ the connection. Changes will be indicated by
+ <tp:member-ref>PresencesChanged</tp:member-ref>
+ signals being emitted.</p>
+
+ <p>This method may be called on a newly-created connection while it
+ is still in the DISCONNECTED state, to request that when the
+ connection connects, it will do so with the selected status.</p>
+
+ <p>In DISCONNECTED state the
+ <tp:member-ref>Statuses</tp:member-ref>
+ property will indicate which statuses are allowed to be set
+ while DISCONNECTED (none, if the Connection Manager doesn't allow
+ this). This value MUST NOT be cached, as the set of allowed
+ presences might change upon connecting.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ Either the specified status is not supported, the specified
+ status cannot be set on the user themselves, or a non-empty
+ message was supplied for a status that does not
+ accept a message.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetPresences">
+ <arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of the contacts whose presence should be obtained.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="presence" type="a{u(uss)}"
+ tp:type="Simple_Contact_Presences">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Presence information in the same format as for the
+ <tp:member-ref>PresencesChanged</tp:member-ref> signal.
+ The returned mapping MUST include an entry for each contact
+ in the method's argument.</p>
+
+ <p>The definition of the connection presence types Unknown
+ and Offline means that if a connection manager will return
+ Unknown for contacts not on the subscribe list, it MUST delay
+ the reply to this method call until it has found out which
+ contacts are, in fact, on the subscribe list.</p>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get presence previously emitted by PresencesChanged for the given
+ contacts. Data is returned in the same structure as the
+ PresencesChanged signal; no additional network requests are made.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
+ <tp:docstring>
+ While discovering the subscribe list in order to distinguish
+ between Unknown and Offline statuses, a network error occurred.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="Statuses" access="read"
+ type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary where the keys are the presence statuses that the user
+ can set on themselves for this connection, and the values are the
+ corresponding presence types.</p>
+
+ <p>While the connection is in the DISCONNECTED state, it contains
+ the set of presence statuses allowed to be set before connecting.
+ The connection manager will attempt to set the appropriate status
+ when the connection becomes connected, but cannot necessarily
+ guarantee it. The available statuses cannot change until the
+ connection status changes, so there is no change notification.</p>
+
+ <p>While the connection is in the CONNECTED state, this property
+ contains the set of presence statuses which are actually available
+ on this protocol. This set is constant for the remaining lifetime
+ of the connection, so again, there is no change notification.</p>
+
+ <p>While the connection is in the CONNECTING state, the value of
+ this property is undefined and SHOULD NOT be used. It can change
+ at any time without notification (in particular, any cached values
+ from when the connection was in the DISCONNECTED or CONNECTING
+ state MUST NOT be assumed to still be correct when the state has
+ become CONNECTED).</p>
+
+ <p>This property MUST include the special statuses "unknown" and
+ "error" if and only if the connection manager can emit them
+ as a contact's status.</p>
+
+ <tp:rationale>
+ For instance, connection managers for local-xmpp (XEP-0174) would
+ omit "unknown" since there is no such concept.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="PresencesChanged">
+ <arg name="presence" type="a{u(uss)}" tp:type="Simple_Contact_Presences">
+ <tp:docstring>
+ A dictionary of contact handles mapped to the status,
+ presence type and status message.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ This signal should be emitted when your own presence has been changed,
+ or the presence of the member of any of the connection's channels has
+ been changed.
+ </tp:docstring>
+ </signal>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface is for services which have a concept of presence which
+ can be published for yourself and monitored on your contacts.</p>
+
+ <p>Presence on an individual (yourself or one of your contacts) is
+ modelled as a status and a status message. Valid statuses are defined
+ per connection, and a list of those that can be set on youself
+ can be obtained from the
+ <tp:member-ref>Statuses</tp:member-ref>
+ property.</p>
+
+ <p>Each status has an arbitrary string identifier which should have an
+ agreed meaning between the connection manager and any client which is
+ expected to make use of it. The following well-known values should be
+ used where possible to allow clients to identify common choices:</p>
+
+ <table>
+ <tr>
+ <th>status identifier</th>
+ <th>Connection_Presence_Type</th>
+ <th>comments</th>
+ </tr>
+ <tr>
+ <td>available</td>
+ <td>Connection_Presence_Type_Available</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>away</td>
+ <td>Connection_Presence_Type_Away</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>brb</td>
+ <td>Connection_Presence_Type_Away</td>
+ <td>Be Right Back (a more specific form of Away)</td>
+ </tr>
+ <tr>
+ <td>busy</td>
+ <td>Connection_Presence_Type_Busy</td>
+ <td></td>
+ </tr>
+ <tr><td>dnd</td>
+ <td>Connection_Presence_Type_Busy</td>
+ <td>Do Not Disturb (a more specific form of Busy)</td>
+ </tr>
+ <tr>
+ <td>xa</td>
+ <td>Connection_Presence_Type_Extended_Away</td>
+ <td>Extended Away</td>
+ </tr>
+ <tr>
+ <td>hidden</td>
+ <td>Connection_Presence_Type_Hidden</td>
+ <td>Also known as "Invisible" or "Appear Offline"</td>
+ </tr>
+ <tr>
+ <td>offline</td>
+ <td>Connection_Presence_Type_Offline</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>unknown</td>
+ <td>Connection_Presence_Type_Unknown</td>
+ <td>special, see below</td>
+ </tr>
+ <tr>
+ <td>error</td>
+ <td>Connection_Presence_Type_Error</td>
+ <td>special, see below</td>
+ </tr>
+ </table>
+
+ <p>As well as these well-known status identifiers, every status also has
+ a numerical type value chosen from ConnectionPresenceType which can be
+ used by the client to classify even unknown statuses into different
+ fundamental types.</p>
+
+ <p>These numerical types exist so that even if a client does not
+ understand the string identifier being used, and hence cannot present
+ the presence to the user to set on themselves, it may display an
+ approximation of the presence if it is set on a contact.</p>
+
+ <p>As well as the normal status identifiers, there are two special ones
+ that may be present: 'unknown' with type Unknown and 'error' with type
+ Error. 'unknown' indicates that it is impossible to determine the
+ presence of a contact at this time, for example because it's not on the
+ 'subscribe' list and the protocol only allows one to determine the
+ presence of contacts you're subscribed to. 'error' indicates that there
+ was a failure in determining the status of a contact.</p>
+
+ <p>If the connection has a 'subscribe' contact list, PresencesChanged
+ signals should be emitted to indicate changes of contacts on this list,
+ and should also be emitted for changes in your own presence. Depending
+ on the protocol, the signal may also be emitted for others such as
+ people with whom you are communicating, and any user interface should
+ be updated accordingly.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 5d3aef3..33f1ede 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -20,6 +20,41 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.ConnectionManager">
+ <tp:simple-type name="Connection_Manager_Name" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a connection manager, found in its well-known
+ bus name and object path. This must be a non-empty string of
+ ASCII letters, digits and underscores, starting with a letter.
+ This is typically the name of the executable with any "telepathy-"
+ prefix removed, and any hyphen/minus signs replaced by
+ underscores.</p>
+
+ <p>Connection manager names SHOULD NOT be the same as the name of
+ the protocol they implement.</p>
+
+ <tp:rationale>
+ <p>This is likely to lead to conflicts between different
+ implementations of the same protocol (or indeed inability
+ to distinguish between the different implementations!). The
+ Telepathy project traditionally uses some sort of pun (Haze is
+ based on libpurple, Salut implements a protocol often called
+ Bonjour, and Wilde implements the OSCAR protocol).</p>
+ </tp:rationale>
+
+ <p>Connection manager names SHOULD NOT be the same as the name of
+ a library on which they are based.</p>
+
+ <tp:rationale>
+ <p>We often abbreviate, for instance, telepathy-haze as "Haze",
+ but abbreviating telepathy-sofiasip to "Sofia-SIP" would cause
+ confusion between the connection manager and the library it
+ uses. Please don't repeat that mistake.</p>
+ </tp:rationale>
+ </tp:docstring>
+ <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
+ characters were not specified</tp:changed>
+ </tp:simple-type>
+
<tp:simple-type name="Protocol" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An instant messaging protocol. It must consist only of ASCII
@@ -47,6 +82,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<li>zephyr - Zephyr</li>
</ul>
</tp:docstring>
+ <tp:changed version="0.17.1">Prior to version 0.17.1, the allowed
+ characters were not specified</tp:changed>
</tp:simple-type>
<tp:struct name="Param_Spec" array-name="Param_Spec_List">
@@ -88,7 +125,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
providing the default.
</tp:docstring>
</tp:flag>
+ <tp:flag suffix="Secret" value="8">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This parameter should be considered private or secret; for
+ instance, clients should store it in a "password safe" like
+ gnome-keyring or kwallet, omit it from debug logs, and use a
+ text input widget that hides the value of the parameter.</p>
+
+ <p>(Clients that support older connection managers may also treat
+ any parameter whose name contains "password" as though it had this
+ flag.)</p>
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+ </tp:flag>
</tp:flags>
+
<method name="GetParameters">
<arg direction="in" name="proto" type="s" tp:type="Protocol">
<tp:docstring>
@@ -112,18 +163,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
<method name="ListProtocols">
<arg direction="out" type="as" tp:type="Protocol[]">
<tp:docstring>
A array of string protocol identifiers supported by this manager
</tp:docstring>
</arg>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <tp:docstring>
Get a list of protocol identifiers that are implemented by this
- connection manager. The following well-known values should be used
- when applicable:
+ connection manager.
</tp:docstring>
</method>
+
<signal name="NewConnection">
<arg name="bus_name" type="s" tp:type="DBus_Bus_Name">
<tp:docstring>
@@ -144,6 +196,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Emitted when a new Connection object is created.
</tp:docstring>
</signal>
+
<method name="RequestConnection">
<arg direction="in" name="proto" type="s" tp:type="Protocol">
<tp:docstring>
@@ -156,7 +209,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
A dictionary mapping parameter name to the variant boxed value
</tp:docstring>
</arg>
- <arg direction="out" type="s">
+ <arg direction="out" type="s" tp:type="DBus_Bus_Name">
<tp:docstring>
A D-Bus service name where the new Connection object can be found
</tp:docstring>
@@ -266,15 +319,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:error>
</tp:possible-errors>
</method>
+
+ <property name="Interfaces" type="as" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the extra interfaces provided by this connection manager
+ (i.e. extra functionality that can be provided even before a
+ connection has been created).</p>
+
+ <p>No interfaces suitable for listing in this property are currently
+ defined; it's provided as a hook for possible future
+ functionality.</p>
+
+ <p>To be compatible with older connection managers, if retrieving
+ this property fails, clients SHOULD assume that its value is
+ an empty list.</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>
<p>For service discovery, each Telepathy connection manager must have
- a <em>connection manager name</em>, which is a non-empty string of
- ASCII letters, digits and underscores, starting with a letter. This
- is typically the name of the executable with any "telepathy-" prefix
- removed.</p>
+ a <em>connection manager name</em> (see
+ <tp:type>Connection_Manager_Name</tp:type> for syntax).</p>
<p>The connection manager must then provide a well-known bus name of
<code>org.freedesktop.Telepathy.ConnectionManager.<em>cmname</em></code>
@@ -313,7 +389,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<code>telepathy/managers/<em>cmname</em>.manager</code> that can be
read without error. This file has the same syntax as a
<a href="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">freedesktop.org Desktop Entry file</a>.</p>
-
+
+ <p>Clients must still support connection managers for which no
+ <code>.manager</code> file can be found, which they can do by activating
+ the connection manager and calling its methods; the
+ <code>.manager</code> file is merely an optimization. Connection managers
+ whose list of protocols can change at any time (for instance, via
+ a plugin architecture) should not install a <code>.manager</code>
+ file.</p>
+
<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
@@ -321,10 +405,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
.manager file contains a key <code>param-<em>p</em></code> with a value
consisting of a D-Bus signature (a single complete type), optionally
followed by a space and a space-separated list of flags. The supported
- flags are <code>required</code>, corresponding to
- Conn_Mgr_Param_Flag_Required, and <code>register</code>, corresponding
- to Conn_Mgr_Param_Flag_Register.
- </p>
+ flags are:</p>
+
+ <ul>
+ <li><code>required</code>, corresponding to
+ Conn_Mgr_Param_Flag_Required</li>
+ <li><code>register</code>, corresponding
+ to Conn_Mgr_Param_Flag_Register</li>
+ <li><code>secret</code>, corresponding
+ to Conn_Mgr_Param_Flag_Secret</li>
+ </ul>
<p>The group may also contain a key <code>default-<em>p</em></code>
whose value is a string form of the default value for the parameter.
@@ -360,6 +450,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
well-known bus name, causing a new connection manager to be activated when
somebody attempts to make a new connection.</p>
</tp:docstring>
+
+ <tp:changed version="0.17.2">Prior to version 0.17.2, support for
+ CMs with no .manager file was not explicitly required.</tp:changed>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index 92be1f2..7d69463 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -181,7 +181,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:enumvalue>
</tp:enum>
<method name="Ready">
- <arg direction="in" name="codecs" type="a(usuuua{ss})">
+ <arg direction="in" name="codecs" type="a(usuuua{ss})"
+ tp:type="Media_Stream_Handler_Codec[]">
<tp:docstring>
As for SupportedCodecs.
</tp:docstring>
@@ -193,7 +194,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</method>
<method name="SetLocalCodecs">
- <arg name="codecs" type="a(usuuua{ss})" direction="in">
+ <arg name="codecs" type="a(usuuua{ss})" direction="in"
+ tp:type="Media_Stream_Handler_Codec[]">
<tp:docstring>Codecs in the same format as for
SupportedCodecs, which have the same semantics as the
local codecs passed to Ready</tp:docstring>
@@ -309,6 +311,64 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
and those supported by the peer.
</tp:docstring>
</method>
+
+ <signal name="SetStreamHeld">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the connection manager wishes to place the stream on
+ hold (so the streaming client should free hardware or software
+ resources) or take the stream off hold (so the streaming client
+ should reacquire the necessary resources).</p>
+
+ <p>When placing a channel's streams on hold, the connection manager
+ SHOULD notify the remote contact that this will be done (if
+ appropriate in the protocol) before it emits this signal.</p>
+
+ <tp:rationale>
+ <p>It is assumed that relinquishing a resource will not fail.
+ If it does, the call is probably doomed anyway.</p>
+ </tp:rationale>
+
+ <p>When unholding a channel's streams, the connection manager
+ SHOULD emit this signal and wait for success to be indicated
+ via HoldState before it notifies the remote contact that the
+ channel has been taken off hold.</p>
+
+ <tp:rationale>
+ <p>This means that if a resource is unavailable, the remote
+ contact will never even be told that we tried to acquire it.</p>
+ </tp:rationale>
+ </tp:docstring>
+ <tp:added version="0.17.3"/>
+
+ <arg name="Held" type="b">
+ <tp:docstring>
+ If true, the stream is to be placed on hold.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="HoldState">
+ <tp:docstring>
+ Notify the connection manager that the stream's hold state has
+ been changed successfully in response to SetStreamHeld.
+ </tp:docstring>
+ <tp:added version="0.17.3"/>
+ <arg direction="in" name="Held" type="b">
+ <tp:docstring>
+ If true, the stream is now on hold.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="UnholdFailure">
+ <tp:docstring>
+ Notify the connection manager that an attempt to reacquire the
+ necessary hardware or software resources to unhold the stream,
+ in response to SetStreamHeld, has failed.
+ </tp:docstring>
+ <tp:added version="0.17.3"/>
+ </method>
+
<tp:docstring>
Handles signalling the information pertaining to a specific media stream.
A client should provide information to this handler as and when it is
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
index a028913..fa78f20 100644
--- a/spec/Properties_Interface.xml
+++ b/spec/Properties_Interface.xml
@@ -39,12 +39,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member type="u" name="New_Flags"/>
</tp:struct>
+ <tp:simple-type name="Property_ID" type="u">
+ <tp:docstring>
+ An unsigned integer used to represent a Telepathy property.
+ </tp:docstring>
+ </tp:simple-type>
+
<tp:struct name="Property_Value" array-name="Property_Value_List">
<tp:docstring>A struct (property ID, value) representing a
property's value, as seen in the PropertiesChanged signal on
the Properties interface, returned by the GetProperties method
and passed to the SetProperties method.</tp:docstring>
- <tp:member type="u" name="Property_ID"/>
+ <tp:member type="u" tp:type="Property_ID" name="Identifier"/>
<tp:member type="v" name="Value"/>
</tp:struct>
@@ -53,7 +59,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Returns an array of (identifier, value) pairs containing the current
values of the given properties.
</tp:docstring>
- <arg direction="in" name="properties" type="au">
+ <arg direction="in" name="properties" type="au" tp:type="Property_ID[]">
<tp:docstring>An array of property identifiers</tp:docstring>
</arg>
<arg direction="out" type="a(uv)" tp:type="Property_Value[]">
diff --git a/spec/all.xml b/spec/all.xml
index 1fb517c..eda2e01 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.17.1</tp:version>
+<tp:version>0.17.9</tp:version>
<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
@@ -30,43 +30,55 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Connection_Interface_Aliasing.xml"/>
<xi:include href="Connection_Interface_Avatars.xml"/>
<xi:include href="Connection_Interface_Capabilities.xml"/>
-<xi:include href="Connection_Interface_Contact_Info.xml"/>
-<xi:include href="Connection_Interface_Forwarding.xml"/>
+<xi:include href="Connection_Interface_Contacts.xml"/>
+<!-- Never implemented, is a terrible API
+<xi:include href="Connection_Interface_Contact_Info.xml"/> -->
+<!-- Never implemented, insufficient (needs conditions)
+<xi:include href="Connection_Interface_Forwarding.xml"/> -->
+<xi:include href="Connection_Interface_Simple_Presence.xml"/>
<xi:include href="Connection_Interface_Presence.xml"/>
-<xi:include href="Connection_Interface_Privacy.xml"/>
+<!-- Never implemented, vague
+<xi:include href="Connection_Interface_Privacy.xml"/> -->
<xi:include href="Connection_Interface_Renaming.xml"/>
+<xi:include href="Connection_Interface_Requests.xml"/>
+
+<xi:include href="Channel_Bundle.xml"/>
<xi:include href="Channel.xml"/>
+<xi:include href="Channel_Future.xml"/>
<xi:include href="Channel_Type_Contact_List.xml"/>
-<xi:include href="Channel_Type_Contact_Search.xml"/>
+<!-- Never implemented, can't be implemented with current dbus-glib, vague
+<xi:include href="Channel_Type_Contact_Search.xml"/> -->
<xi:include href="Channel_Type_Streamed_Media.xml"/>
<xi:include href="Channel_Type_Room_List.xml"/>
<xi:include href="Channel_Type_Text.xml"/>
<xi:include href="Channel_Type_Tubes.xml"/>
<xi:include href="Channel_Interface_Call_Merging.xml"/>
+<xi:include href="Channel_Interface_Call_State.xml"/>
<xi:include href="Channel_Interface_Chat_State.xml"/>
+<xi:include href="Channel_Interface_Delivery_Reporting.xml"/>
<xi:include href="Channel_Interface_DTMF.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_Password.xml"/>
-<xi:include href="Channel_Interface_Transfer.xml"/>
+<!-- Causes havoc, never implemented, unclear requirements
+<xi:include href="Channel_Interface_Transfer.xml"/> -->
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
+<xi:include href="Channel_Interface_Messages.xml"/>
<xi:include href="Media_Session_Handler.xml"/>
<xi:include href="Media_Stream_Handler.xml"/>
<xi:include href="Properties_Interface.xml"/>
+<xi:include href="Account_Manager.xml"/>
+<xi:include href="Account.xml"/>
+
<xi:include href="Channel_Handler.xml"/>
<xi:include href="errors.xml"/>
<xi:include href="generic-types.xml"/>
-<xi:include href="extensions.xml">
- <xi:fallback>
- <!-- absence of non-spec extensions is OK -->
- </xi:fallback>
-</xi:include>
-
</tp:spec>
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index f134d7c..c0a000d 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -5,30 +5,6 @@
<tp:docstring>An unsigned 32-bit integer representing time since 1970</tp:docstring>
</tp:simple-type>
- <tp:simple-type name="Handle" type="u">
- <tp:docstring>An unsigned 32-bit integer representing a handle</tp:docstring>
- </tp:simple-type>
-
- <tp:simple-type name="Contact_Handle" type="u">
- <tp:docstring>An unsigned 32-bit integer representing a handle of type
- Handle_Type_Contact</tp:docstring>
- </tp:simple-type>
-
- <tp:simple-type name="Room_Handle" type="u">
- <tp:docstring>An unsigned 32-bit integer representing a handle of type
- Handle_Type_Room</tp:docstring>
- </tp:simple-type>
-
- <tp:simple-type name="List_Handle" type="u">
- <tp:docstring>An unsigned 32-bit integer representing a handle of type
- Handle_Type_List</tp:docstring>
- </tp:simple-type>
-
- <tp:simple-type name="Group_Handle" type="u">
- <tp:docstring>An unsigned 32-bit integer representing a handle of type
- Handle_Type_Group</tp:docstring>
- </tp:simple-type>
-
<tp:simple-type name="DBus_Bus_Name" type="s">
<tp:docstring>A string representing a D-Bus bus name - either a well-known
name like "org.freedesktop.Telepathy.MissionControl" or a unique name
@@ -41,7 +17,11 @@
</tp:simple-type>
<tp:simple-type name="DBus_Interface" type="s">
- <tp:docstring>A string representing a D-Bus interface</tp:docstring>
+ <tp:docstring>An ASCII string representing a D-Bus interface - two or more
+ elements separated by dots, where each element is a non-empty
+ string of ASCII letters, digits and underscores, not starting with
+ a digit. The maximum total length is 255 characters. For example,
+ "org.freedesktop.DBus.Peer".</tp:docstring>
</tp:simple-type>
<tp:simple-type name="DBus_Signature" type="s">
@@ -50,6 +30,35 @@
with dbus-glib)</tp:docstring>
</tp:simple-type>
+ <tp:simple-type name="DBus_Member" type="s">
+ <tp:docstring>An ASCII string representing a D-Bus method, signal
+ or property name - a non-empty string of ASCII letters, digits and
+ underscores, not starting with a digit, with a maximum length of 255
+ characters. For example, "Ping".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Qualified_Member" type="s">
+ <tp:docstring>A string representing the full name of a D-Bus method,
+ signal or property, consisting of a DBus_Interface, followed by
+ a dot, followed by a DBus_Member. For example,
+ "org.freedesktop.DBus.Peer.Ping".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Qualified_Property_Value_Map">
+ <tp:docstring>A mapping from strings representing D-Bus
+ properties (by their namespaced names) to their values.</tp:docstring>
+ <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
+ <tp:docstring>
+ A D-Bus interface name, followed by a dot and a D-Bus property name.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="v" name="Value">
+ <tp:docstring>
+ The value of the property.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
<tp:mapping name="String_Variant_Map">
<tp:docstring>A mapping from strings to variants representing extra
key-value pairs.</tp:docstring>
--
1.5.6.3
More information about the Telepathy-commits
mailing list