summaryrefslogtreecommitdiff
path: root/spec
diff options
context:
space:
mode:
authorAndre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>2011-01-07 01:08:02 -0200
committerAndre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>2011-01-07 18:27:15 -0200
commitcf6fee0bf643c65956e2ab20ea50666833a0e3af (patch)
treec13fd20a1da3e1d8b4170aa754fb12a3b2e36c08 /spec
Start developement.
Diffstat (limited to 'spec')
-rw-r--r--spec/Account.xml733
-rw-r--r--spec/Account_Interface_Addressing.xml76
-rw-r--r--spec/Account_Interface_Avatar.xml76
-rw-r--r--spec/Account_Interface_Storage.xml169
-rw-r--r--spec/Account_Manager.xml296
-rw-r--r--spec/Authentication_TLS_Certificate.xml305
-rw-r--r--spec/Call_Content.xml291
-rw-r--r--spec/Call_Content_Codec_Offer.xml87
-rw-r--r--spec/Call_Content_Interface_Media.xml331
-rw-r--r--spec/Call_Content_Interface_Mute.xml85
-rw-r--r--spec/Call_Stream.xml261
-rw-r--r--spec/Call_Stream_Endpoint.xml182
-rw-r--r--spec/Call_Stream_Interface_Media.xml447
-rw-r--r--spec/Channel.xml557
-rw-r--r--spec/Channel_Bundle.xml48
-rw-r--r--spec/Channel_Dispatch_Operation.xml483
-rw-r--r--spec/Channel_Dispatcher.xml595
-rw-r--r--spec/Channel_Dispatcher_Interface_Operation_List.xml140
-rw-r--r--spec/Channel_Future.xml68
-rw-r--r--spec/Channel_Handler.xml78
-rw-r--r--spec/Channel_Interface_Addressing.xml107
-rw-r--r--spec/Channel_Interface_Anonymity.xml68
-rw-r--r--spec/Channel_Interface_Call_State.xml147
-rw-r--r--spec/Channel_Interface_Chat_State.xml144
-rw-r--r--spec/Channel_Interface_Conference.xml628
-rw-r--r--spec/Channel_Interface_DTMF.xml342
-rw-r--r--spec/Channel_Interface_Destroyable.xml82
-rw-r--r--spec/Channel_Interface_Group.xml1166
-rw-r--r--spec/Channel_Interface_HTML.xml86
-rw-r--r--spec/Channel_Interface_Hold.xml222
-rw-r--r--spec/Channel_Interface_Media_Signalling.xml235
-rw-r--r--spec/Channel_Interface_Mergeable_Conference.xml110
-rw-r--r--spec/Channel_Interface_Messages.xml1433
-rw-r--r--spec/Channel_Interface_Password.xml104
-rw-r--r--spec/Channel_Interface_Room.xml373
-rw-r--r--spec/Channel_Interface_SASL_Authentication.xml704
-rw-r--r--spec/Channel_Interface_SMS.xml179
-rw-r--r--spec/Channel_Interface_Securable.xml78
-rw-r--r--spec/Channel_Interface_Service_Point.xml86
-rw-r--r--spec/Channel_Interface_Splittable.xml71
-rw-r--r--spec/Channel_Interface_Transfer.xml53
-rw-r--r--spec/Channel_Interface_Tube.xml258
-rw-r--r--spec/Channel_Request.xml300
-rw-r--r--spec/Channel_Type_Call.xml1429
-rw-r--r--spec/Channel_Type_Contact_List.xml104
-rw-r--r--spec/Channel_Type_Contact_Search.xml462
-rw-r--r--spec/Channel_Type_DBus_Tube.xml189
-rw-r--r--spec/Channel_Type_File_Transfer.xml531
-rw-r--r--spec/Channel_Type_Room_List.xml166
-rw-r--r--spec/Channel_Type_Server_Authentication.xml121
-rw-r--r--spec/Channel_Type_Server_TLS_Connection.xml69
-rw-r--r--spec/Channel_Type_Stream_Tube.xml292
-rw-r--r--spec/Channel_Type_Streamed_Media.xml853
-rw-r--r--spec/Channel_Type_Text.xml669
-rw-r--r--spec/Channel_Type_Tubes.xml615
-rw-r--r--spec/Client.xml122
-rw-r--r--spec/Client_Approver.xml197
-rw-r--r--spec/Client_Handler.xml337
-rw-r--r--spec/Client_Handler_Future.xml88
-rw-r--r--spec/Client_Interface_Requests.xml175
-rw-r--r--spec/Client_Observer.xml379
-rw-r--r--spec/Connection.xml1293
-rw-r--r--spec/Connection_Future.xml110
-rw-r--r--spec/Connection_Interface_Addressing.xml258
-rw-r--r--spec/Connection_Interface_Aliasing.xml185
-rw-r--r--spec/Connection_Interface_Anonymity.xml165
-rw-r--r--spec/Connection_Interface_Avatars.xml516
-rw-r--r--spec/Connection_Interface_Balance.xml111
-rw-r--r--spec/Connection_Interface_Capabilities.xml254
-rw-r--r--spec/Connection_Interface_Cellular.xml131
-rw-r--r--spec/Connection_Interface_Client_Types.xml218
-rw-r--r--spec/Connection_Interface_Communication_Policy.xml163
-rw-r--r--spec/Connection_Interface_Contact_Capabilities.xml306
-rw-r--r--spec/Connection_Interface_Contact_Groups.xml549
-rw-r--r--spec/Connection_Interface_Contact_Info.xml550
-rw-r--r--spec/Connection_Interface_Contact_List.xml1085
-rw-r--r--spec/Connection_Interface_Contacts.xml191
-rw-r--r--spec/Connection_Interface_Forwarding.xml346
-rw-r--r--spec/Connection_Interface_Keepalive.xml73
-rw-r--r--spec/Connection_Interface_Location.xml464
-rw-r--r--spec/Connection_Interface_Mail_Notification.xml624
-rw-r--r--spec/Connection_Interface_Power_Saving.xml109
-rw-r--r--spec/Connection_Interface_Presence.xml346
-rw-r--r--spec/Connection_Interface_Privacy.xml94
-rw-r--r--spec/Connection_Interface_Renaming.xml98
-rw-r--r--spec/Connection_Interface_Requests.xml628
-rw-r--r--spec/Connection_Interface_Resources.xml212
-rw-r--r--spec/Connection_Interface_Service_Point.xml136
-rw-r--r--spec/Connection_Interface_Simple_Presence.xml634
-rw-r--r--spec/Connection_Manager.xml614
-rw-r--r--spec/Debug.xml165
-rw-r--r--spec/Media_Session_Handler.xml81
-rw-r--r--spec/Media_Stream_Handler.xml725
-rw-r--r--spec/Properties_Interface.xml194
-rw-r--r--spec/Protocol.xml485
-rw-r--r--spec/Protocol_Interface_Addressing.xml300
-rw-r--r--spec/Protocol_Interface_Avatars.xml157
-rw-r--r--spec/Protocol_Interface_Presence.xml113
-rw-r--r--spec/all.xml303
-rw-r--r--spec/errors.xml564
-rw-r--r--spec/generic-types.xml215
-rw-r--r--spec/template.xml33
102 files changed, 32880 insertions, 0 deletions
diff --git a/spec/Account.xml b/spec/Account.xml
new file mode 100644
index 0000000..acd8c30
--- /dev/null
+++ b/spec/Account.xml
@@ -0,0 +1,733 @@
+<?xml version="1.0" ?>
+<node name="/Account"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
+ but with "-" replaced with "_"
+ (i.e. the same as in the object-path of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</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" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read">
+ <tp:docstring>
+ A list of the extra interfaces provided by this account.
+ </tp:docstring>
+ </property>
+
+ <method name="Remove" tp:name-for-bindings="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:name-for-bindings="Removed">
+ <tp:docstring>
+ This account has been removed.
+
+ <tp:rationale>
+ This is redundant with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
+ 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:name-for-bindings="Account_Property_Changed">
+ <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.
+ <tp:member-ref>Nickname</tp:member-ref>) 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:name-for-bindings="Display_Name">
+ <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@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" tp:name-for-bindings="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" tp:name-for-bindings="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" tp:name-for-bindings="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>
+ </tp:rationale>
+
+ <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:docstring>
+ </property>
+
+ <property name="Nickname" tp:name-for-bindings="Nickname"
+ type="s" 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
+ 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="Service" tp:name-for-bindings="Service" type="s"
+ access="readwrite">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some protocols, like XMPP and SIP, are used by various different
+ user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by
+ Nokia</i>. On accounts for such services, this property SHOULD be
+ set to a string describing the service, which MUST consist only of
+ ASCII letters, numbers and hyphen/minus signs, and start with a
+ letter (matching the requirements for <tp:type>Protocol</tp:type>).
+ For the <tt>jabber</tt> protocol, one of the following service names
+ should be used if possible:</p>
+
+ <ul>
+ <li><tt>google-talk</tt> (for <a
+ href="http://www.google.com/talk/">Google's IM service</a>)</li>
+ <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM
+ service)</li>
+ <li><tt>facebook</tt> (for <a
+ href="http://www.facebook.com/sitetour/chat.php">Facebook's IM
+ service</a>)</li>
+ <li><tt>lj-talk</tt> (for <a
+ href="http://www.livejournal.com/chat/">LiveJournal's IM
+ service</a>)</li>
+
+ </ul>
+
+ <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a
+ corresponding brand-specific icon name, if possible. In the future,
+ this property may be used as an index into additional
+ service-specific customizations. If this property is the empty string
+ (or missing), the service is determined by the protocol name (either
+ because this is a single-service protocol like <tt>msn</tt>, or
+ because this is just a generic <tt>jabber</tt> or <tt>sip</tt>
+ account without specific branding).</p>
+
+ <p>This property MAY be set, if appropriate, when calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager"
+ >CreateAccount</tp:dbus-ref>. Updating this property will fail on
+ externally-stored accounts whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Storage"
+ >StorageRestrictions</tp:dbus-ref> include
+ <code>Cannot_Set_Service</code>.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Parameters" tp:name-for-bindings="Parameters"
+ type="a{sv}" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from connection manager parameter names (as in the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+ 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
+ <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref>
+ property.</p>
+
+ <p>If any of the changed parameters'
+ <tp:type>Conn_Mgr_Param_Flags</tp:type> include
+ <code>DBus_Property</code>, the change will be applied immediately to
+ the
+ corresponding D-Bus Property on the active
+ <tp:member-ref>Connection</tp:member-ref>, if there is one. Changes to
+ other parameters will not take effect until the next time the account
+ is disconnected and reconnected.</p>
+
+ <tp:rationale>
+ <p>In general, reconnecting is a destructive operation that shouldn't
+ happen as a side-effect. In particular, migration tools that
+ twiddle the settings of all accounts shouldn't cause an automatic
+ disconnect and reconnect.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:changed version="0.17.16">
+ parameters which are also D-Bus properties can and should be updated on
+ existing Connections
+ </tp:changed>
+
+ <tp:changed version="0.17.24">
+ return an array of the parameters that won't change until the account
+ is reconnected
+ </tp:changed>
+
+ <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>
+
+ <arg name="Reconnect_Required" type="as" direction="out">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If all of the parameters had the <code>DBus_Property</code> flag,
+ the empty list, signifying that no reconnection is required for the
+ new parameters to take effect. For example, if the only parameter
+ updated is <tt>...Cellular.<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>,
+ the new value can be applied immediately to the connection.</p>
+
+ <p>Otherwise, a list of the names of parameters with changes that
+ will not take effect until the account is reconnected. User
+ interfaces that require "instant apply" semantics MAY call
+ <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a
+ non-empty list. For example, if the caller updates both
+ <tt>...Anonymity.<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt>
+ and <tt>require-encryption</tt>, the former can be applied to the
+ current connection, but the latter needs a reconnect to take
+ effect, so this method should return
+ <code>["require-encryption"]</code>.</p>
+ </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:name-for-bindings="Automatic_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>
+
+ <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>
+
+ <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 value of this property MUST be one that would be acceptable
+ for <tp:member-ref>RequestedPresence</tp:member-ref>,
+ with the additional restriction that the
+ <tp:type>Connection_Presence_Type</tp:type> MUST NOT be Offline.</p>
+
+ <tp:rationale>
+ <p>Otherwise, it would not be possible to use this presence to bring
+ the account online for a channel request.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectAutomatically" type="b" access="readwrite"
+ tp:name-for-bindings="Connect_Automatically">
+ <tp:docstring>
+ If true, the account manager SHOULD attempt to put this account
+ online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
+ 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 <tp:member-ref>AutomaticPresence</tp:member-ref> 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" tp:name-for-bindings="Connection"
+ type="o" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the object path of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to
+ this account, or the special value <code>'/'</code> if there is no
+ connection.</p>
+
+ <p>If this object path is not '/', the Connection's well-known bus
+ name can be derived from this object path by removing the first '/'
+ and replacing subsequent '/' characters with '.'.</p>
+
+ <tp:rationale>
+ Object paths aren't nullable, so we can't use an empty string.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionStatus" type="u" tp:type="Connection_Status"
+ access="read" tp:name-for-bindings="Connection_Status">
+ <tp:docstring>
+ If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
+ the status of that connection.
+ 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"
+ tp:type="Connection_Status_Reason" access="read"
+ tp:name-for-bindings="Connection_Status_Reason">
+ <tp:docstring>
+ The reason for the last change to
+ <tp:member-ref>ConnectionStatus</tp:member-ref>.
+ 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="ConnectionError" tp:name-for-bindings="Connection_Error"
+ access="read" type="s" tp:type="DBus_Error_Name">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the last connection to this account failed with an error,
+ the D-Bus error name of that error; otherwise, the empty string.
+ The account manager is expected to set this by observing the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.ConnectionError</tp:dbus-ref> and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.StatusChanged</tp:dbus-ref>
+ signals.</p>
+
+ <p>If ConnectionError is received before the connection disconnects,
+ its first argument should be used to set this property;
+ otherwise, the Reason argument of StatusChanged should be converted
+ to a suitable D-Bus error name.</p>
+
+ <p>Whenever the Connection connects successfully, this property should
+ be reset to the empty string.</p>
+
+ <tp:rationale>
+ <p>This combines the state-recoverability of
+ <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
+ extensibility of Connection.ConnectionError.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionErrorDetails"
+ tp:name-for-bindings="Connection_Error_Details"
+ access="read" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the last connection to this account failed with an error,
+ a mapping representing any additional information about the last
+ disconnection; otherwise, the empty map. The keys and values are
+ the same as for the second argument of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.ConnectionError</tp:dbus-ref>.</p>
+
+ <p>Whenever the Connection connects successfully, this property should
+ be reset to the empty map.</p>
+
+ <tp:rationale>
+ <p>This combines the state-recoverability of
+ <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
+ extensibility of Connection.ConnectionError.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="CurrentPresence" type="(uss)" access="read"
+ tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence">
+ <tp:docstring>
+ The actual presence. If the connection is not online, the
+ <tp:type>Connection_Presence_Type</tp:type> SHOULD be
+ Connection_Presence_Type_Offline.
+ If the connection is online but does not support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface, the type 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:name-for-bindings="Requested_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 <tp:member-ref>CurrentPresence</tp:member-ref> match
+ <tp:member-ref>RequestedPresence</tp:member-ref> 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 <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>
+
+ <tp:rationale>
+ This corresponds to e.g. GetPresence and GetPresenceMessage
+ in NMC 4.x.
+ </tp:rationale>
+
+ <p>The <tp:type>Connection_Presence_Type</tp:type> in this property
+ MUST NOT be Unset, Unknown or Error.</p>
+
+ <tp:rationale>
+ <p>Requesting those presence types doesn't make sense.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, a change to the presence of this account is
+ in progress.</p>
+
+ <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on
+ an account that could go online, or whenever an account with a
+ non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes
+ able to go online (for instance because
+ <tp:member-ref>Enabled</tp:member-ref> or
+ <tp:member-ref>Valid</tp:member-ref> changes to True),
+ ChangingPresence MUST change to True, and the two property changes MUST
+ be emitted in the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the
+ Set method returns.</p>
+
+ <p>When the account manager succeeds or fails in changing the presence,
+ or the connection disconnects due to an error, ChangingPresence MUST
+ change to False as part of the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ <p>This allows UIs to indicate that a presence change is in progress
+ or has finished, even if the change was initiated by a different
+ UI.</p>
+
+ <p>For instance, Maemo 5 and Empathy indicate a presence change by
+ having the presence indicator alternate between the
+ <tp:member-ref>RequestedPresence</tp:member-ref>
+ and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should
+ start blinking when ChangingPresence becomes true, and stop when it
+ becomes false.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </property>
+
+ <method name="Reconnect" tp:name-for-bindings="Reconnect">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Re-connect this account. If the account is currently disconnected
+ and the requested presence is offline, or if the account
+ is not <tp:member-ref>Enabled</tp:member-ref> or not
+ <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p>
+
+ <p>If the account is disconnected and the requested presence is not
+ offline, this forces an attempt to connect with the requested
+ presence immediately.</p>
+
+ <p>If the account is connecting or connected, this is equivalent to
+ remembering the current value of
+ <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value
+ to (OFFLINE, "offline", ""), waiting for the change to take effect,
+ then setting its value to the value that was previously
+ remembered.</p>
+
+ <tp:rationale>
+ <p>Clients desiring "instant apply" semantics for CM parameters MAY
+ call this method to achieve that.</p>
+ </tp:rationale>
+
+ <p>In particular, if the account's
+ <tp:member-ref>Connection</tp:member-ref> is in the Connecting
+ state, calling this method causes the attempt to connect to be
+ aborted and re-tried.</p>
+
+ <tp:rationale>
+ <p>This is necessary to ensure that the new parameters are
+ picked up.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <property name="NormalizedName" type="s" access="read"
+ tp:name-for-bindings="Normalized_Name">
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ method is called on the
+ result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>
+ 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>
+
+ <property name="HasBeenOnline" tp:name-for-bindings="Has_Been_Online"
+ type="b" access="read">
+ <tp:docstring>
+ If true, this account has successfully been put online at some point
+ in the past.
+
+ <tp:rationale>
+ UIs could apply a policy that the 'account' parameter can only be
+ edited in accounts that have never been online, or that
+ ConnectAutomatically cannot be set on such accounts. The account
+ manager should not enforce such policies, but it can expose enough
+ information to UIs that the UI can decide what to do.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml
new file mode 100644
index 0000000..4b2846b
--- /dev/null
+++ b/spec/Account_Interface_Addressing.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Ltd</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.Addressing">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some accounts can be used for multiple protocols; for instance, SIP
+ and Skype accounts can often be used to contact the PSTN, MSN and
+ Yahoo accounts can contact each other, and XMPP accounts can
+ potentially contact many protocols via a transport.</p>
+ <p>However, if the user does not intend to make use of this functionality,
+ user interfaces can improve clarity by not displaying it: for instance,
+ if a user prefers to call phone numbers via a particular SIP account,
+ when an address book displays a contact with a phone number, it is
+ desirable to display a "call with SIP" button for that account, but
+ avoid displaying similar buttons for any other configured SIP or
+ Skype accounts.</p>
+ <p>The purpose of this interface is to allow this "for use with" information
+ to be recorded and retrieved.</p>
+ </tp:docstring>
+
+ <property name="URISchemes" type="as" access="read"
+ tp:name-for-bindings="URI_Schemes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of fields indicating the type of URI addressing scheme
+ the the account should be used for (eg 'tel') indicating the
+ account is intended for use by applications offering a telephony
+ UI, or 'sip' or 'xmpp' for those protocols</p>
+ <p>Note that these fields signify intent, not ability: It is
+ entirely possible that an account which can be used for a
+ given URI scheme is not wanted for it by the user, and
+ therefore not flagged as such in this field.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="SetURISchemeAssociation"
+ tp:name-for-bindings="Set_URI_Scheme_Association">
+ <tp:docstring>
+ <p>Associate (or disassociate) an account with a particular
+ URI addressing scheme, (such as 'tel' for telephony)</p>
+ </tp:docstring>
+
+ <arg name="URI_Scheme" direction="in" type="s">
+ <tp:docstring>
+ <p>URI scheme to associate/disassociate the account with/from</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Association" direction="in" type="b">
+ <tp:docstring>
+ <p>True to associate this account with a given addressing scheme</p>
+ <p>False if the account should not be associated with said scheme</p>
+ </tp:docstring>
+ </arg>
+
+ </method>
+
+ </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..6c85b8e
--- /dev/null
+++ b/spec/Account_Interface_Avatar.xml
@@ -0,0 +1,76 @@
+<?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:requires interface="org.freedesktop.Telepathy.Account"/>
+
+ <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"/>
+
+ <tp:struct name="Avatar">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A struct containing avatar data marked with its MIME type.</p>
+ </tp:docstring>
+ <tp:member type="ay" name="Avatar_Data"/>
+ <tp:member type="s" name="MIME_Type"/>
+ </tp:struct>
+
+ <property name="Avatar" tp:name-for-bindings="Avatar"
+ type="(ays)" tp:type="Avatar" 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:name-for-bindings="Avatar_Changed">
+ <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_Interface_Storage.xml b/spec/Account_Interface_Storage.xml
new file mode 100644
index 0000000..4e3ba5d
--- /dev/null
+++ b/spec/Account_Interface_Storage.xml
@@ -0,0 +1,169 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Storage"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.Storage">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ This interface extends the core Account interface to specify details
+ regarding the storage of this account.
+ </p>
+
+ <tp:rationale>
+ <p>
+ Single-sign-on systems do not generally have directly user-editable
+ properties for Accounts, and require the user to visit a specific UI
+ to alter their account properties. User interfaces should know not to
+ expose these account properties as user-editable, and instead
+ redirect the user to the appropriate interface.
+ </p>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.19.8"/>
+
+ <property name="StorageProvider" tp:name-for-bindings="Storage_Provider"
+ type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The name of the account storage implementation, which SHOULD start
+ with a reversed domain name in the same way as D-Bus interface names.
+ When this is the empty string the account is internally stored.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageIdentifier"
+ tp:name-for-bindings="Storage_Identifier" type="v" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Unique identification of the account within the storage backend.
+ The contents of the variant are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ <tp:rationale>
+ <p>
+ Different storage systems will have their own way of uniquely
+ identifying an account, typically an integer or a string.
+ Given that all users of this property should have direct knowledge
+ of the backend they should know what types to expect and how to
+ handle it.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageSpecificInformation"
+ tp:name-for-bindings="Storage_Specific_Information" type="a{sv}"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Map containing information specific to the storage backend. The keys
+ and the types of their values are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>, and are not
+ interpreted by the AccountManager implementation.
+ </p>
+ <p>
+ As the values in this map may change at any time (due to an external
+ application manipulating the storage provider directly), this
+ property should not be cached; it should instead be retrieved each
+ time it is needed.
+ </p>
+
+ <tp:rationale>
+ <p>
+ This can be used to provide additional hints to user interfaces
+ aware of a specific storage provider, without requiring those user
+ interfaces to use the
+ <tp:member-ref>StorageIdentifier</tp:member-ref> to query the
+ storage provider directly.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageRestrictions"
+ tp:name-for-bindings="Storage_Restrictions" type="u"
+ tp:type="Storage_Restriction_Flags"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Bitfield which defines what restrictions this Storage method has.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Storage_Restriction_Flags"
+ value-prefix="Storage_Restriction_Flag" type="u">
+ <tp:docstring>
+ Flags indicating restrictions imposed on an Account by its storage
+ method.
+ </tp:docstring>
+
+ <tp:flag suffix="Cannot_Set_Parameters" value="1">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Parameters</tp:dbus-ref> property can't be changed by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account"
+ >UpdateParameters</tp:dbus-ref>.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Enabled" value="2">
+ <tp:docstring>
+ The account can't be enabled/disabled by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Enabled</tp:dbus-ref> property.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Presence" value="4">
+ <tp:docstring>
+ The account's presence can't be changed by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >AutomaticPresence</tp:dbus-ref> properties.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Service" value="8">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref>
+ property cannot be changed.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
new file mode 100644
index 0000000..cd82e7f
--- /dev/null
+++ b/spec/Account_Manager.xml
@@ -0,0 +1,296 @@
+<?xml version="1.0" ?>
+<node name="/Account_Manager"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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>
+
+ <p>Until a mechanism exists for making a reasonable automatic choice
+ of AccountManager implementation, implementations SHOULD NOT
+ register as an activatable service for the AccountManager's
+ well-known bus name. Instead, it is RECOMMENDED that some component
+ of the user's session will select and activate a particular
+ implementation, and that other Telepathy-enabled programs can
+ detect whether Telepathy is in use by checking whether the
+ AccountManager's well-known name is in use at runtime.</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" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" 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:name-for-bindings="Valid_Accounts">
+ <tp:docstring>
+ A list of the valid (complete, usable) <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change
+ notification is via
+ <tp:member-ref>AccountValidityChanged</tp:member-ref>.
+
+ <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:name-for-bindings="Invalid_Accounts">
+ <tp:docstring>
+ A list of incomplete or otherwise unusable <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change
+ notification is via
+ <tp:member-ref>AccountValidityChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="AccountRemoved" tp:name-for-bindings="Account_Removed">
+ <tp:docstring>
+ The given account has been removed.
+
+ <tp:rationale>
+ This is effectively change notification for the valid and invalid
+ accounts lists. On emission of this signal, the Account indicated
+ will no longer be present in either of the 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:name-for-bindings="Account_Validity_Changed">
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Valid" type="b">
+ <tp:docstring>
+ True if the account is now valid.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SupportedAccountProperties"
+ tp:name-for-bindings="Supported_Account_Properties"
+ type="as" tp:type="DBus_Qualified_Member[]" access="read">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the fully qualified names of properties that can be set
+ via the Properties argument to
+ <tp:member-ref>CreateAccount</tp:member-ref> when an account is
+ created.</p>
+
+ <tp:rationale>
+ <p>Examples of good properties to support here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>.
+ </p>
+
+ <p>Examples of properties that would make no sense here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>.
+ </p>
+ </tp:rationale>
+
+ <p>This property MUST NOT include include the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties, which are set using separate arguments.</p>
+
+ <p>This property MAY include the names of properties that, after
+ account creation, will be read-only: this indicates that the property
+ can be set at account creation but not changed later.</p>
+
+ <tp:rationale>
+ <p>For example, an account manager might support migration tools that
+ use this to preserve the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref>
+ property, even though that property is usually read-only.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="CreateAccount" tp:name-for-bindings="Create_Account">
+ <tp:docstring>
+ Request the creation of a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The
+ account manager SHOULD NOT allow invalid accounts to be created.
+ </tp:docstring>
+ <tp:changed version="0.17.24">added the Properties argument</tp:changed>
+
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ property. The account manager SHOULD modify this to make it unique if
+ an Account already exists with the same display name, for instance by
+ appending a number or the 'account' parameter. Account manager
+ implementations SHOULD accept an empty string, but account editing
+ user interfaces should avoid passing an empty string for this
+ parameter.
+
+ <tp:rationale>
+ <p>The account creation UI may ask the user for a name for the new
+ account. If the author of the UI chooses not to do this, the
+ account creation UI is better able to suggest a default display
+ name because it has protocol-specific knowledge which the account
+ manager does not.</p>
+
+ <p>The account manager always knows the complete list of accounts so
+ it can easily tell whether it should append something to the
+ display name to avoid presenting two identically-named accounts to
+ the user.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Parameters" direction="in" type="a{sv}">
+ <tp:docstring>Initial parameter values, as would be passed to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Properties" direction="in" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The values of any other properties to be set immediately on the
+ new Account.</p>
+
+ <p>Only the properties mentioned in
+ <tp:member-ref>SupportedAccountProperties</tp:member-ref> are
+ acceptable here. In particular, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties are never allowed here, since they are set using the other
+ arguments to this method.</p>
+
+ <p>Account manager implementations SHOULD support creating accounts
+ with an empty value for this argument.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Account" direction="out" type="o">
+ <tp:docstring>The new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Connection_Manager is not installed or does not
+ implement the given Protocol, or one of the properties in the
+ Properties argument is unsupported.</p>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Parameters provided omit a required parameter
+ or provide unsupported parameter, or the type of one
+ of the Parameters or Properties is inappropriate.</p>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml
new file mode 100644
index 0000000..db1d76f
--- /dev/null
+++ b/spec/Authentication_TLS_Certificate.xml
@@ -0,0 +1,305 @@
+<?xml version="1.0" ?>
+<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate">
+ <tp:added version="0.19.13">(as stable API)</tp:added>
+
+ <tp:docstring>
+ This object represents a TLS certificate.
+ </tp:docstring>
+
+ <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List"
+ type="ay">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The raw data contained in a TLS certificate.</p>
+
+ <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref>
+ = "x509"), this MUST be in DER format, as defined by the
+ <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a>
+ ITU standard.</p>
+
+ <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref>
+ = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1
+ of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Struct representing one reason why a TLS certificate was rejected.</p>
+ <p>Since there can be multiple things wrong with a TLS certificate,
+ arrays of this type are used to represent lists of reasons for
+ rejection. In that case, the most important reason SHOULD be placed
+ first in the list.</p>
+ </tp:docstring>
+
+ <tp:member name="Reason" type="u"
+ tp:type="TLS_Certificate_Reject_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The value of the TLS_Certificate_Reject_Reason enumeration for
+ this certificate rejection.
+ <tp:rationale>
+ Clients that do not understand the <code>Error</code> member,
+ which may be implementation-specific, can use this property to
+ classify rejection reasons into common categories.
+ </tp:rationale>
+ </p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Error" type="s"
+ tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The DBus error name for this certificate rejection.</p>
+ <p>This MAY correspond to the value of the <code>Reason</code> member,
+ or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Details" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about why the certificate was rejected.
+ This MAY also include one or more of the following well-known keys:</p>
+ <p>
+ <dl>
+ <dt>user-requested (b)</dt>
+ <dd>True if the error was due to an user-requested rejection of
+ the certificate; False if there was an unrecoverable error in the
+ verification process.</dd>
+ <dt>expected-hostname (s)</dt>
+ <dd>If the rejection reason is Hostname_Mismatch, the hostname that
+ the server certificate was expected to have.</dd>
+ <dt>certificate-hostname (s)</dt>
+ <dd>If the rejection reason is Hostname_Mismatch, the hostname of
+ the certificate that was presented.
+ <tp:rationale>
+ <p>For instance, if you try to connect to gmail.com but are presented
+ with a TLS certificate issued to evil.example.org, the error details
+ for Hostname_Mismatch MAY include:</p>
+ <pre>
+ {
+ 'expected-hostname': 'gmail.com',
+ 'certificate-hostname': 'evil.example.org',
+ }
+ </pre>
+ </tp:rationale>
+ </dd>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the error, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ </dl>
+ </p>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:enum type="u" name="TLS_Certificate_State">
+ <tp:docstring>
+ The possible states for a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
+ object.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Pending" value="0">
+ <tp:docstring>
+ The certificate is currently waiting to be accepted or rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Accepted" value="1">
+ <tp:docstring>
+ The certificate has been verified.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Rejected" value="2">
+ <tp:docstring>
+ The certificate has been rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum type="u" name="TLS_Certificate_Reject_Reason">
+ <tp:docstring>
+ Possible reasons to reject a TLS certificate.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ The certificate has been rejected for another reason
+ not listed in this enumeration.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Untrusted" value="1">
+ <tp:docstring>
+ The certificate is not trusted.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Expired" value="2">
+ <tp:docstring>
+ The certificate is expired.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Not_Activated" value="3">
+ <tp:docstring>
+ The certificate is not active yet.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Fingerprint_Mismatch" value="4">
+ <tp:docstring>
+ The certificate provided does not have the expected
+ fingerprint.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Hostname_Mismatch" value="5">
+ <tp:docstring>
+ The hostname certified does not match the provided one.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Self_Signed" value="6">
+ <tp:docstring>
+ The certificate is self-signed.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Revoked" value="7">
+ <tp:docstring>
+ The certificate has been revoked.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Insecure" value="8">
+ <tp:docstring>
+ The certificate uses an insecure cipher algorithm, or is
+ cryptographically weak.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Limit_Exceeded" value="9">
+ <tp:docstring>
+ The length in bytes of the certificate, or the depth of the
+ certificate chain exceed the limits imposed by the crypto
+ library.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="State" type="u" access="read"
+ tp:type="TLS_Certificate_State"
+ tp:name-for-bindings="State">
+ <tp:docstring>
+ The current state of this certificate.
+ State change notifications happen by means of the
+ <tp:member-ref>Accepted</tp:member-ref> and
+ <tp:member-ref>Rejected</tp:member-ref> signals.
+ </tp:docstring>
+ </property>
+
+ <property name="Rejections" type="a(usa{sv})" access="read"
+ tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
+ an array of <tp:type>TLS_Certificate_Rejection</tp:type>
+ structures containing the reason why the certificate is rejected.</p>
+ <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
+ this property is not meaningful, and SHOULD be set to an empty
+ array.</p>
+ <p>The first rejection in the list MAY be assumed to be
+ the most important; if the array contains more than one
+ element, the CM MAY either use the values after the first,
+ or ignore them.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CertificateType" type="s" access="read"
+ tp:name-for-bindings="Certificate_Type">
+ <tp:docstring>
+ The type of this TLS certificate (e.g. 'x509' or 'pgp').
+ <p>This property is immutable</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CertificateChainData" type="aay" access="read"
+ tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more TLS certificates forming a trust chain, each encoded as
+ specified by <tp:type>Certificate_Data</tp:type>.</p>
+ <p>The first certificate in the chain MUST be the server certificate,
+ followed by the issuer's certificate, followed by the issuer's issuer
+ and so on.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="Accepted"
+ tp:name-for-bindings="Accepted">
+ <tp:docstring>
+ The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted.
+ </tp:docstring>
+ </signal>
+
+ <signal name="Rejected"
+ tp:name-for-bindings="Rejected">
+ <tp:docstring>
+ The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected.
+ </tp:docstring>
+ <arg name="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]">
+ <tp:docstring>
+ The new value of the <tp:member-ref>Rejections</tp:member-ref> property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <tp:docstring>
+ Accepts this certificate, i.e. marks it as verified.
+ </tp:docstring>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Rejects this certificate.
+ </tp:docstring>
+ <arg direction="in" type="a(usa{sv})" name="Rejections"
+ tp:type="TLS_Certificate_Rejection[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p>
+ <p>This MUST NOT be an empty array.</p>
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref>
+ is not <code>Pending</code>, or when the provided rejection list is empty.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml
new file mode 100644
index 0000000..17ed710
--- /dev/null
+++ b/spec/Call_Content.xml
@@ -0,0 +1,291 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Content.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents one Content inside a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For
+ example, in an audio/video call there would be one audio content
+ and one video content. Each content has one or more <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which
+ represent the actual transport to one or more remote contacts.
+ </tp:docstring>
+
+ <tp:enum name="Content_Removal_Reason" type="u">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ A representation of the reason for a content to be removed,
+ which may be used by simple clients, or used as a fallback
+ when the DBus_Reason is not understood. This enum will be
+ extended with future reasons as and when appropriate, so
+ clients SHOULD keep up to date with its values, but also be
+ happy to fallback to the Unknown value when an unknown value
+ is encountered.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ We just don't know. Unknown values of this enum SHOULD also be
+ treated like this.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="User_Requested" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local user requests that this content is removed
+ from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Error" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There is an error with the content which means that it
+ has to be removed from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Unsupported" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some aspect of the content is unsupported so has to be
+ removed from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <method name="Remove" tp:name-for-bindings="Remove">
+ <tp:changed version="0.21.2">previously there were no
+ arguments</tp:changed>
+ <tp:docstring>
+ Remove the content from the call.
+ </tp:docstring>
+
+ <arg direction="in" name="Reason" type="u"
+ tp:type="Content_Removal_Reason">
+ <tp:docstring>
+ A generic hangup reason.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Detailed_Removal_Reason" type="s"
+ tp:type="DBus_Error_Name">
+ <tp:docstring>
+ A more specific reason for the content removal, if one is
+ available, or an empty string.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A human-readable message for the reason of removing the
+ content, such as "Fatal streaming failure" or "no codec
+ intersection". This property can be left empty if no reason
+ is to be given.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised when a Call doesn't support removing contents
+ (e.g. a Google Talk video call).
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Removed" tp:name-for-bindings="Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the content is removed from the call. This
+ is the same as the <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT.ContentRemoved</tp:dbus-ref>
+ signal.</p>
+ </tp:docstring>
+ </signal>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:added version="0.19.11"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this content, such as <tp:dbus-ref
+ namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or
+ <tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>.
+ This SHOULD NOT include the Content interface itself, and cannot
+ change once the content has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Name" tp:name-for-bindings="Name" type="s" access="read"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the content.</p>
+
+ <tp:rationale>
+ The content name property should be meaningful, so should be
+ given a name which is significant to the user. The name
+ could be the "audio" or "video" string localized, or perhaps
+ include some string identifying the source, such as a webcam
+ identifier.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Type" tp:name-for-bindings="Type"
+ type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The media type of this content.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_Content_Disposition" type="u">
+ <tp:docstring>
+ The disposition of this content, which defines whether to
+ automatically start sending data on the streams when
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is
+ called on the channel.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The content has no specific disposition
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Initial" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The content was initially part of the call. When
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ is called on the channel, all streams of this content with
+ <tp:dbus-ref
+ namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref>
+ set to <tp:type>Sending_State</tp:type>_Pending_Send will be
+ moved to <tp:type>Sending_State</tp:type>_Sending as if
+ <tp:dbus-ref
+ namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref>
+ (True) had been called.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Disposition" tp:name-for-bindings="Disposition"
+ type="u" tp:type="Call_Content_Disposition" access="read"
+ tp:immutable="yes">
+ <tp:docstring>
+ The disposition of this content.
+ </tp:docstring>
+ </property>
+
+ <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added">
+ <tp:changed version="0.21.2">plural version, renamed from
+ StreamAdded</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when streams are added to a call.</p>
+ </tp:docstring>
+ <arg name="Streams" type="ao">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were
+ added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed">
+ <tp:changed version="0.21.2">plural version, renamed from
+ StreamRemoved</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when streams are removed from a call</p>
+ </tp:docstring>
+ <arg name="Streams" type="ao">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were
+ removed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Streams" tp:name-for-bindings="Streams"
+ type="ao" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of <tp:dbus-ref namespace="ofdT.Call"
+ >Stream.DRAFT</tp:dbus-ref> objects that exist in this
+ content.</p>
+
+ <tp:rationale>
+ In a conference call multiple parties can share one media
+ content (say, audio), but the streaming of that media can
+ either be shared or separate. For example, in a multicast
+ conference all contacts would share one stream, while in a
+ Muji conference there would be a stream for each
+ participant.
+ </tp:rationale>
+
+ <p>Change notification is through the
+ <tp:member-ref>StreamsAdded</tp:member-ref> and
+ <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_Content_Packetization_Type" type="u">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ A packetization method that can be used for a content.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="RTP" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Real-time Transport Protocol, as documented by RFC 3550.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Raw" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Raw media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="MSN_Webcam" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ MSN webcam. This is the video-only one-way type which was
+ used in earlier versions of WLM. Although no longer used,
+ modern WLM clients still support the MSN webcam protocol.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Packetization" tp:name-for-bindings="Packetization"
+ type="u" tp:type="Call_Content_Packetization_Type" access="read"
+ tp:immutable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The packetization method in use for this content.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml
new file mode 100644
index 0000000..f88143f
--- /dev/null
+++ b/spec/Call_Content_Codec_Offer.xml
@@ -0,0 +1,87 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Codec_Offer"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Content.CodecOffer.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents an offer of a Codec payload mapping.
+ </tp:docstring>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The local codec mapping to send to the remote contacts and
+ to use in the <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Accept the updated Codec mapping and update the local mapping.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The codecs given as the argument are invalid in some way.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Reject the proposed update to the codecs
+ FIXME add error codes and strings here
+ </tp:docstring>
+ </method>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this codec offer. This SHOULD
+ NOT include the CodecOffer interface itself, and cannot change
+ once the content has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteContactCodecs"
+ tp:name-for-bindings="Remote_Contact_Codecs"
+ type="a(usuua{ss})" tp:type="Codec[]" access="read"
+ tp:immutable="yes">
+ <tp:docstring>
+ A list of codecs the remote contact supports.
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteContact" tp:name-for-bindings="Remote_Contact"
+ type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes">
+ <tp:docstring>
+ The contact handle that this codec offer applies to.
+ </tp:docstring>
+ </property>
+
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
new file mode 100644
index 0000000..274d8b2
--- /dev/null
+++ b/spec/Call_Content_Interface_Media.xml
@@ -0,0 +1,331 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Content.Interface.Media.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface to use by a software implementation of media
+ streaming. The reason behind splitting the members of this
+ interface out from the main <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is
+ that the software is not necessarily what controls the
+ media. An example of this is in GSM phones, where the CM just
+ tells the phone to dial a number and it does the audio routing
+ in a device specific hardware way and the CM does not need
+ to concern itself with codecs.</p>
+
+ <h4>Codec negotiation</h4>
+
+ <p>When a new <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel
+ appears, whether it was requested or not, a <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ will either be waiting in the
+ <tp:member-ref>CodecOffer</tp:member-ref> property, or will
+ appear at some point via the
+ <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p>
+
+ <p>The <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ property on the codec offer lists the codecs which are
+ supported by the remote contact, and so will determine the
+ codecs that should be proposed by the local user's streaming
+ implementation. An empty list means all codecs can be proposed.</p>
+
+ <p>For incoming calls on protocols where codecs are proposed when
+ starting the call (for example, <a
+ href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>),
+ the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ will contain information on the codecs that have already been
+ proposed by the remote contact, otherwise the codec map will
+ be the empty list.</p>
+
+ <p>The streaming implementation should look at the remote codec
+ map and the codecs known by the local user and call
+ <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref>
+ on the intersection of these two codec lists.</p>
+
+ <p>This means that in practice, outgoing calls will have a codec
+ offer pop up with no information in the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
+ so the local user will call <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
+ with the list of all codecs supported. If this codec offer is
+ accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
+ will fire with the details of the codecs passed into
+ <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If
+ the call is incoming, then the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ will contain details of the remote contact's codecs and the
+ local user will call <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
+ with the codecs that both sides understand. After the codec
+ set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref>
+ will fire to signal this change.</p>
+
+ <h4>Protocols without codec negotiation</h4>
+
+ <p>For protocols where the codecs are not negotiable, instead of
+ popping up the initial content's <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object with an empty <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
+ the CM should set the supported codec values to known codec
+ values in the said object's codec map.</p>
+
+ <h4>Changing codecs mid-call</h4>
+
+ <p>To update the codec list used mid-call, the
+ <tp:member-ref>UpdateCodecs</tp:member-ref> method should be
+ called with details of the new codec list. If this is
+ accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
+ will be emitted with the new codec set.</p>
+
+ <p>If the other side decides to update his or her codec list
+ during a call, a new <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object will appear through
+ <tp:member-ref>NewCodecOffer</tp:member-ref> which should be
+ acted on as documented above.</p>
+
+ </tp:docstring>
+
+ <tp:struct name="Codec" array-name="Codec_List">
+ <tp:docstring>
+ A description of a codec.
+ </tp:docstring>
+ <tp:member name="Identifier" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Numeric identifier for the codec. This will be used as the PT in the
+ SDP or content description.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Name" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The name of the codec.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Clockrate" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The clockrate of the codec.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Channels" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Number of channels of the codec if applicable, otherwise 0.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Extra parameters for this codec.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contact to the list of codecs he or she supports.
+ </tp:docstring>
+ <tp:member name="Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ A contact handle.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs that the contact supports.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Codec_Offering">
+ <tp:docstring>
+ A codec offer and its corresponding remote contact codec map.
+ </tp:docstring>
+ <tp:member name="Codec_Offer" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The object path to the <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref>
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The contact handle that this codec offer applies to.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})"
+ tp:type="Codec[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
+ of the codec offer.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the codecs in use change.</p>
+
+ <p>As well as acting as change notification for the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this
+ signal implies that the <tp:member-ref>CodecOffer</tp:member-ref>
+ property has changed to <code>('/', {})</code>.</p>
+ </tp:docstring>
+ <arg name="Updated_Codecs" type="a{ua(usuua{ss})}"
+ tp:type="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contact to his or her codecs. Each pair in this
+ map is added to the
+ <tp:member-ref>ContactCodecMap</tp:member-ref> property,
+ replacing any previous pair with that key.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of keys which were removed from the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because
+ those contacts left the call.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs">
+ <tp:docstring>
+ Update the local codec mapping. This method should only be
+ used during an existing call to update the codec mapping.
+ </tp:docstring>
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs now supported by the local user.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Raised when a <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object exists and is referred to in the
+ <tp:member-ref>CodecOffer</tp:member-ref> property which
+ should be used instead of calling this method, or before
+ the content's initial <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object has appeared.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map"
+ type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ <tp:docstring>
+ <p>A map from contact handles (including the local user's own handle)
+ to the codecs supported by that contact.</p>
+
+ <p>Change notification is via the
+ <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming
+ implementation MUST respond by calling the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >Accept</tp:dbus-ref> or <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >Reject</tp:dbus-ref> method on the codec offer object.</p>
+
+ <p>Emission of this signal indicates that the
+ <tp:member-ref>CodecOffer</tp:member-ref> property has changed to
+ <code>(Contact, Offer, Codecs)</code>.</p>
+ </tp:docstring>
+ <arg name="Contact" type="u">
+ <tp:docstring>
+ The contact the codec offer belongs to.
+ </tp:docstring>
+ </arg>
+ <arg name="Offer" type="o">
+ <tp:docstring>
+ The object path of the new codec offer. This replaces any previous
+ codec offer.
+ </tp:docstring>
+ </arg>
+ <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
+ of the codec offer.</p>
+
+ <tp:rationale>
+ Having the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ property here saves a D-Bus round-trip - it shouldn't be
+ necessary to get the property from the CodecOffer object, in
+ practice.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
+ type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The object path to the current
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> object, its
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties.
+ If the object path is "/" then there isn't an outstanding
+ codec offer, and the mapping MUST be empty.</p>
+
+ <tp:rationale>
+ Having the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >RemoteContact</tp:dbus-ref> and
+ <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >RemoteContactCodecs</tp:dbus-ref>
+ properties here saves a D-Bus round-trip - it shouldn't be
+ necessary to get these properties from the CodecOffer object, in
+ practice.
+ </tp:rationale>
+
+ <p>Change notification is via the
+ <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the
+ value of this property with a new codec offer), and
+ <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that
+ there is no longer any active codec offer) signals.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml
new file mode 100644
index 0000000..f926e03
--- /dev/null
+++ b/spec/Call_Content_Interface_Mute.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+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.
+
+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.
+
+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.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for calls which may be muted. This only makes sense
+ for channels where audio or video is streaming between members.</p>
+
+ <p>Muting a call content indicates that the user does not wish to send
+ outgoing audio or video.</p>
+
+ <p>Although it's client's responsibility to actually mute the microphone
+ or turn off the camera, using this interface the client can also
+ inform the CM and other clients of that fact.</p>
+
+ <tp:rationale>
+ For some protocols, the fact that the content is muted needs
+ to be transmitted to the peer; for others, the notification
+ to the peer is only informational (eg. XMPP), and some
+ protocols may have no notion of muting at all.
+ </tp:rationale>
+ </tp:docstring>
+
+ <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed">
+ <tp:docstring>
+ Emitted to indicate that the mute state has changed for this call content.
+ This may occur as a consequence of the client calling
+ <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another
+ client has (un)muted the content.
+ </tp:docstring>
+ <arg name="MuteState" type="b">
+ <tp:docstring>
+ True if the content is now muted.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="MuteState" type="b"
+ access="read" tp:name-for-bindings="Mute_State">
+ <tp:docstring>
+ True if the content is muted.
+ </tp:docstring>
+ </property>
+
+ <method name="SetMuted" tp:name-for-bindings="Set_Muted">
+ <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed>
+ <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed>
+ <arg direction="in" name="Muted" type="b">
+ <tp:docstring>
+ True if the client has muted the content.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ <p>Inform the CM that the call content has been muted or unmuted by
+ the client.</p>
+
+ <p>It is the client's responsibility to actually mute or unmute the
+ microphone or camera used for the content. However, the client
+ MUST call this whenever it mutes or unmutes the content.</p>
+ </tp:docstring>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml
new file mode 100644
index 0000000..1d7b281
--- /dev/null
+++ b/spec/Call_Stream.xml
@@ -0,0 +1,261 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Stream.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ One stream inside a <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+
+ <method name="SetSending" tp:name-for-bindings="Set_Sending">
+ <tp:docstring>
+ Set the stream to start or stop sending media from the local
+ user to other contacts.
+ </tp:docstring>
+
+ <arg name="Send" type="b" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If True, the
+ <tp:member-ref>LocalSendingState</tp:member-ref> should
+ change to <tp:type>Sending_State</tp:type>_Sending, if it isn't
+ already.</p>
+
+ <p>If False, the
+ <tp:member-ref>LocalSendingState</tp:member-ref> should
+ change to <tp:type>Sending_State</tp:type>_None, if it isn't
+ already.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
+ <tp:docstring>
+ <p>Request that a remote contact stops or starts sending on
+ this stream.</p>
+
+ <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref>
+ property defines whether the protocol allows the local user to
+ request the other side start sending on this stream.</p>
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Contact from which sending is requested</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Receive" type="b" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, request that the given contact starts to send media.
+ If false, request that the given contact stops sending media.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The request contact is valid but is not involved in this
+ stream.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The protocol does not allow the local user to request the
+ other side starts sending on this stream.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="RemoteMembersChanged"
+ tp:name-for-bindings="Remote_Members_Changed">
+ <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed>
+ <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
+ <tp:docstring>
+ A mapping from channel-specific handles to their updated sending
+ state, whose keys include at least the members who were added,
+ and the members whose states 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 <tp:member-ref>RemoteMembers</tp:member-ref>
+ property, as a result of the contact leaving this stream
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="LocalSendingStateChanged"
+ tp:name-for-bindings="Local_Sending_State_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="State" type="u" tp:type="Sending_State">
+ <tp:docstring>
+ The new value of
+ <tp:member-ref>LocalSendingState</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Sending_State" type="u">
+ <tp:docstring>
+ Enum indicating whether a contact is sending media.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ The contact is not sending media and has not been asked to
+ do so.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Pending_Send" value="1">
+ <tp:docstring>
+ The contact has been asked to start sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Sending" value="2">
+ <tp:docstring>
+ The contact is sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Pending_Stop_Sending" value="3">
+ <tp:docstring>
+ The contact has been asked to stop sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:mapping name="Contact_Sending_State_Map">
+ <tp:docstring>
+ A map from a contact to his or her sending state.
+ </tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact handle.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Sending" type="u" tp:type="Sending_State">
+ <tp:docstring>
+ The sending state of the contact.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:added version="0.19.11"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this stream, such as <tp:dbus-ref
+ namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>.
+ This SHOULD NOT include the Stream interface itself, and cannot
+ change once the stream has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteMembers" tp:name-for-bindings="Remote_Members"
+ type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
+ <tp:changed version="0.21.2">renamed from Senders</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from remote contacts to their sending state. The
+ local user's sending state is shown in
+ <tp:member-ref>LocalSendingState</tp:member-ref>.</p>
+
+ <p><tp:type>Sending_State</tp:type>_Pending_Send indicates
+ that another contact has asked the local user to send
+ media.</p>
+
+ <p>Other contacts' handles in this map indicate whether they are
+ sending media to the contacts in this stream.
+ Sending_State_Pending_Send indicates contacts who are not sending but
+ have been asked to do so.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State"
+ type="u" access="read" tp:type="Sending_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local user's sending state. Media sent on this stream
+ should be assumed to be received, directly or indirectly, by
+ every other contact in the
+ <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change
+ notification is given via the
+ <tp:member-ref>LocalSendingStateChanged</tp:member-ref>
+ signal.</p>
+
+ <tp:rationale>
+ Implementations of the first Call draft had the self handle
+ in the <tp:member-ref>RemoteMembers</tp:member-ref> (then
+ called Members) map and this showed that it's annoying
+ having to keep track of the self handle so that it can be
+ special-cased.
+ </tp:rationale>
+
+ <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for
+ this property indicates that the other side requested the
+ local user start sending media, which can be done by calling
+ <tp:member-ref>SetSending</tp:member-ref>. When a call is
+ accepted, all initial contents with streams that have a
+ local sending state of
+ <tp:type>Sending_State</tp:type>_Pending_Send are
+ automatically set to sending. For example, on an incoming
+ call it means you need to <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ to start the actual call, on an outgoing call it might mean
+ you need to call <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ before actually starting the call.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving"
+ type="b" access="read" tp:immutable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, the user can request that a remote contact starts
+ sending on this stream.</p>
+
+ <tp:rationale>Not all protocols allow the user to ask the
+ other side to start sending media.</tp:rationale>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml
new file mode 100644
index 0000000..4818168
--- /dev/null
+++ b/spec/Call_Stream_Endpoint.xml
@@ -0,0 +1,182 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Endpoint"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Stream.Endpoint.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This object represents an endpoint for a stream. In a one-to-one
+ call, there will be one (bidirectional) stream per content and
+ one endpoint per stream (as there is only one remote
+ contact). In a multi-user call there is a stream for each remote
+ contact and each stream has one endpoint as it refers to the one
+ physical machine on the other end of the stream.</p>
+
+ <p>The multiple endpoint use case appears when SIP call forking
+ is used. Unlike jingle call forking (which is just making
+ multiple jingle calls to different resources appear as one
+ call), SIP call forking is actually done at the server so you
+ have one stream to the remote contact and then and endpoint for
+ each SIP client to be called.</p>
+ </tp:docstring>
+
+ <property name="RemoteCredentials"
+ tp:name-for-bindings="Remote_Credentials"
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ The ICE credentials used for all candidates. If each candidate
+ has different credentials, then this property SHOULD be ("",
+ ""). Per-candidate credentials are set in the
+ <tp:type>Candidate</tp:type>'s
+ <tp:type>Candidate_Info</tp:type> a{sv}.
+ </tp:docstring>
+ </property>
+
+ <signal name="RemoteCredentialsSet"
+ tp:name-for-bindings="Remote_Credentials_Set">
+ <arg name="Username" type="s">
+ <tp:docstring>
+ The username set.
+ </tp:docstring>
+ </arg>
+ <arg name="Password" type="s">
+ <tp:docstring>
+ The password set.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the remote ICE credentials for the endpoint are
+ set. If each candidate has different credentials, then this
+ signal will never be fired.
+ </tp:docstring>
+ </signal>
+
+ <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ A list of candidates for this endpoint.
+ </tp:docstring>
+ </property>
+
+ <signal name="RemoteCandidatesAdded"
+ tp:name-for-bindings="Remote_Candidates_Added">
+ <tp:docstring>
+ Emitted when remote candidates are added to the
+ <tp:member-ref>RemoteCandidates</tp:member-ref> property.
+ </tp:docstring>
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ The candidates that were added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="CandidateSelected"
+ tp:name-for-bindings="Candidate_Selected">
+ <tp:docstring>
+ Emitted when a candidate is selected for use in the stream.
+ </tp:docstring>
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate">
+ <tp:docstring>
+ The candidate that has been selected.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SelectedCandidate"
+ tp:name-for-bindings="Selected_Candidate"
+ type="(usqa{sv})" tp:type="Candidate" access="read">
+ <tp:docstring>
+ The candidate that has been selected for use to stream packets
+ to the remote contact. Change notification is given via the
+ the <tp:member-ref>CandidateSelected</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <method name="SetSelectedCandidate"
+ tp:name-for-bindings="Set_Selected_Candidate">
+ <tp:docstring>
+ Set the value of
+ <tp:member-ref>CandidateSelected</tp:member-ref>.
+ </tp:docstring>
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate" direction="in">
+ <tp:docstring>
+ The candidate that has been selected.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="StreamState" tp:name-for-bindings="Stream_State"
+ type="u" tp:type="Media_Stream_State"
+ access="read">
+ <tp:docstring>
+ The stream state of the endpoint.
+ </tp:docstring>
+ </property>
+
+ <signal name="StreamStateChanged"
+ tp:name-for-bindings="Stream_State_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>StreamState</tp:member-ref>
+ property changes.
+ </tp:docstring>
+ <arg name="state" type="u" tp:type="Media_Stream_State">
+ <tp:docstring>
+ The new <tp:member-ref>StreamState</tp:member-ref> value.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetStreamState"
+ tp:name-for-bindings="Set_Stream_State">
+ <tp:docstring>
+ Change the <tp:member-ref>StreamState</tp:member-ref> of the
+ endpoint.
+ </tp:docstring>
+ <arg direction="in" name="State" type="u" tp:type="Media_Stream_State">
+ <tp:docstring>
+ The requested stream state.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read">
+ <tp:docstring>
+ The transport type for the stream endpoint.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml
new file mode 100644
index 0000000..9e62c87
--- /dev/null
+++ b/spec/Call_Stream_Interface_Media.xml
@@ -0,0 +1,447 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Call.Stream.Interface.Media.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ [FIXME]
+
+ <h4>ICE restarts</h4>
+
+ <p>If the <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref>
+ signal is fired during a call once it has been called before
+ whilst setting up the call for initial use, and the
+ credentials have changed, then there has been an ICE
+ restart. In such a case, the CM SHOULD also empty the remote
+ candidate list in the <tp:dbus-ref
+ namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p>
+
+ <p>If the CM does an ICE restart, then the
+ <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is
+ emitted and the streaming implementation should then call
+ <tp:member-ref>SetCredentials</tp:member-ref> again.</p>
+
+ <p>For more information on ICE restarts see
+ <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245
+ section 9.1.1.1</a></p>
+ </tp:docstring>
+
+ <method name="SetCredentials" tp:name-for-bindings="Set_Credentials">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Used to set the username fragment and password for streams that have
+ global credentials.</p>
+ </tp:docstring>
+ <arg name="Username" type="s" direction="in">
+ <tp:docstring>
+ The username to use when authenticating on the stream.
+ </tp:docstring>
+ </arg>
+ <arg name="Password" type="s" direction="in">
+ <tp:docstring>
+ The password to use when authenticating on the stream.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <tp:mapping name="Candidate_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra information about the candidate. Allowed and mandatory keys
+ depend on the transport protocol used. The following keys are commenly
+ used:</p>
+
+ <dl>
+ <dt>Type (u)</dt>
+ <dd>type of candidate (host, srflx, prflx, relay)</dd>
+
+ <dt>Foundation (s)</dt>
+ <dd>the foundation of this candiate</dd>
+
+ <dt>Protocol (u) </dt>
+ <dd>Underlying protocol of the candidate (udp, tcp) </dd>
+
+ <dt>Priority (u) </dt>
+ <dd>Priority of the candidate </dd>
+
+ <dt>BaseIP (u) </dt>
+ <dd>Base IP of this candidate </dd>
+
+ <dt>Username (s) </dt>
+ <dd>Username of this candidate
+ (only if credentials are per candidate)</dd>
+
+ <dt>Password (s) </dt>
+ <dd>Password of this candidate
+ (only if credentials are per candidate)</dd>
+
+ <dt>RawUDPFallback (b) </dt>
+ <dd>Indicate whether this candidate may be used to provide a UDP
+ fallback</dd>
+ </dl>
+ </tp:docstring>
+ <tp:member name="Key" type="s">
+ <tp:docstring>One of the well-known keys documented here, or an
+ implementation-specific key.</tp:docstring>
+ </tp:member>
+ <tp:member name="Value" type="v">
+ <tp:docstring>The value corresponding to that key.</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Candidate" array-name="Candidate_List">
+ <tp:docstring>A Stream Candidate.</tp:docstring>
+ <tp:member name="Component" type="u">
+ <tp:docstring>The component number.</tp:docstring>
+ </tp:member>
+ <tp:member name="IP" type="s">
+ <tp:docstring>The IP address to use.</tp:docstring>
+ </tp:member>
+ <tp:member name="Port" type="q">
+ <tp:docstring>The port number to use.</tp:docstring>
+ </tp:member>
+ <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:docstring>Additional information about the candidate.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <tp:docstring>
+ Add candidates to the
+ <tp:member-ref>LocalCandidates</tp:member-ref> property and
+ signal them to the remote contact(s).
+ </tp:docstring>
+ <arg name="Candidates" direction="in"
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ The candidates to be added.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="CandidatesPrepared"
+ tp:name-for-bindings="Candidates_Prepared">
+ <tp:docstring>
+ This indicates to the CM that the initial batch of candidates
+ has been added.
+ </tp:docstring>
+ </method>
+
+ <tp:enum type="u" name="Stream_Transport_Type">
+ <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A transport that can be used for streaming.
+ </tp:docstring>
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ The stream transport type is unknown or not applicable
+ (for streams that do not have a configurable transport).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Raw_UDP" value="1">
+ <tp:docstring>
+ Raw UDP, with or without STUN. All streaming clients are assumed to
+ support this transport, so there is no handler capability token for
+ it in the <tp:dbus-ref namespace="ofdT.Channel.Type"
+ >Call.DRAFT</tp:dbus-ref> interface.
+ [This corresponds to "none" or "stun" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="ICE" value="2">
+ <tp:docstring>
+ Interactive Connectivity Establishment, as defined by RFC
+ 5245. Note that this value covers ICE-UDP only.
+ [This corresponds to "ice-udp" in the old
+ Media.StreamHandler interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="GTalk_P2P" value="3">
+ <tp:docstring>
+ Google Talk peer-to-peer connectivity establishment, as implemented
+ by libjingle 0.3.
+ [This corresponds to "gtalk-p2p" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="WLM_2009" value="4">
+ <tp:docstring>
+ The transport used by Windows Live Messenger 2009 or later, which
+ resembles ICE draft 19.
+ [This corresponds to "wlm-2009" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="SHM" value="5">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ Shared memory transport, as implemented by the GStreamer
+ shmsrc and shmsink plugins.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Multicast" value="6">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ Multicast transport.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes">
+ <tp:docstring>
+ The transport for this stream.
+ </tp:docstring>
+ </property>
+
+ <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via the
+ <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <signal name="LocalCandidatesAdded"
+ tp:name-for-bindings="Local_Candidates_Added">
+ <tp:docstring>
+ Emitted when local candidates are added to the
+ <tp:member-ref>LocalCandidates</tp:member-ref> property.
+ </tp:docstring>
+ <arg name="Candidates" type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates that have been added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:struct name="Stream_Credentials">
+ <tp:docstring>A username and password pair.</tp:docstring>
+
+ <tp:member name="Username" type="s">
+ <tp:docstring>The username.</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Password" type="s">
+ <tp:docstring>The password.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via the
+ <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <signal name="LocalCredentialsChanged"
+ tp:name-for-bindings="Local_Credentials_Changed">
+ <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed>
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>LocalCredentials</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Username" type="s" />
+ <arg name="Password" type="s" />
+ </signal>
+
+ <signal name="RelayInfoChanged"
+ tp:name-for-bindings="Relay_Info_Changed">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>RelayInfo</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" />
+ </signal>
+
+ <signal name="STUNServersChanged"
+ tp:name-for-bindings="STUN_Servers_Changed">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>STUNServers</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Servers" type="a(sq)" tp:type="Socket_Address_IP[]" />
+ </signal>
+
+ <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The IP addresses of possible STUN servers to use for NAT
+ traversal, as dotted-quad IPv4 address literals or RFC2373
+ IPv6 address literals. Change notification is via the
+ <tp:member-ref>STUNServersChanged</tp:member-ref>
+ signal. The IP addresses MUST NOT be given as DNS hostnames.</p>
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ to make life easier for streaming implementations.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="RelayInfo" type="aa{sv}" access="read"
+ tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings describing TURN or Google relay servers
+ available for the client to use in its candidate gathering, as
+ determined from the protocol. Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code> - s</dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal. This MUST NOT
+ be a DNS hostname.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ and make life easier for streaming implementations.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>type</code> - s</dt>
+ <dd>
+ <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code>.</p>
+
+ <p>The precise meaning of this key depends on the
+ <tp:member-ref>Transport</tp:member-ref> property: if
+ Transport is ICE, <code>tls</code> means
+ TLS over TCP as referenced by ICE draft 19, and if
+ Transport is GTalk_P2P, <code>tls</code> means
+ a fake SSL session over TCP as implemented by libjingle.</p>
+ </dd>
+
+ <dt><code>port</code> - q</dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code> - s</dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code> - s</dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code> - u</dt>
+ <dd>The component number to use this relay server for, as an
+ ASCII unsigned integer; if not included, this relay server
+ may be used for any or all components.
+
+ <tp:rationale>
+ In ICE draft 6, as used by Google Talk, credentials are only
+ valid once, so each component needs relaying separately.
+ </tp:rationale>
+ </dd>
+ </dl>
+
+ <tp:rationale>
+ <p>An equivalent of the gtalk-p2p-relay-token property on
+ MediaSignalling channels is not included here. The connection
+ manager should be responsible for making the necessary HTTP
+ requests to turn the token into a username and password.</p>
+ </tp:rationale>
+
+ <p>The type of relay server that this represents depends on
+ the value of the <tp:member-ref>Transport</tp:member-ref>
+ property. If Transport is ICE, this is a TURN server;
+ if Transport is GTalk_P2P, this is a Google relay server;
+ otherwise, the meaning of RelayInfo is undefined.</p>
+
+ <p>If relaying is not possible for this stream, the list is
+ empty.</p>
+
+ <p>Change notification is given via the
+ <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ServerInfoRetrieved"
+ tp:name-for-bindings="Server_Info_Retrieved">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that the initial information about STUN and Relay servers
+ has been retrieved, i.e. the
+ <tp:member-ref>HasServerInfo</tp:member-ref> property is
+ now true.</p>
+ </tp:docstring>
+ </signal>
+
+ <property name="HasServerInfo" type="b"
+ tp:name-for-bindings="Has_Server_Info" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if all the initial information about STUN servers and Relay
+ servers has been retrieved. Change notification is via the
+ <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ Streaming implementations that can't cope with STUN and
+ relay servers being added later SHOULD wait for this
+ property to become true before proceeding.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="EndpointsChanged"
+ tp:name-for-bindings="Endpoints_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property
+ changes.
+ </tp:docstring>
+ <arg name="Endpoints_Added" type="ao">
+ <tp:docstring>
+ Endpoints that were added.
+ </tp:docstring>
+ </arg>
+ <arg name="Endpoints_Removed" type="ao">
+ <tp:docstring>
+ Endpoints that no longer exist.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Endpoints" tp:name-for-bindings="Endpoints"
+ type="ao" access="read">
+ <tp:docstring>
+ <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream"
+ >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this
+ stream.</p>
+
+ <p>Change notification is via the
+ <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="PleaseRestartICE"
+ tp:name-for-bindings="Please_Restart_ICE">
+ <tp:docstring>
+ Emitted when the CM does an ICE restart to notify the
+ streaming implementation that it should call
+ <tp:member-ref>SetCredentials</tp:member-ref> again.
+ </tp:docstring>
+ </signal>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel.xml b/spec/Channel.xml
new file mode 100644
index 0000000..11d3e50
--- /dev/null
+++ b/spec/Channel.xml
@@ -0,0 +1,557 @@
+<?xml version="1.0" ?>
+<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 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.Channel">
+
+ <property name="ChannelType" type="s" tp:type="DBus_Interface"
+ access="read" tp:name-for-bindings="Channel_Type">
+ <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
+ <tp:member-ref>GetChannelType</tp:member-ref>.</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" tp:name-for-bindings="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
+ <tp:member-ref>ChannelType</tp:member-ref> is an empty string,
+ clients MUST use the result of calling
+ <tp:member-ref>GetInterfaces</tp:member-ref> 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:name-for-bindings="Target_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 <tp:member-ref>TargetHandleType</tp:member-ref>
+ property.</p>
+
+ <p>This is fixed for the lifetime of the channel, so channels which
+ could potentially be used to communicate with multiple contacts,
+ and do not have an identity of their own (such as a Handle_Type_Room
+ handle), 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. Properties from
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-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" tp:name-for-bindings="Target_ID"
+ 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [T])</li>
+ <li>Channel C closes, removing the last reference to handle T</li>
+ <li><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(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. Properties from
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-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:name-for-bindings="Target_Handle_Type">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</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:name-for-bindings="Close">
+ <tp:docstring>
+ Request that the channel be closed. This is not the case until
+ the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and
+ depending on the connection
+ manager this may simply remove you from the channel on the server,
+ rather than causing it to stop existing entirely. Some channels
+ such as contact list channels may not be closed.
+ </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.NotImplemented">
+ <tp:docstring>
+ This channel may never be closed, e.g. a contact list
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This channel is not currently in a state where it can be closed,
+ e.g. a non-empty user-defined contact group
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Closed" tp:name-for-bindings="Closed">
+ <tp:docstring>
+ Emitted when the channel has been closed. Method calls on the
+ channel are no longer valid after this signal has been emitted,
+ and the connection manager may then remove the object from the bus
+ at any point.
+ </tp:docstring>
+ </signal>
+
+ <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type">
+ <tp:deprecated version="0.17.7">Use the ChannelType
+ property if possible.</tp:deprecated>
+ <arg direction="out" type="s" tp:type="DBus_Interface"
+ name="Channel_Type">
+ <tp:docstring>The interface name</tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the interface name for the type of this channel. Clients
+ SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> 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:name-for-bindings="Get_Handle">
+ <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"
+ name="Target_Handle_Type">
+ <tp:docstring>
+ The same as TargetHandleType.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="u" tp:type="Handle" name="Target_Handle">
+ <tp:docstring>
+ 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. Clients
+ SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetHandleType</tp:member-ref> 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:name-for-bindings="Get_Interfaces">
+ <tp:deprecated version="0.17.7">Use the Interfaces
+ property if possible.</tp:deprecated>
+ <arg direction="out" type="as" tp:type="DBus_Interface[]"
+ name="Interfaces">
+ <tp:docstring>
+ An array of the D-Bus interface names
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get the optional interfaces implemented by the channel.
+ Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref>
+ 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>
+
+ <property name="Requested" tp:name-for-bindings="Requested"
+ type="b" access="read">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel was created in response to a local request,
+ such as 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.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>
+
+ <p>It does not make sense for this property to be in channel
+ requests—it will always be true for channels returned by
+ CreateChannel, and callers of EnsureChannel cannot control whether an
+ existing channel was originally requested locally—so it MUST NOT
+ be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
+ access="read" tp:name-for-bindings="Initiator_Handle">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact who initiated the channel; for instance, the contact
+ who invited the local user to a chatroom, or the contact who
+ initiated a call.</p>
+
+ <p>This does <em>not</em> necessarily represent the contact who
+ created the underlying protocol-level construct. For instance, if
+ Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
+ to join it, then Simon will see Will as the InitiatorHandle of the
+ channel representing the chatroom.</p>
+
+ <tp:rationale>
+ <p>The room creator is generally a less useful piece of information
+ than the inviter, is less likely to be available at invitation
+ time (i.e. can't necessarily be an immutable property), and is
+ less likely to be available at all. The creator of a chatroom
+ is not currently available via Telepathy; if added in future, it
+ is likely to be made available as a property on the Chatroom
+ interface (<a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
+ </tp:rationale>
+
+ <p>For channels requested by the
+ local user, this MUST be the value of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
+ at the time the channel was created (i.e. not a channel-specific
+ handle).</p>
+
+ <tp:rationale>
+ <p>On some protocols, the SelfHandle may change (as signalled by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>),
+ but this property is immutable. Hence, locally-requested channels'
+ InitiatorHandle and InitiatorID may not match the current
+ SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
+ determine whether the channel was created locally.</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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
+ 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:name-for-bindings="Initiator_ID">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the
+ <tp:member-ref>InitiatorHandle</tp:member-ref>
+ 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [I])</li>
+ <li>Channel C closes, removing the last reference to handle I</li>
+ <li><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(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>
+
+ <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
+ be implemented by all channel objects, along with one single channel type,
+ such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref>
+ which represents a list of people (such as a buddy list) or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which
+ represents a channel over which textual messages are sent and received.</p>
+
+ <p>Each Channel's object path MUST start with the object path of
+ its associated <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed
+ by '/'. There MAY be any number of additional object-path components,
+ which clients MUST NOT attempt to parse.</p>
+
+ <tp:rationale>
+ <p>This ensures that Channel object paths are unique, even between
+ Connections and CMs, because Connection object paths are
+ guaranteed-unique via their link to the well-known bus name.</p>
+
+ <p>If all connection managers in use are known to comply with at least
+ spec version 0.17.10, then the Connection's object path can
+ even be determined from the Channel's without any additional
+ information, by taking the first 7 components.</p>
+ </tp:rationale>
+
+ <p>Each channel has a number of immutable properties (which cannot vary
+ after the channel has been announced with <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>),
+ provided to clients in the
+ <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
+ <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref>
+ methods to permit immediate identification of the channel. This interface
+ contains immutable properties common to all channels. In brief:</p>
+
+ <ul>
+ <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of
+ communication carried out on this channel;</li>
+ <li><tp:member-ref>TargetHandleType</tp:member-ref>,
+ <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetID</tp:member-ref> specify the entity with which
+ this channel communicates, such as the other party in a 1-1 call, or
+ the name of a multi-user chat room;</li>
+ <li><tp:member-ref>InitiatorHandle</tp:member-ref> and
+ <tp:member-ref>InitiatorID</tp:member-ref> specify who created this
+ channel;</li>
+ <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local
+ user requested this channel, or whether it is an incoming call, a text
+ conversation started by a remote contact, a chatroom invitation,
+ etc.</li>
+ </ul>
+
+ <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be
+ implemented to indicate other available
+ functionality, such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
+ if the channel contains a number of contacts, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
+ to indicate that a channel may have a password set to require entry, and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref>
+ for typing notifications. The interfaces implemented may not vary after
+ the channel has been created. These other interfaces (along with the
+ interface named by <tp:member-ref>ChannelType</tp:member-ref>) may
+ themselves specify immutable properties to be announced up-front along
+ with the properties on this interface.</p>
+
+ <p>Some channels are “anonymous”, with
+ <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>,
+ which indicates that the channel is defined by some other properties. For
+ instance, transient ad-hoc chat rooms may be defined only by their members (as visible
+ through the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
+ interface), and <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref>
+ channels represent a single search attempt for a particular <tp:dbus-ref
+ namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p>
+
+ <p>Specific connection manager implementations may implement channel types and
+ interfaces which are not contained within this specification in order to
+ support further functionality. To aid interoperability between client and
+ connection manager implementations, the interfaces specified here should be
+ used wherever applicable, and new interfaces made protocol-independent
+ wherever possible. Because of the potential for 3rd party interfaces adding
+ 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>
+
+ <tp:changed version="0.17.10">Previously we did not explicitly
+ guarantee that Channels' object paths had the Connection's object path
+ as a prefix.
+ </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..d211525
--- /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" tp:name-for-bindings="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_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
new file mode 100644
index 0000000..6ec69a6
--- /dev/null
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -0,0 +1,483 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatch_Operation"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.ChannelDispatchOperation">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel dispatch operation is an object in the ChannelDispatcher
+ representing a batch of unrequested channels being announced to
+ client
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>
+ processes.</p>
+
+ <p>These objects can result from new incoming channels or channels
+ which are automatically created for some reason, but cannot result
+ from outgoing requests for channels.</p>
+
+ <p>More specifically, whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ signal contains channels whose
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
+ property is false, or whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal contains a channel with suppress_handler false,
+ one or more ChannelDispatchOperation objects are created for those
+ channels.</p>
+
+ <p>(If some channels in a NewChannels signal are in different bundles,
+ this is an error. The channel dispatcher SHOULD recover by treating
+ the NewChannels signal as if it had been several NewChannels signals
+ each containing one channel.)</p>
+
+ <p>First, the channel dispatcher SHOULD construct a list of all the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s
+ that could handle all the channels (based on their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ property), ordered by
+ priority in some implementation-dependent way. If there are handlers
+ which could handle all the channels, one channel dispatch operation
+ SHOULD be created for all the channels. If there are not, one channel
+ dispatch operation SHOULD be created for each channel, each with
+ a list of channel handlers that could handle that channel.</p>
+
+ <p>If no handler at all can handle a channel, the channel dispatcher
+ SHOULD terminate that channel instead of creating a channel dispatcher
+ for it. It is RECOMMENDED that the channel dispatcher closes
+ the channels using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
+ if supported, or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ otherwise. As a special case, the channel dispatcher SHOULD NOT close
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>
+ channels, and if Close fails, the channel dispatcher SHOULD ignore
+ that channel.</p>
+
+ <tp:rationale>
+ <p>ContactList channels are strange. We hope to replace them with
+ something better, such as an interface on the Connection, in a
+ future version of this specification.</p>
+ </tp:rationale>
+
+ <p>When listing channel handlers, priority SHOULD be given to
+ channel handlers that are already handling channels from the same
+ bundle.</p>
+
+ <p>If a handler with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">BypassApproval</tp:dbus-ref>
+ <code>= True</code> could handle all of the channels in the dispatch
+ operation, then the channel dispatcher SHOULD call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ on that handler, and (assuming the call succeeds) emit
+ <tp:member-ref>Finished</tp:member-ref> and stop processing those
+ channels without involving any approvers.</p>
+
+ <tp:rationale>
+ <p>Some channel types can be picked up "quietly" by an existing
+ channel handler. If a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ channel is added to an existing bundle containing a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channel, there shouldn't be
+ any approvers, flashing icons or notification bubbles, if the
+ the UI for the StreamedMedia channel can just add a text box
+ and display the message.</p>
+ </tp:rationale>
+
+ <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch
+ operation to all relevant approvers (in parallel) and wait for an
+ approver to claim the channels or request that they are handled.
+ See
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ for more details on this.</p>
+
+ <p>Finally, if the approver requested it, the channel dispatcher SHOULD
+ send the channels to a handler.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatch
+ operation. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Connection" tp:name-for-bindings="Connection"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ with which the <tp:member-ref>Channels</tp:member-ref> are
+ associated. The well-known bus name to use can be derived from
+ this object path by removing the leading '/' and replacing all
+ subsequent '/' by '.'. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Account" tp:name-for-bindings="Account"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the <tp:member-ref>Connection</tp:member-ref>
+ and <tp:member-ref>Channels</tp:member-ref> are
+ associated. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ to be dispatched, and their properties. Change notification is via
+ the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
+ cannot be added to this property, only removed).
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel has closed before it could be claimed or handled. If
+ this is emitted for the last remaining channel in a channel
+ dispatch operation, it MUST immediately be followed by
+ <tp:member-ref>Finished</tp:member-ref>.</p>
+
+ <p>This signal MUST NOT be emitted until all Approvers that were
+ invoked have returned (successfully or with an error) from
+ their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ method.</p>
+
+ <tp:rationale>
+ <p>This means that Approvers can connect to the ChannelLost signal
+ in a race-free way. Non-approver processes that discover
+ a channel dispatch operation in some way (such as observers)
+ will have to follow the usual "connect to signals then recover
+ state" model - first connect to ChannelLost and
+ <tp:member-ref>Finished</tp:member-ref>,
+ then download <tp:member-ref>Channels</tp:member-ref> (and
+ on error, perhaps assume that the operation has already
+ Finished).</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>
+ that closed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error indicating why the channel closed. If
+ no better reason can be found,
+ <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
+ be used as a fallback; this means that this error SHOULD NOT be
+ given any more specific meaning.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string associated with the D-Bus error.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
+ type="as" access="read" tp:type="DBus_Well_Known_Name[]">
+ <tp:docstring>
+ <p>The well known bus names (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the possible
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s
+ for these channels. The channel dispatcher MUST place the most
+ preferred handlers first, according to some reasonable heuristic.
+ As a result, approvers SHOULD use the first handler by default.</p>
+
+ <p>The heuristic used to prioritize handlers SHOULD give a higher
+ priority to handlers that are already running.</p>
+
+ <tp:rationale>
+ <p>If, for instance, Empathy and Kopete have similar functionality,
+ and Empathy is running, we should prefer to send channels to it
+ rather than launching Kopete via service activation.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="HandleWith" tp:name-for-bindings="Handle_With">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to accept a channel bundle and request that
+ the given handler be used to handle it.</p>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>.</p>
+
+ <p>However, this method may fail because the dispatch has already been
+ completed and the object has already gone. If this occurs, it
+ indicates that another approver has asked for the bundle to be
+ handled by a particular handler. The approver MUST NOT attempt
+ to interact with the channels further in this case, unless it is
+ separately invoked as the handler.</p>
+
+ <p>Approvers which are also channel handlers SHOULD use
+ <tp:member-ref>Claim</tp:member-ref> instead
+ of HandleWith to request that they can handle a channel bundle
+ themselves.</p>
+
+ <p>(FIXME: list some possible errors)</p>
+
+ <p>If the channel handler raises an error from <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>,
+ this method
+ MAY respond by raising that same error, even if it is not
+ specifically documented here.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel, or the empty string
+ if the client has no preferred channel handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is non-empty, but is not a syntactically
+ correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Claim" tp:name-for-bindings="Claim">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to claim channels for handling
+ internally. If this method is called successfully, the process
+ calling this method becomes the handler for the channel, but
+ <em>does not</em> have the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ method called on it.</p>
+
+ <p>Clients that call Claim on channels but do not immediately
+ close them SHOULD implement the Handler interface and its
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandledChannels</tp:dbus-ref>
+ property.</p>
+
+ <p>Approvers wishing to reject channels MUST call this method to
+ claim ownership of them, and MUST NOT call
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ on the channels unless/until this method returns successfully.</p>
+
+ <tp:rationale>
+ <p>The channel dispatcher can't know how best to close arbitrary
+ channel types, so it leaves it up to the approver to do so.
+ For instance, for Text channels it is necessary
+ to acknowledge any messages that have already been displayed to
+ the user first - ideally, the approver would display and then
+ acknowledge the messages - or to call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
+ if the destructive behaviour of that method is desired.</p>
+
+ <p>Similarly, an Approver for StreamedMedia channels can close the
+ channel with a reason (e.g. "busy") if desired. The channel
+ dispatcher, which is designed to have no specific knowledge
+ of particular channel types, can't do that.</p>
+ </tp:rationale>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>, in the same way as for
+ <tp:member-ref>HandleWith</tp:member-ref>.</p>
+
+ <p>This method may fail because the dispatch operation has already
+ been completed. Again, see HandleWith for more details. The approver
+ MUST NOT attempt to interact with the channels further in this
+ case.</p>
+
+ <p>(FIXME: list some other possible errors)</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that Claim was called, this dispatch operation was
+ processing a call to HandleWith which has now succeeded, so
+ some Handler nominated by another approver is now responsible for
+ the channel.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time">
+ <tp:added version="0.19.6">
+ At the time of writing, no released implementation of the
+ Channel Dispatcher implements this method; clients should fall
+ back to calling <tp:member-ref>HandleWith</tp:member-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the
+ approver to pass an user action time. This timestamp will be passed
+ to the Handler when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ is called.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel, or the empty string
+ if the client has no preferred channel handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is non-empty, but is not a syntactically
+ correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Finished" tp:name-for-bindings="Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when this dispatch operation finishes. The dispatch
+ operation is no longer present and further methods must not be
+ called on it.</p>
+
+ <p>Approvers that have a user interface SHOULD stop notifying the user
+ about the channels in response to this signal; they MAY assume that
+ on errors, they would have received
+ <tp:member-ref>ChannelLost</tp:member-ref> first.</p>
+
+ <p>Its object path SHOULD NOT be reused for a subsequent dispatch
+ operation; the ChannelDispatcher MUST choose object paths
+ in a way that avoids immediate re-use.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients might accidentally call
+ <tp:member-ref>HandleWith</tp:member-ref> or
+ <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation
+ instead of the one they intended to handle.</p>
+ </tp:rationale>
+
+ <p>This signal MUST NOT be emitted until all Approvers that were
+ invoked have returned (successfully or with an error) from
+ their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ method.</p>
+
+ <tp:rationale>
+ <p>This means that Approvers can connect to the ChannelLost signal
+ in a race-free way. Non-approver processes that discover
+ a channel dispatch operation in some way (such as observers)
+ will have to follow the usual "connect to signals then recover
+ state" model - first connect to
+ <tp:member-ref>ChannelLost</tp:member-ref> and
+ Finished, then download <tp:member-ref>Channels</tp:member-ref>
+ (and on error, perhaps assume that the operation has already
+ Finished).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
new file mode 100644
index 0000000..2dd000b
--- /dev/null
+++ b/spec/Channel_Dispatcher.xml
@@ -0,0 +1,595 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.ChannelDispatcher">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel dispatcher is responsible for responding to new
+ channels and launching client processes to handle them. It also
+ provides functionality for client processes to request that new
+ channels are created.</p>
+
+ <p>If a channel dispatcher is running, it is responsible for dispatching
+ new channels on all
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s
+ created by the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ Connections not created by the AccountManager are outside the scope
+ of the channel dispatcher.</p>
+
+ <tp:rationale>
+ <p>Connections created by standalone Telepathy clients
+ that do not intend to interact with the channel dispatcher
+ should be ignored - otherwise, the channel dispatcher would try
+ to launch handlers for channels that the standalone client
+ was already handling internally.</p>
+ </tp:rationale>
+
+ <p>The current channel dispatcher is defined to be the process that
+ owns the well-known bus name
+ <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on
+ the session bus. This process MUST export an object with this
+ interface at the object path
+ <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p>
+
+ <p>Until a mechanism exists for making a reasonable automatic choice
+ of ChannelDispatcher implementation, implementations SHOULD NOT
+ register as an activatable service for the ChannelDispatcher's
+ well-known bus name. Instead, it is RECOMMENDED that some component
+ of the user's session will select and activate a particular
+ implementation, and that other Telepathy-enabled programs
+ can detect whether channel request/dispatch functionality is available
+ by checking whether the ChannelDispatcher's well-known name is in use
+ at runtime.</p>
+
+ <p>There are three categories of client process defined by this
+ specification:</p>
+
+ <dl>
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt>
+ <dd><p>Observers monitor the creation of new channels. This
+ functionality can be used for things like message logging.
+ All observers are notified simultaneously.</p></dd>
+
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>
+ <dd>
+ <p>Approvers notify the user that new channels have been created,
+ and also select which channel handler will be used for the channel,
+ either by asking the user or by choosing the most appropriate
+ channel handler.</p>
+ </dd>
+
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt>
+ <dd>
+ <p>Each new channel or set of channels is passed to exactly one
+ handler as its final destination. A typical channel handler is a
+ user interface process handling channels of a particular type.</p>
+ </dd>
+ </dl>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatcher.
+ </tp:docstring>
+ </property>
+
+ <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Equivalent to calling
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty
+ <var>Hints</var> parameter.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ <tp:changed version="0.19.0">
+ Previously, the spec didn't say that this should disregard the
+ handler's filter. This has been implemented since
+ telepathy-mission-control 5.3.2.
+ </tp:changed>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Equivalent to calling
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty
+ <var>Hints</var> parameter.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The behaviour and rationale are the same as for the
+ corresponding parameter to
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="CreateChannelWithHints"
+ tp:name-for-bindings="Create_Channel_With_Hints">
+ <tp:added version="0.21.5">
+ Support for this method is indicated by the
+ <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
+ Clients MUST recover from this method being unsupported by falling back
+ to <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start a request to create a channel. This initially just creates a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object, which can be used to continue the request and track its
+ success or failure.</p>
+
+ <tp:rationale>
+ <p>The request can take a long time - in the worst case, the
+ channel dispatcher has to ask the account manager to put the
+ account online, the account manager has to ask the operating
+ system to obtain an Internet connection, and the operating
+ system has to ask the user whether to activate an Internet
+ connection using an on-demand mechanism like dialup.</p>
+
+ <p>This means that using a single D-Bus method call and response
+ to represent the whole request will tend to lead to that call
+ timing out, which is not the behaviour we want.</p>
+ </tp:rationale>
+
+ <p>If this method is called for an Account that is disabled, invalid
+ or otherwise unusable, no error is signalled until
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
+ is called, at which point
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
+ is emitted with an appropriate error.</p>
+
+ <tp:rationale>
+ <p>This means there's only one code path for errors, apart from
+ InvalidArgument for "that request makes no sense".</p>
+
+ <p>It also means that the request will proceed if the account is
+ enabled after calling CreateChannel, but before calling
+ Proceed.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
+ property will be set to this value, and it will eventually be
+ passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler—irrespective of whether that handler's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ matches the channel—and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler.</p>
+
+ <tp:rationale>
+ <p>This must be the well-known bus name, not the unique name,
+ to ensure that all handlers do indeed have the Client API,
+ and the Client object on the handler can be located easily.</p>
+
+ <p>This is partly so the channel dispatcher can call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ on it, and partly so the channel dispatcher
+ can recover state if it crashes and is restarted.</p>
+
+ <p>The filter should be disregarded for ease of use of this
+ interface: clients will usually use this argument to request
+ channels be sent to themself, and this should trump the filter
+ not matching. This also allows a client to become the handler
+ for a channel produced by one of its own requests, while not
+ being a candidate to handle other channels of that type.</p>
+ </tp:rationale>
+
+ <p>If this is a well-known bus name and the handler has the
+ Requests interface, the channel dispatcher SHOULD
+ call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
+ on that Handler after this method has returned.</p>
+
+ <tp:rationale>
+ <p>This ordering allows a Handler which calls CreateChannel with
+ itself as the preferred handler to associate the call to
+ AddRequest with that call.</p>
+ </tp:rationale>
+
+ <p>This is copied to the ChannelRequest that is returned,
+ as the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
+ property.</p>
+ </tp:docstring>
+
+ <tp:changed version="0.19.0">
+ Previously, the spec didn't say that this should disregard the
+ handler's filter. This has been implemented since
+ telepathy-mission-control 5.3.2.
+ </tp:changed>
+ </arg>
+
+ <arg direction="in" name="Hints" type="a{sv}">
+ <tp:docstring>
+ <p>Additional information about the channel request, which will be
+ used as the value for the resulting request's <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
+ property.</p>
+
+ <tp:rationale>
+ <p>See the Hints property's documentation for rationale.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="EnsureChannelWithHints"
+ tp:name-for-bindings="Ensure_Channel_With_Hints">
+ <tp:added version="0.21.5">
+ Support for this method is indicated by the
+ <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
+ Clients MUST recover from this method being unsupported by falling back
+ to <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start a request to ensure that a channel exists, creating it if
+ necessary. This initially just creates a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object, which can be used to continue the request and track its
+ success or failure.</p>
+
+ <p>If this method is called for an Account that is disabled, invalid
+ or otherwise unusable, no error is signalled until
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
+ is called, at which point
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
+ is emitted with an appropriate error.</p>
+
+ <tp:rationale>
+ <p>The rationale is as for <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The behaviour and rationale are the same as for the
+ corresponding parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except
+ as noted here.</p>
+
+ <p>If any new channels are created in response to this
+ request, the channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler, and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler. If the requested channel already exists (that
+ is, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
+ returns <code>Yours=False</code>) then the channel dispatcher
+ SHOULD re-dispatch the channel to its existing handler, and MUST
+ NOT dispatch it to this client (unless it is the existing handler);
+ the request is still deemed to have succeeded in this case.</p>
+
+ <tp:rationale>
+ <p>An address book application, for example, might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
+ to ensure that a text channel with a particular contact is
+ displayed to the user; it does not care whether a new channel was
+ made. An IM client might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
+ in response to the user double-clicking an entry in the contact
+ list, with itself as the <code>Preferred_Handler</code>; if the
+ user already has a conversation with that contact in another
+ application, they would expect the existing window to be
+ presented, rather than their double-click leading to an error
+ message. So the request should succeed, even if its
+ <code>Preferred_Handler</code> is not used.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Hints" type="a{sv}">
+ <tp:docstring>
+ Additional information about the channel request, which will be used
+ as the value for the resulting request's <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
+ property.</tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <property name="SupportsRequestHints"
+ tp:name-for-bindings="Supports_Request_Hints"
+ type="b" access="read">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ If <code>True</code>, the channel dispatcher is new enough to support
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref> and
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition
+ to the older <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
+ methods, and also new enough to emit <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref>
+ before the older <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal.
+ If <code>False</code> or missing, only the metadata-less
+ variants are supported.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml
new file mode 100644
index 0000000..be06f5c
--- /dev/null
+++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher_Interface_Operation_List"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.ChannelDispatcher.Interface.OperationList">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface allows users of the ChannelDispatcher to enumerate
+ all the pending dispatch operations, with change notification.</p>
+
+ <tp:rationale>
+ <p>The existence of the
+ <tp:member-ref>DispatchOperations</tp:member-ref> property allows a
+ newly started approver to pick up existing dispatch operations.</p>
+
+ <p>This is on a separate interface so clients that aren't interested
+ in doing this aren't woken up by its signals.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:struct name="Dispatch_Operation_Details"
+ array-name="Dispatch_Operation_Details_List">
+
+ <tp:docstring>
+ Details of a channel dispatch operation.
+ </tp:docstring>
+
+ <tp:member name="Channel_Dispatch_Operation" type="o">
+ <tp:docstring>
+ The object path of the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>.
+ </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 dispatch operation.</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>The rationale is the same as for
+ <tp:type>Channel_Details</tp:type>.</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain at least the following keys:</p>
+ <ul>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Connection</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Account</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers</tp:dbus-ref></li>
+ </ul>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property
+ name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations"
+ type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of ChannelDispatchOperation objects currently being
+ processed. Change notification is via the
+ <tp:member-ref>NewDispatchOperation</tp:member-ref> and
+ <tp:member-ref>DispatchOperationFinished</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="NewDispatchOperation"
+ tp:name-for-bindings="New_Dispatch_Operation">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a dispatch operation is added to
+ <tp:member-ref>DispatchOperations</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was created.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties"
+ type="a{sv}" tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>
+ The same properties that would appear in the Properties member of
+ <tp:type>Dispatch_Operation_Details</tp:type>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="DispatchOperationFinished"
+ tp:name-for-bindings="Dispatch_Operation_Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when a dispatch operation finishes (i.e. exactly once per
+ emission of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>).
+
+ <tp:rationale>
+ Strictly speaking this is redundant with
+ ChannelDispatchOperation.Finished, but it provides full
+ change-notification for the
+ <tp:member-ref>DispatchOperations</tp:member-ref> property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was closed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </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..5bbca17
--- /dev/null
+++ b/spec/Channel_Future.xml
@@ -0,0 +1,68 @@
+<?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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> 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="Bundle" tp:name-for-bindings="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.DRAFT</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
new file mode 100644
index 0000000..edf975e
--- /dev/null
+++ b/spec/Channel_Handler.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <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
+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.ChannelHandler">
+ <tp:deprecated version="0.17.23">
+ Clients should implement <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>
+ instead.
+ </tp:deprecated>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface exported by Mission Control 4 client applications which
+ are able to handle incoming channels.</p>
+ </tp:docstring>
+ <tp:added version="0.17.0"/>
+
+ <method name="HandleChannel" tp:name-for-bindings="Handle_Channel">
+ <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>
+
+ <!-- FIXME: possible errors? -->
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml
new file mode 100644
index 0000000..494fd7b
--- /dev/null
+++ b/spec/Channel_Interface_Addressing.xml
@@ -0,0 +1,107 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 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
+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.Addressing.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.12">(as draft)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface provides properties that can be used for
+ requesting channels through different contact addressing
+ schemes like vCard addresses or URIs.
+ </p>
+ </tp:docstring>
+
+ <property name="TargetVCardField" type="s" access="read"
+ tp:name-for-bindings="Target_VCard_Field">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard field, normalized to lower case,
+ <tp:member-ref>TargetVCardAddress</tp:member-ref> refers to.</p>
+
+ <p>The <code>url</code> vCard field MUST NOT appear here; see
+ <tp:member-ref>TargetURI</tp:member-ref> instead.</p>
+
+ <tp:rationale>
+ <p>In practice, protocols have a limited set of URI
+ schemes that make sense to resolve as a contact.</p>
+ </tp:rationale>
+
+ <p>If this is omitted from a request,
+ <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST be
+ omitted as well.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetURIScheme" type="s" access="read"
+ tp:name-for-bindings="Target_URI_Scheme">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The URI scheme used in <tp:member-ref>TargetURI</tp:member-ref></p>
+
+ <tp:rationale>
+ <p>While this seems redundant, since the scheme is included in
+ <tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ that support a limited set of URI schemes.</p>
+ </tp:rationale>
+
+ <p>If this is omitted from a request,
+ <tp:member-ref>TargetURI</tp:member-ref> MUST be
+ omitted as well.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetVCardAddress" type="s" access="read"
+ tp:name-for-bindings="Target_VCard_Address">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard address of the Channel's target.</p>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetVCardField</tp:member-ref>
+ MUST be present, and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>,
+ and <tp:member-ref>TargetURI</tp:member-ref> MUST NOT be present.
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ must either not be present or set to Handle_Type_Contact.
+ The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested vCard address cannot be found.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetURI" type="s" access="read"
+ tp:name-for-bindings="Target_URI">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The URI of the Channel's target. The URI's scheme (i.e. the
+ part before the first colon) MUST be identical to
+ <tp:member-ref>TargetURIScheme</tp:member-ref>.</p>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetVCardField</tp:member-ref>
+ MUST be present, and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>,
+ and <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST NOT be
+ present.
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ must either not be present or set to Handle_Type_Contact.
+ The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested vCard address cannot be found.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml
new file mode 100644
index 0000000..ef3a3b8
--- /dev/null
+++ b/spec/Channel_Interface_Anonymity.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Anonymity"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity">
+ <tp:added version="0.19.7">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for requesting the anonymity modes of a channel
+ (as defined in <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Anonymity</tp:dbus-ref>).</p>
+ </tp:docstring>
+
+ <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+ access="read" tp:name-for-bindings="Anonymity_Modes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The list of initially requested anonymity modes on the channel. This
+ MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityMandatory" type="b" access="read"
+ tp:name-for-bindings="Anonymity_Mandatory">
+ <tp:docstring>
+ Whether or not the anonymity settings are required for this channel.
+ This MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymousID" type="s" access="read"
+ tp:name-for-bindings="Anonymous_ID">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This is the ID that the remote user of the channel MAY see
+ (assuming there's a single ID). For example, for SIP connections
+ where the From address has been scrambled by the CM, the scrambled
+ address would be available here for the client to see. This is
+ completely optional, and MAY be an empty string ("") in
+ cases where anonymity modes are not set, or the CM doesn't know
+ what the remote contact will see, or any other case where this
+ doesn't make sense.</p>
+
+ <p>This MAY change over the lifetime of the channel, and SHOULD NOT
+ be used with the Request interface.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
new file mode 100644
index 0000000..b0aea59
--- /dev/null
+++ b/spec/Channel_Interface_Call_State.xml
@@ -0,0 +1,147 @@
+<?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 xmlns="http://www.w3.org/1999/xhtml">
+ <p>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;
+ similarly, Jingle implementations are not guaranteed to send
+ <code>&lt;ringing/&gt;</code>).</p>
+
+ <p>To notify the other participant in the call that they are on hold,
+ see <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Hold</tp:dbus-ref>.</p>
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+
+ <method name="GetCallStates" tp:name-for-bindings="Get_Call_States">
+ <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:name-for-bindings="Call_State_Changed">
+ <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:flag suffix="Forwarded" value="8">
+ <tp:docstring>
+ The initiator of the call originally called a contact other than the
+ current recipient of the call, but the call was then forwarded or
+ diverted.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ destination contact may not have been made aware of the call yet
+ (so the Ringing state is not appropriate). This corresponds to SIP's
+ status code 183 Session Progress, and could be used when the
+ outgoing call has reached a gateway, for instance.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Conference_Host" value="32">
+ <tp:added version='0.19.11'/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This contact has merged this call into a conference. Note that GSM
+ provides a notification when the remote party merges a call into a
+ conference, but not when it is split out again; thus, this flag can
+ only indicate that the call has been part of a conference at some
+ point. If a GSM connection manager receives a notification that a
+ call has been merged into a conference a second time, it SHOULD
+ represent this by clearing and immediately re-setting this flag on
+ the remote contact.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml
new file mode 100644
index 0000000..27515d2
--- /dev/null
+++ b/spec/Channel_Interface_Chat_State.xml
@@ -0,0 +1,144 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Chat_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2007 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
+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.ChatState">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+
+ <tp:mapping name="Chat_State_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring>A map from contacts to their chat states.</tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact</tp:docstring>
+ </tp:member>
+ <tp:member name="State" type="u" tp:type="Channel_Chat_State">
+ <tp:docstring>The contact's chat state</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="ChatStates" tp:name-for-bindings="Chat_States"
+ access="read" type="a{uu}" tp:type="Chat_State_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map containing the chat states of all contacts in this
+ channel whose chat state is not Inactive.</p>
+
+ <p>Contacts in this channel, but who are not listed in this map,
+ may be assumed to be in the Inactive state.</p>
+
+ <p>In implementations that do not have this property, its value may be
+ assumed to be empty until a
+ <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates
+ otherwise.</p>
+
+ <tp:rationale>
+ <p>This property was not present in older versions of telepathy-spec,
+ because chat states in XMPP are not state-recoverable (if you
+ miss the change notification signal, there's no way to know the
+ state). However, this property still allows clients to recover
+ state changes that were seen by the CM before the client started
+ to deal with the channel.</p>
+
+ <p>In CMs that follow older spec versions, assuming Inactive will
+ mean that initial chat states will always be assumed to be
+ Inactive, which is the best we can do. XEP 0085 specifies
+ Inactive as the "neutral" state to be assumed unless told
+ otherwise.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="SetChatState" tp:name-for-bindings="Set_Chat_State">
+ <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State">
+ <tp:docstring>
+ The new state.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Set the local state and notify other members of the channel that it
+ has changed.
+ </tp:docstring>
+ <tp:possible-errors>
+ <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:possible-errors>
+ </method>
+ <signal name="ChatStateChanged" tp:name-for-bindings="Chat_State_Changed">
+ <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_Chat_State">
+ <tp:docstring>
+ The new state of this contact.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the state of a member of the channel has changed.
+ This includes local state.
+ </tp:docstring>
+ </signal>
+ <tp:enum name="Channel_Chat_State" type="u">
+ <tp:enumvalue suffix="Gone" value="0">
+ <tp:docstring>
+ The contact has effectively ceased participating in the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Inactive" value="1">
+ <tp:docstring>
+ The contact has not been active for some time.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Active" value="2">
+ <tp:docstring>
+ The contact is actively participating in the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Paused" value="3">
+ <tp:docstring>
+ The contact has paused composing a message.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Composing" value="4">
+ <tp:docstring>
+ The contact is composing a message to be sent to the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels for receiving notifications of remote contacts'
+ state, and for notifying remote contacts of the local state.</p>
+
+ <p>Clients should assume that a contact's state is Channel_Chat_State_Inactive
+ unless they receive a notification otherwise.</p>
+
+ <p>The Channel_Chat_State_Gone state is treated differently to other states:</p>
+ <ul>
+ <li>It may not be used for multi-user chats</li>
+ <li>It may not be explicitly sent</li>
+ <li>It should be automatically sent when the channel is closed</li>
+ <li>It must not be sent to the peer if a channel is closed without being used</li>
+ <li>Receiving it must not cause a new channel to be opened</li>
+ </ul>
+
+ <p>The different states are defined by XEP-0085, but may be applied to any suitable protocol.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
new file mode 100644
index 0000000..abda59e
--- /dev/null
+++ b/spec/Channel_Interface_Conference.xml
@@ -0,0 +1,628 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Conference"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.Conference">
+ <tp:added version="0.19.13">(as stable API)</tp:added>
+ <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>An interface for multi-user conference channels that can "continue
+ from" one or more individual channels. This could be used to invite
+ other contacts to an existing 1-1 text conversation, combine two phone
+ calls into one conference call, and so on, with roughly the same API in
+ each case.</p>
+
+ <tp:rationale>
+ <p>This interface addresses freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls) and <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug
+ #24939</a> (upgrading calls and chats to multi-user).
+ See those bugs for more rationale and use cases.</p>
+ </tp:rationale>
+
+ <p>Existing channels are upgraded by requesting a new channel of the same
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>,
+ listing the channels to be merged into the new conference in the
+ <tp:member-ref>InitialChannels</tp:member-ref> property of the request.
+ If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>,
+ ad-hoc conferences to a set of contacts may be created by requesting a
+ channel, specifying
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in
+ question. A request may specify these alongside
+ <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously
+ upgrade a channel to a conference and invite others to join it.</p>
+
+ <p>Channels with this interface MAY also implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref>
+ to support merging more 1-1 channels into an ongoing conference.
+ Similarly, 1-1 channels MAY implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to
+ support being broken out of a Conference channel.</p>
+
+ <p>The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group</tp:dbus-ref> interface on Conference channels MAY use
+ channel-specific handles for participants; clients SHOULD support
+ both Conferences that have channel-specific handles, and those that
+ do not.</p>
+
+ <tp:rationale>
+ <p>In the GSM case, the Conference's Group interface MAY have
+ channel-specific handles, to represent the fact that the same
+ phone number may be in a conference twice (for instance, it could be
+ the number of a corporate switchboard).</p>
+
+ <p>In the XMPP case, the Conference's Group interface SHOULD have
+ channel-specific handles, to reflect the fact that the participants
+ have MUC-specific identities, and the user might also be able to see
+ their global identities, or not.</p>
+
+ <p>In most other cases, including MSN and link-local XMPP, the
+ Conference's Group interface SHOULD NOT have channel-specific
+ handles, since users' identities are always visible.</p>
+ </tp:rationale>
+
+ <p>Connection managers implementing channels with this interface
+ MUST NOT allow the object paths of channels that could be merged
+ into a Conference to be re-used, unless the channel re-using the
+ object path is equivalent to the channel that previously used it.</p>
+
+ <tp:rationale>
+ <p>If you upgrade some channels into a conference, and then close
+ the original channels, <tp:member-ref>InitialChannels</tp:member-ref>
+ (which is immutable) will contain paths to channels which no longer
+ exist. This implies that you should not re-use channel object paths,
+ unless future incarnations of the path are equivalent.</p>
+
+ <p>For instance, on protocols where you can only have
+ zero or one 1-1 text channels with Emily at one time, it would
+ be OK to re-use the same object path for every 1-1 text channel
+ with Emily; but on protocols where this is not true, it would
+ be misleading.</p>
+ </tp:rationale>
+
+ <h4>Examples of usage</h4>
+
+ <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged
+ into a single conference call by calling:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]
+ })</code>
+ </blockquote>
+
+ <p>which returns a new channel <var>Cn</var> implementing the conference
+ interface. (As a quirk of GSM, both 1-1 will cease to function normally
+ until they are <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref>
+ from the conference, or the conference ends.)</p>
+
+ <p>An XMPP 1-1 conversation <var>C3</var> (with
+ <tt>chris@example.com</tt>, say) can be continued in a newly created
+ multi-user chatroom by calling:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC
+ at the same time:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3],
+ ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net']
+ })</code>
+ </blockquote>
+
+ <p>To continue <var>C3</var> in a particular multi-user
+ chatroom (rather than the implementation inventing a unique name for
+ the room), call:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
+ ...ChannelType: ...Text,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: ...Room,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com',
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Note the use of EnsureChannel — if a channel for
+ <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be
+ equivalent to inviting <tt>chris@example.com</tt> to the existing
+ channel.</p>
+
+ <p>In the above cases, the text channel <var>C3</var> SHOULD remain open
+ and fully functional (until explicitly closed by a client); new
+ incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in
+ <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed
+ only to <tt>chris@example.com</tt>.</p>
+
+ <tp:rationale>
+ <p>If there is an open 1-1 text channel with a contact, in every
+ other situation new messages will appear in that channel. Given
+ that the old channel remains open — which is the least surprising
+ behaviour, and eases us towards a beautiful world where channels
+ never close themselves — it stands to reason that it should be
+ where new messages from Chris should appear. On MSN, creating a
+ conference from <var>C3</var> should migrate the underlying
+ switchboard from <var>C3</var> to the new channel; this is an
+ implementation detail, and should not affect the representation on
+ D-Bus. With a suitable change of terminology, Skype has the same
+ behaviour.</p>
+
+ <p>If the current handler of that channel doesn't want this to happen
+ (maybe it transformed the existing tab into the group chat window,
+ and so there'd be no UI element still around to show new messages),
+ then it should just <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the
+ old 1-1 channel; it'll respawn if necessary.</p>
+ </tp:rationale>
+
+ <p>Either of the XMPP cases could work for Call channels, to
+ upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases
+ could in principle work for link-local XMPP (XEP-0174).</p>
+
+ <p>XMPP and MSN do not natively have a concept of merging two or more
+ channels C1, C2... into one channel, Cn. However, the GSM-style
+ merging API can be supported on XMPP and MSN, as an API short-cut
+ for upgrading C1 into a conference Cn (which invites the
+ TargetHandle of C1 into Cn), then immediately inviting the
+ TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p>
+
+ <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref></h4>
+
+ <p>A GSM connection might advertise the following channel class for
+ conference calls:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/>
+  },<br/>
+  Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia'
+ >InitialAudio</tp:dbus-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>This indicates support for starting audio-only conference calls by
+ merging two or more existing channels (since
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p>
+
+ <p>An XMPP connection might advertise the following classes for ad-hoc
+ multi-user text chats:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/>
+  },<br/>
+  Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+),<br/>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>:
+ Room<br/>
+  },<br/>
+  Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/>
+              <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>The first class indicates support for starting ad-hoc (nameless) chat
+ rooms, upgraded from existing 1-1 channels and/or inviting new
+ contacts, along with a message to be sent along with the invitations.
+ The second indicates support for upgrading to a particular named chat
+ room.</p>
+ </tp:docstring>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ access="read" type="ao">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The individual <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that
+ are continued by this conference, which have the same <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
+
+ <p>This property MUST NOT be requestable; instead, the
+ <tp:member-ref>InitialChannels</tp:member-ref> property may be
+ specified when requesting a channel.</p>
+
+ <tp:rationale>
+ <p>This is consistent with requesting
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than
+ requesting <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref>
+ and some hypothetical ID version of that property.</p>
+ </tp:rationale>
+
+ <p>Change notification is via the
+ <tp:member-ref>ChannelMerged</tp:member-ref> and
+ <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new channel is added to the value of
+ <tp:member-ref>Channels</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>The channel that was added to
+ <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A new channel-specific handle for the <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of
+ <var>Channel</var>, as will appear in
+ <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a
+ global handle is used for
+ <var>Channel</var>'s TargetHandle on the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface
+ of this channel.</tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a channel is removed from the value of
+ <tp:member-ref>Channels</tp:member-ref>, either because it closed
+ or because it was split using the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Splittable.DRAFT.Split</tp:dbus-ref> method.</p>
+
+ <p>If a channel is removed because it was closed, <tp:dbus-ref
+ namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted
+ before this signal.</p>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>The channel that was removed from
+ <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Additional information about the removal, which may include
+ the same well-known keys as the Details argument of
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Group"
+ >MembersChangedDetailed</tp:dbus-ref>, with the same semantics.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
+ access="read" type="ao" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p>
+
+ <p>This property SHOULD be requestable. Omitting it from a request is
+ equivalent to providing it with an empty list as value. Requests
+ where its value has at least two channel paths SHOULD be expected to
+ succeed on any implementation of this interface. If
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref>, then requests with zero
+ or one channel paths SHOULD also succeed; otherwise, clients SHOULD
+ NOT make requests with zero or one paths for this property.</p>
+
+ <tp:rationale>
+ <p>In GSM, a pair of calls can be merged into a conference, but you
+ can't start a conference call from zero or one existing calls. In
+ XMPP and MSN, you can create a new chatroom, or upgrade one 1-1
+ channel into a chatroom; however, on these protocols, it is also
+ possible to fake GSM-style merging by upgrading the first channel,
+ then inviting the targets of all the other channels into it.</p>
+ </tp:rationale>
+
+ <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD
+ NOT be altered by merging them into a conference. However, depending on
+ the protocol, the Channels MAY be placed in a "frozen" state by placing
+ them in this property's value or by calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p>
+
+ <tp:rationale>
+ <p>In Jingle, nothing special will happen to merged calls. UIs MAY
+ automatically place calls on hold before merging them, if that is
+ the desired behaviour; this SHOULD always work. Not doing
+ an implicit hold/unhold seems to preserve least-astonishment.</p>
+
+ <p>In GSM, the calls that are merged go into a state similar to
+ Hold, but they cannot be unheld, only split from the conference
+ call using <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p>
+ </tp:rationale>
+
+ <p>Depending on the protocol, it might be signalled to remote users
+ that this channel is a continuation of all the requested channels,
+ or that it is only a continuation of the first channel in the
+ list.</p>
+
+ <tp:rationale>
+ <p>In MSN, the conference steals the underlying switchboard (protocol
+ construct) from one of its component channels, so the conference
+ appears to remote users to be a continuation of that channel and no
+ other. The connection manager has to make some arbitrary choice, so
+ we arbitrarily mandate that it SHOULD choose the first channel in
+ the list as the one to continue.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialInviteeHandles"
+ tp:name-for-bindings="Initial_Invitee_Handles"
+ access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes"
+ tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of additional contacts invited to this conference when it
+ was created.</p>
+
+ <p>If it is possible to invite new contacts when creating a conference
+ (as opposed to merging several channels into one new conference
+ channel), this property SHOULD be requestable, and appear in the allowed
+ properties in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property
+ SHOULD NOT be requestable, and its value SHOULD always be the empty
+ list.</p>
+
+ <tp:rationale>
+ <p>On GSM you have to place a 1-1 call before you can merge it into a
+ conference; on the other hand, you can invite new contacts to XMPP
+ Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a
+ 1-1 channel with them first.</p>
+ </tp:rationale>
+
+ <p>If included in a request, the given contacts are automatically
+ invited into the new channel, as if they had been added with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
+ <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after
+ the channel was created.</p>
+
+ <tp:rationale>
+ <p>This is a simple convenience API for the common case that a UI
+ upgrades a 1-1 chat to a multi-user chat solely in order to invite
+ someone else to participate.</p>
+ </tp:rationale>
+
+ <p>If the local user was not the initiator of this channel, the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
+ property, together with any other contacts invited at the same time
+ (if that information is known).</p>
+
+ <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be
+ combined in a single request.</p>
+
+ <tp:rationale>
+ <p>For example, if you have a 1-1 channel C1 with Rob, and you want
+ to invite Sjoerd to join the discussion, you can do so by
+ requesting a channel with InitialChannels=[C1] and
+ InitialInviteeHandles=[sjoerd],
+ or InitialChannels=[C1] and
+ InitialInviteeIDs=["sjoerd@example.com"].</p>
+ </tp:rationale>
+
+ <p>If a request includes some combination of InitialInviteeHandles,
+ InitialInviteeIDs and InitialChannels, then the value of
+ InitialInviteeHandles on the resulting channel SHOULD be the union of
+ the handles from InitialInviteeHandles, the handles corresponding
+ to the InitialInviteeIDs, and the target handles of the
+ InitialChannels, with any duplicate handles removed. Because this
+ property is immutable, its value SHOULD be computed before the
+ channel is announced via the NewChannels signal.</p>
+
+ <tp:rationale>
+ <p>This simplifies identification of new channels in clients - they
+ only have to look at one of the properties, not both. For example,
+ after either of the requests mentioned above, the NewChannels
+ signal would announce the channel with InitialChannels=[C1],
+ InitialInviteeHandles=[rob, sjoerd], and
+ InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialInviteeIDs"
+ tp:name-for-bindings="Initial_Invitee_IDs"
+ access="read" type="as" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of additional contacts invited to this conference when it
+ was created.</p>
+
+ <p>This property SHOULD be requestable if and only if
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable.
+ Its semantics are the same, except that it takes a list of the
+ string representations of contact handles; invitations are sent to
+ any contact present in either or both of these properties.</p>
+
+ <p>When a channel is created, the values of InitialInviteeHandles and
+ InitialInviteeIDs MUST correspond to each other. In particular, this
+ means that the value of InitialInviteeIDs will include the TargetID
+ of each channel in InitialChannels, and the ID corresponding to each
+ handle in InitialInviteeHandles.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message"
+ access="read" type="s" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The message that was sent to the
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were
+ invited.</p>
+
+ <p>This property SHOULD be requestable, and appear in the allowed
+ properties in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref>, in protocols where
+ invitations can have an accompanying text message.</p>
+
+ <tp:rationale>
+ <p>This allows invitations with a message to be sent when using
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> or
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>If the local user was not the initiator of this channel, the
+ message with which they were invited (if any) SHOULD appear in the
+ value of this property.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="OriginalChannels" tp:name-for-bindings="Original_Channels"
+ type="a{uo}" tp:type="Channel_Originator_Map"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>On GSM conference calls, it is possible to have the same phone
+ number in a conference twice; for instance, it could be the number of
+ a corporate switchboard. This is represented using channel-specific
+ handles; whether or not a channel uses channel-specific handles is
+ reported in <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>.
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref>
+ property specifies the mapping from opaque channel-specific handles
+ to actual numbers; this property specifies the original 1-1 channel
+ corresponding to each channel-specific handle in the conference.</p>
+
+ <p>In protocols where this situation cannot arise, such as XMPP,
+ this property MAY remain empty.</p>
+
+ <p>For example, consider this situation:</p>
+
+ <ol>
+ <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact
+ <tt>+441234567890</tt> (which is assigned the handle <var>h</var>,
+ say), and ask to be put through to Simon McVittie;</li>
+ <li>Put that call on hold;</li>
+ <li>Place another call (with path <tt>/call/to/jonny</tt>) to
+ <tt>+441234567890</tt>, and ask to be put
+ through to Jonny Lamb;</li>
+ <li>Request a new channel with
+ <tp:member-ref>InitialChannels</tp:member-ref>:
+ <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li>
+ </ol>
+
+ <p>The new channel will have the following properties, for some handles
+ <var>s</var> and <var>j</var>:</p>
+
+ <blockquote>
+ <code>{<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>:
+ Channel_Specific_Handles | (other flags),<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>:
+ [self_handle, s, j],<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>:
+ { s: h, j: h },<br/>
+ ...<tp:member-ref>InitialChannels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>Channels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>OriginalChannels</tp:member-ref>:
+ { s: '/call/to/simon', j: '/call/to/jonny' },<br/>
+ # ...standard properties like ChannelType: Group elided...<br/>
+ }</code>
+ </blockquote>
+
+ <p>Change notification is via the
+ <tp:member-ref>ChannelMerged</tp:member-ref> and
+ <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if
+ <var>Channel_Specific_Handle</var> in the former is non-zero, this
+ property SHOULD be updated to map that handle to the merged channel's
+ path.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Channel_Originator_Map">
+ <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A channel-specific handle for a participant in this conference.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Original_Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The object path of <tp:member-ref>Channels</tp:member-ref>
+ representing the original 1-1 channel with
+ <var>Channel_Specific_Handle</var>.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A mapping from members of a conference to the original 1-1 channel with
+ that contact, if any. See
+ <tp:member-ref>OriginalChannels</tp:member-ref> for details.
+ </tp:docstring>
+ </tp:mapping>
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml
new file mode 100644
index 0000000..d74ea6f
--- /dev/null
+++ b/spec/Channel_Interface_DTMF.xml
@@ -0,0 +1,342 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 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.Channel.Interface.DTMF">
+ <tp:xor-requires>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/>
+ </tp:xor-requires>
+ <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this
+ interface should now be ignored by CMs. This is primarily to allow this
+ interface to be used with <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref>
+ channels.</tp:changed>
+
+ <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
+ type. The event codes used are in common with those defined in <a
+ href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
+ listed in the <tp:type>DTMF_Event</tp:type> enumeration.
+ </tp:docstring>
+
+ <method name="StartTone" tp:name-for-bindings="Start_Tone">
+ <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became
+ vestigial.</tp:changed>
+ <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the tone SHOULD be sent to all
+ eligible streams in the channel.</tp:docstring>
+ </arg>
+ <arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
+ <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ <p>Start sending a DTMF tone to all eligible streams in the channel.
+ Where possible, the tone will continue until
+ <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols,
+ it may only be possible to send events with a predetermined length. In
+ this case, the implementation MAY emit a fixed-length tone, and the
+ StopTone method call SHOULD return NotAvailable.</p>
+ <tp:rationale>
+ The client may wish to control the exact duration and timing of the
+ tones sent as a result of user's interaction with the dialpad, thus
+ starting and stopping the tone sending explicitly.
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="StopTone" tp:name-for-bindings="Stop_Tone">
+ <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became
+ vestigial.</tp:changed>
+ <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the sending SHOULD be stoped in
+ all eligible streams in the channel.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Stop sending any DTMF tones which have been started using the
+ <tp:member-ref>StartTone</tp:member-ref> or
+ <tp:member-ref>MultipleTones</tp:member-ref> methods.
+ If there is no current tone, this method will do nothing.
+ If MultipleTones was used, the client should not assume the
+ sending has stopped immediately; instead, the client should wait
+ for the StoppedTones signal.
+ <tp:rationale>
+ On some protocols it might be impossible to cancel queued tones
+ immediately.
+ </tp:rationale>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Continuous tones are not supported by this stream. Deprecated,
+ since stream IDs are ignored.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones">
+ <tp:added version="0.19.6" />
+ <tp:changed version="0.21.3">The characters [pPxXwW,] must
+ also be supported.</tp:changed>
+ <arg direction="in" name="Tones" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A string representation of one or more DTMF
+ events. Implementations of this method MUST support all of the
+ following characters in this string:</p>
+
+ <ul>
+ <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#'
+ correspond to the members of <tp:type>DTMF_Event</tp:type></li>
+
+ <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an
+ implementation-defined pause, typically for 3 seconds</li>
+
+ <li>'w' or 'W' waits for the user to continue, by stopping
+ interpretation of the string, and if there is more to be played,
+ emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal
+ with the rest of the string as its argument: see that signal
+ for details</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ <p>Send multiple DTMF events to all eligible streams in the channel.
+ Each tone will be played for an implementation-defined number of
+ milliseconds (typically 250ms), followed by a gap before the next tone
+ is played (typically 100ms). The
+ duration and gap are defined by the protocol or connection manager.</p>
+
+ <tp:rationale>
+ <p>In cases where the client knows in advance the tone sequence it
+ wants to send, it's easier to use this method than manually start
+ and stop each tone in the sequence.</p>
+
+ <p>The tone and gap lengths may need to vary for interoperability,
+ according to the protocol and other implementations' ability to
+ recognise tones. At the time of writing, GStreamer uses a
+ minimum of 250ms tones and 100ms gaps when playing in-band DTMF
+ in the normal audio stream, or 70ms tones and 50ms gaps when
+ encoding DTMF as <code>audio/telephone-event</code>.</p>
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The supplied Tones string was invalid.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="CurrentlySendingTones"
+ tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ Indicates whether there are DTMF tones currently being sent in the
+ channel. If so, the client should wait for
+ <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to
+ send more tones.
+ </tp:docstring>
+ </property>
+
+ <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
+ type="s" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ <p>If non-empty in a channel request that will create a new channel,
+ the connection manager should send the tones immediately after
+ at least one eligible audio stream has been created in the
+ channel.</p>
+
+ <p>This property is immutable (cannot change).</p>
+ </tp:docstring>
+ </property>
+
+ <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones"
+ type="s" access="read">
+ <tp:added version="0.21.3" />
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The tones waiting for the user to continue, if any.</p>
+
+ <p>When this property is set to a non-empty value,
+ <tp:member-ref>TonesDeferred</tp:member-ref> is emitted.
+ When any tones are played (i.e. whenever
+ <tp:member-ref>SendingTones</tp:member-ref> is emitted),
+ this property is reset to the empty string.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred">
+ <tp:added version="0.21.3" />
+ <arg name="Tones" type="s">
+ <tp:docstring>The new non-empty value of
+ <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when 'w' or 'W', indicating "wait for the user to continue",
+ is encountered while playing a DTMF string queued by
+ <tp:member-ref>MultipleTones</tp:member-ref> or
+ <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events
+ after the 'w', which have not yet been played, are placed in the
+ <tp:member-ref>DeferredTones</tp:member-ref> property and copied
+ into this signal's argument.</p>
+
+ <p>When the channel handler is ready to continue, it MAY pass the
+ value of <tp:member-ref>DeferredTones</tp:member-ref> to
+ <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending.
+ Alternatively, it MAY ignore the deferred tones, or even play
+ different tones instead. Any deferred tones are discarded the next
+ time a tone is played.</p>
+
+ <p>This signal SHOULD NOT be emitted if there is nothing left to play,
+ i.e. if the 'w' was the last character in the DTMF string.</p>
+ </tp:docstring>
+ </signal>
+
+ <signal name="SendingTones" tp:name-for-bindings="Sending_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Tones" type="s">
+ <tp:docstring>DTMF string (one or more events) that is to be played.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tone(s)are being sent to all eligible streams in the channel.
+ The signal is provided to indicating the fact that the streams are
+ currently being used to send one or more DTMF tones, so any other
+ media input is not getting through to the audio stream. It also
+ serves as a cue for the
+ <tp:member-ref>StopTone</tp:member-ref> method.</p>
+ </tp:docstring>
+ </signal>
+
+ <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Cancelled" type="b">
+ <tp:docstring>True if the DTMF tones were actively cancelled via
+ <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tones have finished playing on streams in this channel.</p>
+ </tp:docstring>
+ </signal>
+
+ <tp:enum name="DTMF_Event" type="y">
+ <tp:enumvalue suffix="Digit_0" value="0">
+ <tp:docstring>0</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_1" value="1">
+ <tp:docstring>1</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_2" value="2">
+ <tp:docstring>2</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_3" value="3">
+ <tp:docstring>3</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_4" value="4">
+ <tp:docstring>4</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_5" value="5">
+ <tp:docstring>5</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_6" value="6">
+ <tp:docstring>6</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_7" value="7">
+ <tp:docstring>7</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_8" value="8">
+ <tp:docstring>8</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_9" value="9">
+ <tp:docstring>9</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Asterisk" value="10">
+ <tp:docstring>*</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Hash" value="11">
+ <tp:docstring>#</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_A" value="12">
+ <tp:docstring>A</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_B" value="13">
+ <tp:docstring>B</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_C" value="14">
+ <tp:docstring>C</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_D" value="15">
+ <tp:docstring>D</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml
new file mode 100644
index 0000000..ce55923
--- /dev/null
+++ b/spec/Channel_Interface_Destroyable.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Destroyable"
+ 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.Destroyable">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.17.14">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface exists to support channels where
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ is insufficiently destructive. At the moment this means
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref>,
+ but the existence of this interface means that unsupported channels
+ can be terminated in a non-channel-type-specific way.</p>
+ </tp:docstring>
+
+ <method name="Destroy" tp:name-for-bindings="Destroy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Close the channel abruptly, possibly with loss of data. The
+ connection manager MUST NOT re-create the channel unless/until
+ more events occur.</p>
+
+ <tp:rationale>
+ <p>The main motivating situation for this method is that when a Text
+ channel with pending messages is closed with Close, it comes back
+ as an incoming channel (to avoid a race between Close and an
+ incoming message). If Destroy is called on a Text channel, the CM
+ should delete all pending messages and close the channel, and
+ the channel shouldn't be re-created until/unless another message
+ arrives.</p>
+ </tp:rationale>
+
+ <p>Most clients SHOULD call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ instead. However, if a client explicitly intends to destroy the
+ channel with possible loss of data, it SHOULD call this method
+ if this interface is supported (according to the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref>
+ property), falling back to Close if not.</p>
+
+ <p>In particular, channel dispatchers SHOULD use this method if
+ available when terminating channels that cannot be handled
+ correctly (for instance, if no handler has been installed for
+ a channel type, or if the handler crashes repeatedly).</p>
+
+ <p>Connection managers do not need to implement this interface on
+ channels where Close and Destroy would be equivalent.</p>
+
+ <tp:rationale>
+ <p>Callers need to be able to fall back to Close in any case.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </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
new file mode 100644
index 0000000..92de9c5
--- /dev/null
+++ b/spec/Channel_Interface_Group.xml
@@ -0,0 +1,1166 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 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.Channel.Interface.Group">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List">
+ <tp:docstring>A structure representing a contact whose attempt to
+ join a group is to be confirmed by the local user using
+ <tp:member-ref>AddMembers</tp:member-ref>.</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" tp:name-for-bindings="Add_Members">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to invite to the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Invite all the given contacts into the channel, or accept requests for
+ channel membership for contacts on the pending local list.</p>
+
+ <p>A message may be provided along with the request, which will be sent
+ to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
+ CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT
+ <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+ message should be provided.</p>
+
+ <p>Attempting to add contacts who are already members is allowed;
+ connection managers must silently accept this, without error.</p>
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members">
+ <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 GetLocalPendingMembersWithInfo if necessary.
+ </tp:deprecated>
+
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Members">
+ <tp:docstring>
+ array of handles of current members
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Local_Pending">
+ <tp:docstring>
+ array of handles of local pending members
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Remote_Pending">
+ <tp:docstring>
+ array of handles of remote pending members
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns arrays of all current, local and remote pending channel
+ members.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <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>
+ The <tp:member-ref>AddMembers</tp:member-ref> method can be used to
+ add or invite members who are
+ not already in the local pending list (which is always valid).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Can_Remove" value="2">
+ <tp:docstring>
+ The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
+ to remove channel members
+ (removing those on the pending local list is always valid).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Can_Rescind" value="4">
+ <tp:docstring>
+ The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
+ on people on the remote
+ pending list.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Add" value="8">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>AddMembers</tp:member-ref> on
+ contacts who are not currently pending members.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Remove" value="16">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are currently channel members.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Accept" value="32">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>AddMembers</tp:member-ref> on
+ contacts who are locally pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Reject" value="64">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are locally pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Rescind" value="128">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are remote pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Channel_Specific_Handles" value="256">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The members of this group have handles which are specific to
+ this channel, and are not valid as general-purpose handles on
+ the connection. Depending on the channel, it may be possible to
+ check the <tp:member-ref>HandleOwners</tp:member-ref> property or
+ call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the
+ owners of these handles, which should be done if you wish to (e.g.)
+ subscribe to the contact's presence.
+ </p>
+
+ <p>
+ Connection managers must ensure that any given handle is not
+ simultaneously a general-purpose handle and a channel-specific
+ handle.
+ </p>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Only_One_Group" value="512">
+ <tp:docstring>
+ Placing a contact in multiple groups of this type is not allowed
+ and will raise NotAvailable (on services where contacts may only
+ be in one user-defined group, user-defined groups will have
+ this flag).
+ </tp:docstring>
+ </tp:flag>
+ <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 no handle owners are
+ available, apart from the owner of the
+ <tp:member-ref>SelfHandle</tp:member-ref>.
+
+ <tp:rationale>
+ This used to be an important optimization to avoid repeated
+ GetHandleOwners calls, before we introduced the
+ <tp:member-ref>HandleOwners</tp:member-ref> property and
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> 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:flag suffix="Members_Changed_Detailed" value="4096">
+ <tp:docstring>
+ Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref>
+ will be emitted for changes to this group's members in addition to
+ <tp:member-ref>MembersChanged</tp:member-ref>.
+ Clients can then connect to the former and ignore emission of the
+ latter. This flag's state MUST NOT change over the lifetime of a
+ channel.
+
+ <tp:rationale>
+ If it were allowed to change, client bindings would have to always
+ connect to MembersChanged just in case the flag ever went away (and
+ generally be unnecessarily complicated), which would mostly negate
+ the point of having this flag in the first place.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Depart" value="8192">
+ <tp:added version="0.17.21"/>
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ the <tp:member-ref>SelfHandle</tp:member-ref>.
+
+ <tp:rationale>
+ This would be set for XMPP Multi-User Chat or IRC channels,
+ but not for a typical implementation of streamed media calls.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
+ access="read" tp:name-for-bindings="Group_Flags">
+ <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 <tp:member-ref>GroupFlagsChanged</tp:member-ref> 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" tp:name-for-bindings="Get_Group_Flags">
+ <arg direction="out" type="u" tp:type="Channel_Group_Flags"
+ name="Group_Flags">
+ <tp:docstring>
+ The value of the GroupFlags property
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> 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:name-for-bindings="Handle_Owners">
+ <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
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal.
+ </tp:docstring>
+ <tp:added version="0.17.6"/>
+ </property>
+
+ <signal name="HandleOwnersChanged"
+ tp:name-for-bindings="Handle_Owners_Changed">
+ <tp:docstring>
+ Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref>
+ 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 <tp:member-ref>MembersChanged</tp:member-ref> signal
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners">
+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of integer handles representing members of the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners">
+ <tp:docstring>
+ An array of integer handles representing the owner handles of
+ the given room members, in the same order, or 0 if the
+ owner is not available
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on
+ the channel, then the handles of the group members are specific
+ to this channel, and are not meaningful in a connection-wide
+ context such as contact lists. This method allows you to find
+ 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"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag,
+ so handles in this channel are globally meaningful and calling
+ this method is not necessary
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ One of the given handles is not a member
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetLocalPendingMembers"
+ tp:name-for-bindings="Get_Local_Pending_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <tp:docstring>
+ Returns the To_Be_Added handle (only) for each structure in the
+ <tp:member-ref>LocalPendingMembers</tp:member-ref> 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:name-for-bindings="Get_Local_Pending_Members_With_Info">
+ <tp:added version="0.15.0" />
+ <tp:docstring>
+ Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> 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[]"
+ name="Info">
+ <tp:docstring>
+ An array of structs containing:
+ <ul>
+ <li>
+ A handle representing the contact requesting channel membership
+ </li>
+ <li>
+ A handle representing the contact making the request, or 0 if
+ unknown
+ </li>
+ <li>
+ The reason for the request: one of the values of
+ <tp:type>Channel_Group_Change_Reason</tp:type>
+ </li>
+ <li>
+ A string message containing the reason for the request if any (or
+ blank if none)
+ </li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <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="LocalPendingMembers" access="read"
+ type="a(uuus)" tp:type="Local_Pending_Info[]"
+ tp:name-for-bindings="Local_Pending_Members">
+ <tp:docstring>
+ An array of structs containing handles representing contacts
+ requesting channel membership and awaiting local approval with
+ <tp:member-ref>AddMembers</tp:member-ref>.
+ </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" tp:name-for-bindings="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" tp:name-for-bindings="Get_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <tp:docstring>
+ Returns the <tp:member-ref>Members</tp:member-ref> 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:name-for-bindings="Remote_Pending_Members">
+ <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"
+ tp:name-for-bindings="Get_Remote_Pending_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <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
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>
+ 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>
+
+ <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed">
+ <tp:docstring>
+ Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> 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:name-for-bindings="Self_Handle">
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>
+ channels). Note that this is different from the result of
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>
+ 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" tp:name-for-bindings="Get_Self_Handle">
+ <arg direction="out" type="u" tp:type="Contact_Handle"
+ name="Self_Handle"/>
+ <tp:docstring>
+ Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref>
+ 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" tp:name-for-bindings="Group_Flags_Changed">
+ <arg name="Added" type="u" tp:type="Channel_Group_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been set
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="u" tp:type="Channel_Group_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been cleared
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the flags as returned by
+ <tp:member-ref>GetGroupFlags</tp:member-ref> are changed.
+ The user interface should be updated as appropriate.
+ </tp:docstring>
+ </signal>
+
+ <tp:enum name="Channel_Group_Change_Reason" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The reason for a set of handles to move to one of
+ <tp:member-ref>Members</tp:member-ref>,
+ <tp:member-ref>LocalPendingMembers</tp:member-ref> or
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed
+ from the group. A client may supply a reason when attempting to
+ remove members from a group with
+ <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons
+ are supplied by the CM when emitting
+ <tp:member-ref>MembersChanged</tp:member-ref> and
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason
+ codes have different meanings depending on the <var>Actor</var> in a
+ MembersChanged signal.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>No reason was provided for this change.</p>
+
+ <p>In particular, this reason SHOULD be used when representing
+ users joining a named chatroom in the usual way, users leaving
+ a chatroom by their own request, and normal termination of a
+ StreamedMedia call by the remote user.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed from
+ a group for this reason and the actor is not the SelfHandle, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Terminated</code>.</p>
+
+ <p>If the SelfHandle is removed from a group for this reason and
+ the actor is also the SelfHandle, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a user going offline. Also used when
+ user is already offline, but this wasn't known previously.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is offline, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Offline.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If a handle is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Offline</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Kicked" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Busy" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a busy indication.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is busy, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Busy.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Busy</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invited" value="4">
+ <tp:docstring>
+ The change is due to an invitation. This reason SHOULD only be used
+ when contacts are added to the remote-pending set (to indicate that
+ the contact has been invited) or to the members (to indicate that
+ the contact has accepted the invitation).
+
+ <tp:rationale>
+ Otherwise, what would it mean?
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Banned" value="5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick+ban operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="6">
+ <tp:docstring>
+ The change is due to an error occurring.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_Contact" value="7">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact does not exist.</p>
+
+ <p>For instance, if the user invites a nonexistent contact to a
+ chatroom or attempts to call a nonexistent contact, this could
+ be indicated by the CM adding that contact's handle to
+ remote-pending for reason None or Invited, then removing it for
+ reason Invalid_Contact. In the case of a 1-1 StreamedMedia
+ call, the CM SHOULD remove the self handle from the Group
+ in the same signal.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="No_Answer" value="8">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact did not respond.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called did not respond, or the
+ local user did not respond to an incoming call, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason No_Answer.</p>
+
+ <tp:rationale>
+ Documenting existing practice.
+ </tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.NoAnswer</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Renamed" value="9">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because a contact's unique identifier changed.
+ There must be exactly one handle in the removed set and exactly
+ one handle in one of the added sets. The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref>
+ signal on the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref>
+ interface will have been emitted for the same handles,
+ shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Permission_Denied" value="10">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because there was no permission to contact the
+ requested handle.</p>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Separated" value="11">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If members are removed with this reason code, the change is
+ because the group has split into unconnected parts which can only
+ communicate within themselves (e.g. netsplits on IRC use this
+ reason code).
+ </p>
+ <p>
+ If members are added with this reason code, the change is because
+ unconnected parts of the group have rejoined. If this channel
+ carries messages (e.g. <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref>
+ channels) applications must
+ assume that the contacts being added are likely to have missed some
+ messages as a result of the separation, and that the contacts
+ in the group are likely to have missed some messages from the
+ contacts being added.
+ </p>
+ <p>Note that from the added contacts' perspective, they have been
+ in the group all along, and the contacts we indicate to be in
+ the group (including the local user) have just rejoined
+ the group with reason Separated. Application protocols in Tubes
+ should be prepared to cope with this situation.
+ </p>
+
+ <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be
+ removed from channels with this reason.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <signal name="MembersChanged" tp:name-for-bindings="Members_Changed">
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string message from the server, or blank if not
+ </tp:docstring>
+ </arg>
+ <arg name="Added" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members added to the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members removed from the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending local approval
+ </tp:docstring>
+ </arg>
+ <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending remote approval
+ </tp:docstring>
+ </arg>
+ <arg name="Actor" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact handle of the person who made the change, or 0
+ if not known
+ </tp:docstring>
+ </arg>
+ <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason">
+ <tp:docstring>
+ A reason for the change
+ </tp:docstring>
+ </arg>
+ <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
+ <tp:member-ref>HandleOwners</tp:member-ref> property.
+ In practice, this will mean that
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> 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>
+
+ <p>See <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ for an overview of how group state changes are used to indicate the
+ progress of a call.</p>
+ </tp:docstring>
+ </signal>
+
+ <tp:mapping name="Handle_Identifier_Map">
+ <tp:docstring>
+ A map from handles to the corresponding normalized string identifier.
+ </tp:docstring>
+ <tp:added version="0.17.17"/>
+
+ <tp:member type="u" name="Handle" tp:type="Contact_Handle">
+ <tp:docstring>
+ A nonzero handle
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Identifier">
+ <tp:docstring>
+ The same string that would be returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ for this handle.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="MembersChangedDetailed"
+ tp:name-for-bindings="Members_Changed_Detailed">
+ <arg name="Added" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members added to the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members removed from the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending local approval
+ </tp:docstring>
+ </arg>
+ <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending remote approval
+ </tp:docstring>
+ </arg>
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Information about the change, which may include the following
+ well-known keys:</p>
+
+ <dl>
+ <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt>
+ <dd>The contact handle of the person who made the change; 0 or
+ omitted if unknown or not applicable.</dd>
+
+ <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt>
+ <dd>A reason for the change.</dd>
+
+ <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt>
+ <dd>
+ <p>The string identifiers for handles mentioned in this signal, to
+ give clients the minimal information necessary to react to the
+ event without waiting for round-trips. Connection managers
+ SHOULD include the identifiers for members added to the group and
+ for the actor (if any); they MAY omit the identifiers for handles
+ which have been removed from the group.</p>
+
+ <tp:rationale>
+ <p>On IRC, an event such as a netsplit could cause the vast
+ majority of a channel to leave. Given that clients should
+ already know the identifiers of a channel's members, including
+ potentially hundreds of strings in the netsplit signal is
+ unnecessary.</p>
+ </tp:rationale>
+
+ <p>Clients MUST NOT assume that the presence or absence of a
+ handle in this mapping is meaningful. This mapping is merely
+ an optimization for round-trip reduction, and connection
+ managers MAY add additional handles, omit some handles, or
+ omit the mapping completely.</p>
+ </dd>
+
+ <dt>message (s)</dt>
+ <dd>A string message from the server regarding the change</dd>
+
+ <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt>
+ <dd>A (possibly implementation-specific) DBus error describing the
+ change, providing more specific information than the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This
+ MUST only be present if it is strictly more informative than
+ 'change-reason'; if present, 'change-reason' MUST be set to the
+ closest available reason.
+
+ <tp:rationale>
+ A SIP connection manager might want to signal "402 Payment
+ required" as something more specific than Error or
+ Permission_Denied so that a SIP-aware UI could handle it
+ specially; including a namespaced error permits this to be done
+ without <tp:type>Channel_Group_Change_Reason</tp:type> being
+ extended to encompass every error any CM ever wants to report.
+ </tp:rationale>
+ </dd>
+
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change. SHOULD NOT be shown to
+ users in normal circumstances.</dd>
+ </dl>
+ </tp:docstring>
+ </arg>
+ <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. This signal provides a superset of the information provided by
+ <tp:member-ref>MembersChanged</tp:member-ref>;
+ if the channel's <tp:member-ref>GroupFlags</tp:member-ref>
+ contains Members_Changed_Detailed, then clients may listen exclusively
+ to this signal in preference to that signal.</p>
+
+ <p>All channel-specific handles that are mentioned in this signal
+ MUST be represented in the value of the
+ <tp:member-ref>HandleOwners</tp:member-ref> property. In practice,
+ this will mean that
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted
+ <em>before</em> emitting a MembersChangedDetailed signal in which
+ channel-specific handles are added, but that it is emitted
+ <em>after</em> emitting a MembersChangedDetailed signal in which
+ channel-specific handles are removed.</p>
+
+ <p>See <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ for an overview of how group state changes are used to indicate the
+ progress of a call.</p>
+ </tp:docstring>
+ <tp:added version="0.17.16"/>
+ </signal>
+
+ <method name="RemoveMembers" tp:name-for-bindings="Remove_Members">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to remove from the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Requests the removal of contacts from a channel, reject their
+ request for channel membership on the pending local list, or
+ rescind their invitation on the pending remote list.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group,
+ it can be removed via this method, in order to leave the group
+ gracefully. This is the recommended way to leave a chatroom, close
+ or reject a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call, and so on.</p>
+
+ <p>Accordingly, connection managers SHOULD support
+ doing this, regardless of the value of
+ <tp:member-ref>GroupFlags</tp:member-ref>.
+ If doing so fails with PermissionDenied, this is considered to a bug
+ in the connection manager, but clients MUST recover by falling back
+ to closing the channel with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method.</p>
+
+ <p>Removing any contact from the local pending list is always
+ allowed. Removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members
+ is allowed if and only if Channel_Group_Flag_Can_Remove is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>,
+ while removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list
+ is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>.</p>
+
+ <p>A message may be provided along with the request, which will be
+ sent to the server if supported. See the
+ Channel_Group_Flag_Message_Remove,
+ Channel_Group_Flag_Message_Depart,
+ Channel_Group_Flag_Message_Reject and
+ Channel_Group_Flag_Message_Rescind
+ <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+ message should be provided.</p>
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveMembersWithReason"
+ tp:name-for-bindings="Remove_Members_With_Reason">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to remove from the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Reason" type="u"
+ tp:type="Channel_Group_Change_Reason">
+ <tp:docstring>
+ A reason for the change
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may
+ be provided where
+ appropriate. The reason code may be ignored if the underlying
+ protocol is unable to represent the given reason.
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The provided reason code was invalid.
+ </tp:docstring>
+ </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
+ cannot be presumed by the channel's existence (for example, a channel you
+ may request membership of but your request may not be granted).</p>
+
+ <p>This interface implements three lists: a list of current members
+ (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending
+ and remote pending members
+ (<tp:member-ref>LocalPendingMembers</tp:member-ref> and
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively).
+ Contacts on the remote
+ pending list have been invited to the channel, but the remote user has not
+ accepted the invitation. Contacts on the local pending list have requested
+ membership of the channel, but the local user of the framework must accept
+ their request before they may join. A single contact should never appear on
+ more than one of the three lists. The lists are empty when the channel is
+ created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal
+ (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains
+ Members_Changed_Detailed, the
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal)
+ should be emitted when information
+ is retrieved from the server, or changes occur.</p>
+
+ <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates
+ that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from
+ the channel, and the channel subsequently emits <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>,
+ clients SHOULD consider the details given in the MembersChanged or
+ MembersChangedDetailed signal to be the reason why the channel closed.</p>
+
+ <p>Addition of members to the channel may be requested by using
+ <tp:member-ref>AddMembers</tp:member-ref>. If
+ remote acknowledgement is required, use of the AddMembers method will cause
+ users to appear on the remote pending list. If no acknowledgement is
+ required, AddMembers will add contacts to the member list directly. If a
+ contact is awaiting authorisation on the local pending list, AddMembers
+ will grant their membership request.</p>
+
+ <p>Removal of contacts from the channel may be requested by using
+ <tp:member-ref>RemoveMembers</tp:member-ref>. If a contact is awaiting
+ authorisation on the local pending
+ list, RemoveMembers will refuse their membership request. If a contact is
+ on the remote pending list but has not yet accepted the invitation,
+ RemoveMembers will rescind the request if possible.</p>
+
+ <p>It should not be presumed that the requester of a channel implementing this
+ interface is immediately granted membership, or indeed that they are a
+ member at all, unless they appear in the list. They may, for instance,
+ be placed into the remote pending list until a connection has been
+ established or the request acknowledged remotely.</p>
+
+ <p>If the local user joins a Group channel whose members or other state
+ cannot be discovered until the user joins (e.g. many chat room
+ implementations), the connection manager should ensure that the channel
+ is, as far as possible, in a consistent state before adding the local
+ contact to the members set; until this happens, the local contact should
+ be in the remote-pending set. For instance, if the connection manager
+ queries the server to find out the initial members list for the
+ channel, it should leave the local contact in the remote-pending set
+ until it has finished receiving the initial members list.
+ </p>
+
+ <p>If the protocol provides no reliable way to tell whether the complete
+ initial members list has been received yet, the connection manager
+ should make a best-effort attempt to wait for the full list
+ (in the worst case, waiting for a suitable arbitrary timeout)
+ rather than requiring user interfaces to do so on its behalf.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
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
new file mode 100644
index 0000000..ef5a08f
--- /dev/null
+++ b/spec/Channel_Interface_Hold.xml
@@ -0,0 +1,222 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Hold" 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-2008 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+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.
+
+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.
+
+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.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold">
+ <tp:xor-requires>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/>
+ </tp:xor-requires>
+ <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 may put the channel on hold.
+ This only makes sense for channels where
+ you are streaming media to or from the members. (To see whether the
+ other participant has put you on hold, see <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref>.)</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
+ connection manager free up any resources that are only needed for
+ an actively used channel (e.g. in a GSM or PBX call, it will be
+ necessary to place an active call on hold before you can start
+ another call).</p>
+ </tp:docstring>
+
+ <method name="GetHoldState" tp:name-for-bindings="Get_Hold_State">
+ <tp:docstring>
+ Return whether the local user has placed the channel on hold.
+ </tp:docstring>
+
+ <arg name="HoldState" direction="out" type="u"
+ tp:type="Local_Hold_State">
+ <tp:docstring>
+ The state of the channel
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reason" direction="out" type="u"
+ tp:type="Local_Hold_State_Reason">
+ <tp:docstring>
+ The reason why the channel is in that state
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="HoldStateChanged" tp:name-for-bindings="Hold_State_Changed">
+ <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
+ <tp:member-ref>RequestHold</tp:member-ref>, 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 value="1" suffix="Held">
+ <tp:docstring>
+ All streams are held (the call is on hold)
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Pending_Hold">
+ <tp:docstring>
+ 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:enumvalue value="3" suffix="Pending_Unhold">
+ <tp:docstring>
+ 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>
+
+ <tp:enum name="Local_Hold_State_Reason" type="u">
+ <tp:docstring>
+ 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>
+
+ <tp:enumvalue value="0" suffix="None">
+ <tp:docstring>
+ 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>
+ </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" tp:name-for-bindings="Request_Hold">
+ <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 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
+ <tp:member-ref>HoldStateChanged</tp:member-ref> 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.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>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
new file mode 100644
index 0000000..242c952
--- /dev/null
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -0,0 +1,235 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 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.Channel.Interface.MediaSignalling">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for signalling a channel containing synchronised media
+ sessions which can contain an arbitrary number of streams. The
+ presence of this interface on a Channel indicates that the connection
+ manager will not carry out the actual streaming for this channel,
+ and that the client handling the channel is responsible for doing
+ so; in most cases we recommend doing this by using the
+ telepathy-farsight library.</p>
+
+ <tp:rationale>
+ <p>Streaming audio and (particularly) video requires a high level of
+ integration with the UI, and having the connection manager act as
+ a proxy would be likely to introduce unacceptable latency. As a
+ result, audio/video streaming is offloaded into the client
+ where possible, as an exception to the general design of
+ Telepathy.</p>
+ </tp:rationale>
+
+ <p>The negotiation interface is based on the API of the
+ <a href="http://farsight.freedesktop.org/">Farsight</a> library.
+ This, in turn, is based upon the IETF MMusic ICE drafts, where
+ connections are established by signalling potential connection
+ candidates to the peer until a usable connection is found, and
+ codecs are negotiated with an SDP-style offer and answer. However,
+ the principles should be applicable to other media streaming methods
+ and the API re-used without difficulty.</p>
+
+ <p>Note that the naming conventions used in the MediaStreamHandler
+ and MediaSessionHandler interfaces are rather confusing; methods
+ have signal-like names and signals have method-like names, due to
+ the API being based rather too closely on that of Farsight. This
+ is for historical reasons and will be fixed in a future release
+ of the Telepathy specification.</p>
+ </tp:docstring>
+
+ <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"
+ tp:name-for-bindings="Get_Session_Handlers">
+ <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"
+ name="Session_Handlers"/>
+ <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" tp:name-for-bindings="New_Session_Handler">
+ <arg name="Session_Handler" type="o">
+ <tp:docstring>
+ Object path of the new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Media.SessionHandler</tp:dbus-ref>
+ object
+ </tp:docstring>
+ </arg>
+ <arg name="Session_Type" tp:type="Media_Session_Type" type="s">
+ <tp:docstring>
+ String indicating type of session, eg &quot;rtp&quot;
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal that a session handler object has been created. The client
+ should create a session object and create streams for the streams
+ within.
+ </tp:docstring>
+ </signal>
+
+ <tp:property name="nat-traversal" type="s">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ A string indicating the NAT traversal techniques employed by the
+ streams within this channel if they do not have a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property. The possible values are the same as for the NATTraversal
+ property on the streams.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="stun-server" type="s">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ The IP address or hostname of the STUN server to use for NAT traversal
+ if the individual streams do not specify one.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="stun-port" type="q">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ The UDP port number to use on the provided STUN server.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="gtalk-p2p-relay-token" type="s">
+ <tp:deprecated version="0.17.22">XMPP connection managers
+ supporting the Google Talk relay server SHOULD make the necessary
+ HTTP requests to find a username and password, and use those
+ to populate the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref>
+ property on the Media.StreamHandler.</tp:deprecated>
+ <tp:docstring>
+ The authentication token for use with the Google Talk peer-to-peer relay
+ server.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:hct name="gtalk-p2p">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>gtalk-p2p</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="ice-udp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>ice-udp</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="wlm-8.5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-8.5</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="wlm-2009">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-2009</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="video/h264" is-family="yes">
+ <tp:docstring>
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on StreamedMedia channels.</p>
+ </tp:rationale>
+
+ <p>For example, a client could advertise support for
+ Speex, Theora and H264 by having three
+ handler capability tokens,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>,
+ in its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.</p>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:hct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml
new file mode 100644
index 0000000..cd606c1
--- /dev/null
+++ b/spec/Channel_Interface_Mergeable_Conference.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Mergeable_Conference"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.MergeableConference.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Conference"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for multi-user conference channels that can have
+ additional individual channels merged into them after they are
+ created.</p>
+
+ <tp:rationale>
+ <p>This interface addresses part of freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls). GSM is currently
+ the only protocol known to implement this; PBXs might implement
+ it too.</p>
+
+ <p>It might be made into a mandatory-to-implement part of Conference,
+ or kept as a separate interface, when stabilized.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <method name="Merge"
+ tp:name-for-bindings="Merge">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given channel be incorporated into this
+ channel.</p>
+
+ <p>The given channel SHOULD be added to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.Channels</tp:dbus-ref> if and only if the
+ underlying protocol signals the merge in some way. It MUST NOT be
+ added to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.InitialChannels</tp:dbus-ref> (to preserve
+ immutability).</p>
+
+ <tp:rationale>
+ <p>In GSM it is possible to merge additional calls into an ongoing
+ conference.</p>
+
+ <p>In XMPP this method could be implemented to merge a 1-1 Text
+ channel into a MUC Text channel by inviting the peer from the Text
+ channel into the MUC, or to merge a 1-1 Jingle call into a Muji
+ call by inviting the peer from the Jingle call into the Muji call.
+ (MUC and Muji channels are both implemented by XMPP MUCs, with
+ Handle_Type_Room.)</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel with the same <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>
+ as this one, but with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given channel isn't suitable for merging into this one: for
+ instance, it might have the wrong channel type or handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It will never be possible to merge channels into this particular
+ conference.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The given channel is theoretically suitable for merging into this
+ one, but that's not currently possible for some reason (for
+ instance, this SHOULD be raised if a limit on the number of
+ channels in a conference is exceeded).
+ <strong>[FIXME: PermissionDenied?]</strong>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
new file mode 100644
index 0000000..62e8384
--- /dev/null
+++ b/spec/Channel_Interface_Messages.xml
@@ -0,0 +1,1433 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Messages"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+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">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:added version="0.17.16">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref>
+ interface to support more general messages, including:</p>
+
+ <ul>
+ <li>messages with attachments (like MIME multipart/mixed)</li>
+ <li>groups of alternatives (like MIME multipart/alternative)</li>
+ <li>delivery reports (which replace <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>),
+ addding support for protocols where the message content is not echoed
+ back to the sender on failure and for receiving positive
+ acknowledgements, as well as ensuring that incoming delivery reports
+ are not lost if no client is handling the channel yet;</li>
+ <li>any extra types of message we need in future</li>
+ </ul>
+
+ <p>Incoming messages, outgoing messages, and delivery reports are all
+ represented as lists of <tp:type>Message_Part</tp:type> structures,
+ with a format reminiscent of e-mail. Messages are sent by calling
+ <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are
+ announced to other clients which may be interested in the channel by
+ the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming
+ messages and delivery reports are signalled by
+ <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the
+ the <tp:member-ref>PendingMessages</tp:member-ref> property until
+ acknowledged by calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.
+ Only the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ for a channel should acknowledge messages; <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s
+ (such as loggers) and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
+ for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p>
+
+ <tp:rationale>
+ <p>If observers were allowed to acknowledge messages, then messages
+ might have been acknowledged before the handler even got to see the
+ channel, and hence could not be shown to the user.</p>
+ </tp:rationale>
+
+ <p>If this interface is present, clients that support it SHOULD
+ listen for the <tp:member-ref>MessageSent</tp:member-ref> and
+ <tp:member-ref>MessageReceived</tp:member-ref> signals, and
+ ignore the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
+ signals on the Text interface (which are guaranteed to duplicate
+ signals from this interface).</p>
+
+ <p>Although this specification supports formatted (rich-text)
+ messages with unformatted alternatives, implementations SHOULD NOT
+ attempt to send formatted messages until the Telepathy specification
+ has also been extended to cover capability discovery for message
+ formatting.</p>
+
+ <tp:rationale>
+ We intend to expose all rich-text messages as XHTML-IM, but on some
+ protocols, formatting is an extremely limited subset of that format
+ (e.g. there are protocols where foreground/background colours, font
+ and size can be set, but only for entire messages).
+ Until we can tell UIs what controls to offer to the user, it's
+ unfriendly to offer the user controls that may have no effect.
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="SupportedContentTypes" type="as" access="read"
+ tp:name-for-bindings="Supported_Content_Types"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>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.
+ This list MUST NOT be empty, since all Messages implementations
+ MUST accept messages containing a single "text/plain" part.</p>
+
+ <p>Items in this list MUST be normalized to lower-case.</p>
+
+ <p>Some examples of how this property interacts with the
+ <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p>
+
+ <dl>
+ <dt>A simple IM implementation: only plain text messages are
+ allowed</dt>
+ <dd>SupportedContentTypes = ['text/plain'],
+ MessagePartSupportFlags = 0</dd>
+
+ <dt>Formatted text with a plain text alternative is allowed (see the
+ HTML interface draft)</dt>
+ <dd>SupportedContentTypes = ['text/html', 'text/plain'],
+ MessagePartSupportFlags = 0</dd>
+
+ <dt>JPEG or PNG images may be sent, but without any attached
+ text</dt>
+ <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
+ 'image/png'], MessagePartSupportFlags = 0</dd>
+
+ <dt>Unformatted text to which an optional JPEG or PNG image may be
+ attached</dt>
+ <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
+ 'image/png'], MessagePartSupportFlags = One_Attachment</dd>
+
+ <dt>Formatted text to which arbitrarily many images may be
+ attached</dt>
+ <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg',
+ 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags =
+ One_Attachment | Multiple_Attachments</dd>
+
+ <dt>A full SIP implementation: arbitrary MIME messages are
+ allowed</dt>
+ <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags =
+ One_Attachment | Multiple_Attachments</dd>
+ </dl>
+ </tp:docstring>
+ </property>
+
+ <property name="MessageTypes" type="au"
+ tp:type="Channel_Text_Message_Type[]" access="read"
+ tp:name-for-bindings="Message_Types"
+ tp:immutable="yes">
+ <tp:added version="0.21.5">
+ This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text"
+ >GetMessageTypes</tp:dbus-ref>; fall back to that method for
+ compatibility with older connection managers.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of message types which may be sent on this channel.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="MessagePartSupportFlags" type="u"
+ tp:type="Message_Part_Support_Flags" access="read"
+ tp:name-for-bindings="Message_Part_Support_Flags"
+ tp:immutable="yes">
+ <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>If no flags are set, this indicates that messages may contain
+ a single message part whose content-type is any of the types
+ from SupportedContentTypes, possibly with some alternatives.</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 so far 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>
+
+ <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some
+ examples.</p>
+ </tp:docstring>
+
+ <tp:flag suffix="One_Attachment" value="1">
+ <tp:docstring>
+ <tp:member-ref>SendMessage</tp:member-ref> 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="2">
+ <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"
+ array-depth="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Part of a message's content. In practice, this mapping never
+ appears in isolation: incoming messages are represented by a list of
+ <tp:type>Message_Part</tp:type> mappings in the
+ <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing
+ messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as
+ a list of these mappings.</p>
+
+ <p>The first part of the message contains "headers", which refer
+ to the entire message. The second and subsequent parts contain the
+ message's content, including plain text, formatted text and/or
+ attached files. Well-known keys for the header and body parts are
+ defined by the <tp:type>Message_Header_Key</tp:type> and
+ <tp:type>Message_Body_Key</tp:type> types, respectively. It is an
+ error for a connection manager to put keys referring to the message
+ as a whole in the second or subsequent Message_Part, or keys intended
+ for body parts in the first Message_Part; clients MUST recover from
+ this error by ignoring these mis-placed keys.</p>
+
+ <tp:rationale>
+ <p>Instead of representing messages as aa{sv} where the first
+ dictionary is special (a dictionary of headers), we could have
+ used a signature like (a{sv}aa{sv}) to separate out the headers
+ and the body parts.</p>
+
+ <p>However, this would make access to the messages more awkward.
+ In Python, the syntax for access to a header field would remain
+ <code>message[0]['message-type']</code>, but access to a body
+ field in the second body part would change from
+ <code>message[2]['content'] to message[1][1]['content']</code>. In
+ GLib, the message would change from being a
+ <code>GPtrArray(GHashTable)</code> to being a
+ <code>GValueArray(GHashTable, GPtrArray(GHashTable))</code> which
+ is rather inconvenient to dereference.</p>
+ </tp:rationale>
+
+ <p>In any group of parts with the same non-empty value for the
+ <tt>alternative</tt> key (which represent alternative versions of the
+ same content), more faithful versions of the intended message MUST
+ come before less faithful versions (note that this order is the
+ opposite of MIME <tt>multipart/alternative</tt> parts). Clients
+ SHOULD display the first alternative that they understand.</p>
+
+ <tp:rationale>
+ <p>Specifying the preference order means that if the underlying
+ protocol doesn't support alternatives, the CM can safely delete
+ everything apart from the first supported alternative when
+ sending messages.</p>
+
+ <p>The order is the reverse of MIME because MIME's rationale for
+ placing the "plainest" part first (legibility in pre-MIME UAs)
+ does not apply to us, and placing the most preferred part
+ first simplifies display (a client can iterate the message
+ in order, display the first alternative that it understands,
+ and skip displaying all subsequent parts with the same
+ "alternative" key).</p>
+ </tp:rationale>
+
+ <p>Clients SHOULD present all parts that are not redundant
+ alternatives in the order they appear in this array, possibly
+ excluding parts that are referenced by another displayed part.
+ It is implementation-specific how the parts are presented to the
+ user.</p>
+
+ <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>Connection managers, clients and extensions to this specification
+ SHOULD NOT include <tp:type>Handle</tp:type>s as values in a
+ Message_Part, except for <code>message-sender</code> in the
+ header.</p>
+
+ <tp:rationale>
+ <p>Reference-counting handles in clients becomes problematic if
+ the channel proxy cannot know whether particular map values
+ are handles or not.</p>
+ </tp:rationale>
+
+ <h4>Example messages</h4>
+
+ <p>A rich-text message, with an embedded image, might be represented
+ as:</p>
+
+ <pre>
+[
+ {
+ 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+ 'message-sender': 42,
+ 'message-sent': 1210067943,
+ 'message-received': 1210067947,
+ 'message-type': 0, # = Channel_Text_Message_Type_Normal
+ 'pending-message-id': 437,
+ },
+ { 'alternative': 'main',
+ 'content-type': 'text/html',
+ 'content': 'Here is a photo of my cat:&lt;br /&gt;' +
+ '&lt;img src="cid:catphoto" alt="lol!" /&gt;' +
+ '&lt;br /&gt;Isn't it cute?',
+ },
+ { 'alternative': 'main',
+ 'content-type': 'text/plain',
+ 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?',
+ },
+ { 'identifier': 'catphoto',
+ 'content-type': 'image/jpeg',
+ 'size': 101000,
+ 'needs-retrieval': True,
+ },
+]</pre>
+
+ <p>telepathy-ring, Nokia's GSM connection manager, represents vCards
+ sent via SMS as:</p>
+
+ <pre>
+[
+ {
+ 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c',
+ 'message-sender': 42,
+ 'message-sent': 1210067943,
+ 'message-received': 1210067947,
+ 'message-type': 0, # = Channel_Text_Message_Type_Normal
+ 'pending-message-id': 437,
+ },
+ { 'content-type': 'text/x-vcard',
+ 'content': [ 0x66, 0x69, 0x71, ...], # vCard data as an array of bytes
+ },
+]</pre>
+
+ <h3>Delivery reports</h3>
+
+ <div>
+ <p>Delivery reports are also represented as messages with the
+ <tt>message-type</tt> header mapping to
+ <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report.
+ Delivery reports SHOULD contain the <tt>message-sender</tt> header,
+ mapping to the intended recipient of the original message, if
+ possible; other headers specific to delivery reports are defined by
+ the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second
+ and subsequent parts, if present, are a human-readable report from
+ the IM service.</p>
+
+ <p>For backwards- and forwards-compatibility, whenever a delivery
+ error report is signalled—that is, with <tt>delivery-status</tt>
+ mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or
+ Permanently_Failed—<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ SHOULD also be emitted; whenever <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ is emitted, a delivery report MUST also be signalled.
+ Delivery report messages on this interface MUST be represented in
+ emissions of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
+ as messages with the Non_Text_Content
+ <tp:type>Channel_Text_Message_Flags</tp:type>; clients which
+ understand this interface SHOULD ignore the SendError signal in
+ favour of listening for delivery reports, as mentioned in the
+ introduction.</p>
+
+ <p>The result of attempting to send delivery reports using
+ <tp:member-ref>SendMessage</tp:member-ref> is currently
+ undefined.</p>
+
+ <h4>Example delivery reports</h4>
+
+ <dl>
+ <dt>A minimal delivery report indicating permanent failure of the
+ sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
+ reason</dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]</pre></dd>
+
+ <dt>A delivery report where the failed message is echoed back to the
+ sender rather than being referenced by ID, and the failure reason
+ is that this protocol cannot send messages to offline contacts
+ such as the contact with handle 123</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Temporarily_Failed,
+'delivery-error': Channel_Text_Send_Error_Offline,
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+
+# no body
+]</pre></dd>
+
+ <dt>A maximally complex delivery report: the server reports a
+ bilingual human-readable failure message because the user sent
+ a message "Hello, world!" with token
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
+ with handle 123, but that handle represents a contact who does not
+ actually exist</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+},
+{ # message from server (alternative in English)
+'alternative': '404',
+'content-type': 'text/plain',
+'lang': 'en',
+'content': 'I have no contact with that name',
+},
+{ # message from server (alternative in German)
+'alternative': '404'.
+'content-type': 'text/plain',
+'lang': 'de',
+'content', 'Ich habe keinen Kontakt mit diesem Namen',
+}
+]</pre></dd>
+
+ <dt>A minimal delivery report indicating successful delivery
+ of the sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Delivered,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]</pre></dd>
+
+ </dl>
+
+ </div>
+ </tp:docstring>
+
+ <tp:member name="Key" type="s">
+ <tp:docstring>
+ A key, which SHOULD be one of the well-known keys specified by
+ <tp:type>Message_Header_Key</tp:type>,
+ <tp:type>Message_Body_Key</tp:type> or
+ <tp:type>Delivery_Report_Header_Key</tp:type> if possible.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Value" type="v">
+ <tp:docstring>
+ The value corresponding to the given key, which SHOULD be one of the
+ specified types for well-known keys.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:simple-type type="s" name="Message_Header_Key">
+ <tp:added version="0.19.8"/>
+ <tp:changed version="0.21.5">
+ Removed <tt>protocol-token</tt>—which had never been implemented—and
+ respecified <tt>message-token</tt> not to have unimplementable
+ uniqueness guarantees.
+ </tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a
+ message, which contains metadata about the message as a whole, along
+ with the corresponding value types. Some keys make sense for both
+ incoming and outgoing messages, while others are only meaningful for
+ one or the other.</p>
+
+ <dl>
+ <dt>message-token (s -
+ <tp:type>Protocol_Message_Token</tp:type>)
+ </dt>
+ <dd>
+ <p>An opaque identifier for the message, as used by the
+ underlying protocol. For outgoing messages, this SHOULD be
+ globally unique; for incoming messages, this is <em>not</em>
+ guaranteed to uniquely identify a message, <em>even within the
+ scope of a single channel or contact</em>; the only guarantee
+ made is that two messages with different <tt>message-token</tt>
+ headers are different messages.</p>
+
+ <p>Clients wishing to determine whether a new message with the
+ <tt>scrollback</tt> header matches a previously-logged message
+ with the same <tt>message-token</tt> SHOULD compare the
+ message's sender, contents, <tt>message-sent</tt> or
+ <tt>message-received</tt> timestamp, etc. Note that, in XMPP,
+ the server only supplies a timestamp for scrollback messages,
+ not for messages received while you are in a room; thus,
+ non-scrollback messages will lack a <tt>message-sent</tt>
+ timestamp.</p>
+
+ <tp:rationale>
+ <p>In practice, most protocols do not provide globally-unique
+ identifiers for messages. Connection managers, being
+ stateless, do not have the necessary information — namely, IM
+ logs — to generate reliable unique tokens for messages.</p>
+
+ <p>For instance, some XMPP clients (including Gabble) stamp
+ messages they send with unique identifiers, but others number
+ outgoing messages in a conversation from 1 upwards.</p>
+ </tp:rationale>
+ </dd>
+
+ <dt>message-sent (x - <tp:type>Unix_Timestamp64</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; SHOULD always be present
+ on outgoing messages.</dd>
+
+ <dt>message-received (x - <tp:type>Unix_Timestamp64</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-sender-id (s)</dt>
+ <dd>The identifier of the contact who sent the message,
+ i.e. the result of calling <tp:dbus-ref
+ namespace="ofdT.Connection">InspectHandles</tp:dbus-ref>
+ on <code>message-sender</code>. If omitted, clients MUST
+ fall back to looking at <code>message-sender</code>.</dd>
+
+ <dt>sender-nickname (s)</dt>
+ <dd>The nickname chosen by the sender of the message, which can be
+ different for each message in a conversation.</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. MAY
+ be omitted for normal chat messages.</dd>
+
+ <dt>supersedes (s – <tp:type>Protocol_Message_Token</tp:type>)</dt>
+ <dd>If present, this message supersedes a previous message,
+ identified by its <tt>protocol-token</tt> or
+ <tt>message-token</tt> header. The user interface MAY, for
+ example, choose to replace the superseded message with this
+ message, or grey out the superseded message.
+
+ <tp:rationale>Skype, for example, allows the user to amend
+ messages they have already sent (to correct typos,
+ etc.).</tp:rationale>
+ </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>
+
+ <dt>scrollback (b)</dt>
+ <dd>If present and true, the incoming message was part of a
+ replay of message history (this matches the Scrollback flag in
+ <tp:type>Channel_Text_Message_Flags</tp:type>). This flag
+ does not make sense on outgoing messages and SHOULD NOT
+ appear there.</dd>
+
+ <dt>rescued (b)</dt>
+ <dd>If present and true, the incoming message has been seen in
+ a previous channel during the lifetime of the Connection,
+ but had not been acknowledged when that channel closed, causing
+ an identical channel (in which the message now appears) to open.
+ This matches the Rescued flag in
+ <tp:type>Channel_Text_Message_Flags</tp:type>; it
+ does not make sense on outgoing messages, and SHOULD NOT
+ appear there.</dd>
+ </dl>
+
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type type="s" name="Message_Body_Key">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the second and subsequent
+ <tp:type>Message_Part</tp:type>s of a message, which contain the
+ message content, along with the corresponding value types.</p>
+
+ <dl>
+ <dt>identifier (s —
+ <tp:type>Protocol_Content_Identifier</tp:type>)</dt>
+ <dd>An opaque identifier for this part.
+ Parts of a message MAY reference other parts by treating
+ this identifier as if it were a MIME Content-ID and using
+ 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>content-type (s)</dt>
+ <dd>
+ <p>The MIME type of this part. See the documentation
+ for <tp:member-ref>MessageReceived</tp:member-ref> and
+ <tp:member-ref>MessageSent</tp:member-ref> for notes on the
+ special status of "text/plain" parts.</p>
+
+ <p>Connection managers MUST NOT signal parts without a
+ 'content-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 'content-type' key, which
+ are reserved for future expansion.</p>
+
+ <p>When sending messages, clients SHOULD normalize the
+ content-type to lower case, but connection managers SHOULD NOT
+ rely on this. When signalling sent or received messages,
+ connection managers MUST normalize the content-type to lower
+ case.</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>thumbnail (b)</dt>
+ <dd>
+ <p>This part is a thumbnail. To represent an image together with
+ its thumbnail in a single message, there should be one part for
+ the full image followed by a part for the thumbnail (following
+ the “more complete versions first” requirement), with the same
+ 'alternative' value. For example:</p>
+
+ <pre>
+[ ... ,
+ { 'alternative': 'catphoto',
+ 'content-type': 'image/jpeg',
+ 'size': 150000,
+ 'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+ },
+ { 'alternative': 'catphoto',
+ 'content-type': 'image/jpeg'
+ 'size': 1024,
+ 'thumbnail': True,
+ 'content': [0xFF, 0xD8, ... 0xFF 0xD9],
+ },
+ ...
+]</pre>
+ </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 must be retrieved on demand (like MIME's
+ <tt>message/external-body</tt>) by a mechanism to be defined later.
+
+ <tp:rationale>The mechanism was meant to be
+ <tp:member-ref>GetPendingMessageContent</tp:member-ref>, but
+ that didn't work out. It's worth leaving the header in in
+ preparation for a future mechanism.
+ </tp:rationale>
+ </dd>
+
+ <dt>truncated (b)</dt>
+ <dd>The content available via the 'content' key 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>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type type="s" name="Delivery_Report_Header_Key">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a
+ delivery report, along with the corresponding value types. Some of
+ these are special-cases of headers defined by
+ <tp:type>Message_Header_Key</tp:type>.</p>
+
+ <dl>
+ <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>, as
+ defined by <tp:type>Message_Header_Key</tp:type>)</dt>
+ <dd>MUST be the intended recipient of the original message, if
+ available (zero or omitted if the intended recipient is
+ unavailable or is not a contact, e.g. a chatroom), even if the
+ delivery report actually came from an intermediate server.</dd>
+
+ <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>,
+ as defined by <tp:type>Message_Header_Key</tp:type>)</dt>
+ <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
+
+ <dt>delivery-status (u - <tp:type>Delivery_Status</tp:type>)</dt>
+ <dd>The status of the message. All delivery reports MUST contain
+ this key in the first Message_Part.</dd>
+
+ <dt>delivery-token (s - <tp:type>Protocol_Message_Token</tp:type>)</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. 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 -
+ <tp:type>Channel_Text_Send_Error</tp:type>)</dt>
+ <dd>
+ The reason for the failure. MUST be omitted if this was a
+ successful delivery; SHOULD be omitted if it would be
+ Channel_Text_Send_Error_Unknown.
+ </dd>
+
+ <dt>delivery-dbus-error (s -
+ <tp:type>DBus_Error_Name</tp:type>)</dt>
+ <dd>
+ The reason for the failure, specified as a (possibly
+ implementation-specific) D-Bus error. MUST be omitted if this was
+ a successful delivery. If set, the 'delivery-error' key SHOULD be
+ set to the closest available value.
+ </dd>
+
+ <dt>delivery-error-message (s)</dt>
+ <dd>
+ Debugging information on why the message could not be delivered.
+ MUST be omitted if this was a successful delivery; MAY always be
+ omitted.
+ </dd>
+
+ <dt>delivery-echo (aa{sv} - <tp:type>Message_Part[]</tp:type>)</dt>
+ <dd>
+ <p>The message content, as defined by the Messages interface.
+ Omitted if no content is available. Content MAY have been
+ 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>
+ </dd>
+
+ </dl>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type type="u" name="Message_Part_Index"
+ array-name="Message_Part_Index_List">
+ <tp:deprecated version="0.21.5">
+ This type is only used by
+ <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is
+ unimplemented and deprecated.
+ </tp:deprecated>
+ <tp:added version="0.17.17"/>
+ <tp:docstring>
+ The index of a message part within a message.
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Message_Part_Content_Map">
+ <tp:added version="0.17.17"/>
+ <tp:deprecated version="0.21.5">
+ This structure is only used by
+ <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is
+ unimplemented and deprecated.
+ </tp:deprecated>
+ <tp:docstring>
+ A mapping from message part indexes to their content, as returned by
+ <tp:member-ref>GetPendingMessageContent</tp:member-ref>.
+ </tp:docstring>
+
+ <tp:member type="u" tp:type="Message_Part_Index" name="Part">
+ <tp:docstring>
+ Indexes into the array of <tp:type>Message_Part</tp:type>s that
+ represents a message. The "headers" part (which is not a valid
+ argument to GetPendingMessageContent) is considered to be part 0,
+ so the valid part numbers start at 1 (for the second message part).
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="v" name="Content">
+ <tp:docstring>
+ The message part's content. The variant MUST contain either 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.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:simple-type type="s" name="Protocol_Message_Token"
+ array-name="Protocol_Message_Token_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An opaque token used to identify messages in the underlying.
+ protocol. As a special case, the empty string indicates that there
+ is no particular identification for a message.</p>
+
+ <p>CM implementations SHOULD use an identifier expected to be unique,
+ such as a UUID, for outgoing messages (if possible).</p>
+
+ <p>Some protocols can only track a limited number of messages
+ in a small message-ID space (SMS messages are identified by a single
+ byte), and some implementations send non-unique identifiers (some
+ XMPP clients use very simple message IDs, such as an incrementing
+ integer that resets to 1 at the beginning of each connection). As a
+ result, clients MUST NOT assume that protocol tokens will not be
+ re-used.</p>
+
+ <p>In particular, clients SHOULD use a 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:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Protocol_Content_Identifier" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A protocol-specific identifier for a blob of content, as used for
+ the <tt>identifier</tt> key in a <tp:type>Message_Part</tp:type>. The
+ same identifier MAY be re-used if the same content, byte-for-byte,
+ appears as a part of several messages.</p>
+
+ <tp:rationale>
+ <p>On XMPP, these identifiers might be Content-IDs for custom
+ smileys implemented using <a
+ href="http://xmpp.org/extensions/xep-0231.html">XEP-0232 Bits of
+ Binary</a>; the same smiley might well appear in multiple
+ messages.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <method name="SendMessage" tp:name-for-bindings="Send_Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Submit a message to the server for sending.
+ If this method returns successfully, the message has been submitted
+ to the server and the <tp:member-ref>MessageSent</tp:member-ref>
+ signal is emitted. A corresponding
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
+ signal on the Text interface MUST also be emitted.</p>
+
+ <p>This method MUST return before the MessageSent signal is
+ emitted.</p>
+
+ <tp:rationale>
+ <p>This means that the process sending the message is the first
+ to see the <tp:type>Protocol_Message_Token</tp:type>, and can
+ relate the message to the corresponding
+ <tp:member-ref>MessageSent</tp:member-ref> signal by comparing
+ message tokens (if supported by the protocol).</p>
+ </tp:rationale>
+
+ <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>
+
+ <p>If this method succeeds, message submission to the server has
+ succeeded, but the message has not necessarily reached its intended
+ recipient. If a delivery failure is detected later, this is
+ signalled by receiving a message whose <code>message-type</code>
+ header maps to
+ <tp:type>Channel_Text_Message_Type</tp:type>_Delivery_Report.
+ Similarly, if delivery is detected to have been successful
+ (which is not possible in all protocols), a successful delivery
+ report will be signalled.</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.
+ This MUST NOT include the following headers, or any others that
+ do not make sense for a client to specify:
+ <code>message-sender</code>, <code>message-sender-id</code>,
+ <code>message-sent</code>, <code>message-received</code>,
+ <code>pending-message-id</code>.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Flags" type="u"
+ tp:type="Message_Sending_Flags">
+ <tp:docstring>
+ Flags affecting how the message is sent. The channel MAY ignore some
+ or all flags, depending on
+ <tp:member-ref>DeliveryReportingSupport</tp:member-ref>; the flags
+ that were handled by the CM are provided in
+ <tp:member-ref>MessageSent</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="s" tp:type="Protocol_Message_Token"
+ name="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. Some indication of which
+ flags are supported is provided by the
+ <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property.
+ </tp:docstring>
+
+ <tp:flag suffix="Report_Delivery" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Provide a successful delivery report if possible, even if this is
+ not the default for this protocol. Ignored if delivery reports are
+ not possible on this protocol.</p>
+
+ <tp:rationale>
+ <p>In some protocols, like XMPP, it is not conventional to request
+ or send positive delivery notifications.</p>
+ </tp:rationale>
+
+ <p>Delivery failure reports SHOULD always be sent, but if this flag
+ is present, the connection manager MAY also try harder to obtain
+ failed delivery reports or allow them to be matched to outgoing
+ messages.</p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Report_Read" value="2">
+ <tp:added version="0.19.9"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Provide a delivery report when the message is read by the
+ recipient, even if this is not the default for this protocol.
+ Ignored if read reports are not possible on this protocol.</p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Report_Deleted" value="4">
+ <tp:added version="0.19.9"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Provide a delivery report when the message is deleted by the
+ recipient, even if this is not the default for this protocol.
+ Ignored if such reports are not possible on this protocol.</p>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <signal name="MessageSent" tp:name-for-bindings="Message_Sent">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that a message has been submitted for sending. This
+ MUST be emitted exactly once per emission of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>
+ signal on the Text interface, for backwards-compatibility; clients
+ SHOULD ignore the latter if this interface is present, as mentioned
+ in the introduction.</p>
+
+ <p>This SHOULD be emitted as soon as the CM determines it's
+ theoretically possible to send the message (e.g. the parameters are
+ supported and correct).</p>
+
+ <tp:rationale>
+ <p>This signal allows a process that is not the caller of
+ SendMessage to log sent messages.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The message content (see <tp:type>Message_Part</tp:type> for full
+ details). If the message that was passed to
+ <tp:member-ref>SendMessage</tp:member-ref> has a formatted text
+ part that the connection manager recognises, but no
+ <tt>text/plain</tt> alternative, the CM MUST use the formatted text
+ part to generate a <tt>text/plain</tt> alternative which is also
+ included in this signal argument.</p>
+
+ <p>The connection manager SHOULD include the
+ <code>message-sender</code>, <code>message-sender-id</code> and
+ <code>message-sent</code> headers in the representation of the
+ message that is signalled here. If the channel has
+ channel-specific handles, the <code>message-sender</code> and
+ <code>message-sender-id</code> SHOULD reflect the sender that
+ other contacts will see.</p>
+
+ <p>If the connection manager can predict that the message will be
+ altered during transmission, this argument SHOULD reflect what
+ other contacts will receive, rather than being a copy of the
+ argument to SendMessage (if the message is truncated,
+ formatting or alternatives are dropped, etc., then the edited
+ version SHOULD appear in this signal).</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Flags" type="u" tp:type="Message_Sending_Flags">
+ <tp:docstring>
+ <p>Flags affecting how the message was sent. The flags might be a
+ subset of those passed to SendMessage if the caller requested
+ unsupported flags.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message_Token" type="s" tp:type="Protocol_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:name-for-bindings="Pending_Messages">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of incoming messages that have neither been acknowledged nor
+ rejected. This list is a more detailed version of the one returned
+ by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.ListPendingMessages</tp:dbus-ref>,
+ and contains the same messages, uniquely identified by the same
+ pending message IDs. Its items can be removed using
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>MessageReceived</tp:member-ref> and
+ <tp:member-ref>PendingMessagesRemoved</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="PendingMessagesRemoved"
+ tp:name-for-bindings="Pending_Messages_Removed">
+ <tp:docstring>
+ The messages with the given IDs have been removed from the
+ <tp:member-ref>PendingMessages</tp:member-ref> 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:name-for-bindings="Get_Pending_Message_Content">
+ <tp:deprecated version='0.21.5'
+ xmlns="http://www.w3.org/1999/xhtml">
+ This method has never been implemented, and in any case would have been
+ impossible to use correctly when multiple clients (such as a logger and
+ the handler) are interested in a text channel. See <a
+ href='https://bugs.freedesktop.org/show_bug.cgi?id=26417'>freedesktop.org
+ bug #26417</a> for more details.
+ </tp:deprecated>
+ <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:type="Message_Part_Index[]">
+ <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:type="Message_Part_Content_Map">
+ <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
+ 'content-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:name-for-bindings="Message_Received">
+ <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
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
+ signal on the Text interface, for backwards-compatibility; clients
+ SHOULD ignore the latter in favour of this signal if this interface is
+ present, as mentioned in the introduction.
+ </tp:docstring>
+
+ <arg type="aa{sv}" tp:type="Message_Part[]" name="Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The message content, including any attachments or alternatives. If
+ the incoming message contains formatted text without a plain text
+ alternative, the connection manager MUST generate a
+ <tt>text/plain</tt> alternative from the formatted text, and
+ include it in this message (both here, and in the
+ <tp:member-ref>PendingMessages</tp:member-ref> property).</p>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Delivery_Status" value-prefix="Delivery_Status"
+ plural="Delivery_Statuses" 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
+ <tp:type>Delivery_Report_Header_Key</tp:type>s.</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:enumvalue suffix="Accepted" value="4">
+ <tp:docstring>
+ An intermediate server has accepted the message but the message
+ has not been yet delivered to the ultimate recipient. The
+ connection manager might send a Failed report or Delivered report
+ later.
+
+ <tp:rationale>
+ Similar to "202 Accepted" success code in SIP; analogous to
+ 251 and 252 responses in SMTP.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Read" value="5">
+ <tp:added version="0.19.9"/>
+ <tp:docstring>
+ The message has been read by the intended recipient.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Deleted" value="6">
+ <tp:added version="0.19.9"/>
+ <tp:docstring>
+ The message has been deleted by the intended recipient. This MAY be
+ signalled on its own if the message is deleted without being read, or
+ after <code>Read</code> if the message was read before being deleted.
+ </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, as found on the
+ <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. 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. Note that CMs may always provide more
+ reports than are requested in the
+ <tp:type>Message_Sending_Flags</tp:type> passed to
+ <tp:member-ref>SendMessage</tp:member-ref>.
+
+ <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 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: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:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Receive_Read" value="4">
+ <tp:added version="0.19.9"/>
+ <tp:docstring>
+ Clients MAY expect to receive <tp:type>Delivery_Status</tp:type>
+ <code>Read</code> reports if Message_Sending_Flag_Report_Read
+ is specified when sending.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Receive_Deleted" value="8">
+ <tp:added version="0.19.9"/>
+ <tp:docstring>
+ Clients MAY expect to receive <tp:type>Delivery_Status</tp:type>
+ <code>Deleted</code> reports if Message_Sending_Flag_Report_Deleted
+ is specified when sending.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="DeliveryReportingSupport" access="read"
+ tp:type="Delivery_Reporting_Support_Flags" type="u"
+ tp:name-for-bindings="Delivery_Reporting_Support"
+ tp:immutable="yes">
+ <tp:docstring>
+ A bitfield indicating features supported by this channel.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml
new file mode 100644
index 0000000..4e201dd
--- /dev/null
+++ b/spec/Channel_Interface_Password.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>
+Copyright © 2005-2009 Collabora Limited
+Copyright © 2005-2009 Nokia Corporation
+Copyright © 2006 INdT
+ </tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Password">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:flags name="Channel_Password_Flags" value-prefix="Channel_Password_Flag" type="u">
+ <tp:flag suffix="Provide" value="8">
+ <tp:docstring>
+ The <tp:member-ref>ProvidePassword</tp:member-ref> method must be
+ called now for the user to join the channel
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+ <method name="GetPasswordFlags" tp:name-for-bindings="Get_Password_Flags">
+ <arg direction="out" type="u" tp:type="Channel_Password_Flags"
+ name="Password_Flags">
+ <tp:docstring>
+ An integer with the logical OR of all the flags set
+ (values of ChannelPasswordFlags)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the bitwise-OR of the flags relevant to the password on this
+ channel. The user interface can use this to present information about
+ which operations are currently valid.
+ </tp:docstring>
+ <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="PasswordFlagsChanged"
+ tp:name-for-bindings="Password_Flags_Changed">
+ <arg name="Added" type="u" tp:type="Channel_Password_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been set
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="u" tp:type="Channel_Password_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been cleared
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the flags as returned by
+ <tp:member-ref>GetPasswordFlags</tp:member-ref> are changed.
+ The user interface should be updated as appropriate.
+ </tp:docstring>
+ </signal>
+ <method name="ProvidePassword" tp:name-for-bindings="Provide_Password">
+ <arg direction="in" name="Password" type="s">
+ <tp:docstring>
+ The password
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="b" name="Correct">
+ <tp:docstring>
+ A boolean indicating whether or not the password was correct
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Provide the password so that the channel can be joined. Must be
+ called with the correct password in order for channel joining to
+ proceed if the 'provide' password flag is set.
+ </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.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for channels that may have a password set that users need
+ to provide before being able to join, or may be able to view or change
+ once they have joined the channel.</p>
+
+ <p>The <tp:member-ref>GetPasswordFlags</tp:member-ref> method and the
+ associated <tp:member-ref>PasswordFlagsChanged</tp:member-ref>
+ signal indicate whether the channel has a password, whether the user
+ must now provide it to join, and whether it can be viewed or changed
+ by the user.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Room.xml b/spec/Channel_Interface_Room.xml
new file mode 100644
index 0000000..ffdf4a9
--- /dev/null
+++ b/spec/Channel_Interface_Room.xml
@@ -0,0 +1,373 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Room"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Room.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.19.11">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Different IM protocols use a variety of ways to name chat rooms. The
+ simplest example is perhaps IRC, where chat rooms have short,
+ persistent, human-readable string names, and are generally global
+ across the network. Skype chat rooms have persistent string names, so
+ you can leave and re-join a room, but these names are opaque unique
+ identifiers. MSN chat rooms are unnamed, and you can only join one by
+ being invited. And XMPP wins the coveted “most complicated chat rooms”
+ prize: chat rooms may be hosted by different servers with different DNS
+ names; normally they have human-readable names, except that all MUCs on
+ Google Talk's conference server have UUIDs as names, and <a
+ href="http://xmpp.org/extensions/xep-0045.html#createroom-unique"><acronym
+ title="XMPP Extension Protocol">XEP</acronym>-0045 §10.1.4
+ <q>Requesting a Unique Room Name</q></a> defines a protocol for
+ requesting a unique, opaque room name on the server.</p>
+
+ <p>This interface intends to support and differentiate these mechanisms
+ more clearly than the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ properties can alone. It initially contains a pair of properties used
+ to represent the human-readable parts of a
+ <tp:type>Room_Handle</tp:type>'s identifier, if any. The above examples
+ for different protocols are represented as follows:</p>
+
+ <ul>
+ <li>The IRC channel <tt>#telepathy</tt> on Freenode is represented by a
+ channel with properties
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>Room</code>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ = <code>"#telepathy"</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>"#telepathy"</code>,
+ <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+ that the room has a human-readable identifier, and is not confined to
+ a particular server on the network.
+
+ <tp:rationale>
+ Actually, IRC supports creating “local” channels specific to the
+ server they are created on. These channels have identifiers
+ starting with <tt>&amp;</tt> rather than <tt>#</tt>. These could be
+ represented by setting <tp:member-ref>Server</tp:member-ref>
+ appropriately.
+ </tp:rationale>
+ </li>
+
+ <li>A Skype group chat with opaque identifier <tt>0xdeadbeef</tt> has
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>Room</code>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ = <code>"0xdeadbeef"</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+ <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+ that the room has an identifier but no human-readable name.
+ </li>
+
+ <li>An MSN group chat has
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>None</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+ <tp:member-ref>Server</tp:member-ref> = <code>""</code>, indicating
+ that the room has neither an identifier (so it cannot be re-joined
+ later) nor a human-readable name.
+ </li>
+
+ <li>A standard Jabber multi-user chat
+ <tt>jdev@conference.jabber.org</tt> has
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>Room</code>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ = <code>"jdev@conference.jabber.org"</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>"jdev"</code>,
+ <tp:member-ref>Server</tp:member-ref> = <code>"conference.jabber.org"</code>.
+ </li>
+
+ <li>A Google Talk private MUC <tt>private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com</tt> has
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>Room</code>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ = <code>"private-chat-11111x1x-11xx-111x-1111-111x1xx11x11@groupchat.google.com"</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+ <tp:member-ref>Server</tp:member-ref> =
+ <code>"groupchat.google.com"</code>, indicating that the room has a
+ persistent identifier, no human-readable name, and is hosted by a
+ particular server.
+ </li>
+
+ <li>Similarly, a XEP-0045 §10.1.4 uniquely-named room
+ <tt>lrcgsnthzvwm@conference.jabber.org</tt> has
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = <code>Room</code>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ = <code>"lrcgsnthzvwm@conference.jabber.org"</code>,
+ <tp:member-ref>RoomID</tp:member-ref> = <code>""</code>,
+ <tp:member-ref>Server</tp:member-ref> =
+ <code>"conference.jabber.org"</code>, indicating that the room has a
+ persistent identifier, no human-readable name, and is hosted by a
+ particular server.
+ </li>
+ </ul>
+
+ <h4>Requestable channel classes</h4>
+
+ <p>If the connection supports joining text chat rooms by unique
+ identifier, like Skype, it should advertise a
+ <tp:type>Requestable_Channel_Class</tp:type> matching:</p>
+
+ <blockquote>
+ <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+ >Text</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref>: Room,
+ },
+ Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetID</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandle</tp:dbus-ref>,
+ ]
+)</pre></blockquote>
+
+ <p>Channel requests must specify either <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetID</tp:dbus-ref> or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandle</tp:dbus-ref>.</p>
+
+ <p>If, like IRC, the room identifiers are also human-readable, the
+ RCCs should also include RoomID in <var>Allowed_Properties</var>:</p>
+
+ <blockquote>
+ <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+ >Text</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref>: Room,
+ },
+ Allowed = [ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetID</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandle</tp:dbus-ref>,
+ ...<tp:member-ref>RoomID</tp:member-ref>
+ ]
+),
+
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+ >Text</tp:dbus-ref>
+ },
+ Allowed = [ ...<tp:member-ref>RoomID</tp:member-ref>,
+ ]
+)</pre></blockquote>
+
+ <p>Requests may specify the RoomID in place of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ . Note how <tp:member-ref>RoomID</tp:member-ref> appears
+ in <var>Allowed_Properties</var> of a different RCC because
+ when <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> is omitted (or is None), both
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandle</tp:dbus-ref> and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetID</tp:dbus-ref> must also be omitted.
+ <tp:member-ref>RoomID</tp:member-ref> is allowed in conjuction
+ with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ in some situations, as explained below in the <em>Requesting room
+ channels</em> section.
+ </p>
+
+ <p>If rooms may be on different servers, <tp:member-ref>Server</tp:member-ref>
+ should also be included in the allowed properties, but
+ CMs MUST use a reasonable default
+ <tp:member-ref>Server</tp:member-ref> if not explicitly
+ specified in a channel request. The CM's default server MAY
+ be configurable by a connection parameter specified on a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
+ >RequestConnection</tp:dbus-ref> call, similarly to how the
+ fallback conference server is specified on jabber connections in
+ gabble.</p>
+
+ <p>If the protocol supports unnamed rooms, <tp:member-ref>RoomID</tp:member-ref>
+ should be fixed to the empty string, and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ should be None:</p>
+
+ <blockquote>
+ <pre>
+( Fixed = { ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type"
+ >Text</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref>: None,
+ ...<tp:member-ref>RoomID</tp:member-ref>: "",
+ },
+ Allowed = [ ]
+)</pre></blockquote>
+
+ <h4>Requesting room channels</h4>
+
+ <p>When explicitly joining a room, the CM cannot know whether the room
+ ID is unique or not. As a result, if this is the case, adding an
+ empty string <tp:member-ref>RoomID</tp:member-ref> into the channel
+ request will ensure the CM knows. For example:</p>
+
+ <blockquote>
+ <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "qwerasdfzxcv@conference.jabber.org",
+ ...<tp:member-ref>RoomID</tp:member-ref>: ""
+}</pre></blockquote>
+
+ <p>If <tp:member-ref>RoomID</tp:member-ref> features in
+ <var>Allowed_Properties</var> then the only value allowed in conjunction
+ with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ is the empty string. Requests with conflicting
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>
+ and <tp:member-ref>RoomID</tp:member-ref> properties
+ will fail with InvalidArgument.</p>
+
+ <p>To create a XEP-0045 §10.1.4 uniquely-named room channel
+ on the conference.jabber.org server, then the following channel
+ request should be made:</p>
+
+ <blockquote>
+ <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+ ...<tp:member-ref>RoomID</tp:member-ref>: ""
+ ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
+}</pre>
+ </blockquote>
+
+ <p>If everything is successful, then when the channel request is
+ satisfied, a new channel will appear with the following properties:</p>
+
+ <blockquote>
+ <pre>
+{ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Room,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: "kajsdhkajshdfjkshdfjkhs@conference.jabber.org",
+ ...<tp:member-ref>RoomID</tp:member-ref>: ""
+ ...<tp:member-ref>Server</tp:member-ref>: "conference.jabber.org"
+}</pre>
+ </blockquote>
+
+ <p>The CM will have received the unique room name (kajsdhkajshdfjkshdfjkhs)
+ and then created a room with such a name on the said server. The empty
+ <tp:member-ref>RoomID</tp:member-ref> property shows that the room name
+ is not human-readable.</p>
+
+ </tp:docstring>
+
+ <property name="RoomID" tp:name-for-bindings="Room_ID" type="s"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The human-readable identifier of a chat room. Note that if
+ non-empty, this property (and perhaps also
+ <tp:member-ref>Server</tp:member-ref>) should be sufficient in
+ a channel request to join the room. XMPP MUCs have a room name
+ concept which is more like a topic, except more
+ persistent. This D-Bus property is <strong>not</strong> this
+ XMPP room name, but the bit before the @ in the room jid.</p>
+
+ <p>This property cannot change during the lifetime of the channel. It
+ should appear in the <var>Allowed_Properties</var> of a
+ <tp:type>Requestable_Channel_Class</tp:type> for the connection if
+ rooms on this connection have human-readable names, and can be joined
+ by name.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Server" tp:name-for-bindings="Server" type="s"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For protocols with a concept of chatrooms on multiple servers with
+ different DNS names (like XMPP), the DNS name of the server hosting
+ this channel (for example, <tt>"conference.jabber.org"</tt> or
+ <tt>"groupchat.google.com"</tt>). For other protocols, the empty
+ string.</p>
+
+ <p>This property cannot change during the lifetime of the channel. It
+ should appear in the <var>Allowed_Properties</var> of a
+ <tp:type>Requestable_Channel_Class</tp:type> for the connection if
+ and only if non-empty values are supported.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:struct name="Room_Subject">
+ <tp:docstring>
+ A struct representing the subject of a room channel.
+ </tp:docstring>
+ <tp:member type="s" name="Subject">
+ <tp:docstring>
+ A human-readable description of the current subject of
+ conversation in the channel, similar to /topic in IRC.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Actor">
+ <tp:docstring>
+ A normalized contact ID representing who last modified the
+ subject, or the empty string if it is not known.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="x" tp:type="Unix_Timestamp64" name="Timestamp">
+ <tp:docstring>
+ A unix timestamp indicating when the subject was last modified.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="Subject" tp:name-for-bindings="Subject"
+ type="(ssx)" tp:type="Room_Subject" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The subject on the room such as the topic in an IRC channel,
+ or the room name in XMPP MUCs. In protocols which do not support
+ subjects (like MSN), this property should be ("", "", 0).</p>
+
+ <tp:rationale>This property replaces the subject, subject-contact, and
+ subject-timestamp Telepathy properties of Text channels, as Telepathy
+ properties are soon to be deprecated completely.</tp:rationale>
+
+ <p>This property may change during the lifetime of the channel and
+ MUST not be included in a channel request.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_SASL_Authentication.xml b/spec/Channel_Interface_SASL_Authentication.xml
new file mode 100644
index 0000000..38568b1
--- /dev/null
+++ b/spec/Channel_Interface_SASL_Authentication.xml
@@ -0,0 +1,704 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_SASL_Authentication"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2010 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
+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.SASLAuthentication">
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel interface for SASL authentication,
+ as defined by
+ <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>.
+ When this interface appears on a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channel, it represents authentication with the server. In future,
+ it could also be used to authenticate with secondary services,
+ or even to authenticate end-to-end connections with contacts. As a result,
+ this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type"
+ >ServerAuthentication</tp:dbus-ref> to allow for a potential future
+ Channel.Type.PeerAuthentication interface.</p>
+
+ <p>In any protocol that requires a password, the connection manager can
+ use this channel to let a user interface carry out a simple SASL-like
+ handshake with it, as a way to get the user's credentials
+ interactively. This can be used to connect to protocols that may
+ require a password, without requiring that the password is saved in
+ the <tp:dbus-ref
+ namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p>
+
+ <p>In some protocols, such as XMPP, authentication with the server
+ is also carried out using SASL. In these protocols, a channel with this
+ interface can provide a simple 1:1 mapping of the SASL negotiations
+ taking place in the protocol, allowing more advanced clients to
+ perform authentication via SASL mechanisms not known to the
+ connection manager.</p>
+
+ <tp:rationale>
+ <p>By providing SASL directly when the protocol supports it, we can
+ use mechanisms like Kerberos or Google's <code>X-GOOGLE-TOKEN</code>
+ without specific support in the connection manager.</p>
+ </tp:rationale>
+
+ <p>For channels managed by a
+ <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>,
+ only the channel's <tp:dbus-ref
+ namespace="ofdT.Client">Handler</tp:dbus-ref> may call the
+ methods on this interface. Other clients MAY observe the
+ authentication process by watching its signals and properties.</p>
+
+ <tp:rationale>
+ <p>There can only be one Handler, which is a good fit for SASL's
+ 1-1 conversation between a client and a server.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:simple-type name="SASL_Mechanism" type="s"
+ array-name="SASL_Mechanism_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A SASL mechanism, as defined by
+ <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>
+ and registered in
+ <a href="http://www.iana.org/assignments/sasl-mechanisms">the
+ IANA registry of SASL mechanisms</a>, or an unregistered
+ SASL mechanism such as <code>X-GOOGLE-TOKEN</code> used in the
+ same contexts.</p>
+
+ <p>As a special case, pseudo-mechanisms starting with
+ <code>X-TELEPATHY-</code> are defined by this specification.
+ Use of these pseudo-mechanisms indicates that the user's credentials
+ are to be passed to the connection manager, which will then use
+ them for authentication with the service, either by implementing
+ the client side of some SASL mechanisms itself or by using a
+ non-SASL protocol. The only such pseudo-mechanism currently
+ defined is <code>X-TELEPATHY-PASSWORD</code>.</p>
+
+ <p>The <code>X-TELEPATHY-PASSWORD</code> mechanism is extremely
+ simple:</p>
+
+ <ul>
+ <li>The client MUST call
+ <tp:member-ref>StartMechanismWithData</tp:member-ref>, with
+ Initial_Data set to the password encoded in UTF-8.
+ For simplicity, calling <tp:member-ref>StartMechanism</tp:member-ref>
+ followed by calling <tp:member-ref>Respond</tp:member-ref> is not
+ allowed in this mechanism.</li>
+
+ <li>The connection manager uses the password, together with
+ authentication details from the Connection parameters, to
+ authenticate itself to the server.</li>
+
+ <li>When the connection manager finishes its attempt to authenticate
+ to the server, the channel's state changes to
+ either SASL_Status_Server_Succeeded or
+ SASL_Status_Server_Failed as appropriate.</li>
+ </ul>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="AvailableMechanisms"
+ tp:name-for-bindings="Available_Mechanisms"
+ type="as" tp:type="SASL_Mechanism[]"
+ access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The SASL mechanisms as offered by the server, plus any
+ pseudo-SASL mechanisms supported by the connection manager for
+ credentials transfer. For instance, in a protocol that
+ natively uses SASL (like XMPP), this might be
+ <code>[ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5",
+ "SCRAM-SHA-1" ]</code>.</p>
+
+ <p>To make it possible to implement a very simple password-querying
+ user interface without knowledge of any particular SASL mechanism,
+ implementations of this interface MUST implement the
+ pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>, unless none
+ of the available mechanisms use a password at all.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="HasInitialData" tp:name-for-bindings="Has_Initial_Data"
+ type="b" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, <tp:member-ref>StartMechanismWithData</tp:member-ref>
+ can be expected to work for SASL mechanisms not starting with
+ <code>X-TELEPATHY-</code> (this is the case in most, but not all,
+ protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref>
+ must be used instead.</p>
+
+ <p>This property does not affect the <code>X-TELEPATHY-</code>
+ pseudo-mechanisms such as <code>X-TELEPATHY-PASSWORD</code>,
+ which can use
+ <tp:member-ref>StartMechanismWithData</tp:member-ref> regardless
+ of the value of this property.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CanTryAgain" tp:name-for-bindings="Can_Try_Again"
+ type="b" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, <tp:member-ref>StartMechanism</tp:member-ref> and (if
+ supported) <tp:member-ref>StartMechanismWithData</tp:member-ref>
+ can be expected to work when in one of the Failed states. If
+ false, the only thing you can do after failure is to close the
+ channel.</p>
+
+ <tp:rationale>
+ <p>Retrying isn't required to work, although some protocols and
+ implementations allow it.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property type="u" tp:type="SASL_Status" access="read"
+ name="SASLStatus" tp:name-for-bindings="SASL_Status">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The current status of this channel.
+ Change notification is via the
+ <tp:member-ref>SASLStatusChanged</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <property type="s" tp:type="DBus_Error_Name" access="read"
+ name="SASLError" tp:name-for-bindings="SASL_Error">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The reason for the <tp:member-ref>SASLStatus</tp:member-ref>, or
+ an empty string if the state is neither
+ Server_Failed nor Client_Failed.</p>
+
+ <p>In particular, an ordinary authentication failure (as would
+ be produced for an incorrect password) SHOULD be represented by
+ <tp:error-ref>AuthenticationFailed</tp:error-ref>,
+ cancellation by the user's request SHOULD be represented
+ by <tp:error-ref>Cancelled</tp:error-ref>, and
+ cancellation by a local process due to inconsistent or invalid
+ challenges from the server SHOULD be represented by
+ <tp:error-ref>ServiceConfused</tp:error-ref>.</p>
+
+ <p>If this interface appears on a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channel, and connection to the server fails with an authentication
+ failure, this error code SHOULD be copied into the
+ <tp:dbus-ref
+ namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>
+ signal.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="SASLErrorDetails"
+ tp:name-for-bindings="SASL_Error_Details"
+ access="read" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tp:member-ref>SASLError</tp:member-ref> is non-empty,
+ any additional information about the last
+ disconnection; otherwise, the empty map. The keys and values are
+ the same as for the second argument of
+ <tp:dbus-ref
+ namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p>
+
+ <p>If this interface appears on a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channel, and connection to the server fails with an authentication
+ failure, these details SHOULD be copied into the
+ <tp:dbus-ref
+ namespace="ofdT">Connection.ConnectionError</tp:dbus-ref>
+ signal.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="AuthorizationIdentity"
+ tp:name-for-bindings="Authorization_Identity"
+ type="s" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The identity for which authorization is being attempted,
+ typically the 'account' from the <tp:dbus-ref
+ namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>
+ parameters, normalized and formatted according to the
+ conventions used for SASL in this protocol.</p>
+
+ <tp:rationale>
+ <p>The normalization used for SASL might not be the same
+ normalization used elsewhere: for instance, in a protocol
+ with email-like identifiers such as XMPP or SIP, the user
+ "juliet@example.com" might have to authenticate to the
+ example.com server via SASL PLAIN as "juliet".</p>
+ </tp:rationale>
+
+ <p>This is usually achieved by using the authorization identity for
+ authentication, but an advanced Handler could offer the option
+ to authenticate under a different identity.</p>
+
+ <p>The terminology used here is that the authorization identity
+ is who you want to act as, and the authentication identity is
+ used to prove that you may do so. For instance, if Juliet is
+ authorized to access a role account, "sysadmin@example.com",
+ and act on its behalf, it might be possible to authenticate
+ as "juliet@example.com" with her own password, but request to
+ be authorized as "sysadmin@example.com" instead of her own
+ account. See
+ <a href="http://tools.ietf.org/html/rfc4422#section-3.4.1">RFC
+ 4422 §3.4.1</a> for more details.</p>
+
+ <tp:rationale>
+ <p>In SASL the authorization identity is normally guessed from
+ the authentication identity, but the information available
+ to the connection manager is the identity for which
+ authorization is required, such as the desired JID in XMPP,
+ so that's what we signal to UIs; it's up to the UI to
+ choose whether to authenticate as the authorization identity
+ or some other identity.</p>
+
+ <p>As a concrete example, the "sysadmin" XMPP account mentioned
+ above would have <code>{ 'account': 'sysadmin@example.com' }</code>
+ in its Parameters, and this property would also be
+ 'sysadmin@example.com'. A simple Handler would
+ merely prompt for sysadmin@example.com's password,
+ and use that JID as both the authorization and authentication
+ identity, which might result in SASL PLAIN authentication with the
+ initial response
+ '\000sysadmin@example.com\000root'.</p>
+
+ <p>A more advanced Handler might also ask for an authentication
+ identity, defaulting to 'sysadmin@example.com'; if Juliet
+ provided authentication identity 'juliet@example.com' and
+ password 'romeo', the Handler might perform SASL PLAIN
+ authentication using the initial response
+ 'sysadmin@example.com\000juliet@example.com\000romeo'.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="DefaultUsername"
+ tp:name-for-bindings="Default_Username"
+ type="s" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The default username for use with SASL mechanisms that deal
+ with a "simple username" (as defined in <a
+ href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>). If
+ such a SASL mechanism is in use, clients SHOULD default to
+ using the DefaultUsername; also, if the client uses
+ the DefaultUsername, it SHOULD assume that the authorization
+ identity <tp:member-ref>AuthorizationIdentity</tp:member-ref>
+ will be derived from it by the server.</p>
+
+ <tp:rationale>
+ <p>In XMPP, <a href="http://trac.tools.ietf.org/wg/xmpp/trac/ticket/49">
+ servers typically expect</a> "user@example.com" to
+ authenticate with username "user"; this was a SHOULD in <a
+ href="http://tools.ietf.org/html/rfc3920">RFC 3920</a>.</p>
+
+ <p><a
+ href="http://tools.ietf.org/html/draft-ietf-xmpp-3920bis-19">3920bis</a>
+ weakens that SHOULD to "in the absence of local information
+ provided by the server, an XMPP client SHOULD assume that
+ the authentication identity for such a SASL mechanism is the
+ combination of a user name and password, where the simple
+ user name is the localpart of the user's JID".</p>
+ </tp:rationale>
+
+ <p>For example, in the simple case, if the user connects with
+ <tp:dbus-ref
+ namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({
+ account: "<tt>user@example.com</tt>" }) and use PLAIN with
+ password "password", he or she should authenticate like so:
+ "<tt>\0user\0password</tt>" and the channel will look like
+ this:</p>
+
+<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "user",
+ "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "user@example.com }
+</pre></blockquote>
+
+ <p>In the complex case, if the same user is using his or her
+ sysadmin powers to log in as the "announcements" role address,
+ he or she would connect with <tp:dbus-ref
+ namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({
+ account: "<tt>announcements@example.com</tt>" }) and the SASL
+ channel would look like this:</p>
+
+<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "announcements",
+ "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "announcements@example.com }
+</pre></blockquote>
+
+ <p>A sufficiently elaborate UI could give the opportunity
+ to override the username from "announcements" to "user".
+ The user's simple username is still "user", and the password is
+ still "password", but this time he or she is trying to authorize
+ to act as <tt>announcements@example.com</tt>, so the UI would
+ have to perform SASL PLAIN with this string:
+ "<tt>announcements@example.com\0user\0password</tt>", where
+ "announcements@example.com" is the
+ <tp:member-ref>AuthorizationIdentity</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="DefaultRealm" tp:name-for-bindings="Default_Realm"
+ type="s" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The default realm (as defined in
+ <a href="http://tools.ietf.org/html/rfc2831#section-2.1.1">RFC
+ 2831</a>) to use for authentication, if the server does not
+ supply one.</p>
+
+ <tp:rationale>
+ <p>The server is not required to provide a realm; if it doesn't,
+ the client is expected to ask the user or provide a sensible
+ default, typically the requested DNS name of the server.
+ In some implementations of <code>DIGEST-MD5</code>, the
+ server does not specify a realm, but expects that the client
+ will choose a particular default, and authentication will
+ fail if the client's default is different. Connection
+ managers for protocols where this occurs are more easily able
+ to work around these implementations than a generic client
+ would be.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="StartMechanism" tp:name-for-bindings="Start_Mechanism">
+ <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism">
+ <tp:docstring>
+ The chosen mechanism.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start an authentication try using <var>Mechanism</var>, without
+ sending initial data (an "initial response" as defined in RFC
+ 4422).</p>
+
+ <tp:rationale>
+ <p>This method is appropriate for mechanisms where the client
+ cannot send anything until it receives a challenge from the
+ server, such as
+ <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>
+ in "initial authentication" mode.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The channel is not in a state where starting authentication makes
+ sense (i.e. SASL_Status_Not_Started, or (if
+ <tp:member-ref>CanTryAgain</tp:member-ref> is true)
+ SASL_Status_Server_Failed or
+ SASL_Status_Client_Failed). You should call
+ <tp:member-ref>AbortSASL</tp:member-ref> and wait for
+ SASL_Status_Client_Failed before starting another attempt.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The server or connection manager doesn't implement the given
+ SASL mechanism. Choose a SASL mechanism from
+ <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort
+ authentication if none of them are suitable.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="StartMechanismWithData"
+ tp:name-for-bindings="Start_Mechanism_With_Data">
+ <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism">
+ <tp:docstring>
+ The chosen mechanism.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Initial_Data" type="ay">
+ <tp:docstring>
+ Initial data (an "initial response" in RFC 4422's terminology) to send
+ with the mechanism.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start an authentication try using <var>Mechanism</var>, and send
+ <var>Initial_Data</var> as the "initial response" defined in
+ <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422
+ §3.3</a>.</p>
+
+ <tp:rationale>
+ <p>This method is appropriate for mechanisms where the client may
+ send data first, such as <code>PLAIN</code>, or must send data
+ first, such as
+ <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>
+ in "subsequent authentication" mode.</p>
+
+ <p>Having two methods allows any mechanism where it makes a difference
+ to distinguish between the absence of an initial response
+ (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte
+ initial response (StartMechanismWithData, with Initial_Data
+ empty).</p>
+ </tp:rationale>
+
+ <p>If the <tp:member-ref>HasInitialData</tp:member-ref>
+ property is false, this indicates that the underlying protocol
+ does not make it possible to send initial data. In such protocols,
+ this method may only be used for the <code>X-TELEPATHY-</code>
+ pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>),
+ and will fail if used with an ordinary SASL mechanism.</p>
+
+ <tp:rationale>
+ <p>For instance, the IRC SASL extension implemented in Charybdis and
+ Atheme does not support initial data - the first message in the
+ exchange only carries the mechanism. This is significant if using
+ <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>,
+ which cannot be used in the faster "subsequent authentication"
+ mode on a protocol not supporting initial data.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The channel is not in a state where starting authentication makes
+ sense (i.e. SASL_Status_Not_Started, or (if
+ <tp:member-ref>CanTryAgain</tp:member-ref> is true)
+ SASL_Status_Server_Failed or
+ SASL_Status_Client_Failed). You should call
+ <tp:member-ref>AbortSASL</tp:member-ref> and wait for
+ SASL_Status_Client_Failed before starting another attempt.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The server or connection manager doesn't implement the given
+ SASL mechanism (choose one from
+ <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort
+ authentication if none of them are suitable), or doesn't allow
+ initial data to be sent (as indicated by
+ <tp:member-ref>HasInitialData</tp:member-ref>; call
+ <tp:member-ref>StartMechanism</tp:member-ref> instead).
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Respond" tp:name-for-bindings="Respond">
+ <arg direction="in" name="Response_Data" type="ay">
+ <tp:docstring>
+ The response data.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Send a response to the the last challenge received via
+ <tp:member-ref>NewChallenge</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Either the state is not In_Progress, or no challenge has been
+ received yet, or you have already responded to the last challenge.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AcceptSASL" tp:name-for-bindings="Accept_SASL">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the channel's status is SASL_Status_Server_Succeeded,
+ this method confirms successful authentication and advances
+ the status of the channel to SASL_Status_Succeeded.</p>
+
+ <p>If the channel's status is SASL_Status_In_Progress, calling this
+ method indicates that the last
+ <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact
+ additional data sent after a successful SASL negotiation, and
+ declares that from the client's point of view, authentication
+ was successful. This advances the state of the channel to
+ SASL_Status_Client_Accepted.</p>
+
+ <p>In mechanisms where the server authenticates itself to the client,
+ calling this method indicates that the client considers this to have
+ been successful. In the case of <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channels, this means that the connection manager MAY continue to
+ connect, and MAY advance the <tp:dbus-ref
+ namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Either the state is neither In_Progress nor Server_Succeeded, or no
+ challenge has been received yet, or you have already responded to
+ the last challenge.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AbortSASL" tp:name-for-bindings="Abort_SASL">
+ <arg direction="in" name="Reason" type="u" tp:type="SASL_Abort_Reason">
+ <tp:docstring>
+ Reason for abort.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Debug_Message" type="s">
+ <tp:docstring>
+ Debug message for abort.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Abort the current authentication try.</p>
+
+ <p>If the current status is SASL_Status_Server_Failed or
+ SASL_Status_Client_Failed, this method returns successfully, but has
+ no further effect. If the current status is SASL_Status_Succeeded
+ or SASL_Status_Client_Accepted then NotAvailable is raised.
+ Otherwise, it changes the channel's state to
+ SASL_Status_Client_Failed, with an appropriate error name and
+ reason code.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The current state is either Succeeded or Client_Accepted.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="SASLStatusChanged" tp:name-for-bindings="SASL_Status_Changed">
+ <tp:docstring>
+ Emitted when the status of the channel changes.
+ </tp:docstring>
+ <arg type="u" tp:type="SASL_Status" name="Status">
+ <tp:docstring>
+ The new value of <tp:member-ref>SASLStatus</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ <arg type="s" tp:type="DBus_Error_Name" name="Reason">
+ <tp:docstring>
+ The new value of <tp:member-ref>SASLError</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ <arg type="a{sv}" tp:type="String_Variant_Map" name="Details">
+ <tp:docstring>
+ The new value of <tp:member-ref>SASLErrorDetails</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="NewChallenge" tp:name-for-bindings="New_Challenge">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new challenge is received from the server, or when
+ a message indicating successful authentication and containing
+ additional data is received from the server.</p>
+
+ <p>When the channel's handler is ready to proceed, it should respond
+ to the challenge by calling <tp:member-ref>Respond</tp:member-ref>,
+ or respond to the additional data by calling
+ <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call
+ <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p>
+ </tp:docstring>
+ <arg name="Challenge_Data" type="ay">
+ <tp:docstring>
+ The challenge data or additional data from the server.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="SASL_Abort_Reason" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A reason why SASL authentication was aborted by the client.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Invalid_Challenge" value="0">
+ <tp:docstring>
+ The server sent an invalid challenge or data.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="User_Abort" value="1">
+ <tp:docstring>
+ The user aborted the authentication.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="SASL_Status" type="u" plural="SASL_Statuses">
+ <tp:enumvalue suffix="Not_Started" value="0">
+ <tp:docstring>
+ The initial state. The Handler SHOULD either
+ call <tp:member-ref>AbortSASL</tp:member-ref>, or connect to the
+ <tp:member-ref>NewChallenge</tp:member-ref> signal then call
+ <tp:member-ref>StartMechanism</tp:member-ref> or
+ <tp:member-ref>StartMechanismWithData</tp:member-ref>.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="In_Progress" value="1">
+ <tp:docstring>
+ The challenge/response exchange is in progress. The Handler SHOULD
+ call either <tp:member-ref>Respond</tp:member-ref> or
+ <tp:member-ref>AcceptSASL</tp:member-ref> exactly once per emission
+ of <tp:member-ref>NewChallenge</tp:member-ref>, or call
+ <tp:member-ref>AbortSASL</tp:member-ref> at any time.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Server_Succeeded" value="2">
+ <tp:docstring>
+ The server has indicated successful authentication, and the
+ connection manager is waiting for confirmation from the Handler.
+ The Handler must call either <tp:member-ref>AcceptSASL</tp:member-ref> or
+ <tp:member-ref>AbortSASL</tp:member-ref> to indicate whether it
+ considers authentication to have been successful.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Client_Accepted" value="3">
+ <tp:docstring>
+ The Handler has indicated successful authentication, and the
+ connection manager is waiting for confirmation from the server.
+ The state will progress to either Succeeded or Server_Failed when
+ confirmation is received.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Succeeded" value="4">
+ <tp:docstring>
+ Everyone is happy (the server sent success, and the client has called
+ <tp:member-ref>AcceptSASL</tp:member-ref>). Connection to the server
+ will proceed as soon as this state is reached. The Handler SHOULD
+ call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ to close the channel.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Server_Failed" value="5">
+ <tp:docstring>
+ The server has indicated an authentication failure.
+ If <tp:member-ref>CanTryAgain</tp:member-ref> is true,
+ the client may try to authenticate again, by calling
+ <tp:member-ref>StartMechanism</tp:member-ref> or
+ <tp:member-ref>StartMechanismWithData</tp:member-ref> again.
+ Otherwise, it should give up completely, by calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ on the channel.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Client_Failed" value="6">
+ <tp:docstring>
+ The client has indicated an authentication failure. The
+ possible actions are the same as for Server_Failed.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml
new file mode 100644
index 0000000..4cfe3f2
--- /dev/null
+++ b/spec/Channel_Interface_SMS.xml
@@ -0,0 +1,179 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_SMS"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+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.
+
+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
+Library General Public License for more details.
+
+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.
+ </tp:license>
+
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.SMS">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:added version='0.19.12'>Imported from
+ rtcom-telepathy-glib, with the unused properties removed and the
+ documentation tidied up.</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface contains SMS-specific properties for text
+ channels.</p>
+
+ <p>The presence of this interface on a channel does not imply that
+ messages will be delivered via SMS.</p>
+
+ <p>This interface MAY appear in the
+ <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property
+ of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be
+ immutable and false. It SHOULD appear on channels where
+ <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and
+ also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is
+ mutable (i.e. channels that might fall back to sending SMS at any
+ time, such as on MSN).</p>
+
+ <h4>Handler filters</h4>
+
+ <p>A handler for class 0 SMSes should advertise the following filter:</p>
+
+ <blockquote><code>
+{ ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/>
+  ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>:
+ <tp:type>Handle_Type</tp:type>_Contact,<br/>
+  ...<tp:dbus-ref namespace='ofdT.Channel.Interface'>SMS.Flash</tp:dbus-ref>:
+ True,<br/>
+}</code></blockquote>
+
+ <p>It should also set its <tp:dbus-ref
+ namespace='ofdT.Client.Handler'>BypassApproval</tp:dbus-ref> property
+ to <code>True</code>, so that it is invoked immediately for new
+ channels.</p>
+ </tp:docstring>
+
+ <property name="Flash" tp:name-for-bindings="Flash"
+ type="b" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <code>True</code>, then this channel is exclusively for
+ receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref
+ namespace='ofdT.Channel.Interface.Messages'>SendMessage</tp:dbus-ref>
+ on this channel). If <code>False</code>, no incoming class 0 SMSes
+ will appear on this channel.</p>
+
+ <p>This property is immutable (cannot change), and therefore SHOULD
+ appear wherever immutable properties are reported, e.g. <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Requests"
+ >NewChannels</tp:dbus-ref> signals.</p>
+
+ <tp:rationale>
+ <p>Class 0 SMSes should be displayed immediately to the user, and
+ need not be saved to the device memory unless the user explicitly
+ chooses to do so. This is unlike “normal”, class 1 SMSes, which
+ must be stored, but need not be shown immediately in their entirity
+ to the user.</p>
+
+ <p>Separating class 0 SMSes into their own channel with this
+ immutable property allows them to be dispatched to a different
+ <tp:dbus-ref namespace='ofdT.Client'>Handler</tp:dbus-ref>—which
+ would include this property in its <tp:dbus-ref
+ namespace='ofdT.Client.Handler'
+ >HandlerChannelFilter</tp:dbus-ref>—avoiding the normal Text
+ channel handler having to decide for each message whether it should
+ be displayed to the user immediately or handled normally.</p>
+
+ <p>Currently, no mechanism is defined for <em>sending</em> class 0
+ SMSes. It seems reasonable to support specifying the class of an
+ outgoing SMS in its header <tp:type>Message_Part</tp:type>, rather
+ than requiring the UI to request a special channel for such SMSes;
+ hence, we define here that channels with Flash set to
+ <code>True</code> are read-only.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="SMSChannel"
+ tp:name-for-bindings="SMS_Channel"
+ type="b"
+ access="read" tp:requestable="yes" tp:immutable="sometimes">
+ <tp:added version="0.21.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If TRUE, messages sent and received on this channel are transmitted
+ via SMS.</p>
+
+ <p>If this property is included in the channel request, the
+ Connection Manager MUST return an appropriate channel (i.e. if TRUE
+ the channel must be for SMSes, if FALSE it must not), or else fail
+ to provide the requested channel with the
+ <tp:error-ref>NotCapable</tp:error-ref>
+ error.</p>
+
+ <p>For example, to explicitly request an SMS channel to a contact.
+ You might construct a channel request like:</p>
+
+ <blockquote><pre>{
+ Channel.Type: Channel.Type.Text,
+ Channel.TargetHandleType: Handle_Type_Contact,
+ Channel.TargetID: escher.cat,
+ Channel.Interface.SMS.SMSChannel: True,
+}</pre></blockquote>
+
+ <tp:rationale>
+ Some protocols allow us to send SMSes to a remote contact, without
+ knowing the phone number to which those SMSes will be sent. This
+ provides a mechanism to request such channels.
+ </tp:rationale>
+
+ <p>If this property is not included in the channel request, the
+ Connection Manager MAY return an SMS channel if that is the most
+ appropriate medium (i.e. if the channel target is a phone
+ number).</p>
+
+ <tp:rationale>
+ To some types of identifiers (i.e. phone numbers) it only makes
+ sense to return an SMS channel, this is what happens currently with
+ telepathy-ring. We don't want to break this behaviour when we are
+ not explicit about the type of channel we want. Alternatively, for
+ protocols where there is an SMS fallback for IM messages, it's
+ possible that we don't care what sort of channel we get, and simply
+ want notification of the transport.
+ </tp:rationale>
+
+ <p>Some protocols have a fallback to deliver IM messages via SMS.
+ On these protocols, the Connection Manager SHOULD set the property
+ value as appropriate, and notify its change with
+ <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p>
+
+ <tp:rationale>
+ Protocols such as MSN can fall back to delivering IM messages via
+ SMS. Where possible we want clients to be able to inform the user
+ that their messages are going to be redirected to the remote
+ contact's phone.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="SMSChannelChanged"
+ tp:name-for-bindings="SMS_Channel_Changed">
+ <tp:added version="0.21.7"/>
+ <arg name="SMSChannel" type="b">
+ <tp:docstring>
+ The new value for <tp:member-ref>SMSChannel</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ This signal indicates a change in the
+ <tp:member-ref>SMSChannel</tp:member-ref> property.
+ </tp:docstring>
+ </signal>
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_Securable.xml b/spec/Channel_Interface_Securable.xml
new file mode 100644
index 0000000..d9d9713
--- /dev/null
+++ b/spec/Channel_Interface_Securable.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Securable"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright>
+
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Securable">
+ <tp:added version="0.21.5">as stable API</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface exists to expose security information about
+ <tp:dbus-ref namespace="ofdT">Channel</tp:dbus-ref>s. The two
+ properties are sometimes immutable and can be used to make
+ decisions on how cautious to be about transferring sensitive
+ data. The special case of <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channels is one example of where the two properties are
+ immutable.</p>
+
+ <p>For example, clients MAY use these properties to decide
+ whether the <code>PLAIN</code> mechanism is acceptable for a
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>
+ channel.</p>
+ </tp:docstring>
+
+ <property name="Encrypted"
+ tp:name-for-bindings="Encrypted" type="b"
+ access="read" tp:immutable="sometimes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel occurs over an encrypted
+ connection. This <strong>does not</strong> imply that steps
+ have been taken to avoid man-in-the-middle attacks.</p>
+
+ <tp:rationale>
+ <p>For future support for <a
+ href="http://tools.ietf.org/html/rfc5056">RFC 5056 Channel
+ Binding</a> it is desirable to be able to use some SASL
+ mechanisms over an encrypted connection to an unverified peer,
+ which can prove that it is the desired destination during
+ the SASL negotiation.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Verified"
+ tp:name-for-bindings="Verified" type="b"
+ access="read" tp:immutable="sometimes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel occurs over a connection that is
+ protected against tampering, and has been verified to be with
+ the desired destination: for instance, one where TLS was
+ previously negotiated, and the TLS certificate has been
+ verified against a configured certificate authority or
+ accepted by the user.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml
new file mode 100644
index 0000000..787397b
--- /dev/null
+++ b/spec/Channel_Interface_Service_Point.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint">
+ <tp:added version="0.19.7">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels
+ that can indicate when/if they are connected to some form
+ of service point. For example, when
+ dialing 9-1-1 in the US, a GSM modem/network will recognize that as
+ an emergency call, and inform higher levels of the stack that the
+ call is being handled by an emergency service. In this example,
+ the call is handled by a Public Safety Answering Point (PSAP) which is labeled
+ as "urn:service:sos". Other networks and protocols may handle this
+ differently while still using this interface.</p>
+
+ <p>Note that while the majority of examples given in this
+ documentation are for GSM calls, they could just as easily be
+ SIP calls, GSM SMS's, etc.</p>
+ </tp:docstring>
+
+ <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point"
+ type="(us)" tp:type="Service_Point" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This property is used to indicate that the channel target is a
+ well-known service point. Please note that the CM (or lower layers
+ of the stack or network) may forward the connection to other other
+ service points, which the CM SHOULD indicate via
+ <tp:member-ref>ServicePointChanged</tp:member-ref>
+ signal.</p>
+
+ <p>This property SHOULD be set for channel requests that are
+ specifically targeting service points.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point"
+ type="(us)" tp:type="Service_Point" access="read">
+ <tp:docstring>
+ The service point that the channel is connected to. If the channel is
+ not connected to a service point, the CM MUST set the
+ <tp:type>Service_Point_Type</tp:type> field to None; for instance,
+ this will be the case for ordinary calls.
+ </tp:docstring>
+ </property>
+
+ <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed">
+ <tp:docstring>
+ <p>Emitted when a channel changes the service point that it's connected to. This
+ might be a new call being connected to a service, a call connected to
+ a service being routed to a different service
+ (ie, an emergency call being routed from a generic emergency PSAP to
+ a poison control PSAP), or any number of other things.</p>
+
+ <p>Note that this should be emitted as soon as the CM has been notified
+ of the switch, and has updated its internal state. The CM MAY still
+ be in the process of connecting to the new service point.</p>
+ </tp:docstring>
+
+ <arg name="Service_Point" type="(us)" tp:type="Service_Point">
+ <tp:docstring>
+ The new service point that is being used.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Splittable.xml b/spec/Channel_Interface_Splittable.xml
new file mode 100644
index 0000000..760c134
--- /dev/null
+++ b/spec/Channel_Interface_Splittable.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Splittable"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.Splittable.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels that can be made conceptually part of a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference</tp:dbus-ref>, and can then be detached from that
+ conference.</p>
+
+ <tp:rationale>
+ <p>This interface addresses part of freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls). GSM is currently
+ the only protocol known to implement this; PBXs might implement
+ it too.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <method name="Split"
+ tp:name-for-bindings="Split">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that this channel is removed from any
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference</tp:dbus-ref> of which it is a part.</p>
+
+ <p>This implies that the media streams within the conference are put on
+ hold and the media streams within the member channel leaving the
+ conference are unheld.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ This channel isn't in a conference.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This channel is in a conference but can't currently be split away
+ from it.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_Transfer.xml b/spec/Channel_Interface_Transfer.xml
new file mode 100644
index 0000000..02591c1
--- /dev/null
+++ b/spec/Channel_Interface_Transfer.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Transfer" 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) 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.Channel.Interface.Transfer"
+ tp:causes-havoc='not well-tested'>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <method name="Transfer">
+ <arg direction="in" name="Member" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the member to transfer
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Destination" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the destination contact
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the given channel member instead connects to a different
+ contact ID.
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring>
+ An interface for channels where you may request that one of the members
+ connects to somewhere else instead.
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
new file mode 100644
index 0000000..858a15d
--- /dev/null
+++ b/spec/Channel_Interface_Tube.xml
@@ -0,0 +1,258 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
+ two or more IM users, used to allow applications on the users'
+ systems to communicate without having to establish network
+ connections themselves. Currently, two types of tube exist:
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Channel.Type.DBusTube</tp:dbus-ref> and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
+ the properties, signals and methods common to both types of tube;
+ you can only create channels of a specific tube type, not of this
+ type. A tube channel contains exactly one tube; if you need several
+ tubes, you have to create several tube channels.</p>
+
+ <p>Tube channels can be requested for <tp:type>Handle_Type</tp:type>
+ Contact (for 1-1 communication) or Room (to communicate with others in
+ the room simultaneously).</p>
+
+ <p>As an exception to the usual handling of capabilities, connection managers
+ for protocols with capability discovery (such as XMPP) SHOULD advertise the
+ capability representing each Tube type that they support
+ (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
+ even if no client has indicated via
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
+ that such a tube is supported. They SHOULD also allow clients to offer tubes with any
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref>
+ to any contact which supports the corresponding tube capability.</p>
+
+ <tp:rationale>
+ <p>This lowers the barrier to entry for those writing new tube
+ applications, and preserves interoperability with older versions of
+ the Telepathy stack which did not support rich capabilities.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
+ access="read" tp:name-for-bindings="Parameters">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Each tube has a dictionary of arbitrary parameters. Parameters are
+ commonly used to bootstrap legacy protocols where you can't
+ negotiate parameters in-band. The allowable keys,
+ types and values are defined by the service, but connection managers
+ must support the value being a string (D-Bus type <tt>'s'</tt>),
+ array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
+ type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
+ (D-Bus type <tt>'b'</tt>).</p>
+
+ <p>When the tube is offered, the parameters are transmitted with the
+ offer and appear as a property of the incoming tube for other
+ participants.</p>
+
+ <p>For example, a stream tube for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref>
+ <tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
+ use the following properties, as defined in <a
+ href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
+ Service Types</a>:</p>
+
+ <pre>
+{ 'u': 'some-username',
+ 'p': 'top-secret-password',
+ 'path': '/etc/passwd',
+}</pre>
+
+ <p>When requesting a tube with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request; instead, it is set
+ when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref>
+ (as appropriate) is called. Its value is undefined until the tube is
+ offered; once set, its value MUST NOT change.</p>
+
+ <p>When receiving an incoming tube, this property is immutable and so advertised in the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="State" type="u" tp:type="Tube_Channel_State" access="read"
+ tp:name-for-bindings="State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>State of the tube in this channel.</p>
+
+ <p>When requesting a tube with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Tube_Channel_State" type="u">
+ <tp:enumvalue suffix="Local_Pending" value="0">
+ <tp:docstring>
+ The initiator offered the tube. The tube is waiting to be
+ accepted/closed locally. If the client accepts the tube, the tube's
+ state will be Open.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Remote_Pending" value="1">
+ <tp:docstring>
+ The tube is waiting to be accepted/closed remotely. If the
+ recipient accepts the tube, the tube's state will be Open.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="2">
+ <tp:docstring>
+ The initiator offered the tube and the recipient accepted it. The
+ tube is open for traffic. The tube's state stays in this state until
+ it is closed.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Not_Offered" value="3">
+ <tp:docstring>
+ The tube channel has been requested but the tube is not yet offered.
+ The client should offer the tube to the recipient and the tube's
+ state will be Remote_Pending. The method used to offer the tube
+ depends on the tube type.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <signal name="TubeChannelStateChanged"
+ tp:name-for-bindings="Tube_Channel_State_Changed">
+ <tp:docstring>
+ Emitted when the state of the tube channel changes. Valid state
+ transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
+ </tp:docstring>
+ <arg name="State" type="u" tp:type="Tube_Channel_State">
+ <tp:docstring>
+ The new state of the tube.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Socket_Address_Type" type="u">
+ <tp:enumvalue suffix="Unix" value="0">
+ <tp:docstring>
+ A Unix socket. The address variant contains a byte-array, signature 'ay',
+ containing the path of the socket.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Abstract_Unix" value="1">
+ <tp:docstring>
+ An abstract Unix socket. The address variant contains a byte-array,
+ signature 'ay', containing the path of the socket including the
+ leading null byte.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv4" value="2">
+ <tp:docstring>
+ An IPv4 socket. The address variant contains a Socket_Address_IPv4,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv4 dotted-quad address literal
+ (and must not be a DNS name), while the 16-bit unsigned integer is
+ the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="IPv6" value="3">
+ <tp:docstring>
+ An IPv6 socket. The address variant contains a Socket_Address_IPv6,
+ i.e. a structure with signature (sq)
+ in which the string is an IPv6 address literal as specified in
+ RFC2373 (and must not be a DNS name), while the 16-bit unsigned
+ integer is the port number.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ </tp:enum>
+
+ <tp:enum name="Socket_Access_Control" type="u"
+ array-name="Socket_Access_Control_List">
+ <tp:enumvalue suffix="Localhost" value="0">
+ <tp:docstring>
+ The IP or Unix socket can be accessed by any local user (e.g.
+ a Unix socket that accepts all local connections, or an IP socket
+ listening on 127.0.0.1 (or ::1) or rejecting connections not from
+ that address). The associated variant must be ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Port" value="1">
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+ containing the string form of an IP address of the appropriate
+ version, and a port number. The socket can only be accessed if the
+ connecting process has that address and port number; all other
+ connections will be rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Netmask" value="2">
+ <tp:deprecated version="0.17.25">This has never been implemented.
+ If you want to share a service to your whole LAN, Telepathy is
+ not the way to do it.</tp:deprecated>
+ <tp:docstring>
+ May only be used on IP sockets. The associated variant must contain
+ a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
+ signature (sy), containing the string form of an
+ IP address of the appropriate version, and a prefix length "n".
+ The socket can only be accessed if the first n bits of the
+ connecting address match the first n bits of the given address.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Credentials" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>May only be used on UNIX sockets.
+ The connecting process must send a byte when
+ it first connects, which is not considered to be part of the data
+ stream. If the operating system uses sendmsg() with SCM_CREDS or
+ SCM_CREDENTIALS to pass credentials over sockets, the connecting
+ process must do so if possible; if not, it must still send the
+ byte.</p>
+
+ <p>The listening process will disconnect the connection unless it
+ can determine by OS-specific means that the connecting process
+ has the same user ID as the listening process.</p>
+
+ <p>The associated variant must be ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
new file mode 100644
index 0000000..1a9c397
--- /dev/null
+++ b/spec/Channel_Request.xml
@@ -0,0 +1,300 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Request"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.ChannelRequest">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel request is an object in the ChannelDispatcher representing
+ an ongoing request for some channels to be created or found. There
+ can be any number of ChannelRequest objects at the same time.</p>
+
+ <p>Its well-known bus name is the same as that of the ChannelDispatcher,
+ "org.freedesktop.Telepathy.ChannelDispatcher".</p>
+
+ <tp:rationale>
+ <p>See
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.CreateChannel</tp:dbus-ref>
+ for rationale for ChannelRequest being a separate object.</p>
+ </tp:rationale>
+
+ <p>A channel request can be cancelled by any client (not just the one
+ that requested it). This means that the ChannelDispatcher will
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ the resulting channel, or refrain from requesting it at all, rather
+ than dispatching it to a handler.</p>
+ </tp:docstring>
+
+ <property name="Account" tp:name-for-bindings="Account"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ on which this request was made. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="UserActionTime" tp:name-for-bindings="User_Action_Time"
+ type="x" tp:type="User_Action_Timestamp" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This property is set when the channel request is created,
+ and can never change.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="PreferredHandler" tp:name-for-bindings="Preferred_Handler"
+ type="s" tp:type="DBus_Well_Known_Name" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable.</p>
+
+ <p>This property is set when the channel request is created,
+ and can never change.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}"
+ tp:type="Qualified_Property_Value_Map[]"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of dictionaries containing desirable properties for
+ the channel or channels to be created.</p>
+
+ <tp:rationale>
+ <p>This is an array so that we could add a CreateChannels method in
+ future without redefining the API of ChannelRequest.</p>
+ </tp:rationale>
+
+ <p>This property is set when the channel request is created,
+ and can never change.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel request.
+ This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <method name="Proceed" tp:name-for-bindings="Proceed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Proceed with the channel request.</p>
+
+ <tp:rationale>
+ <p>The client that created this object calls this method
+ when it has connected signal handlers for
+ <tp:member-ref>Succeeded</tp:member-ref> and
+ <tp:member-ref>Failed</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>Clients other than the client which created the ChannelRequest
+ MUST NOT call this method.</p>
+
+ <p>This method SHOULD return immediately; on success, the request
+ might still fail, but this will be indicated asynchronously
+ by the <tp:member-ref>Failed</tp:member-ref> signal.</p>
+
+ <p>Proceed cannot fail, unless clients have got the life-cycle
+ of a ChannelRequest seriously wrong (e.g. a client calls this
+ method twice, or a client that did not create the ChannelRequest
+ calls this method). If it fails, clients SHOULD assume that the
+ whole ChannelRequest has become useless.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This method has already been called, so it is no longer
+ available. Stop calling it.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Cancel" tp:name-for-bindings="Cancel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Cancel the channel request. The precise effect depends on the
+ current progress of the request.</p>
+
+ <p>If the connection manager has not already been asked to create
+ a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted
+ immediately, and the channel request is removed.</p>
+
+ <p>If the connection manager has already been asked to create a
+ channel but has not produced one yet (e.g. if <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ has been called, but has not yet returned), then the
+ ChannelDispatcher will remember that the request has been cancelled.
+ When the channel appears, it will be closed (if it was newly
+ created and can be closed), and will not be dispatched to a
+ handler.</p>
+
+ <p>If the connection manager has already returned a channel, but the
+ channel has not yet been dispatched to a handler
+ then the channel dispatcher will not dispatch that
+ channel to a handler. If the channel was newly created for this
+ request, the channel dispatcher will close it with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>;
+ otherwise, the channel dispatcher will ignore it. In either case,
+ <tp:member-ref>Failed</tp:member-ref> will be emitted when processing
+ has been completed.</p>
+
+ <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to
+ this method, the error SHOULD be
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
+
+ <p>If the channel has already been dispatched to a handler, then
+ it's too late to call this method, and the channel request will
+ no longer exist.</p>
+ </tp:docstring>
+ </method>
+
+ <signal name="Failed" tp:name-for-bindings="Failed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has failed. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error. This can come from various sources,
+ including the error raised by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ or an error generated
+ to represent failure to establish the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ If the first argument of the D-Bus error message was a string,
+ that string. Otherwise, an empty string.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="Succeeded" tp:name-for-bindings="Succeeded">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel request has succeeded. It is no longer present,
+ and further methods must not be called on it.</p>
+ </tp:docstring>
+ </signal>
+
+ <property name="Hints" tp:name-for-bindings="Hints"
+ type="a{sv}" access="read">
+ <tp:added version="0.21.5"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary of metadata provided by the channel
+ requester, which the handler and other clients MAY choose to
+ interpret. Currently no standard keys are defined; clients MAY
+ choose to use platform-specific keys for their own purposes, but MUST
+ ignore unknown keys and MUST cope with expected keys being
+ missing. Clients SHOULD namespace hint names by having them
+ start with a reversed domain name, in the same way as D-Bus
+ interface names.</p>
+
+ <tp:rationale>This property might be used to pass a contact ID for a
+ telephone number shared between two contacts from the address book to
+ the call UI, so that if you try to call “Mum”, the call UI knows this
+ rather than having to guess or show “Calling Mum or Dad”. The format
+ of these contact IDs would be platform-specific, so we leave the
+ definition of the dictionary entry up to the platform in question.
+ But third-party channel requesters might not include the contact ID,
+ so the call UI has to be able to deal with it not being
+ there.</tp:rationale>
+
+ <p>The channel dispatcher does not currently interpret any of these
+ hints: they are solely for communication between cooperating
+ clients. If hints that do affect the channel dispatcher are added in
+ future, their names will start with an appropriate reversed domain
+ name (e.g. <code>org.freedesktop.Telepathy</code> for hints defined
+ by this specification, or an appropriate vendor name for third-party
+ plugins).</p>
+
+ <p>This property may be set when the channel request is created, and
+ can never change. Since it is immutable, it SHOULD be included in the
+ dictionary of properties passed to <tp:dbus-ref
+ namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref>
+ by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel">
+ <tp:added version="0.21.5"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Variant of the <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal
+ allowing to get the channel which has been created.</p>
+
+ <p>This signal MUST be emitted if the
+ <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>'s
+ <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">SupportsRequestHints</tp:dbus-ref>
+ property is true. If supported, it MUST be emitted before
+ the <tp:member-ref>Succeeded</tp:member-ref> signal.</p>
+ </tp:docstring>
+
+ <arg name="Connection" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Connection owning the channel.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Connection_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A subset of the Connection's properties, currently unused.
+ This parameter may be used in future.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel which has been created.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same immutable properties of the Channel that would appear
+ in a <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests"
+ >NewChannels</tp:dbus-ref> signal.</p>
+ </tp:docstring>
+ </arg>
+
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
new file mode 100644
index 0000000..039c1f9
--- /dev/null
+++ b/spec/Channel_Type_Call.xml
@@ -0,0 +1,1429 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Call" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for making audio and video calls. Call
+ channels supersede the old <tp:dbus-ref
+ namespace="ofdT.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channel type. Call channels are much more flexible than its
+ predecessor and allow more than two participants.</p>
+
+ <p>Handlers are advised against executing all the media
+ signalling, codec and candidate negotiation themselves but
+ instead use a helper library such as <a
+ href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a>
+ which when given a new Call channel will set up the
+ transports and codecs and create GStreamer pads which
+ can be added to the handler UI. This is useful as it means
+ the handler does not have to worry how exactly the
+ connection between the call participants is being made.</p>
+
+ <p>The <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> and
+ <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
+ properties in a Call channel refer to the contact that the
+ user initially called, or which contact initially called the
+ user. Even in a conference call, where there are multiple
+ contacts in the call, these properties refer to the
+ initial contact, who might have left the conference since
+ then. As a result, handlers should not rely on these
+ properties.</p>
+
+ <h4>Contents</h4>
+
+ <p><tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>
+ objects represent the actual media that forms the Call (for
+ example an audio content and a video content). Calls always
+ have one or more Content objects associated with them. As a
+ result, a new Call channel request MUST have either
+ <tp:member-ref>InitialAudio</tp:member-ref>=True, or
+ <tp:member-ref>InitialVideo</tp:member-ref>=True, or both,
+ as the Requestable Channel Classes will document.</p>
+
+ <p><tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects have
+ one or more stream associated with them. More information on
+ these streams and how to maniuplate them can be found on the
+ <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>
+ interface page.</p>
+
+ <h4>Outgoing calls</h4>
+
+ <p>To make an audio-only call to a contact <tt>foo@example.com</tt>
+ handlers should call:</p>
+
+ <blockquote>
+ <pre>
+<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
+ ...<tp:member-ref>InitialAudio</tp:member-ref>: True,
+})</pre></blockquote>
+
+ <p>As always, <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> may be used
+ in place of
+ <tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>
+ if the contact's handle is already known. To make an audio
+ and video call, the handler should also specify
+ <tp:member-ref>InitialVideo</tp:member-ref> The
+ connection manager SHOULD return a channel whose immutable
+ properties contain the local user as the <tp:dbus-ref
+ namespace="ofdT.Channel">InitiatorHandle</tp:dbus-ref>, the
+ remote contact as the <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref> =
+ <code>True</code> (indicating the call is outgoing).</p>
+
+ <p>After a new Call channel is requested, the
+ <tp:member-ref>CallState</tp:member-ref> property will be
+ <tp:type>Call_State</tp:type>_Pending_Initiator. As the local
+ user is the initiator, the call must be accepted by the handler
+ by calling the <tp:member-ref>Accept</tp:member-ref> method.
+ At this point, <tp:member-ref>CallState</tp:member-ref> changes
+ to <tp:type>Call_State</tp:type>_Pending_Receiver which signifies
+ that the call is ringing, waiting for the remote contact to
+ accept the call. All changes to
+ <tp:member-ref>CallState</tp:member-ref> property are signalled
+ using the <tp:member-ref>CallStateChanged</tp:member-ref>
+ signal.</p>
+
+ <p>When the call is accepted by the remote contact, the
+ <tp:member-ref>CallStateChanged</tp:member-ref> signal fires
+ again to show that <tp:member-ref>CallState</tp:member-ref> =
+ <tp:type>Call_State</tp:type>_Accepted.</p>
+
+ <p>At this point <a
+ href="http://telepathy.freedesktop.org/doc/telepathy-farsight/">telepathy-farsight</a>
+ will signal that a pad is available for the handler to show
+ in the user interface.</p>
+
+ <h5>Missed calls</h5>
+
+ <p>If the remote contact does not accept the call in time, then
+ the call can be terminated by the server. Note that this only
+ happens in some protocols. Most XMPP clients, for example, do
+ not do this and rely on the call initiator terminating the call.
+ A missed call is shown in a Call channel by the
+ <tp:member-ref>CallState</tp:member-ref> property changing to
+ <tp:type>Call_State</tp:type>_Ended, and the
+ <tp:member-ref>CallStateReason</tp:member-ref> property changing
+ to (remote contact,
+ <tp:type>Call_State_Change_Reason</tp:type>_No_Answer, "").</p>
+
+ <h5>Rejected calls</h5>
+
+ <p>If the remote contact decides he or she does not feel like
+ talking to the local user, he or she can reject his or her
+ incoming call. This will be shown in the Call channel by
+ <tp:member-ref>CallState</tp:member-ref> changing to
+ <tp:type>Call_State</tp:type>_Ended and the
+ <tp:member-ref>CallStateReason</tp:member-ref> property
+ changing to (remote contact,
+ <tp:type>Call_State</tp:type>_Change_Reason_User_Requested,
+ "org.freedesktop.Telepathy.Error.Rejected").</p>
+
+ <h4>Incoming calls</h4>
+
+ <p>When an incoming call occurs, something like the following
+ <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal will occur:</p>
+
+ <blockquote>
+ <pre>
+<tp:dbus-ref namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>([
+ /org/freedesktop/Telepathy/Connection/foo/bar/foo_40bar_2ecom/CallChannel,
+ {
+ ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandle</tp:dbus-ref>: 42,
+ ...<tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>: False,
+ ...<tp:member-ref>InitialAudio</tp:member-ref>: True,
+ ...<tp:member-ref>InitialVideo</tp:member-ref>: True,
+ ...<tp:member-ref>InitialAudioName</tp:member-ref>: "audio",
+ ...<tp:member-ref>InitialVideoName</tp:member-ref>: "video",
+ ...<tp:member-ref>MutableContents</tp:member-ref>: True,
+ }])</pre></blockquote>
+
+ <p>The <tp:member-ref>InitialAudio</tp:member-ref> and
+ <tp:member-ref>InitialVideo</tp:member-ref> properties show that
+ the call has been started with two contents: one for audio
+ streaming and one for video streaming. The
+ <tp:member-ref>InitialAudioName</tp:member-ref> and
+ <tp:member-ref>InitialVideoName</tp:member-ref> properties also
+ show that the aforementioned audio and video contents have names
+ "audio" and "video".</p>
+
+ <p>Once the handler has notified the local user that there is an
+ incoming call waiting for acceptance, the handler should call
+ <tp:member-ref>SetRinging</tp:member-ref> to let the CM know.
+ The new channel should also be given to telepathy-farsight to
+ work out how the two participants will connect together.
+ telepathy-farsight will call the appropriate methods on the call's
+ <tp:dbus-ref namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>s
+ to negotiate codecs and transports.</p>
+
+ <p>To pick up the call, the handler should call
+ <tp:member-ref>Accept</tp:member-ref>. The
+ <tp:member-ref>CallState</tp:member-ref> property changes to
+ <tp:type>Call_State</tp:type>_Accepted and once media is
+ being transferred, telepathy-farsight will notify the
+ handler of a new pad to be shown to the local user in the
+ UI</p>
+
+ <p>To reject the call, the handler should call the
+ <tp:member-ref>Hangup</tp:member-ref> method. The
+ <tp:member-ref>CallState</tp:member-ref> property will change to
+ <tp:type>Call_State</tp:type>_Ended and the
+ <tp:member-ref>CallStateReason</tp:member-ref> property will
+ change to (self handle,
+ <tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
+ "org.freedesktop.Telepathy.Error.Rejected").</p>
+
+ <h4>Ongoing calls</h4>
+
+ <h5>Adding and removing contents</h5>
+
+ <p>When a call is open, new contents can be added as long as the
+ CM supports it. The
+ <tp:member-ref>MutableContents</tp:member-ref> property will let
+ the handler know whether further contents can be added or
+ existing contents removed. An example of this is starting a
+ voice call between a contact and then adding a video content.
+ To do this, the should call
+ <tp:member-ref>AddContent</tp:member-ref> like this:</p>
+
+ <blockquote>
+ <pre><tp:member-ref>AddContent</tp:member-ref>("video",
+ <tp:type>Media_Stream_Type</tp:type>_Video)</pre>
+ </blockquote>
+
+ <p>Assuming no errors, the new video content will be added to
+ the call. telepathy-farsight will pick up the new content and
+ perform the transport and codec negotiation automatically.
+ telpathy-farsight will signal when the video is ready to
+ show in the handler's user interface.</p>
+
+ <p>A similar method is used for removing contents from a call,
+ except that the <tp:dbus-ref
+ namespace="ofdT.Call.Content.DRAFT">Remove</tp:dbus-ref> method
+ is on the <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> object.</p>
+
+ <h5>Ending the call</h5>
+
+ <p>To end the call, the handler should call the
+ <tp:member-ref>Hangup</tp:member-ref> method. The
+ <tp:member-ref>CallState</tp:member-ref> property will change to
+ <tp:type>Call_State</tp:type>_Ended and
+ <tp:member-ref>CallStateReason</tp:member-ref> will change
+ to (self handle,
+ <tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
+ "org.freedesktop.Telepathy.Error.Cancelled").</p>
+
+ <p>If the other participant hangs up first then the
+ <tp:member-ref>CallState</tp:member-ref> property will change to
+ <tp:type>Call_State</tp:type>_Ended and
+ <tp:member-ref>CallStateReason</tp:member-ref> will change
+ to (remote contact,
+ <tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
+ "org.freedesktop.Telepathy.Error.Terminated").</p>
+
+ <h4>Multi-party calls</h4>
+
+ [TODO]
+
+ <h4>Call states</h4>
+
+ <p>There are many combinations of the
+ <tp:member-ref>CallState</tp:member-ref> and
+ <tp:member-ref>CallStateReason</tp:member-ref> properties which
+ mean different things. Here is a table to try to make these
+ meanings clearer:</p>
+
+ <table>
+ <tr>
+ <th rowspan="2"><tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref></th>
+ <th rowspan="2"><tp:member-ref>CallState</tp:member-ref></th>
+ <th colspan="3"><tp:member-ref>CallStateReason</tp:member-ref></th>
+ <th rowspan="2">Meaning</th>
+ </tr>
+ <tr>
+ <th>Actor</th>
+ <th>Reason</th>
+ <th>DBus_Reason</th>
+ </tr>
+ <!-- Pending_Initiator -->
+ <tr>
+ <td>True</td>
+ <td><tp:type>Call_State</tp:type>_Pending_Initiator</td>
+ <td>Self handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td>""</td>
+ <td>The outgoing call channel is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref>.</td>
+ </tr>
+ <!-- Pending_Receiver -->
+ <tr>
+ <td>True</td>
+ <td><tp:type>Call_State</tp:type>_Pending_Receiver</td>
+ <td>Self handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td>""</td>
+ <td>The outgoing call is waiting for the remote contact to pick up the call.</td>
+ </tr>
+ <tr>
+ <td>False</td>
+ <td><tp:type>Call_State</tp:type>_Pending_Receiver</td>
+ <td>0</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_Unknown</td>
+ <td>""</td>
+ <td>The incoming call is waiting for the local user to call <tp:member-ref>Accept</tp:member-ref> on the call.</td>
+ </tr>
+ <!-- Accepted -->
+ <tr>
+ <td>True</td>
+ <td><tp:type>Call_State</tp:type>_Accepted</td>
+ <td>Remote contact handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td>""</td>
+ <td>The remote contact accepted the outgoing call.</td>
+ </tr>
+ <tr>
+ <td>False</td>
+ <td><tp:type>Call_State</tp:type>_Accepted</td>
+ <td>Self handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td>""</td>
+ <td>The local user accepted the incoming call.</td>
+ </tr>
+ <!-- Ended -->
+ <tr>
+ <td>True or False</td>
+ <td><tp:type>Call_State</tp:type>_Ended</td>
+ <td>Self handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td><tp:error-ref>Cancelled</tp:error-ref></td>
+ <td>The local user hung up the incoming or outgoing call.</td>
+ </tr>
+ <tr>
+ <td>True or False</td>
+ <td><tp:type>Call_State</tp:type>_Ended</td>
+ <td>Remote contact handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td><tp:error-ref>Terminated</tp:error-ref></td>
+ <td>The remote contact hung up the incoming or outgoing call.</td>
+ </tr>
+ <tr>
+ <td>True</td>
+ <td><tp:type>Call_State</tp:type>_Ended</td>
+ <td>Remote contact handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_No_Answer</td>
+ <td>""</td>
+ <td>The outgoing call was not picked up and the call ended.</td>
+ </tr>
+ <tr>
+ <td>False</td>
+ <td><tp:type>Call_State</tp:type>_Ended</td>
+ <td>Remote contact handle</td>
+ <td><tp:type>Call_State_Change_Reason</tp:type>_User_Requested</td>
+ <td><tp:error-ref>PickedUpElsewhere</tp:error-ref></td>
+ <td>The incoming call was ended because it was picked up elsewhere.</td>
+ </tr>
+ </table>
+
+ <h4>Requestable channel classes</h4>
+
+ <p>The <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ for <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels
+ can be:</p>
+
+ <blockquote>
+ <pre>
+[( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
+ ...<tp:member-ref>InitialVideo</tp:member-ref>: True
+ },
+ Allowed = [ ...<tp:member-ref>InitialVideoName</tp:member-ref>,
+ ...<tp:member-ref>InitialAudio</tp:member-ref>,
+ ...<tp:member-ref>InitialAudioName</tp:member-ref>
+ ]
+),
+( Fixed = { ...<tp:dbus-ref namespace="ofdT.Channel">ChannelType</tp:dbus-ref>: ...<tp:dbus-ref namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>: Contact,
+ ...<tp:member-ref>InitialAudio</tp:member-ref>: True
+ },
+ Allowed = [ ...<tp:member-ref>InitialAudioName</tp:member-ref>,
+ ...<tp:member-ref>InitialVideo</tp:member-ref>,
+ ...<tp:member-ref>InitialVideoName</tp:member-ref>
+ ]
+)]</pre></blockquote>
+
+ <p>Clients aren't allowed to make outgoing calls that have
+ neither initial audio nor initial video. Clearly, CMs
+ which don't support video should leave out the first class and
+ omit <tp:member-ref>InitialVideo</tp:member-ref> from the second
+ class, and vice versa for CMs without audio support.</p>
+
+ <p>Handlers should not close <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels
+ without first calling <tp:member-ref>Hangup</tp:member-ref> on
+ the channel. If a Call handler crashes, the <tp:dbus-ref
+ namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will call
+ <tp:dbus-ref namespace="ofdT.Channel">Close</tp:dbus-ref> on the
+ channel which SHOULD also imply a call to
+ <tp:member-ref>Hangup</tp:member-ref>(<tp:type>Call_State_Change_Reason</tp:type>_User_Requested,
+ "org.freedesktop.Telepathy.Error.Terminated", "") before
+ actually closing the channel.</p>
+
+ </tp:docstring>
+
+ <method name="SetRinging" tp:name-for-bindings="Set_Ringing">
+ <tp:changed version="0.21.2">renamed from Ringing</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Indicate that the local user has been alerted about the incoming
+ call.</p>
+
+ <p>This method is only useful if the
+ channel's <tp:dbus-ref namespace="ofdT.Channel">Requested</tp:dbus-ref>
+ property is False, and
+ the <tp:member-ref>CallState</tp:member-ref> is
+ <tp:type>Call_State</tp:type>_Pending_Receiver (an incoming
+ call waiting on the local user to pick up). While this is
+ the case, this method SHOULD change the
+ <tp:member-ref>CallFlags</tp:member-ref> to include
+ <tp:type>Call_Flags</tp:type>_Locally_Ringing, and notify the
+ remote contact that the local user has been alerted (if the
+ protocol implements this); repeated calls to this method
+ SHOULD succeed, but have no further effect.</p>
+
+ <p>In all other states, this method SHOULD fail with the error
+ NotAvailable.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The call was <tp:dbus-ref namespace="ofdT.Channel"
+ >Requested</tp:dbus-ref>, so ringing does not make sense.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call is no longer in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For incoming calls in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver, accept the
+ incoming call; this changes the
+ <tp:member-ref>CallState</tp:member-ref> to
+ <tp:type>Call_State</tp:type>_Accepted.</p>
+
+ <p>For outgoing calls in state
+ <tp:type>Call_State</tp:type>_Pending_Initiator, actually
+ call the remote contact; this changes the
+ <tp:member-ref>CallState</tp:member-ref> to
+ <tp:type>Call_State</tp:type>_Pending_Receiver.</p>
+
+ <p>Otherwise, this method SHOULD fail with the error NotAvailable.</p>
+
+ <p>This method should be called exactly once per Call, by whatever
+ client (user interface) is handling the channel.</p>
+
+ <p>When this method is called, for each <tp:dbus-ref
+ namespace="ofdT.Call" >Content.DRAFT</tp:dbus-ref> whose
+ <tp:dbus-ref namespace="ofdT.Call.Content.DRAFT"
+ >Disposition</tp:dbus-ref> is
+ <tp:type>Call_Content_Disposition</tp:type>_Initial, any
+ streams where the <tp:dbus-ref
+ namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref>
+ is <tp:type>Sending_State</tp:type>_Pending_Send will be
+ moved to <tp:type>Sending_State</tp:type>_Sending as if
+ <tp:dbus-ref namespace="ofdT.Call.Stream.DRAFT"
+ >SetSending</tp:dbus-ref>(True) had been called.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call is not in one of the states where this method makes sense.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Hangup" tp:name-for-bindings="Hangup">
+ <tp:docstring>
+ Request that the call is ended. All contents will be removed
+ from the Call so that the
+ <tp:member-ref>Contents</tp:member-ref> property will be the
+ empty list.
+ </tp:docstring>
+
+ <arg direction="in" name="Reason"
+ type="u" tp:type="Call_State_Change_Reason">
+ <tp:docstring>
+ A generic hangup reason.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Detailed_Hangup_Reason"
+ type="s" tp:type="DBus_Error_Name">
+ <tp:docstring>
+ A more specific reason for the call hangup, if one is available, or
+ an empty string otherwise.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A human-readable message to be sent to the remote contact(s).
+
+ <tp:rationale>
+ XMPP Jingle allows calls to be terminated with a human-readable
+ message.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The call has already been ended.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AddContent" tp:name-for-bindings="Add_Content">
+ <tp:docstring>
+ Request that a new <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> of type
+ Content_Type is added to the Call. Handlers should check the
+ value of the <tp:member-ref>MutableContents</tp:member-ref>
+ property before trying to add another content as it might not
+ be allowed.
+ </tp:docstring>
+ <arg direction="in" name="Content_Name" type="s">
+ <tp:docstring>
+ <p>The suggested name of the content to add.</p>
+
+ <tp:rationale>
+ The content name property should be meaningful, so should
+ be given a name which is significant to the user. The name
+ could be a localized "audio", "video" or perhaps include
+ some string identifying the source, such as a webcam
+ identifier.
+ </tp:rationale>
+
+ <p>If there is already a content with the same name as this
+ property then a sensible suffix should be added. For example,
+ if this argument is "audio" but a content of the same name
+ already exists, a sensible suffix such as " (1)" is appended
+ to name the new content "audio (1)". A further content with the
+ name "audio" would then be named "audio (2)".</p>
+
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Content_Type" type="u"
+ tp:type="Media_Stream_Type">
+ <tp:docstring>
+ The media stream type of the content to be added to the
+ call.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Content" type="o">
+ <tp:docstring>
+ Path to the newly-created <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Call.Content.DRAFT</tp:dbus-ref> object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The media stream type given is invalid.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The media stream type requested is not implemented by the
+ CM.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The content type requested cannot be added to this
+ call. Examples of why this might be the case include
+ because a second video stream cannot be added, or a
+ content cannot be added when the content set isn't
+ mutable.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="ContentAdded"
+ tp:name-for-bindings="Content_Added">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call"
+ >Content.DRAFT</tp:dbus-ref> is added to the call.</p>
+ </tp:docstring>
+ <arg name="Content" type="o">
+ <tp:docstring>
+ Path to the newly-created <tp:dbus-ref namespace="ofdT.Call"
+ >Content.DRAFT</tp:dbus-ref> object.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ContentRemoved" tp:name-for-bindings="Content_Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a <tp:dbus-ref namespace="ofdT.Call"
+ >Content.DRAFT</tp:dbus-ref> is removed from the call.</p>
+ </tp:docstring>
+ <arg name="Content" type="o">
+ <tp:docstring>
+ The <tp:dbus-ref namespace="ofdT.Call"
+ >Content.DRAFT</tp:dbus-ref> which was removed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Contents" type="ao" access="read"
+ tp:name-for-bindings="Contents">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> objects that
+ are part of this call. Change notification is via the
+ <tp:member-ref>ContentAdded</tp:member-ref> and
+ <tp:member-ref>ContentRemoved</tp:member-ref> signals.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum type="u" name="Call_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The state of a call, as a whole.</p>
+
+ <p>The allowed transitions are:</p>
+
+ <ul>
+ <li>Pending_Initiator → Pending_Receiver (for outgoing calls,
+ when <tp:member-ref>Accept</tp:member-ref> is called)</li>
+ <li>Pending_Receiver → Accepted (for incoming calls, when
+ <tp:member-ref>Accept</tp:member-ref> is called; for outgoing
+ calls to a contact, when the remote contact accepts the call;
+ for joining a conference call, when the local user successfully
+ joins the conference)</li>
+ <li>Accepted → Pending_Receiver (when transferred to another
+ contact)</li>
+ <li>any state → Ended (when the call is terminated normally, or
+ when an error occurs)</li>
+ </ul>
+
+ <p>Clients MAY consider unknown values from this enum to be an
+ error - additional values will not be defined after the Call
+ specification is declared to be stable.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value = "0">
+ <tp:docstring>
+ The call state is not known. This call state MUST NOT appear as a
+ value of the <tp:member-ref>CallState</tp:member-ref> property, but
+ MAY be used by client code to represent calls whose state is as yet
+ unknown.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Pending_Initiator" value = "1">
+ <tp:docstring>
+ The initiator of the call hasn't accepted the call yet. This state
+ only makes sense for outgoing calls, where it means that the local
+ user has not yet sent any signalling messages to the remote user(s),
+ and will not do so until <tp:member-ref>Accept</tp:member-ref> is
+ called.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Pending_Receiver" value = "2">
+ <tp:docstring>
+ The receiver (the contact being called) hasn't accepted the call yet.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Accepted" value = "3">
+ <tp:docstring>
+ The contact being called has accepted the call.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Ended" value = "4">
+ <tp:docstring>
+ The call has ended, either via normal termination or an error.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:flags name="Call_Flags" value-prefix="Call_Flag" type="u">
+ <tp:docstring>
+ A set of flags representing the status of the call as a whole,
+ providing more specific information than the
+ <tp:member-ref>CallState</tp:member-ref>. Many of these flags only make
+ sense in a particular state.
+ </tp:docstring>
+
+ <tp:flag suffix="Locally_Ringing" value="1">
+ <tp:docstring>
+ The local contact has been alerted about the call but has not
+ responded; if possible, the remote contact(s) have been informed of
+ this fact. This flag only makes sense on incoming calls in
+ state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD
+ be set when <tp:member-ref>SetRinging</tp:member-ref> is
+ called successfully, and unset when the state changes.
+ </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).
+ This flag only makes sense on outgoing 1-1 calls in
+ state <tp:type>Call_State</tp:type>_Pending_Receiver. It SHOULD be
+ set or unset according to informational messages from other
+ contacts.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Locally_Held" value="4">
+ <tp:docstring>
+ The call has been put on hold by the local user, e.g. using
+ the <tp:dbus-ref namespace="ofdT.Channel.Interface"
+ >Hold</tp:dbus-ref> interface. This flag SHOULD only be set
+ if there is at least one Content, and all Contents are
+ locally held; it makes sense on calls in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver
+ or <tp:type>Call_State</tp:type>_Accepted.
+
+ <tp:rationale>
+ Otherwise, in transient situations where some but not all contents
+ are on hold, UIs would falsely indicate that the call as a whole
+ is on hold, which could lead to the user saying something they'll
+ regret, while under the impression that the other contacts can't
+ hear them!
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Forwarded" value="8">
+ <tp:docstring>
+ The initiator of the call originally called a contact other than the
+ current recipient of the call, but the call was then forwarded or
+ diverted. This flag only makes sense on outgoing calls, in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver or
+ <tp:type>Call_State</tp:type>_Accepted. It SHOULD be set or unset
+ according to informational messages from other contacts.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ contact may not have been made aware of the call yet
+ (so the Ringing state is not appropriate). This corresponds to SIP's
+ status code 183 Session Progress, and could be used when the
+ outgoing call has reached a gateway, for instance.
+ This flag only makes sense on outgoing calls in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver, and SHOULD be set
+ or unset according to informational messages from servers, gateways
+ and other infrastructure.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Clearing" value="32">
+ <tp:docstring>
+ This flag only occurs when the CallState is Ended. The call with
+ this flag set has ended, but not all resources corresponding to the
+ call have been freed yet.
+
+ Depending on the protocol there might be some audible feedback while
+ the clearing flag is set.
+
+ <tp:rationale>
+ In calls following the ITU-T Q.931 standard there is a period of
+ time between the call ending and the underlying channel being
+ completely free for re-use.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Muted" value="64">
+ <tp:docstring>
+ The call has been muted by the local user, e.g. using the
+ <tp:dbus-ref namespace="ofdT.Call.Content.Interface"
+ >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only
+ be set if there is at least one Content, and all Contents
+ are locally muted; it makes sense on calls in state
+ <tp:type>Call_State</tp:type>_Pending_Receiver or
+ <tp:type>Call_State</tp:type>_Accepted.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="CallStateDetails"
+ tp:name-for-bindings="Call_State_Details" type="a{sv}" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map used to provide optional extensible details for the
+ <tp:member-ref>CallState</tp:member-ref>,
+ <tp:member-ref>CallFlags</tp:member-ref> and/or
+ <tp:member-ref>CallStateReason</tp:member-ref>.</p>
+
+ <p>Well-known keys and their corresponding value types include:</p>
+
+ <dl>
+ <dt>hangup-message - s</dt>
+ <dd>An optional human-readable message sent when the call was ended,
+ corresponding to the Message argument to the
+ <tp:member-ref>Hangup</tp:member-ref> method. This is only
+ applicable when the call state is <tp:type>Call_State</tp:type>_Ended.
+ <tp:rationale>
+ XMPP Jingle can send such messages.
+ </tp:rationale>
+ </dd>
+
+ <dt>queue-message - s</dt>
+ <dd>An optional human-readable message sent when the local contact
+ is being held in a queue. This is only applicable when
+ <tp:type>Call_Flags</tp:type>_Queued is in the call flags.
+ <tp:rationale>
+ SIP 182 notifications can have human-readable messages attached.
+ </tp:rationale>
+ </dd>
+
+ <dt>debug-message - s</dt>
+ <dd>A message giving further details of any error indicated by the
+ <tp:member-ref>CallStateReason</tp:member-ref>. This will not
+ normally be localized or suitable for display to users, and is only
+ applicable when the call state is
+ <tp:type>Call_State</tp:type>_Ended.</dd>
+ </dl>
+ </tp:docstring>
+ </property>
+
+ <property name="CallState" type="u" access="read"
+ tp:name-for-bindings="Call_State" tp:type="Call_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The current high-level state of this call. The
+ <tp:member-ref>CallFlags</tp:member-ref> provide additional
+ information, and the <tp:member-ref>CallStateReason</tp:member-ref>
+ and <tp:member-ref>CallStateDetails</tp:member-ref> explain the
+ reason for the current values for those properties.</p>
+
+ <p>Note that when in a conference call, this property is
+ purely to show your state in joining the call. The receiver
+ (or remote contact) in this context is the conference server
+ itself. The property does not change when other call members'
+ states change.</p>
+
+ <p>Clients MAY consider unknown values in this property to be an
+ error.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CallFlags" type="u" access="read"
+ tp:name-for-bindings="Call_Flags" tp:type="Call_Flags">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Flags representing the status of the call as a whole,
+ providing more specific information than the
+ <tp:member-ref>CallState</tp:member-ref>.</p>
+
+ <p>Clients are expected to ignore unknown flags in this property,
+ without error.</p>
+
+ <p>When an ongoing call is active and not on hold or has any
+ other problems, this property will be 0.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_State_Change_Reason" type="u">
+ <tp:docstring>
+ A simple representation of the reason for a change in the call's
+ state, which may be used by simple clients, or used as a fallback
+ when the DBus_Reason member of a <tp:type>Call_State_Reason</tp:type>
+ struct is not understood.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ We just don't know. Unknown values of this enum SHOULD also be
+ treated like this.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="User_Requested" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change was requested by the contact indicated by the Actor
+ member of a <tp:type>Call_State_Reason</tp:type> struct.</p>
+
+ <p>If the Actor is the local user, the DBus_Reason SHOULD be the
+ empty string.</p>
+
+ <p>If the Actor is a remote user, the DBus_Reason SHOULD be the empty
+ string if the call was terminated normally, but MAY be a non-empty
+ error name to indicate error-like call termination reasons (call
+ rejected as busy, kicked from a conference by a moderator, etc.).</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Forwarded" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The call was forwarded. If known, the handle of the contact
+ the call was forwarded to will be indicated by the Actor member
+ of a <tp:type>Call_State_Reason</tp:type> struct.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="No_Answer" value="3">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The <tp:member-ref>CallState</tp:member-ref> changed from
+ <tp:type>Call_State</tp:type>_Pending_Receiver to
+ <tp:type>Call_State</tp:type>_Ended because the initiator
+ ended the call before the receiver accepted it. With an
+ incoming call this state change reason signifies a missed
+ call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Call_State_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A description of the reason for a change to the
+ <tp:member-ref>CallState</tp:member-ref> and/or
+ <tp:member-ref>CallFlags</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <tp:member type="u" tp:type="Contact_Handle" name="Actor">
+ <tp:docstring>
+ The contact responsible for the change, or 0 if no contact was
+ responsible.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" tp:type="Call_State_Change_Reason" name="Reason">
+ <tp:docstring>
+ The reason, chosen from a limited set of possibilities defined by
+ the Telepathy specification. If
+ <tp:type>Call_State_Change_Reason</tp:type>_User_Requested then
+ the Actor member will dictate whether it was the local user or
+ a remote contact responsible.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="s" tp:type="DBus_Error_Name" name="DBus_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specific reason for the change, which may be a D-Bus error in
+ the Telepathy namespace, a D-Bus error in any other namespace
+ (for implementation-specific errors), or the empty string to
+ indicate that the state change was not an error.</p>
+
+ <p>This SHOULD be an empty string for changes to any state other
+ than Ended.</p>
+
+ <p>The errors Cancelled and Terminated SHOULD NOT be used here;
+ an empty string SHOULD be used instead.</p>
+
+ <tp:rationale>
+ <p>Those error names are used to indicate normal call
+ termination by the local user or another user, respectively,
+ in contexts where a D-Bus error name must appear.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="CallStateReason" tp:name-for-bindings="Call_State_Reason"
+ type="(uus)" access="read" tp:type="Call_State_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The reason for the last change to the
+ <tp:member-ref>CallState</tp:member-ref> and/or
+ <tp:member-ref>CallFlags</tp:member-ref>. The
+ <tp:member-ref>CallStateDetails</tp:member-ref> MAY provide additional
+ information.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="CallStateChanged"
+ tp:name-for-bindings="Call_State_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the state of the call as a whole changes.</p>
+
+ <p>This signal is emitted for any change in the properties
+ corresponding to its arguments, even if the other properties
+ referenced remain unchanged.</p>
+ </tp:docstring>
+
+ <arg name="Call_State" type="u" tp:type="Call_State">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallState</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_Flags" type="u" tp:type="Call_Flags">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallFlags</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Call_State_Details" type="a{sv}">
+ <tp:docstring>
+ The new value of the <tp:member-ref>CallStateDetails</tp:member-ref>
+ property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="HardwareStreaming" tp:name-for-bindings="Hardware_Streaming"
+ type="b" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If this property is True, all of the media streaming is done by some
+ mechanism outside the scope of Telepathy.</p>
+
+ <tp:rationale>
+ <p>A connection manager might be intended for a specialized hardware
+ device, which will take care of the audio streaming (e.g.
+ telepathy-yafono, which uses GSM hardware which does the actual
+ audio streaming for the call).</p>
+ </tp:rationale>
+
+ <p>If this is False, the handler is responsible for doing the actual
+ media streaming for at least some contents itself. Those contents
+ will have the <tp:dbus-ref namespace="ofdT.Call.Content.Interface"
+ >Media.DRAFT</tp:dbus-ref> interface, to communicate the necessary
+ information to a streaming implementation. Connection managers SHOULD
+ operate like this, if possible.</p>
+
+ <tp:rationale>
+ <p>Many connection managers (such as telepathy-gabble) only do the
+ call signalling, and expect the client to do the actual streaming
+ using something like
+ <a href="http://farsight.freedesktop.org/">Farsight</a>, to improve
+ latency and allow better UI integration.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <tp:flags type="u" name="Call_Member_Flags" value-prefix="Call_Member_Flag">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A set of flags representing the status of a remote contact in a
+ call.</p>
+
+ <p>It is protocol- and client-specific whether a particular contact
+ will ever have a particular flag set on them, and Telepathy clients
+ SHOULD NOT assume that a flag will ever be set.</p>
+
+ <tp:rationale>
+ <p>180 Ringing in SIP, and its equivalent in XMPP, are optional
+ informational messages, and implementations are not required
+ to send them. The same applies to the messages used to indicate
+ hold state.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:flag suffix="Ringing" value = "1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The remote contact's client has told us that the contact has been
+ alerted about the call but has not responded.</p>
+
+ <tp:rationale>
+ <p>This is a flag per member, not a flag for the call as a whole,
+ because in Muji conference calls, you could invite someone and
+ have their state be "ringing" for a while.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Held" value = "2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The call member has put this call on hold.</p>
+
+ <tp:rationale>
+ <p>This is a flag per member, not a flag for the call as a whole,
+ because in conference calls, any member could put the conference
+ on hold.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Conference_Host" value="4">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This contact has merged this call into a conference. Note that GSM
+ provides a notification when the remote party merges a call into a
+ conference, but not when it is split out again; thus, this flag can
+ only indicate that the call has been part of a conference at some
+ point. If a GSM connection manager receives a notification that a
+ call has been merged into a conference a second time, it SHOULD
+ represent this by clearing and immediately re-setting this flag on
+ the remote contact.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:mapping name="Call_Member_Map" array-name="Call_Member_Map_List">
+ <tp:docstring>A mapping from handles to their current state in the call.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Handle" name="key"/>
+ <tp:member type="u" tp:type="Call_Member_Flags" name="Flag"/>
+ </tp:mapping>
+
+ <signal name="CallMembersChanged"
+ tp:name-for-bindings="Call_Members_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>CallMembers</tp:member-ref> property
+ changes in any way, either because contacts have been added to the
+ call, contacts have been removed from the call, or contacts' flags
+ have changed.
+ </tp:docstring>
+
+ <arg name="Flags_Changed" type="a{uu}" tp:type="Call_Member_Map">
+ <tp:docstring>
+ A map from members of the call to their new call member flags,
+ including at least the members who have been added to
+ <tp:member-ref>CallMembers</tp:member-ref>, and the members whose
+ flags have changed.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who have left the call, i.e. keys to be removed
+ from <tp:member-ref>CallMembers</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CallMembers" tp:name-for-bindings="Call_Members"
+ type="a{uu}" access="read" tp:type="Call_Member_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A mapping from the remote contacts that are part of this call to flags
+ describing their status. This mapping never has the local user's handle
+ as a key.</p>
+
+ <p>When the call ends, this property should be an empty list,
+ and notified with
+ <tp:member-ref>CallMembersChanged</tp:member-ref></p>
+
+ <p>If the Call implements
+ <tp:dbus-ref namespace="ofdT.Channel.Interface"
+ >Group</tp:dbus-ref> and the Group members are
+ channel-specific handles, then this call SHOULD also use
+ channel-specific handles.</p>
+
+ <p>Anonymous members are exposed as channel-specific handles
+ with no owner.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialTransport" tp:name-for-bindings="Initial_Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read"
+ tp:requestable="yes" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If set on a requested channel, this indicates the transport that
+ should be used for this call. Where not applicable, this property
+ is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown,
+ in particular, on CMs with hardware streaming.</p>
+
+ <tp:rationale>
+ When implementing a voip gateway one wants the outgoing leg of the
+ gatewayed to have the same transport as the incoming leg. This
+ property allows the gateway to request a Call with the right
+ transport from the CM.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
+ type="b" access="read" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If set to True in a channel request that will create a new channel,
+ the connection manager should immediately attempt to establish an
+ audio stream to the remote contact, making it unnecessary for the
+ client to call <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">AddContent</tp:dbus-ref>.</p>
+
+ <p>If this property, or InitialVideo, is passed to EnsureChannel
+ (as opposed to CreateChannel), the connection manager SHOULD ignore
+ these properties when checking whether it can return an existing
+ channel as suitable; these properties only become significant when
+ the connection manager has decided to create a new channel.</p>
+
+ <p>If True on a requested channel, this indicates that the audio
+ stream has already been requested and the client does not need to
+ call RequestStreams, although it MAY still do so.</p>
+
+ <p>If True on an unrequested (incoming) channel, this indicates that
+ the remote contact initially requested an audio stream; this does
+ not imply that that audio stream is still active (as indicated by
+ <tp:dbus-ref namespace="ofdT.Channel.Type.Call.DRAFT"
+ >Contents</tp:dbus-ref>).</p>
+
+ <p>The name of this new content can be decided by using the
+ <tp:member-ref>InitialAudioName</tp:member-ref> property.</p>
+
+ <p>Connection managers that support the <tp:dbus-ref
+ namespace="ofdT.Connection.Interface">ContactCapabilities</tp:dbus-ref>
+ interface SHOULD represent the capabilities of receiving audio
+ and/or video calls by including a channel class in
+ a contact's capabilities with ChannelType = Call
+ in the fixed properties dictionary, and InitialAudio and/or
+ InitialVideo in the allowed properties list. Clients wishing to
+ discover whether a particular contact is likely to be able to
+ receive audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all clients support video calls, and it would also be
+ possible (although unlikely) to have a client which could only
+ stream video, not audio.</p>
+ </tp:rationale>
+
+ <p>Clients that are willing to receive audio and/or video calls
+ SHOULD include the following among their channel classes if
+ calling <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
+ (clients of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ SHOULD instead arrange for the ChannelDispatcher to do this,
+ by including the filters in their <tp:dbus-ref
+ namespace="ofdT.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ properties):</p>
+
+ <ul>
+ <li>{ ChannelType = Call }</li>
+ <li>{ ChannelType = Call, InitialAudio = True }
+ if receiving calls with audio is supported</li>
+ <li>{ ChannelType = Call, InitialVideo = True }
+ if receiving calls with video is supported</li>
+ </ul>
+
+ <tp:rationale>
+ <p>Connection managers for protocols with capability discovery,
+ like XMPP, need this information to advertise the appropriate
+ capabilities for their protocol.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
+ type="b" access="read" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
+ a video stream. This property is immutable (cannot change).</p>
+
+ <p>In particular, note that if this property is False, this does not
+ imply that an active video stream has not been added, only that no
+ video stream was active at the time the channel appeared.</p>
+
+ <p>This property is the correct way to discover whether connection
+ managers, contacts etc. support video calls; it appears in
+ capabilities structures in the same way as InitialAudio.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialAudioName" tp:name-for-bindings="Initial_Audio_Name"
+ type="s" access="read" tp:immutable="yes" tp:requestable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tp:member-ref>InitialAudio</tp:member-ref> is set to
+ True, then this property will name the intial audio content
+ with the value of this property.</p>
+
+ <tp:rationale>
+ <p>Content names are meant to be significant, but if no name
+ can be given to initial audio content, then its name cannot
+ be meaningful or even localized.</p>
+ </tp:rationale>
+
+ <p>If this property is empty or missing from the channel
+ request and InitialAudio is True, then the CM must come up
+ with a sensible for the content, such as "audio".</p>
+
+ <p>If the protocol has no concept of stream names then this
+ property will not show up in the allowed properties list of
+ the Requestable Channel Classes for call channels.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialVideoName" tp:name-for-bindings="Initial_Video_Name"
+ type="s" access="read" tp:immutable="yes" tp:requestable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as
+ <tp:member-ref>InitialAudioName</tp:member-ref>, but for a
+ video stream created by setting
+ <tp:member-ref>InitialVideo</tp:member-ref> to True. This
+ property is immutable and so cannot change.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="MutableContents" tp:name-for-bindings="Mutable_Contents"
+ type="b" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If True, a stream of a different content type can be added
+ after the Channel has been requested </p>
+
+ <p>If this property is missing, clients SHOULD assume that it is False,
+ and thus that the channel's streams cannot be changed once the call
+ has started.</p>
+
+ <p>If this property isn't present in the "allowed" set in any of the
+ Call entries contact capabilities, then user interfaces MAY choose to
+ show a separate "call" option for each class of call.</p>
+
+ <tp:rationale>
+ <p>For example, once an audio-only Google Talk call has started,
+ it is not possible to add a video stream; both audio and video
+ must be requested at the start of the call if video is desired.
+ User interfaces may use this pseudo-capability as a hint to
+ display separate "Audio call" and "Video call" buttons, rather
+ than a single "Call" button with the option to add and remove
+ video once the call has started for contacts without this flag.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <tp:hct name="audio">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This client supports audio calls.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="video">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This client supports video calls.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="gtalk-p2p">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is <tp:type>Stream_Transport_Type</tp:type>_GTalk_P2P.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="ice">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is <tp:type>Stream_Transport_Type</tp:type>_ICE.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="wlm-2009">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is <tp:type>Stream_Transport_Type</tp:type>_WLM_2009.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="shm">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Interface.Media.DRAFT">Transport</tp:dbus-ref>
+ property is <tp:type>Stream_Transport_Type</tp:type>_SHM.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="video/h264" is-family="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on Call channels.</p>
+ </tp:rationale>
+
+ <p>For example, a client could advertise support for audio and video
+ calls using Speex, Theora and H264 by having five handler capability
+ tokens in its <tp:dbus-ref
+ namespace="ofdT.Client.Handler">Capabilities</tp:dbus-ref>
+ property:</p>
+
+ <ul>
+ <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio</code></li>
+ <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/audio/speex</code></li>
+ <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video</code></li>
+ <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/theora</code></li>
+ <li><code>org.freedesktop.Telepathy.Channel.Type.Call.DRAFT/video/h264</code></li>
+ </ul>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:hct>
+
+ </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
new file mode 100644
index 0000000..5a0d333
--- /dev/null
+++ b/spec/Channel_Type_Contact_List.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Contact_List" 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) 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.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
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
+ for managing buddy lists and privacy lists
+ on the server. This channel type has no methods because all of the
+ functionality it represents is available via the group interface.</p>
+
+ <p>There are currently two types of contact list:
+ HANDLE_TYPE_LIST is a &quot;magic&quot; server-defined list, and
+ HANDLE_TYPE_GROUP is a user-defined contact group.</p>
+
+ <p>For server-defined lists like the subscribe list, singleton instances
+ 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
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>
+ with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_LIST and one of the
+ following identifiers:</p>
+
+ <ul>
+ <li>subscribe - the group of contacts for whom you receive presence</li>
+ <li>publish - the group of contacts who may receive your presence</li>
+ <li>hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence</li>
+ <li>allow - a group of contacts who may send you messages</li>
+ <li>deny - a group of contacts who may not send you messages</li>
+ <li>stored - on protocols where the user's contacts are stored, this
+ contact list contains all stored contacts regardless of subscription
+ status.</li>
+ </ul>
+
+ <p>A contact can be in several server-defined lists. All lists are optional
+ to implement. If <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
+ for a particular contact list raises an error, this indicates that the
+ connection manager makes no particular statement about the list's contents;
+ clients MUST NOT consider this to be fatal.</p>
+
+ <p>If a client wants to list all of a user's contacts, it is appropriate to
+ use the union of the subscribe, publish and stored lists, including the
+ local and remote pending members.</p>
+
+ <p>For example in XMPP, contacts who have the subscription type "none",
+ "from", "to" and "both" can be respectively in the lists:</p>
+
+ <ul>
+ <li>"none": stored</li>
+ <li>"from": stored and publish</li>
+ <li>"to": stored and subscribe</li>
+ <li>"both": stored, publish and subscribe</li>
+ </ul>
+
+ <p>These contact list channels may not be closed.</p>
+
+ <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
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>
+ with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_GROUP and with the
+ name set to the human-readable UTF-8 name of the group.</p>
+
+ <p>User-defined groups may be deleted by calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> on the
+ channel, but only if
+ the group is already empty. Closing a channel to a non-empty group is
+ not allowed; its members must be set to the empty set first.</p>
+
+ <p>On some protocols (e.g. XMPP) empty groups are not represented on the
+ 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
new file mode 100644
index 0000000..fefa77a
--- /dev/null
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -0,0 +1,462 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 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.Channel.Type.ContactSearch">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.19.10">
+ as stable API. Changes from draft 2:
+ <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers
+ rather than handles; consequently, the values need not include
+ <tt>x-telepathy-identifier</tt>.
+ </tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for searching server-stored user directories. A new
+ channel should be requested by a client for each search attempt, and
+ closed when the search is completed or the required result has been
+ found. Channels of this type should have <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+ <code>None</code> (and hence <tp:dbus-ref
+ namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and
+ <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>
+ <code>""</code>). Requests for channels of this type need only
+ optionally specify the <tp:member-ref>Server</tp:member-ref> property
+ (if it is an allowed property in the connection's <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p>
+
+ <p>Before searching, the
+ <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
+ inspected to determine the valid search keys which can be provided to
+ the <tp:member-ref>Search</tp:member-ref> method. A search request is
+ then started by providing some of these terms to the Search method, and
+ the <tp:member-ref>SearchState</tp:member-ref> will change from
+ <code>Not_Started</code> to <code>In_Progress</code>. As results are
+ returned by the server, the
+ <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
+ for each contact found; when the search is complete, the search state
+ will be set to <code>Completed</code>. If the search fails after Search
+ has been called, the state will change to <code>Failed</code>. A
+ running search can be cancelled by calling
+ <tp:member-ref>Stop</tp:member-ref>.</p>
+
+ <p>If the protocol supports limiting the number of results returned by a
+ search and subsequently requesting more results, after
+ <tp:member-ref>Limit</tp:member-ref> results have been received the
+ search state will be set to <code>More_Available</code>. Clients may
+ call <tp:member-ref>More</tp:member-ref> to request another
+ <tp:member-ref>Limit</tp:member-ref> results. If allowed by the
+ connection manager, clients may specify the "page size" by specifying
+ <tp:member-ref>Limit</tp:member-ref> when calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ </p>
+
+ <p>The client should call the channel's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method when it is finished with the channel.</p>
+
+ <p>Each channel can only be used for a single search; a new channel
+ should be requested for each subsequent search. Connection managers
+ MUST support multiple ContactSearch channels being open at once (even
+ to the same server, if applicable).</p>
+
+ <p>It does not make sense to request this channel type using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
+ clients SHOULD request channels of this type using
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+ instead.</p>
+
+ <tp:rationale>
+ <p>A contact search channel that is already in use for a different
+ search isn't useful.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:enum name="Channel_Contact_Search_State" type="u">
+ <tp:enumvalue suffix="Not_Started" value="0">
+ <tp:docstring>The search has not started</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="In_Progress" value="1">
+ <tp:docstring>The search is in progress</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="More_Available" value="2">
+ <tp:docstring>The search has paused, but more results can be retrieved
+ by calling <tp:member-ref>More</tp:member-ref>.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Completed" value="3">
+ <tp:docstring>The search has been completed</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Failed" value="4">
+ <tp:docstring>The search has failed</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="SearchState" tp:name-for-bindings="Search_State"
+ access="read" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>
+ The current state of this search channel object. Change notification
+ is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="SearchStateChanged"
+ tp:name-for-bindings="Search_State_Changed">
+ <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>The new search state</tp:docstring>
+ </arg>
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ If the new state is <code>Failed</code>, the name of a D-Bus error
+ describing what went wrong. Otherwise, the empty string.
+ </tp:docstring>
+ </arg>
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about the state transition, which may
+ include the following well-known keys:</p>
+
+ <dl>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ </dl>
+
+ <tp:rationale>
+ <p>This argument allows for future extensions. For instance,
+ if moving to state <code>Failed</code> because the server
+ rejected one of our search terms, we could define a key
+ that indicates which terms were invalid.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+ changes. The implementation MUST NOT make transitions other than the
+ following:</p>
+
+ <ul>
+ <li><code>Not_Started</code> → <code>In_Progress</code></li>
+ <li><code>In_Progress</code> → <code>More_Available</code></li>
+ <li><code>More_Available</code> → <code>In_Progress</code></li>
+ <li><code>In_Progress</code> → <code>Completed</code></li>
+ <li><code>In_Progress</code> → <code>Failed</code></li>
+ </ul>
+ </tp:docstring>
+ </signal>
+
+ <tp:simple-type name="Contact_Search_Key" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Any of the following search keys, with the indicated result for
+ the search:</p>
+
+ <dl>
+ <dt>The empty string</dt>
+ <dd>Search for the search term in some implementation-dependent
+ set of fields, using an implementation-dependent algorithm
+ (e.g. searching for each word mentioned)
+ <tp:rationale>
+ The "one big search box" approach to searching, as is familiar
+ from Google. The Sametime plugin to Pidgin appears to search in
+ this way.
+ </tp:rationale>
+ </dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type></dt>
+ <dd>Search for the search term in fields matching that name (for
+ instance, <code>nickname</code> would search nicknames, and
+ <code>tel</code> would search any available phone number,
+ regardless of its work/home/mobile/... status).</dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type> followed by
+ "<code>;</code>" and a
+ <tp:type>VCard_Type_Parameter</tp:type> of the form
+ "<code>type=...</code>"</dt>
+ <dd>Search for the search term in fields of that name and type
+ only (for instance, <code>tel;type=mobile</code>).</dd>
+
+ <dt><code>x-telepathy-identifier</code></dt>
+ <dd>Search for contacts whose identifier in the IM protocol
+ matches the search term (e.g. contains it as a substring)
+ <tp:rationale>
+ Otherwise, starting a search by identifier would require the UI
+ to know the vCard field name corresponding to identifiers in
+ this protocol, which might be non-standard (like
+ <code>x-jabber</code>) or not exist at all.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-gender</code></dt>
+ <dd>For the search term "male" or "female", search only for contacts
+ listed as male or female, respectively. The results for other
+ search terms are undefined; it is likely that contacts with
+ unspecified gender will only be matched if this search key
+ is omitted from the request.
+ <tp:rationale>
+ Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
+ also supports limiting search results by gender.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-family</code></dt>
+ <dd>Search for the search term in contacts' family names
+ (the first component of the vCard field <code>n</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC seem to support this mode of searching.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-given</code></dt>
+ <dd>Search for the search term in contacts' given names
+ (the second component of the vCard field <code>n</code>).
+ <tp:rationale>
+ As for <code>x-n-family</code>.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-online</code></dt>
+ <dd>For the search term "yes", search only for contacts who are
+ currently online. The results for other search terms are undefined.
+ <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
+ </dd>
+
+ <dt><code>x-adr-locality</code></dt>
+ <dd>Search for the search term as a locality or city (the fourth
+ component of the vCard field <code>adr</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC appear to support this.
+ </tp:rationale>
+ </dd>
+ </dl>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="Limit" type="u" access="read" tp:name-for-bindings="Limit"
+ tp:immutable='yes' tp:requestable='sometimes'>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If supported by the protocol, the maximum number of results that
+ should be returned, where <code>0</code> represents no limit. If the
+ protocol does not support limiting results, this should be
+ <code>0</code>.</p>
+
+ <p>For example, if the terms passed to
+ <tp:member-ref>Search</tp:member-ref> match <i>Antonius</i>,
+ <i>Bridget</i> and <i>Charles</i> and this property is
+ <code>2</code>, the search service SHOULD only return <i>Antonius</i>
+ and <i>Bridget</i>.</p>
+
+ <p>This property SHOULD be requestable if and only if the protocol
+ supports specifying a limit; implementations SHOULD use
+ <code>0</code> as the default if possible, or a protocol-specific
+ sensible default otherwise.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="AvailableSearchKeys" type="as" access="read"
+ tp:name-for-bindings="Available_Search_Keys" tp:immutable='yes'>
+ <tp:docstring>
+ The set of search keys supported by this channel. Example values
+ include [""] (for protocols where several address fields are
+ implicitly searched) or ["x-n-given", "x-n-family", "nickname",
+ "email"] (for XMPP XEP-0055, without extensibility via Data Forms).
+
+ <tp:rationale>
+ It can be in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal for round-trip reduction.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Contact_Search_Map">
+ <tp:docstring>A map from search keys to search terms.</tp:docstring>
+ <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
+ <tp:docstring>
+ The search key to match against
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Term" type="s">
+ <tp:docstring>
+ The term or terms to be searched for in the search key; depending on
+ the protocol and the server implementation, this may be matched by
+ exact or approximate equality, substring matching, word matching
+ or any other matching algorithm
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="Search" tp:name-for-bindings="Search">
+ <arg direction="in" name="Terms"
+ type="a{ss}" tp:type="Contact_Search_Map">
+ <tp:docstring>
+ A dictionary mapping search key names to the desired values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Send a request to start a search for contacts on this connection. This
+ may only be called while the <tp:member-ref>SearchState</tp:member-ref>
+ is Not_Started; a valid search request will cause the
+ <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
+ with the state In_Progress.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is no longer
+ Not_Started, so this method is no longer available.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The search terms included something this connection manager cannot
+ search for.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="More" tp:name-for-bindings="More">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Request that a search in <tp:member-ref>SearchState</tp:member-ref>
+ <code>More_Available</code> move back to state <code>In_Progress</code>
+ and continue listing up to <tp:member-ref>Limit</tp:member-ref> more results.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is not
+ <code>More_Available</code>.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Stop" tp:name-for-bindings="Stop">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Stop the current search. This may not be called while the
+ <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called
+ while the SearchState is In_Progress,
+ <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted,
+ with the state Failed and the error
+ <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Cancelled</tp:error-ref></code>.</p>
+
+ <p>Calling this method on a search in state Completed or Failed
+ succeeds, but has no effect.</p>
+
+ <tp:rationale>
+ <p>Specifying Stop to succeed when the search has finished means that
+ clients who call Stop just before receiving
+ <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to
+ handle a useless error.</p>
+ </tp:rationale>
+
+ <p>Depending on the protocol, the connection manager may not be
+ able to prevent the server from sending further results after this
+ method returns; if this is the case, it MUST ignore any further
+ results.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so
+ this method is not yet available.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:mapping name="Contact_Search_Result_Map">
+ <tp:docstring>A map from contact identifier to search result, emitted in
+ the <tp:member-ref>SearchResultReceived</tp:member-ref>
+ signal.</tp:docstring>
+
+ <tp:member name="Contact_Identifier" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The identifier of a contact matching the search terms.
+
+ <tp:rationale>
+ This is an identifier rather than a handle in case we make handles
+ immortal; see <a
+ href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a>
+ and <a
+ href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347
+ comment 5</a>.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of fields representing information about this
+ contact, in the same format used in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo</tp:dbus-ref>
+ interface. It is possible that a separate call to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref>
+ would return more information than this signal provides.</p>
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="SearchResultReceived"
+ tp:name-for-bindings="Search_Result_Received">
+ <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map">
+ <tp:docstring>A mapping from contact identifier to an array of fields
+ representing information about this contact.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Emitted when a some search results are received from the server.
+ This signal can be fired arbitrarily many times so clients MUST NOT
+ assume they'll get only one signal.
+ </tp:docstring>
+ </signal>
+
+ <property name="Server" tp:name-for-bindings="Server"
+ type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'>
+ <tp:docstring>
+ <p>For protocols which support searching for contacts on multiple
+ servers with different DNS names (like XMPP), the DNS name of the
+ server being searched by this channel, e.g.
+ "characters.shakespeare.lit". Otherwise, the empty string.</p>
+
+ <tp:rationale>
+ <p>XEP 0055 defines a mechanism for XMPP clients to search services
+ of their choice for contacts, such as users.jabber.org (the "Jabber
+ User Directory").</p>
+ </tp:rationale>
+
+ <p>This property SHOULD be requestable if and only if the
+ protocol supports querying multiple different servers;
+ implementations SHOULD use a sensible default if possible if this
+ property is not specified in a channel request.</p>
+
+ <tp:rationale>
+ <p>This allows a client to perform searches on a protocol it knows
+ nothing about without requiring the user to guess a valid server's
+ hostname.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
new file mode 100644
index 0000000..9615763
--- /dev/null
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -0,0 +1,189 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus
+ traffic.</p>
+
+ <p>For each D-Bus tube, the connection manager listens on a D-Bus
+ server address, as detailed in the D-Bus specification. On this
+ address, it emulates a bus upon which each tube participant appears
+ as an endpoint.</p>
+
+ <p>The objects and interfaces which are expected to exist on the
+ emulated bus depend on the well-known name; typically, either the
+ participant who initiated the tube is expected to export the same
+ objects/interfaces that would be exported by a service of that name
+ on a bus, or all participants are expected to export those
+ objects/interfaces.</p>
+
+ <p>In a multi-user context (Handle_Type_Room) the tube behaves
+ like the D-Bus bus daemon, so participants can send each other
+ private messages, or can send broadcast messages which are
+ received by everyone in the tube (including themselves).
+ Each participant has a D-Bus unique name; connection managers
+ MUST prevent participants from sending messages with the wrong
+ sender unique name, and SHOULD attempt to avoid participants
+ receiving messages not intended for them.</p>
+
+ <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like
+ a peer-to-peer D-Bus connection - arbitrary D-Bus messages with
+ any sender and/or destination can be sent by each participant,
+ and each participant receives all messages sent by the other
+ participant.</p>
+
+ </tp:docstring>
+
+ <method name="Offer" tp:name-for-bindings="Offer">
+ <tp:docstring>
+ Offers a D-Bus tube providing the service specified.
+ </tp:docstring>
+ <arg direction="in" name="parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ The dictionary of arbitrary
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
+ to send with the tube offer.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the connection manager applies to the D-Bus socket.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="address" type="s">
+ <tp:docstring>
+ The string describing the address of the private bus. The client
+ SHOULD NOT attempt to connect to the address until the tube is open.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact associated with this channel doesn't have tubes
+ capabilities.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <tp:docstring>
+ Accept a D-Bus tube that's in the "local pending" state. The
+ connection manager will attempt to open the tube. The tube remains in
+ the "local pending" state until the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
+ signal is emitted.
+ </tp:docstring>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the connection manager applies to the D-Bus socket.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="address" type="s">
+ <tp:docstring>
+ The string describing the address of the private bus. The client
+ SHOULD NOT attempt to connect to the address until the tube is open.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
+ <tp:docstring>
+ Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
+ participant opens or closes the tube. This provides change
+ notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
+ </tp:docstring>
+ <arg name="Added" type="a{us}" tp:type="DBus_Tube_Participants">
+ <tp:docstring>
+ Array of handles and D-Bus names of new participants.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ Array of handles of former participants.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="ServiceName" type="s" access="read"
+ tp:name-for-bindings="Service_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A string representing the service name that will be used over the
+ tube. It SHOULD be a well-known D-Bus service name, of the form
+ <tt>com.example.ServiceName</tt>.</p>
+ <p>When the tube is offered, the service name is transmitted to the
+ other end.</p>
+ <p>When requesting a channel with
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
+ this property MUST be included in the request.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="DBusNames" tp:name-for-bindings="DBus_Names"
+ access="read" type="a{us}" tp:type="DBus_Tube_Participants">
+ <tp:docstring>
+ For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
+ between contact handles and their unique bus names on this tube.
+ For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
+ dictionary. Change notification is via
+ <tp:member-ref>DBusNamesChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="DBus_Tube_Participants">
+ <tp:docstring>Represents the participants in a multi-user D-Bus tube, as
+ used by the <tp:member-ref>DBusNames</tp:member-ref> property and the
+ <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle">
+ <tp:docstring>
+ The handle of a participant in this D-Bus tube.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
+ <tp:docstring>
+ That participant's unique name.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="SupportedAccessControls" type="au"
+ tp:type="Socket_Access_Control[]" access="read"
+ tp:name-for-bindings="Supported_Access_Controls">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the access control types that are supported with this channel.
+ Note that only Socket_Access_Control_Localhost and
+ Socket_Access_Control_Credentials can be used with D-Bus tubes.</p>
+
+ <p>When requesting a channel with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request.</p>
+
+ </tp:docstring>
+ </property>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
new file mode 100644
index 0000000..19dda06
--- /dev/null
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -0,0 +1,531 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>
+ Copyright © 2008-2009 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
+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
+Library 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.Type.FileTransfer">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.17.18">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for transferring files. The
+ transmission of data between contacts is achieved by reading from
+ or writing to a socket. The type of the socket (local Unix, IPv4,
+ etc.) is decided on when the file transfer is offered or accepted.</p>
+
+ <p>A socket approach is used to make the transfer less dependent on both
+ client and connection manager knowing the same protocols. As an example,
+ when browsing an SMB share in a file manager, one selects "Send file"
+ and chooses a contact. Instead of passing a URL which would then require
+ the connection manager to connect to the SMB share itself, the client
+ passes a stream from which the connection manager reads, requiring no
+ further connection to the share. It also allows connection managers to
+ be more restricted in their access to the system, allowing tighter
+ security policies with eg SELinux, or more flexible deployments which
+ cross user or system boundaries.</p>
+
+ <p>The Telepathy client should connect to the socket or address that
+ the connection manager has set up and provided back to the clients
+ through the two methods.</p>
+
+ <ul><li>In order to send a file, one should request a FileTransfer
+ channel for a contact, including at least the mandatory properties
+ (<tp:member-ref>Filename</tp:member-ref>,
+ <tp:member-ref>Size</tp:member-ref> and <tp:member-ref>ContentType</tp:member-ref>).
+ Then, one should
+ call <tp:member-ref>ProvideFile</tp:member-ref> to configure the socket that
+ will be used to transfer the file.</li>
+
+ <li>In order to receive an incoming file transfer, one should call
+ <tp:member-ref>AcceptFile</tp:member-ref> and then wait until the state
+ changes to Open. When the receiver wants to resume a transfer, the Offset
+ argument should be should be set to a non-zero value when calling
+ <tp:member-ref>AcceptFile</tp:member-ref>.</li>
+
+ <li>Once the offset has been negotiated, the
+ <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
+ is emitted and the <tp:member-ref>InitialOffset</tp:member-ref> property
+ is defined. The <tp:member-ref>InitialOffsetDefined</tp:member-ref>
+ signal is emitted before channel becomes Open.
+ The receiver MUST check the value of
+ <tp:member-ref>InitialOffset</tp:member-ref> for a difference in offset
+ from the requested value in AcceptFile.</li>
+
+ <li>When the state changes to Open, Clients can start the transfer of the
+ file using the offset previously announced.
+ </li></ul>
+
+ <p>If something goes wrong with the transfer,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ should be called on the channel.</p>
+
+ <p>The File channel type may be requested for handles of type
+ HANDLE_TYPE_CONTACT. If the channel is requested for any other
+ handle type then the behaviour is undefined.</p>
+
+ <p>Connection managers SHOULD NOT advertise support for file transfer to
+ other contacts unless it has been indicated by a call to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>.
+ </p>
+ <tp:rationale>
+ <p>People would send us files, and it would always fail. That would be silly.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="State" type="u" tp:type="File_Transfer_State"
+ access="read" tp:name-for-bindings="State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The state of the file transfer as described by the
+ File_Transfer_State enum.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ContentType" type="s" access="read"
+ tp:name-for-bindings="Content_Type">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The file's MIME type. This cannot change once the channel has
+ been created.</p>
+
+ <p>This property is mandatory when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. Protocols which do not have a content-type property with file
+ transfers should set this value to application/octet-stream.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Filename" type="s" access="read"
+ tp:name-for-bindings="Filename">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the file on the sender's side. This is therefore given
+ as a suggested filename for the receiver. This cannot change
+ once the channel has been created.</p>
+
+ <p>This property should be the basename of the file being sent. For example,
+ if the sender sends the file /home/user/monkey.pdf then this property should
+ be set to monkey.pdf.</p>
+
+ <p>This property is mandatory when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. This property cannot be empty and MUST be set to a sensible value.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Size" type="t" access="read"
+ tp:name-for-bindings="Size">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The size of the file. If this property is set, then the file
+ transfer is guaranteed to be this size. This cannot change once
+ the channel has been created.</p>
+
+ <p>When you are creating a channel with this property, its value
+ MUST be accurate and in bytes. However, when receiving a file, this
+ property still MUST be in bytes but might not be entirely accurate
+ to the byte.</p>
+
+ <p>This property is mandatory when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. If this information isn't provided in the protocol, connection managers MUST set it
+ to UINT64_MAX.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ContentHashType" type="u" tp:type="File_Hash_Type"
+ access="read" tp:name-for-bindings="Content_Hash_Type">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of the <tp:member-ref>ContentHash</tp:member-ref> property.</p>
+
+ <p>This property is optional when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. However, if you wish to include the <tp:member-ref>ContentHash</tp:member-ref>
+ property you MUST also include this property. If you omit this property from a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method call then its value will be assumed to be File_Hash_Type_None.</p>
+
+ <p>For each supported hash type, implementations SHOULD include an entry
+ in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ with this property fixed to that hash type. If the protocol supports
+ offering a file without a content hash, implementations SHOULD list
+ this property in Allowed in a requestable channel class, mapping hash
+ types they don't understand to None.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="ContentHash" type="s" access="read"
+ tp:name-for-bindings="Content_Hash">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Hash of the contents of the file transfer, of type described
+ in the value of the <tp:member-ref>ContentHashType</tp:member-ref>
+ property.</p>
+
+ <p>This property is optional when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. Its value MUST correspond to the appropriate type of the
+ <tp:member-ref>ContentHashType</tp:member-ref> property. If the
+ ContentHashType property is not set, or set to File_Hash_Type_None,
+ then this property will not even be looked at.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Description" type="s" access="read"
+ tp:name-for-bindings="Description">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Description of the file transfer. This cannot change once the
+ channel has been created.</p>
+
+ <p>This property is optional when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method. If this property was not provided by the remote party, connection managers MUST set it to
+ the empty string.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Date" type="x" access="read"
+ tp:type="Unix_Timestamp64" tp:name-for-bindings="Date">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The last modification time of the file being transferred. This
+ cannot change once the channel has been created</p>
+
+ <p>This property is optional when requesting the channel with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>
+ method.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="AvailableSocketTypes" type="a{uau}"
+ tp:type="Supported_Socket_Map" access="read"
+ tp:name-for-bindings="Available_Socket_Types">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A mapping from address types (members of Socket_Address_Type) to
+ arrays of access-control type (members of Socket_Access_Control)
+ that the connection manager supports for sockets with that
+ address type. For simplicity, if a CM supports offering a
+ particular type of file transfer, it is assumed to support accepting
+ it. Connection Managers MUST support at least Socket_Address_Type_IPv4.</p>
+
+ <p>A typical value for a host without IPv6 support:</p>
+
+ <pre>
+ {
+ Socket_Address_Type_IPv4:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+ Socket_Access_Control_Netmask],
+ Socket_Address_Type_Unix:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+ }
+ </pre>
+ </tp:docstring>
+ </property>
+
+ <property name="TransferredBytes" type="t" access="read"
+ tp:name-for-bindings="Transferred_Bytes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The number of bytes that have been transferred at the time of
+ requesting the property. This will be updated as the file transfer
+ continues.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialOffset" type="t" access="read"
+ tp:name-for-bindings="Initial_Offset">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The offset in bytes from where the file should be sent. This MUST
+ be respected by both the receiver and the sender after the state
+ becomes Open, but before any data is sent or received. Until the
+ <tp:member-ref>InitialOffsetDefined</tp:member-ref> signal
+ is emitted, this property is undefined.</p>
+
+ <p>Before setting the <tp:member-ref>State</tp:member-ref> property to
+ Open, the connection manager MUST set the InitialOffset property,
+ possibly to 0.</p>
+
+ <p>This property MUST NOT change after the state of the transfer has
+ changed to Open.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="File_Transfer_State" type="u">
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ An invalid state type used as a null value. This value MUST NOT
+ appear in the State property.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Pending" value="1">
+ <tp:docstring>
+ The file transfer is waiting to be accepted/closed by the receiver.
+ The receiver has to call <tp:member-ref>AcceptFile</tp:member-ref>,
+ then wait for the state to change to Open and check the offset value.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Accepted" value="2">
+ <tp:docstring>
+ The receiver has accepted the transfer. The sender now has to
+ call <tp:member-ref>ProvideFile</tp:member-ref> to actually start the transfer.
+ The receiver should now wait for the state to change to Open
+ and check the offset value.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="3">
+ <tp:docstring>
+ The file transfer is open for traffic.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Completed" value="4">
+ <tp:docstring>
+ The file transfer has been completed successfully.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Cancelled" value="5">
+ <tp:docstring>
+ The file transfer has been cancelled.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="File_Transfer_State_Change_Reason" type="u">
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ No reason was specified.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Requested" value="1">
+ <tp:docstring>
+ The change in state was requested.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Local_Stopped" value="2">
+ <tp:docstring>
+ The file transfer was cancelled by the local user.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Remote_Stopped" value="3">
+ <tp:docstring>
+ The file transfer was cancelled by the remote user.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Local_Error" value="4">
+ <tp:docstring>
+ The file transfer was cancelled because of a local error.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Remote_Error" value="5">
+ <tp:docstring>
+ The file transfer was cancelled because of a remote error.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="File_Hash_Type" type="u">
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ No hash.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="MD5" value="1">
+ <tp:docstring>
+ MD5 digest as a string of 32 ASCII hex digits.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="SHA1" value="2">
+ <tp:docstring>
+ SHA1 digest as a string of ASCII hex digits.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="SHA256" value="3">
+ <tp:docstring>
+ SHA256 digest as a string of ASCII hex digits.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <method name="AcceptFile" tp:name-for-bindings="Accept_File">
+ <tp:docstring>
+ Accept a file transfer that's in the Pending state. The file
+ transfer's state becomes Accepted after this method is called.
+ At this point the client can connect to the socket. CM MUST emit
+ <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change
+ the state to Open before writing to the socket.
+ Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case
+ its value differs from the offset that was specified as an argument
+ to AcceptFile.
+ </tp:docstring>
+ <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of address the connection manager should listen on.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The type of access control the connection manager should apply to
+ the socket.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control_Param" type="v">
+ <tp:docstring>
+ A parameter for the access control type, to be interpreted as
+ specified in the documentation for the Socket_Access_Control enum.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Offset" type="t">
+ <tp:docstring>
+ The desired offset in bytes where the file transfer should start.
+ The offset is taken from the beginning of the file. Specifying an
+ offset of zero will start the transfer from the beginning of the
+ file. The offset that is actually given in the
+ <tp:member-ref>InitialOffset</tp:member-ref> property can differ
+ from this argument where the requested offset is not supported.
+ (For example, some protocols do not support offsets at all so
+ the InitialOffset property will always be 0.)
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address" type="v">
+ <tp:docstring>
+ The address on which the connection manager will listen for
+ connections for this file transfer.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given address type or access-control mechanism is not supported.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:docstring>
+ Your address type, access control, access control parameter,
+ offset, or a combination of all four is invalid.
+ </tp:docstring>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The file transfer is not in the Pending state, there isn't
+ or there is a local error with acquiring a socket.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="ProvideFile" tp:name-for-bindings="Provide_File">
+ <tp:docstring>
+ Provide the file for an outgoing file transfer which has been offered.
+ Opens a socket that the client can use to provide a file to the connection manager.
+ The channel MUST have been requested, and will change state
+ to Open when this method is called if its state was Accepted.
+ </tp:docstring>
+ <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of address the connection manager should listen on.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The type of access control the connection manager should apply to
+ the socket.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control_Param" type="v">
+ <tp:docstring>
+ A parameter for the access control type, to be interpreted as
+ specified in the documentation for the Socket_Access_Control enum.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address" type="v">
+ <tp:docstring>
+ The address on which the connection manager will listen for
+ connections for this file transfer.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given address type or access-control mechanism is not supported.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:docstring>
+ Your address type, access control, access control parameter, or
+ a combination of all three is invalid.
+ </tp:docstring>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Channel is not an outgoing transfer, ProvideFile has already been called,
+ or there was a local error acquiring the socket.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="FileTransferStateChanged"
+ tp:name-for-bindings="File_Transfer_State_Changed">
+ <tp:docstring>
+ Emitted when the state of a file transfer changes.
+ </tp:docstring>
+ <arg name="State" type="u" tp:type="File_Transfer_State">
+ <tp:docstring>
+ The new state of the file transfer; see the File_Transfer_State enumeration.
+ </tp:docstring>
+ </arg>
+ <arg name="Reason" type="u" tp:type="File_Transfer_State_Change_Reason">
+ <tp:docstring>
+ The reason for the state change; see the File_Transfer_State_Change_Reason
+ enumeration.
+ The value will always be File_Transfer_State_Change_Reason_None, except
+ when changing state to cancelled.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="TransferredBytesChanged"
+ tp:name-for-bindings="Transferred_Bytes_Changed">
+ <tp:docstring>
+ Emitted when the number of transferred bytes changes. This will not be
+ signalled with every single byte change. Instead, the most frequent
+ this signal will be emitted is once a second. This should be
+ sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref>
+ property SHOULD NOT be polled.
+ </tp:docstring>
+ <arg name="Count" type="t">
+ <tp:docstring>
+ The number of already transferred bytes.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="InitialOffsetDefined"
+ tp:name-for-bindings="Initial_Offset_Defined">
+ <tp:docstring>
+ Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref>
+ property has been negotiated. This signal MUST be emitted before the channel
+ becomes Open and clients have to use this offset when transferring the
+ file.
+ </tp:docstring>
+ <arg name="InitialOffset" type="t">
+ <tp:docstring>
+ The value of the <tp:member-ref>InitialOffset</tp:member-ref> property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
new file mode 100644
index 0000000..98f7458
--- /dev/null
+++ b/spec/Channel_Type_Room_List.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 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.Channel.Type.RoomList">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:struct name="Room_Info" array-name="Room_Info_List">
+ <tp:member type="u" tp:type="Room_Handle" name="Handle"/>
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
+ <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/>
+ </tp:struct>
+
+ <property name="Server" tp:name-for-bindings="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" tp:name-for-bindings="Get_Listing_Rooms">
+ <arg direction="out" type="b" name="In_Progress">
+ <tp:docstring>
+ A boolean indicating if room listing is in progress
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Check to see if there is already a room list request in progress
+ on this channel.
+ </tp:docstring>
+ </method>
+
+ <signal name="GotRooms" tp:name-for-bindings="Got_Rooms">
+ <arg name="Rooms" type="a(usa{sv})" tp:type="Room_Info[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structs containing:
+ <ul>
+ <li>an integer room handle</li>
+ <li>a string representing the D-Bus interface name of the channel type</li>
+ <li>a dictionary mapping string keys to variant boxed information</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when information about rooms on the server becomes available.
+ The array contains the room handle (as can be passed to the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
+ method with HANDLE_TYPE_ROOM), the channel
+ type, and a dictionary containing further information about the
+ room as available. The following well-known keys and types are
+ recommended for use where appropriate:</p>
+
+ <dl>
+ <dt>handle-name (s)</dt>
+ <dd>The identifier of the room (as would be returned by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd>
+
+ <dt>name (s)</dt>
+ <dd>The human-readable name of the room if different from the handle</dd>
+
+ <dt>description (s)</dt>
+ <dd>A description of the room's overall purpose</dd>
+
+ <dt>subject (s)</dt>
+ <dd>The current subject of conversation in the room (as would
+ be returned by getting the string part of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >Subject</tp:dbus-ref> property)</dd>
+
+ <dt>members (u)</dt>
+ <dd>The number of members in the room</dd>
+
+ <dt>password (b)</dt>
+ <dd>True if the room requires a password to enter</dd>
+
+ <dt>invite-only (b)</dt>
+ <dd>True if you cannot join the room, but must be invited</dd>
+
+ <dt>room-id (s)</dt>
+ <dd>The human-readable identifier of a chat room (as would be
+ returned by getting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >RoomID</tp:dbus-ref> property)</dd>
+
+ <dt>server (s)</dt>
+ <dd>The DNS name of the server hosting these channels (as would be
+ returned by getting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >Server</tp:dbus-ref> property)</dd>
+ </dl>
+ </tp:docstring>
+ </signal>
+ <method name="ListRooms" tp:name-for-bindings="List_Rooms">
+ <tp:docstring>
+ Request the list of rooms from the server. The
+ <tp:member-ref>ListingRooms</tp:member-ref> (True) signal should be
+ emitted when this request is being processed,
+ <tp:member-ref>GotRooms</tp:member-ref> when any room information is
+ received, and <tp:member-ref>ListingRooms</tp:member-ref> (False) when
+ the request is complete.
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <method name="StopListing" tp:name-for-bindings="Stop_Listing">
+ <tp:docstring>
+ Stop the room listing if it's in progress, but don't close the channel.
+ The <tp:member-ref>ListingRooms</tp:member-ref> (False) signal should
+ be emitted when the listing stops.
+ </tp:docstring>
+ </method>
+ <signal name="ListingRooms" tp:name-for-bindings="Listing_Rooms">
+ <arg name="Listing" type="b">
+ <tp:docstring>A boolean indicating if room listing is in progress</tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted to indicate whether or not room listing request is currently
+ in progress.
+ </tp:docstring>
+ </signal>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for listing named channels available on the server. Once the
+ <tp:member-ref>ListRooms</tp:member-ref> method is called, it emits signals for rooms present on the
+ server, until you <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> this
+ channel. In some cases, it may not be possible
+ to stop the deluge of information from the server. This channel should be
+ closed when the room information is no longer being displayed, so that the
+ room handles can be freed.</p>
+
+ <p>This channel type may be implemented as a singleton on some protocols, so
+ clients should be prepared for the eventuality that they are given a
+ channel that is already in the middle of listing channels. The
+ <tp:member-ref>ListingRooms</tp:member-ref> signal, or
+ <tp:member-ref>GetListingRooms</tp:member-ref> method, can be used to check
+ this.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Server_Authentication.xml b/spec/Channel_Type_Server_Authentication.xml
new file mode 100644
index 0000000..76599aa
--- /dev/null
+++ b/spec/Channel_Type_Server_Authentication.xml
@@ -0,0 +1,121 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Server_Authentication" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2010 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
+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.Type.ServerAuthentication">
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type for a channel representing an authentication step with the
+ server. The actual authentication functionality is implemented by
+ the additional interface named in
+ <tp:member-ref>AuthenticationMethod</tp:member-ref>,
+ such as <tp:dbus-ref namespace="ofdT"
+ >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p>
+
+ <p>Future authentication steps also supported by this channel type might
+ include solving a captcha and/or agreeing to an EULA or terms-of-use
+ document; each of these would be represented by a channel with this
+ type, but a different
+ <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p>
+
+ <p>Channels of this type will normally be be signalled and dispatched
+ while the <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref>
+ owning them is in the CONNECTING state. They MAY also appear on a
+ Connection in the CONNECTED state, for instance if periodic
+ re-authentication is required.</p>
+
+ <p>Normally, only one channel of this type will
+ exist on a given Connection; if there is more than one, the handler
+ must complete authentication with each of them in turn.</p>
+
+ <p>Channels of this type cannot be requested with methods such as
+ <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ They always have <tp:dbus-ref
+ namespace="ofdT.Channel">Requested</tp:dbus-ref> = False,
+ <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> = None
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ = 0.</p>
+
+ <p>While it is CONNECTING, the Connection MUST NOT proceed with
+ connection, or signal
+ <tp:dbus-ref namespace="ofdT.Connection">StatusChanged</tp:dbus-ref>
+ to the CONNECTED state, until each channel of this type has either
+ been accepted as having a positive result (for instance, on SASL
+ channels this is done with the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.SASLAuthentication"
+ >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref
+ namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p>
+
+ <tp:rationale>
+ <p>ServerAuthentication channels normally represent the client
+ authenticating itself to the server, but can also be used for the
+ server to authenticate itself to the client (i.e. prove that it is
+ in fact the desired server and not an imposter). Until the
+ authentication handler has confirmed this, connection should not
+ continue.</p>
+ </tp:rationale>
+
+ <p>If a channel of this type is closed with the <tp:dbus-ref
+ namespace="ofdT.Channel">Close</tp:dbus-ref> method before
+ authentication has succeeded, this indicates that the Handler has
+ given up its attempts to authenticate or that no Handler is
+ available.</p>
+
+ <p>If this occurs, the connection manager MAY attempt to continue
+ connection (for instance, performing SASL authentication by using any
+ credentials passed to <tp:dbus-ref
+ namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>,
+ for instance from the <tp:dbus-ref
+ namespace="ofdT">Account.Parameters</tp:dbus-ref>). If this fails
+ or has already been tried, the <tp:dbus-ref
+ namespace="ofdT">Connection</tp:dbus-ref> will
+ disconnect.</p>
+
+ <tp:rationale>
+ <p>In particular, the <tp:dbus-ref
+ namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will close the
+ channel if it cannot find a handler.</p>
+ </tp:rationale>
+
+ <p>When the connection is done with the channel and it is no
+ longer needed, it is left open until either the connection state
+ turns to DISCONNECTED or the handler closes the channel. The
+ channel SHOULD NOT close itself once finished with.</p>
+ </tp:docstring>
+
+ <property name="AuthenticationMethod"
+ tp:name-for-bindings="Authentication_Method"
+ type="s" tp:type="DBus_Interface" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This property defines the method used for the authentication step
+ represented by this channel, which MUST be one of this channel's
+ <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref>.</p>
+
+ <p>The initially-defined interface that can be used here is
+ <tp:dbus-ref namespace="ofdT"
+ >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml
new file mode 100644
index 0000000..1f3348e
--- /dev/null
+++ b/spec/Channel_Type_Server_TLS_Connection.xml
@@ -0,0 +1,69 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Server_TLS_Connection"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright>
+ <tp:license>
+ 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.
+
+ 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.
+
+ 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.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection">
+ <tp:added version="0.19.13">(as stable API)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type that carries a TLS certificate between a server
+ and a client connecting to it.</p>
+ <p>Channels of this kind always have <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> = False,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = None and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ = 0, and cannot be requested with methods such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>.
+ Also, they SHOULD be dispatched while the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ owning them is in the CONNECTING state.</p>
+ <p>In this case, handlers SHOULD accept or reject the certificate, using
+ the relevant methods on the provided object, or MAY just <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the channel before doing so, to fall
+ back to a non-interactive verification process done inside the CM.</p>
+ <p>For example, channels of this kind can pop up while a client is
+ connecting to an XMPP server.</p>
+ </tp:docstring>
+
+ <property name="ServerCertificate" type="o" access="read"
+ tp:name-for-bindings="Server_Certificate">
+ <tp:docstring>
+ <p>A <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
+ containing the certificate chain as sent by the server,
+ and other relevant information.</p>
+ <p>This property is immutable.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Hostname" type="s" access="read"
+ tp:name-for-bindings="Hostname">
+ <tp:added version="0.19.12"/>
+ <tp:docstring>
+ The hostname of the server we expect <tp:member-ref>ServerCertificate</tp:member-ref>
+ to certify; clients SHOULD verify <tp:member-ref>ServerCertificate</tp:member-ref> against
+ this hostname when checking its validity.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
new file mode 100644
index 0000000..63e7b2f
--- /dev/null
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -0,0 +1,292 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A stream tube is a transport for ordered, reliable data transfer,
+ similar to SOCK_STREAM sockets.</p>
+
+ <p>When offering a stream tube, the initiating client creates a local
+ listening socket and offers it to the recipient client using the
+ <tp:member-ref>Offer</tp:member-ref> method. When a
+ recipient accepts a stream tube using the
+ <tp:member-ref>Accept</tp:member-ref> method, the
+ recipient's connection manager creates a new local listening socket.
+ Each time the recipient's client connects to this socket, the
+ initiator's connection manager proxies this connection to the
+ originally offered socket.</p>
+
+ </tp:docstring>
+
+ <method name="Offer" tp:name-for-bindings="Offer">
+ <tp:docstring>
+ Offer a stream tube exporting the local socket specified.
+ </tp:docstring>
+ <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of the listening address of the local service, as a member of
+ Socket_Address_Type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="address" type="v">
+ <tp:docstring>
+ The listening address of the local service, as indicated by the
+ address_type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the local service applies to the local socket,
+ specified so the connection manager can behave appropriately
+ when it connects.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ The dictionary of arbitrary
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">Parameters</tp:dbus-ref>
+ to send with the tube offer.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact associated with this channel doesn't have tube
+ capabilities.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The connection manager doesn't support the given address type
+ or access-control type.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <tp:docstring>
+ Accept a stream tube that's in the "local pending" state. The
+ connection manager will attempt to open the tube. The tube remains in
+ the "local pending" state until the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
+ signal is emitted.
+ </tp:docstring>
+ <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of address the connection manager should listen on.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of access control the connection manager should apply to
+ the socket.</p>
+
+ <p>Note that if you plan to establish more than one connection
+ through the tube, the Socket_Access_Control_Port access control
+ can't be used as you can't connect more than once from the same
+ port.</p>
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="access_control_param" type="v">
+ <tp:docstring>
+ A parameter for the access control type, to be interpreted as
+ specified in the documentation for the Socket_Access_Control enum.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="address" type="v">
+ <tp:docstring>
+ The address on which the connection manager will listen for
+ connections to this tube. The client should not attempt to connect
+ to the address until the tube is open.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The access_control_param is invalid with the given access_control.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given address type or access-control mechanism is not supported.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="NewRemoteConnection"
+ tp:name-for-bindings="New_Remote_Connection">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted each time a participant opens a new connection to its
+ socket.</p>
+
+ <p>This signal is only fired on the offering side.</p>
+ </tp:docstring>
+ <arg name="Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the participant who opened the new connection
+ </tp:docstring>
+ </arg>
+ <arg name="Connection_Param" type="v">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A parameter which can be used by the listening process to identify
+ the connection. Note that this parameter has a meaningful value
+ only in the Socket_Access_Control_Port and
+ Socket_Access_Control_Credentials cases. If a different
+ Socket_Access_Control has been chosen when offering the tube, this
+ parameter should be ignored.</p>
+
+ <p>In the Socket_Access_Control_Port case, the variant
+ contains a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
+ containing the address from which the CM is connected to the client
+ application.</p>
+
+ <p>In the Socket_Access_Control_Credentials case, the variant
+ contains the byte (D-Bus signature 'y') that has been sent with
+ the credentials.</p>
+ </tp:docstring>
+ </arg>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The unique ID associated with this connection. This ID will be used
+ to identifiy the connection when reporting errors with
+ <tp:member-ref>ConnectionClosed</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="NewLocalConnection"
+ tp:name-for-bindings="New_Local_Connection">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the tube application connects to the CM's socket.</p>
+
+ <p>This signal is only fired on the accepting side.</p>
+ </tp:docstring>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The unique ID associated with this connection. This ID will be used
+ to identifiy the connection when reporting errors with
+ <tp:member-ref>ConnectionClosed</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ConnectionClosed"
+ tp:name-for-bindings="Connection_Closed"
+ tp:type="Stream_Tube_Connection_Closed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a connection has been closed.</p>
+ </tp:docstring>
+ <arg name="Connection_ID" type="u" tp:type="Stream_Tube_Connection_ID">
+ <tp:docstring>
+ The ID of the connection.
+ </tp:docstring>
+ </arg>
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error describing the error that occurred.</p>
+
+ <p>The following errors can be used:</p>
+ <ul>
+ <li><code>org.freedesktop.Telepathy.Error.Cancelled</code>:
+ user closed the socket or the tube.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionLost</code>:
+ the bytestream relaying connection's data has been broken.</li>
+ <li><code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>:
+ the tube offer refused the connection.</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A debug message.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Service" type="s" access="read"
+ tp:name-for-bindings="Service">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p> 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".</p>
+ <p>When the tube is offered, the service name is transmitted to the
+ other end.</p>
+ <p>When requesting a channel with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ this property MUST be included in the request.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="SupportedSocketTypes" type="a{uau}"
+ tp:type="Supported_Socket_Map" access="read"
+ tp:name-for-bindings="Supported_Socket_Types">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A mapping from address types (members of Socket_Address_Type) to
+ arrays of access-control type (members of Socket_Access_Control)
+ that the connection manager supports for stream tubes with that
+ address type. For simplicity, if a CM supports offering a
+ particular type of tube, it is assumed to support accepting it.</p>
+
+ <p>A typical value for a host without IPv6 support:</p>
+
+ <pre>
+ {
+ Socket_Address_Type_IPv4:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+ Socket_Access_Control_Netmask],
+ Socket_Address_Type_Unix:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+ }
+ </pre>
+
+ <p>Connection Managers MUST support at least IPv4 with the localhost
+ access control.</p>
+
+ <p>When requesting a channel with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+ this property MUST NOT be included in the request.</p>
+
+ </tp:docstring>
+ </property>
+
+ <tp:simple-type name="Stream_Tube_Connection_ID" type="u">
+ <tp:docstring>An identifier for a stream tube connection.
+ These are defined with the
+ <tp:member-ref>NewLocalConnection</tp:member-ref> or
+ <tp:member-ref>NewRemoteConnection</tp:member-ref> signals
+ and are used by <tp:member-ref>ConnectionClosed</tp:member-ref>
+ to identify the closed connection.
+ </tp:docstring>
+ </tp:simple-type>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
new file mode 100644
index 0000000..aa2b903
--- /dev/null
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -0,0 +1,853 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 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.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"
+ array-name="Media_Stream_Type_List">
+ <tp:enumvalue suffix="Audio" value="0">
+ <tp:docstring>An audio stream</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Video" value="1">
+ <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>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connecting" value="1">
+ <tp:docstring>The stream is trying to connect.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connected" value="2">
+ <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>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Send" value="1">
+ <tp:docstring>Media are being sent, but not received</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Receive" value="2">
+ <tp:docstring>Media are being received, but not sent</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Bidirectional" value="3">
+ <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>
+ The local user has been asked to send media by the remote user.
+ Call <tp:member-ref>RequestStreamDirection</tp:member-ref> to
+ indicate whether or not this is acceptable.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Remote_Send" value="2">
+ <tp:docstring>
+ The remote user has been asked to send media by the local user.
+ The <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal
+ will be emitted when the remote user accepts or rejects this
+ change.
+ </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"
+ array-name="Stream_ID_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An unsigned integer identifying a stream within a channel.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <method name="ListStreams" tp:name-for-bindings="List_Streams">
+ <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"
+ name="Streams">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structs containing:
+ <ul>
+ <li>the stream identifier</li>
+ <li>the contact handle who the stream is with (or 0 if the stream
+ represents more than a single member)</li>
+ <li>the type of the stream</li>
+ <li>the current stream state</li>
+ <li>the current direction of the stream</li>
+ <li>the current pending send flags</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns an array of structs representing the streams currently active
+ within this channel. Each stream is identified by an unsigned integer
+ which is unique for each stream within the channel.
+ </tp:docstring>
+ </method>
+
+ <method name="RemoveStreams" tp:name-for-bindings="Remove_Streams">
+ <arg direction="in" name="Streams" type="au" tp:type="Stream_ID[]">
+ <tp:docstring>
+ An array of stream identifiers (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given streams are removed. If all streams are
+ removed, the channel MAY close.</p>
+
+ <p>Clients SHOULD NOT attempt to terminate calls by removing all the
+ streams; instead, clients SHOULD terminate calls by removing the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.SelfHandle</tp:dbus-ref>
+ from the channel, using either
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref>
+ or
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>.
+ </p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ A stream identifier is unknown
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestStreamDirection"
+ tp:name-for-bindings="Request_Stream_Direction">
+ <arg direction="in" name="Stream_ID" type="u">
+ <tp:docstring>
+ The stream identifier (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Stream_Direction" type="u" tp:type="Media_Stream_Direction">
+ <tp:docstring>
+ The desired stream direction (a value of MediaStreamDirection)
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request a change in the direction of an existing stream. In particular,
+ this might be useful to stop sending media of a particular type,
+ or inform the peer that you are no longer using media that is being
+ sent to you.</p>
+
+ <p>Depending on the protocol, streams which are no longer sending in
+ either direction should be removed and a
+ <tp:member-ref>StreamRemoved</tp:member-ref> signal emitted.
+ Some direction changes can be enforced locally (for example,
+ BIDIRECTIONAL -&gt; RECEIVE can be achieved by merely stopping sending),
+ others may not be possible on some protocols, and some need agreement
+ from the remote end. In this case, the MEDIA_STREAM_PENDING_REMOTE_SEND
+ flag will be set in the
+ <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal, and the
+ signal
+ emitted again without the flag to indicate the resulting direction when
+ the remote end has accepted or rejected the change.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ A stream identifier is unknown
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested direction is not available on this stream
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestStreams" tp:name-for-bindings="Request_Streams">
+ <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" tp:type="Media_Stream_Type[]">
+ <tp:docstring>
+ An array of stream types (values of MediaStreamType)
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a(uuuuuu)" tp:type="Media_Stream_Info[]"
+ name="Streams">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structs (in the same order as the given stream types)
+ containing:
+ <ul>
+ <li>the stream identifier</li>
+ <li>the contact handle who the stream is with (or 0 if the stream
+ represents more than a single member)</li>
+ <li>the type of the stream</li>
+ <li>the current stream state</li>
+ <li>the current direction of the stream</li>
+ <li>the current pending send flags</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that streams be established to exchange the given types of
+ media with the given member. In general this will try and establish a
+ bidirectional stream, but on some protocols it may not be possible to
+ indicate to the peer that you would like to receive media, so a
+ send-only stream will be created initially. In the cases where the
+ stream requires remote agreement (eg you wish to receive media from
+ them), the <tp:member-ref>StreamDirectionChanged</tp:member-ref> signal
+ will be emitted with the
+ MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
+ with the flag cleared when the remote end has replied.</p>
+
+ <p>If streams of the requested types already exist, calling this
+ method results in the creation of additional streams. Accordingly,
+ clients wishing to have exactly one audio stream or exactly one
+ video stream SHOULD check for the current streams using
+ <tp:member-ref>ListStreams</tp:member-ref> before calling this
+ method.</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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
+ 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref>
+ 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">
+ <tp:docstring>
+ A stream type given is invalid.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ A stream type given is not implemented by the connection manager.
+ Since 0.17.23, connection managers SHOULD raise this error
+ in preference to InvalidArgument.
+ <tp:rationale>
+ Connection managers can't know whether an unknown number
+ is a valid stream type that was introduced in a later spec
+ version.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ That contact's client does not implement one of the given stream
+ types. For this method, clients SHOULD consider this error and
+ NotCapable to be equivalent.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ That contact's client does not implement one of the given stream
+ types. Since 0.17.23, connection managers SHOULD raise
+ this in preference to NotAvailable.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="StreamAdded" tp:name-for-bindings="Stream_Added">
+ <arg name="Stream_ID" type="u">
+ <tp:docstring>
+ The stream identifier (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <arg name="Contact_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact handle who the stream is with (or 0 if it
+ represents more than a single member)
+ </tp:docstring>
+ </arg>
+ <arg name="Stream_Type" type="u" tp:type="Media_Stream_Type">
+ <tp:docstring>
+ The stream type (a value from MediaStreamType)
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new stream has been added to this channel.
+ Clients SHOULD assume that the stream's
+ <tp:type>Media_Stream_State</tp:type> is initially Disconnected.</p>
+
+ <p>If a connection manager needs to represent the addition of a stream
+ whose state is already Connecting or Connected, it MUST do this
+ by emitting StreamAdded, closely followed by
+ <tp:member-ref>StreamStateChanged</tp:member-ref> indicating a
+ change to the appropriate state.</p>
+
+ <tp:rationale>
+ <p>Historically, it was not clear from the StreamAdded signal what
+ the state of the stream was. telepathy-spec 0.17.22
+ clarified this.</p>
+ </tp:rationale>
+
+ <p>Similarly, clients SHOULD assume that the initial
+ <tp:type>Media_Stream_Direction</tp:type> of a newly added stream
+ is Receive, and that the initial
+ <tp:type>Media_Stream_Pending_Send</tp:type> is
+ Pending_Local_Send.</p>
+
+ <p>If a connection manager needs to represent the addition of a stream
+ whose direction or pending-send differs from those initial values,
+ it MUST do so by emitting StreamAdded, closely followed by
+ <tp:member-ref>StreamDirectionChanged</tp:member-ref> indicating a
+ change to the appropriate direction and pending-send state.</p>
+
+ <tp:rationale>
+ <p>StreamAdded doesn't itself indicate the stream's direction; this
+ is unfortunate, but is preserved for compatibility.</p>
+
+ <p>This is the appropriate direction for streams added by a remote
+ contact on existing connection managers, and does not violate
+ user privacy by automatically sending audio or video (audio streams
+ start off muted, video streams start off not sending). For
+ streams added by the local user using the client receiving the
+ signal, the true direction can also be determined from the return
+ value of the <tp:member-ref>RequestStreams</tp:member-ref>
+ method.</p>
+
+ <p>Existing clients typically operate by maintaining a separate
+ idea of the directions that they would like the streams to have,
+ and enforcing these intended directions by calling
+ <tp:member-ref>RequestStreamDirection</tp:member-ref> whenever
+ needed.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ <signal name="StreamDirectionChanged"
+ tp:name-for-bindings="Stream_Direction_Changed">
+ <arg name="Stream_ID" type="u">
+ <tp:docstring>
+ The stream identifier (as defined in <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <arg name="Stream_Direction" type="u" tp:type="Media_Stream_Direction">
+ <tp:docstring>
+ The new stream direction (as defined in ListStreams)
+ </tp:docstring>
+ </arg>
+ <arg name="Pending_Flags" type="u" tp:type="Media_Stream_Pending_Send">
+ <tp:docstring>
+ The new pending send flags (as defined in ListStreams)
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the direction or pending flags of a stream are
+ changed.</p>
+
+ <p>If the MEDIA_STREAM_PENDING_LOCAL_SEND flag is set, the remote user
+ has requested that we begin sending on this stream.
+ <tp:member-ref>RequestStreamDirection</tp:member-ref>
+ should be called to indicate whether or not this change is
+ acceptable.</p>
+
+ <tp:rationale>
+ <p>This allows for a MSN-style user interface, "Fred has asked you
+ to enable your webcam. (Accept | Reject)", if desired.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ <signal name="StreamError" tp:name-for-bindings="Stream_Error">
+ <arg name="Stream_ID" type="u">
+ <tp:docstring>
+ The stream identifier (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <arg name="Error_Code" type="u" tp:type="Media_Stream_Error">
+ <tp:docstring>
+ A stream error number, one of the values of MediaStreamError
+ </tp:docstring>
+ </arg>
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string describing the error (for debugging purposes only)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a stream encounters an error.
+ </tp:docstring>
+ </signal>
+
+ <signal name="StreamRemoved" tp:name-for-bindings="Stream_Removed">
+ <arg name="Stream_ID" type="u">
+ <tp:docstring>
+ stream_id - the stream identifier (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a stream has been removed from this channel.
+ </tp:docstring>
+ </signal>
+
+ <signal name="StreamStateChanged"
+ tp:name-for-bindings="Stream_State_Changed">
+ <arg name="Stream_ID" type="u">
+ <tp:docstring>
+ The stream identifier (as defined in
+ <tp:member-ref>ListStreams</tp:member-ref>)
+ </tp:docstring>
+ </arg>
+ <arg name="Stream_State" type="u" tp:type="Media_Stream_State">
+ <tp:docstring>
+ The new stream state (as defined in ListStreams)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a member's stream's state changes.
+ </tp:docstring>
+ </signal>
+
+ <property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If set to true in a channel request that will create a new channel,
+ the connection manager should immediately attempt to establish an
+ audio stream to the remote contact, making it unnecessary for the
+ client to call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p>
+
+ <p>If this property, or InitialVideo, is passed to EnsureChannel
+ (as opposed to CreateChannel), the connection manager SHOULD ignore
+ these properties when checking whether it can return an existing
+ channel as suitable; these properties only become significant when
+ the connection manager has decided to create a new channel.</p>
+
+ <p>If true on a requested channel, this indicates that the audio
+ stream has already been requested and the client does not need to
+ call RequestStreams, although it MAY still do so.</p>
+
+ <p>If true on an unrequested (incoming) channel, this indicates that
+ the remote contact initially requested an audio stream; this does
+ not imply that that audio stream is still active (as indicated by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p>
+
+ <p>This property is immutable (cannot change), and therefore SHOULD
+ appear wherever immutable properties are reported, e.g. <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signals.</p>
+
+ <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale>
+
+ <p>Connection managers capable of signalling audio calls to contacts
+ SHOULD include a channel class in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
+ = <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = Contact in the fixed properties dictionary, and InitialAudio
+ (and also InitialVideo, if applicable) in the allowed properties
+ list. Clients wishing to discover whether a connection manager
+ can signal audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all protocols support signalling video calls, and it would be
+ possible (although unlikely) to have a protocol where only video,
+ and not audio, could be signalled.</p>
+ </tp:rationale>
+
+ <p>Connection managers that support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
+ interface SHOULD represent the capabilities of receiving audio
+ and/or video calls by including a channel class in
+ a contact's capabilities with ChannelType = StreamedMedia
+ in the fixed properties dictionary, and InitialAudio and/or
+ InitialVideo in the allowed properties list. Clients wishing to
+ discover whether a particular contact is likely to be able to
+ receive audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all clients support video calls, and it would also be
+ possible (although unlikely) to have a client which could only
+ stream video, not audio.</p>
+ </tp:rationale>
+
+ <p>Clients that are willing to receive audio and/or video calls
+ SHOULD include the following among their channel classes if
+ calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
+ (clients of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ SHOULD instead arrange for the ChannelDispatcher to do this,
+ by including the filters in their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ properties):</p>
+
+ <ul>
+ <li>{ ChannelType = StreamedMedia }</li>
+ <li>{ ChannelType = StreamedMedia, InitialAudio = true }
+ if receiving calls with audio is supported</li>
+ <li>{ ChannelType = StreamedMedia, InitialVideo = true }
+ if receiving calls with video is supported</li>
+ </ul>
+
+ <tp:rationale>
+ <p>Connection managers for protocols with capability discovery,
+ like XMPP, need this information to advertise the appropriate
+ capabilities for their protocol.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
+ a video stream. This property is immutable (cannot change).</p>
+
+ <p>In particular, note that if this property is false, this does not
+ imply that an active video stream has not been added, only that no
+ video stream was active at the time the channel appeared.</p>
+
+ <p>This property is the correct way to discover whether connection
+ managers, contacts etc. support video calls; it appears in
+ capabilities structures in the same way as InitialAudio.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tt>True</tt>, once streams have been requested for this channel
+ (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or
+ <tp:member-ref>InitialVideo</tp:member-ref> when the channel is
+ requested, or by calling
+ <tp:member-ref>RequestStreams</tp:member-ref> on a channel with no
+ streams), a stream of a different content type cannot be added;
+ subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref>
+ that attempt to do so will fail.</p>
+
+ <p>If this property is missing, clients SHOULD assume that it is false,
+ and thus that the channel's streams can be changed once the call has
+ started.</p>
+
+ <p>If this property is present in the "allowed" set in all of the
+ StreamedMedia entries in a contact's capabilities, then user
+ interfaces MAY choose to show a separate "call" option for each
+ class of call.</p>
+
+ <tp:rationale>
+ <p>For example, once an audio-only Google Talk call has started,
+ it is not possible to add a video stream; both audio and video
+ must be requested at the start of the call if video is desired.
+ User interfaces may use this pseudo-capability as a hint to
+ display separate "Audio call" and "Video call" buttons, rather
+ than a single "Call" button with the option to add and remove
+ video once the call has started for contacts without this flag.
+ </p>
+ </tp:rationale>
+
+ <p>This property is immutable, and therefore SHOULD be announced
+ in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>,
+ etc.</p>
+ </tp:docstring>
+ </property>
+
+ <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 signals to indicate when streams have been added, removed
+ and changed status. The state of the call (ringing remotely, ringing
+ locally, answered, missed, etc.) are represented using the properties
+ and signals of the Group interface.</p>
+
+ <p>In general this should be used in conjunction with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface to exchange connection candidates and codec choices with
+ whichever component is responsible for the streams. However, in certain
+ applications where no candidate exchange is necessary (eg the streams
+ are handled by specialised hardware which is controlled directly by the
+ connection manager), the signalling interface can be omitted and this
+ channel type used simply to control the streams.</p>
+
+ <h4>Outgoing calls</h4>
+
+ <p>To make an audio-only call to a contact <tt>foo@example.com</tt>,
+ clients should call:</p>
+
+ <blockquote>
+ <pre>
+<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Contact,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'foo@example.com',
+ <tp:member-ref>InitialAudio</tp:member-ref>: True,
+)</pre></blockquote>
+
+ <p>As always, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ may be used in place of TargetID if the contact's handle is already
+ known. To make an audio-and-video call, the client should also specify
+ <tp:member-ref>InitialVideo</tp:member-ref>. The connection manager
+ SHOULD return a channel whose immutable properties contain the local
+ user as the <tp:dbus-ref namespace='ofdT.Channel'>InitiatorHandle</tp:dbus-ref>,
+ the remote contact as the <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>True</code>
+ (indicating that the call is outgoing); the <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Group</tp:dbus-ref> interface should
+ initially have the local user in <tp:dbus-ref
+ namespace='ofdT.Channel.Interface.Group'>Members</tp:dbus-ref> and the remote
+ contact in <tp:dbus-ref
+ namespace='ofdT.Channel.Interface.Group'>RemotePendingMembers</tp:dbus-ref>, to
+ indicate that we are awaiting their response.</p>
+
+ <p>The contact answering the call is represented by the CM signalling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>,
+ moving the remote contact to Members, with the remote contact as the
+ <var>Actor</var> and <var>Reason</var> <code>None</code>. The contact
+ rejecting the call is represented by both contacts being removed from
+ the group, with the remote contact as the <var>Actor</var> and
+ <var>Reason</var> set appropriately. The local user may hang up at any
+ time by calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>
+ to remove themself, with an appropriate reason; the CM SHOULD relay the
+ reason to the remote contact, and emit MembersChanged removing both
+ contacts from the group with the self handle as the <var>Actor</var>.</p>
+
+ <p>(In the past, several other patterns have been used to place outgoing
+ calls; see
+ <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a>
+ for the details.)</p>
+
+ <h4>Incoming calls</h4>
+
+ <p>Incoming calls' immutable properties should contain <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = Contact, both <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">InitiatorHandle</tp:dbus-ref>
+ set to the remote contact, <tp:dbus-ref
+ namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>False</code>
+ (indicating that this is an incoming call), and appropriate values of
+ <tp:member-ref>InitialAudio</tp:member-ref> and
+ <tp:member-ref>InitialVideo</tp:member-ref>; the Group interface should
+ initially have the local user in <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref>
+ and the remote contact in <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Group">Members</tp:dbus-ref>,
+ indicating that the contact is awaiting our response.</p>
+
+ <p>To accept the call, use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref>
+ to move the local user to the group's members. To reject the call, use
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>
+ to remove the local member from the group, with an appropriate reason.
+ If the remote user ends the call before it is answered, this is
+ represented by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>
+ removing both parties from the group with the remote contact as the
+ <var>Actor</var>, and <var>Reason</var> set appropriately.</p>
+
+ <p>Note that the call may end with the self handle as the
+ <var>Actor</var> without the user having chosen to reject the call, as
+ indicated by the nature of the <var>Reason</var>. Specifically, some
+ local component may time out the call (indicating this with reason
+ <code>No_Answer</code>; for example, the CM may have forwarded the call
+ to another number, as configured using <tp:dbus-ref
+ namespace='ofdT.Connection.Interface'>Forwarding.DRAFT</tp:dbus-ref>),
+ or something may have gone wrong with the call
+ (indicated by reason <code>Error</code>). Such calls SHOULD be
+ considered missed, just as if the remote contact had hung up before the
+ local user answered the call.</p>
+
+ <tp:rationale>
+ <p>This is a bit awkward, but these are the best ways we can represent
+ these situations. It's important to document which calls should be
+ considered missed, to ensure that the user can be notified.</p>
+ </tp:rationale>
+
+ <p>When the local user accepts an incoming call, the connection manager
+ SHOULD change the direction of any streams with pending local send
+ to be sending, without altering whether those streams are
+ receiving.</p>
+
+ <tp:rationale>
+ <p>This matches existing practice, and means that a client
+ can answer incoming calls and get an unmuted microphone/activated
+ webcam without having to take additional action to accept the
+ stream directions.</p>
+
+ <p>It does, however, introduce a race condition: a client believing
+ that it is accepting an audio-only call by calling AddMembers
+ can inadvertantly accept an audio + video call (and hence activate
+ sending from a webcam without the user's permission) if a video
+ stream is added just before AddMembers is processed. This race
+ should be removed when this specification is revised.</p>
+ </tp:rationale>
+
+ <h4>During a call</h4>
+
+ <p>If <tp:member-ref>ImmutableStreams</tp:member-ref> is
+ <code>False</code>, new streams may be requested using
+ <tp:member-ref>RequestStreams</tp:member-ref> (to add video to an
+ audio-only call, for instance), and existing streams may be removed using
+ <tp:member-ref>RemoveStreams</tp:member-ref> (for example, to downgrade
+ an audio-video call to audio-only). The call may be ended by calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>; the call ending is signalled by the CM emitting <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>,
+ removing both parties from the group.</p>
+
+ <h4>Handler filters</h4>
+
+ <p>For historical reasons, handlers must specify more than one filter if
+ they want to correctly advertise support for audio and/or video calls. If
+ they can handle channels using the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface, they should also advertise various
+ <tp:type>Handler_Capability_Token</tp:type>s to indicate which codecs and
+ transports they support. See <tp:member-ref>InitialAudio</tp:member-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling/video/h264</tp:dbus-ref>
+ for the gory details. In summary:</p>
+
+ <dl>
+ <dt>To advertise support for streamed media in general, include the
+ following filter in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>:</dt>
+ <dd><pre>
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+ '...Channel.TargetHandleType': Contact,
+}</pre></dd>
+
+ <dt>To advertise support for audio calls, also include the following
+ filter:</dt>
+ <dd><pre>
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+ '...Channel.TargetHandleType': Contact,
+ '...Channel.Type.StreamedMedia.InitialAudio': True,
+}</pre></dd>
+
+ <dt>To advertise support for video calls, also include the following
+ filter:</dt>
+ <dd><pre>
+{ '...Channel.ChannelType': '...Channel.Type.StreamedMedia' ,
+ '...Channel.TargetHandleType': Contact,
+ '...Channel.Type.StreamedMedia.InitialVideo': True,
+}</pre></dd>
+
+ <dt>If you use telepathy-farsight, and have H.264 support, you probably
+ want these <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>:</dt>
+ <dd><pre>
+[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp",
+ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p",
+ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264",
+]</pre></dd>
+ </dl>
+ </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
+ Channel.Type.StreamedMedia in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref>
+ interface. See the <tp:member-ref>InitialAudio</tp:member-ref>
+ property for details of the mechanisms that will replace this.
+ </tp:docstring>
+ <tp:flag suffix="Audio" value="1">
+ <tp:docstring>
+ The handle is capable of using audio streams within a media channel.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Video" value="2">
+ <tp:docstring>
+ The handle is capable of using video streams within a media channel.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="NAT_Traversal_STUN" value="4">
+ <tp:docstring>
+ The handle is capable of performing STUN to traverse NATs.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="NAT_Traversal_GTalk_P2P" value="8">
+ <tp:docstring>
+ The handle is capable of establishing Google Talk peer-to-peer
+ connections (as implemented in libjingle 0.3) to traverse NATs.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16">
+ <tp:docstring>
+ The handle is capable of establishing ICE UDP peer-to-peer
+ connections (as defined by the IETF MMUSIC working group) to traverse
+ NATs.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Immutable_Streams" value="32">
+ <tp:docstring>
+ Channels whose target handle is this contact will have
+ <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>.
+ </tp:docstring>
+ </tp:flag>
+
+ </tp:flags>
+
+ </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
new file mode 100644
index 0000000..0cd4d5b
--- /dev/null
+++ b/spec/Channel_Type_Text.xml
@@ -0,0 +1,669 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 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.Channel.Type.Text">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires
+ interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
+ <tp:changed version="0.21.5">The Messages interface is now
+ mandatory</tp:changed>
+
+ <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List">
+ <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:deprecated version="0.21.5">New APIs should use
+ an array of <tp:type>Message_Part</tp:type> instead.</tp:deprecated>
+ <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
+ <tp:member-ref>ListPendingMessages</tp:member-ref>. The arguments of
+ the <tp:member-ref>Received</tp:member-ref> signal also match this
+ struct's signature.</tp:docstring>
+ <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"/>
+ <tp:member type="u" tp:type="Channel_Text_Message_Flags" name="Flags"/>
+ <tp:member type="s" name="Text"/>
+ </tp:struct>
+
+ <method name="AcknowledgePendingMessages"
+ tp:name-for-bindings="Acknowledge_Pending_Messages">
+ <arg direction="in" name="IDs" type="au" tp:type="Message_ID[]">
+ <tp:docstring>
+ The IDs of the messages to acknowledge
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform the channel that you have handled messages by displaying them to
+ the user (or equivalent), so they can be removed from the pending queue.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <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" tp:name-for-bindings="Get_Message_Types">
+ <tp:deprecated version="0.21.5">Consulting
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >MessageTypes</tp:dbus-ref> is preferred.
+ </tp:deprecated>
+ <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]"
+ name="Available_Types">
+ <tp:docstring>
+ An array of integer message types (ChannelTextMessageType)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Return an array indicating which types of message may be sent on this
+ channel.
+ </tp:docstring>
+ </method>
+
+ <method name="ListPendingMessages"
+ tp:name-for-bindings="List_Pending_Messages">
+ <tp:deprecated version="0.21.5">Consulting
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >PendingMessages</tp:dbus-ref> is preferred.
+ </tp:deprecated>
+ <arg direction="in" name="Clear" type="b">
+ <tp:docstring>
+ If true, behave as if
+ <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also
+ been called.
+ </tp:docstring>
+ <tp:deprecated version="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[]"
+ name="Pending_Messages">
+ <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>
+ <li>a Unix timestamp indicating when the message was received</li>
+ <li>the contact handle for the contact who sent the message</li>
+ <li>the message type, taken from ChannelTextMessageType</li>
+ <li>the bitwise-OR of the message flags from ChannelTextMessageFlags</li>
+ <li>the text of the message</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ List the messages currently in the pending queue, and optionally
+ remove then all.
+ </tp:docstring>
+ </method>
+
+ <signal name="LostMessage" tp:name-for-bindings="Lost_Message">
+ <tp:deprecated version="0.21.5">In practice, this signal
+ was not emitted, and does not have useful semantics.</tp:deprecated>
+ <tp:docstring>
+ This signal is emitted to indicate that an incoming message was
+ not able to be stored and forwarded by the connection manager
+ due to lack of memory.
+ </tp:docstring>
+ </signal>
+
+ <signal name="Received" tp:name-for-bindings="Received">
+ <tp:deprecated version="0.21.5">The
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >MessageReceived</tp:dbus-ref> signal is more informative.
+ </tp:deprecated>
+ <arg name="ID" type="u">
+ <tp:docstring>
+ A numeric identifier for acknowledging the message
+ </tp:docstring>
+ </arg>
+ <arg name="Timestamp" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ A Unix timestamp indicating when the message was received
+ </tp:docstring>
+ </arg>
+ <arg name="Sender" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the contact who sent the message
+ </tp:docstring>
+ </arg>
+ <arg name="Type" type="u" tp:type="Channel_Text_Message_Type">
+ <tp:docstring>
+ 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
+ </tp:docstring>
+ </arg>
+ <arg name="Text" type="s">
+ <tp:docstring>
+ The text of the message
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signals that a message with the given id, timestamp, sender, type
+ and text has been received on this channel. Applications that catch
+ this signal and reliably inform the user of the message should
+ acknowledge that they have dealt with the message with the
+ <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method.
+ </tp:docstring>
+ </signal>
+
+ <method name="Send" tp:name-for-bindings="Send">
+ <tp:deprecated version="0.21.5">The
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >SendMessage</tp:dbus-ref> method is more flexible.
+ </tp:deprecated>
+ <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type">
+ <tp:docstring>
+ An integer indicating the type of the message
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Text" type="s">
+ <tp:docstring>
+ The message to send
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that a message be sent on this channel. When the message has
+ been submitted for delivery, this method will return and the
+ <tp:member-ref>Sent</tp:member-ref> signal will be emitted. If the
+ message cannot be submitted for delivery, the method returns an error
+ and no signal is emitted.</p>
+
+ <p>This method SHOULD return before the Sent signal is
+ emitted.</p>
+
+ <tp:rationale>
+ <p>When a Text channel implements the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref>
+ interface, that "SHOULD" becomes a "MUST".</p>
+ </tp:rationale>
+ </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.InvalidArgument"/>
+ <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>
+ An unknown error occurred
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring>
+ The requested contact was offline
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_Contact" value="2">
+ <tp:docstring>
+ The requested contact is not valid
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Permission_Denied" value="3">
+ <tp:docstring>
+ The user does not have permission to speak on this channel
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Too_Long" value="4">
+ <tp:docstring>
+ The outgoing message was too long and was rejected by the server
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Not_Implemented" value="5">
+ <tp:docstring>
+ The channel doesn't support sending text messages to the requested
+ contact
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <signal name="SendError" tp:name-for-bindings="Send_Error">
+ <tp:deprecated version="0.21.5">Delivery reporting is now
+ provided by the <tp:dbus-ref namespace="ofdT.Channel.Interface"
+ >Messages</tp:dbus-ref> interface.
+ </tp:deprecated>
+ <arg name="Error" type="u" tp:type="Channel_Text_Send_Error">
+ <tp:docstring>
+ The error that occurred
+ </tp:docstring>
+ </arg>
+ <arg name="Timestamp" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ The Unix timestamp indicating when the message was sent
+ </tp:docstring>
+ </arg>
+ <arg name="Type" type="u" tp:type="Channel_Text_Message_Type">
+ <tp:docstring>
+ The message type
+ </tp:docstring>
+ </arg>
+ <arg name="Text" type="s">
+ <tp:docstring>
+ The text of the message
+ </tp:docstring>
+ </arg>
+ <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
+ <tp:member-ref>Sent</tp:member-ref> has already been emitted and
+ <tp:member-ref>Send</tp:member-ref> 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" tp:name-for-bindings="Sent">
+ <tp:deprecated version="0.21.5">The
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >MessageSent</tp:dbus-ref> signal is more informative.
+ </tp:deprecated>
+ <arg name="Timestamp" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ Unix timestamp indicating when the message was sent
+ </tp:docstring>
+ </arg>
+ <arg name="Type" type="u" tp:type="Channel_Text_Message_Type">
+ <tp:docstring>
+ The message type (normal, action, notice, etc) from
+ ChannelTextMessageType
+ </tp:docstring>
+ </arg>
+ <arg name="Text" type="s">
+ <tp:docstring>
+ The text of the message. If the message was, or will be, altered
+ during transmission, this argument SHOULD reflect what other
+ contacts will receive rather than being a copy of the argument
+ to <tp:member-ref>Send</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that a message has been submitted for sending.</p>
+ </tp:docstring>
+ </signal>
+
+ <tp:enum name="Channel_Text_Message_Type" type="u"
+ array-name="Channel_Text_Message_Type_List">
+ <tp:docstring>
+ The type of message.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Normal" value="0">
+ <tp:docstring>
+ 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
+ "* &lt;sender&gt; &lt;action&gt;", 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.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Delivery_Report" value="4">
+ <tp:docstring>
+ A delivery report. This message type MUST NOT appear unless the
+ channel supports the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref>
+ interface; see <tp:type>Message_Part</tp:type> for the format that
+ delivery reports must take.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u">
+ <tp:deprecated version="0.21.5">The
+ <tp:dbus-ref namespace="ofdT.Channel.Interface"
+ >Messages</tp:dbus-ref> interface has an extensible data structure
+ including separate booleans for most of these flags.
+ </tp:deprecated>
+ <tp:flag suffix="Truncated" value="1">
+ <tp:docstring>
+ The incoming message was truncated to a shorter length by the
+ 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref>
+ 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:flag suffix="Scrollback" value="4">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The incoming message was part of a replay of message history.</p>
+
+ <tp:rationale>
+ <p>In XMPP multi-user chat, a few past messages are replayed
+ when you join a chatroom. A sufficiently capable IRC connection
+ manager could also set this flag on historical messages when
+ connected to a proxy like bip or irssi-proxy. The existence
+ of this flag allows loggers and UIs to use better heuristics
+ when eliminating duplicates (a simple implementation made
+ possible by this flag would be to avoid logging scrollback
+ at all).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Rescued" value="8">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The incoming message has been seen in a previous channel during
+ the lifetime of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, but
+ had not been acknowledged
+ when that channel closed, causing an identical channel (the
+ channel in which the message now appears) to open.</p>
+
+ <tp:rationale>
+ <p>This means that a logger (which should already have seen the
+ message in the previous channel) is able to recognise and ignore
+ these replayed messages.</p>
+ </tp:rationale>
+ </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
+ aware of their identity.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="invite-only" type="b">
+ <tp:docstring>
+ True if people may not join the channel until they have been invited.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="limit" type="u">
+ <tp:docstring>
+ The limit to the number of members, if limited is true.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="limited" type="b">
+ <tp:docstring>
+ True if there is a limit to the number of channel members.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="moderated" type="b">
+ <tp:docstring>
+ True if channel membership is not sufficient to allow participation.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="name" type="s">
+ <tp:docstring>
+ A human-visible name for the channel, if it differs from the channel's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="description" type="s">
+ <tp:docstring>
+ A human-readable description of the channel's overall purpose.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="password" type="s">
+ <tp:docstring>
+ The password required to enter the channel if password-required is true.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="password-required" type="b">
+ <tp:docstring>
+ True if a password must be provided to enter the channel.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="persistent" type="b">
+ <tp:docstring>
+ True if the channel will remain in existence on the server after all
+ members have left it.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="private" type="b">
+ <tp:docstring>
+ True if the channel is not visible to non-members.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="subject" type="s">
+ <tp:docstring>
+ A human-readable description of the current subject of conversation in
+ the channel, similar to /topic in IRC. This is equivalent to the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >Subject</tp:dbus-ref> property in the Room interface which will replace
+ this Telepathy property.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="subject-contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ A contact handle representing who last modified the subject, or 0
+ if it isn't known. This is equivalent to the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >Subject</tp:dbus-ref> property in the Room interface which will replace
+ this Telepathy property.
+ </tp:docstring>
+ </tp:property>
+ <tp:property name="subject-timestamp" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ A unix timestamp indicating when the subject was last modified.
+ This is equivalent to the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Room.DRAFT"
+ >Subject</tp:dbus-ref> property in the Room interface which will replace
+ this Telepathy property.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for sending and receiving messages. This channel type
+ is primarily used for textual messages, but can also be used for
+ formatted text, text with "attachments", or binary messages on some
+ protocols.</p>
+
+ <p>Most of the methods and signals on this interface are deprecated,
+ since they only support plain-text messages with limited metadata.
+ See the mandatory <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Messages</tp:dbus-ref>
+ interface for the modern equivalents.</p>
+
+ <p>When a message is received, an identifier is assigned and a
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >MessageReceived</tp:dbus-ref> signal emitted, and the message
+ is placed in a pending queue represented by the
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >PendingMessages</tp:dbus-ref> property.
+ When the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ for a channel has handled the message by showing it to the user
+ (or equivalent), it should acknowledge the receipt of that message
+ using the <tp:member-ref>AcknowledgePendingMessages</tp:member-ref>
+ 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>Sending messages can be requested using the
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages"
+ >SendMessage</tp:dbus-ref> method, which will return
+ successfully when the message has been submitted for sending, or
+ return an error with no signal emission if there is an immediate
+ failure. If a message is submitted for sending but delivery of the
+ message later fails, this is indicated by a delivery report, which
+ is received in the same way as an incoming message.</p>
+
+ <p>Simple one-to-one chats (such as streams of private messages in
+ XMPP or IRC) should be represented by a Text channel whose
+ <tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref>
+ is <tp:type>Handle_Type</tp:type>_Contact. The expected way to
+ request such a channel is to set the ChannelType, TargetHandleType,
+ and either TargetHandle or TargetID in a call to EnsureChannel.</p>
+
+ <p>Named chat rooms whose identity can be saved and used again later
+ (IRC channels, Jabber MUCs) are expected to be represented by Text
+ channels with <tp:type>Handle_Type</tp:type>_Room and the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
+ interface. In protocols where a chatroom can be used as a continuation
+ of one or more one-to-one chats, these channels should also have the
+ <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref>
+ interface.</p>
+
+ <p>Unnamed, transient chat rooms which cannot be rejoined by their
+ unique identifier (e.g. a conversation on MSN which has, or once had,
+ three or more participants) are expected to be represented by Text
+ channels with Handle_Type_None (and hence TargetHandle 0), the
+ <tp:dbus-ref namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
+ interface, and optionally the
+ <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref>
+ interface.</p>
+
+ <p>On protocols like MSN 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, the initial one-to-one conversation
+ SHOULD be represented with Handle_Type_Contact. If a third participant
+ joins or is invited, this SHOULD be represented by signalling
+ a new <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> channel
+ with the one-to-one channel in its <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Conference"
+ >InitialChannels</tp:dbus-ref>, migrating the underlying protocol
+ object from the one-to-one channel to the Conference channel,
+ and creating a new protocol-level conversation if the one-to-one
+ channel is re-used. See the Conference interface for more details.</p>
+
+ <tp:rationale>
+ <p>This keeps the presentation of all one-to-one conversations
+ uniform, and makes it easier to hand over a conversation from a
+ 1-1-specific UI to a more elaborate multi-user UI; while it does
+ require UIs to understand Conference to follow the
+ upgrade, UIs that will deal with XMPP need to understand Conference
+ anyway.</p>
+ </tp:rationale>
+
+ <p>If a channel of type Text is closed while it has pending messages,
+ the connection manager MUST allow this, but SHOULD open a new channel
+ to deliver those messages, signalling it as a new channel with the
+ <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal. The new channel should resemble the old channel, but have
+ Requested = FALSE regardless of its previous value; the InitiatorHandle
+ and InitiatorID should correspond to the sender of one of the pending
+ messages.</p>
+
+ <tp:rationale>
+ <p>In effect, this turns this situation, in which a client
+ is likely to lose messages:</p>
+
+ <ul>
+ <li>UI window is closed</li>
+ <li>message arrives</li>
+ <li>text channel emits Received</li>
+ <li>UI calls Close on text channel before it has seen the
+ Received signal</li>
+ <li>text channel emits Closed and closes</li>
+ </ul>
+
+ <p>into something nearly equivalent to this situation, which is
+ fine:</p>
+
+ <ul>
+ <li>UI window is closed</li>
+ <li>UI calls Close on text channel</li>
+ <li>text channel emits Closed and closes</li>
+ <li>message arrives</li>
+ <li>new text channel is created, connection emits NewChannels</li>
+ <li>(the same or a different) UI handles it</li>
+ </ul>
+
+ <p>Requested must be set to FALSE so the replacement channel
+ will be handled by something.</p>
+
+ <p>In practice, connection managers usually implement this by keeping
+ the same internal object that represented the old channel, adjusting
+ its properties, signalling that it was closed, then immediately
+ re-signalling it as a new channel.</p>
+ </tp:rationale>
+
+ <p>As a result, Text channels SHOULD implement <tp:dbus-ref
+ namespace="ofdT">Channel.Interface.Destroyable</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>This "respawning" behaviour becomes problematic if there is no
+ suitable handler for Text channels, or if a particular message
+ repeatedly crashes the Text channel handler; a channel dispatcher
+ can't just Close() the channel in these situations, because
+ it will come back.</p>
+
+ <p>In these situations, the channel dispatcher needs a last-resort
+ way to destroy the channel and stop it respawning. It could either
+ acknowledge the messages itself, or use the Destroyable interface;
+ the Destroyable interface has the advantage that it's not
+ channel-type-dependent, so the channel dispatcher only has to
+ understand one extra interface, however many channel types
+ eventually need a distinction between Close and Destroy.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
new file mode 100644
index 0000000..c0a973f
--- /dev/null
+++ b/spec/Channel_Type_Tubes.xml
@@ -0,0 +1,615 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>
+ Copyright © 2007-2009 Collabora Limited
+ </tp:copyright>
+ <tp:license>
+ 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.
+
+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.
+
+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.
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.Tubes">
+
+ <tp:deprecated version="0.17.25">Client implementations
+ SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref>
+ instead.</tp:deprecated>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A "tube" is a mechanism for arbitrary data transfer. Two types of
+ data transfer are currently specified: D-Bus messages, and streams of
+ bytes. Each tube has a service name, which is a string specifying the
+ kind of communication that takes place over it, and a dictionary of
+ arbitrary parameters. Tube parameters are commonly used for bootstrap
+ information such as usernames and passwords. Each tube is identified
+ by a locally unique identifier.</p>
+
+ <p>The Tubes channel type may be requested for handles of type
+ HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p>
+
+ <p>Stream tubes specify listening addresses using pairs of parameters
+ with signature 'u', 'v', where the integer 'u' is a member of
+ Socket_Address_Type and the v is dependent on the type of address.</p>
+ </tp:docstring>
+
+ <tp:simple-type name="Tube_ID" type="u">
+ <tp:docstring>An identifier for a tube. These are local to a Tubes
+ channel, and may not be assumed to be the same as the other
+ participants' idea of the tube identifier.</tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="Tube_Info" array-name="Tube_Info_List">
+ <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" 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"/>
+ <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
+ <tp:member type="u" tp:type="Tube_State" name="State"/>
+ </tp:struct>
+
+ <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List">
+ <tp:docstring>Represents a participant in a multi-user D-Bus tube, as
+ returned by <tp:member-ref>GetDBusNames</tp:member-ref> and seen in the
+ <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle">
+ <tp:docstring>
+ The handle of a participant in this D-Bus tube.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
+ <tp:docstring>
+ That participant's unique name.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:enum name="Tube_Type" type="u" array-name="Tube_Type_List">
+ <tp:enumvalue suffix="DBus" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The tube is D-Bus tube as described by the
+ org.freedesktop.Telepathy.Channel.Type.DBusTube interface.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Stream" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The tube is stream tube as described by the
+ org.freedesktop.Telepathy.Channel.Type.StreamTube interface.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Tube_State" type="u">
+ <tp:enumvalue suffix="Local_Pending" value="0">
+ <tp:docstring>
+ The tube is waiting to be accepted/closed locally.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Remote_Pending" value="1">
+ <tp:docstring>
+ The tube is waiting to be accepted/closed remotely.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="2">
+ <tp:docstring>
+ The tube is open for traffic.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:mapping name="Supported_Socket_Map">
+ <tp:docstring>The supported socket address and access-control types
+ for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
+ <tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/>
+ <tp:member name="Access_Control" type="au"
+ tp:type="Socket_Access_Control[]"/>
+ </tp:mapping>
+
+ <method name="GetAvailableStreamTubeTypes"
+ tp:name-for-bindings="Get_Available_Stream_Tube_Types">
+ <tp:docstring>List the available address types and access-control types
+ for stream tubes.</tp:docstring>
+ <arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map"
+ name="Available_Stream_Tube_Types">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A mapping from address types (members of Socket_Address_Type) to
+ arrays of access-control type (members of Socket_Access_Control)
+ that the connection manager supports for stream tubes with that
+ address type. For simplicity, if a CM supports offering a
+ particular type of tube, it is assumed to support accepting it.</p>
+
+ <p>A typical value for a host without IPv6 support:</p>
+
+ <pre>
+ {
+ Socket_Address_Type_IPv4:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Port,
+ Socket_Access_Control_Netmask],
+ Socket_Address_Type_Unix:
+ [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials]
+ }
+ </pre>
+
+ <p>If stream tubes are not supported, this will be an empty
+ dictionary.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="GetAvailableTubeTypes"
+ tp:name-for-bindings="Get_Available_Tube_Types">
+ <arg direction="out" type="au" tp:type="Tube_Type[]"
+ name="Available_Tube_Types">
+ <tp:docstring>
+ An array of the available tube types, as defined by the Tube_Type
+ enum.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="ListTubes" tp:name-for-bindings="List_Tubes">
+ <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"
+ name="Tubes">
+ <tp:docstring>
+ Return an array of tuples, each representing a tube, with the
+ following members:
+
+ <ul>
+ <li>the tube's ID</li>
+ <li>the tube's initiator</li>
+ <li>the tube's type</li>
+ <li>the tube's service</li>
+ <li>the tube's parameters</li>
+ <li>the tube's state</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <!-- this tp:name-for-bindings is ugly, but compatible with
+ the code generation in telepathy-glib versions that did not use
+ tp:name-for-bindings -->
+ <method name="OfferDBusTube" tp:name-for-bindings="Offer_D_Bus_Tube">
+ <tp:docstring>
+ Offers a D-Bus tube providing the service specified.
+ </tp:docstring>
+ <arg direction="in" name="Service" type="s">
+ <tp:docstring>
+ A string representing the service name that will be used over the
+ tube.
+ It should be a well-known D-Bus service name, of the form
+ com.example.ServiceName.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ A dictionary of properties for the new tube; the allowable keys,
+ types and values are defined by the service. Connection managers
+ must support the value being any primitive (non-container)
+ D-Bus type, or a byte array 'ay'.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID">
+ <tp:docstring>
+ The ID of the new tube.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact associated with this channel doesn't have tubes
+ capabilities.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The connection manager doesn't support D-Bus tubes.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
+ <tp:docstring>
+ Offer a stream tube exporting the local socket specified.
+ </tp:docstring>
+ <arg direction="in" name="Service" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ 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".
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary of properties for the new tube; the allowable keys,
+ types and values are defined by the service. Connection managers
+ must support the value being any primitive (non-container)
+ D-Bus type, or a byte array 'ay'.</p>
+ <p>These should usually be the same key-value pairs specified for
+ use in the DNS-SD TXT record for that service.</p>
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of the listening address of the local service, as a member of
+ Socket_Address_Type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Address" type="v">
+ <tp:docstring>
+ The listening address of the local service, as indicated by the
+ address_type.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The access control the local service applies to the local socket,
+ specified so the connection manager can behave appropriately
+ when it connects.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control_Param" type="v">
+ <tp:docstring>
+ A parameter for the access control type, to be interpreted as
+ specified in the documentation for the Socket_Access_Control enum.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID">
+ <tp:docstring>
+ The ID of the new tube.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact associated with this channel doesn't have tube
+ capabilities.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The connection manager doesn't support stream tubes, or
+ does not support the given address type or access-control type.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="NewTube" tp:name-for-bindings="New_Tube">
+ <tp:docstring>
+ Emitted when a tube is created.
+ </tp:docstring>
+ <arg name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the new tube.
+ </tp:docstring>
+ </arg>
+ <arg name="Initiator" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the contact who initiated the tube.
+ </tp:docstring>
+ </arg>
+ <arg name="Type" type="u" tp:type="Tube_Type">
+ <tp:docstring>
+ The tube type, as defined by the Tube_Type enum.
+ </tp:docstring>
+ </arg>
+ <arg name="Service" type="s">
+ <tp:docstring>
+ A string representing the service that will be used over the tube.
+ </tp:docstring>
+ </arg>
+ <arg name="Parameters" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring>
+ The new tube's properties.
+ </tp:docstring>
+ </arg>
+ <arg name="State" type="u" tp:type="Tube_State">
+ <tp:docstring>
+ The new tube's state.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <!-- this tp:name-for-bindings is ugly, but compatible with
+ the code generation in telepathy-glib versions that did not use
+ tp:name-for-bindings -->
+ <method name="AcceptDBusTube" tp:name-for-bindings="Accept_D_Bus_Tube">
+ <tp:docstring>
+ Accept a D-Bus tube that's in the "local pending" state. The
+ connection manager will attempt to open the tube. The tube remains in
+ the "local pending" state until the TubeStateChanged signal is
+ emitted.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube to accept.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address" type="s">
+ <tp:docstring>
+ The string describing the address of the private bus. The client
+ should not attempt to connect to the address until the tube is open.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given tube ID is invalid or does not refer to a D-Bus
+ tube.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
+ <tp:docstring>
+ Accept a stream tube that's in the "local pending" state. The
+ connection manager will attempt to open the tube. The tube remains in
+ the "local pending" state until the TubeStateChanged signal is
+ emitted.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube to accept.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Address_Type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of address the connection manager should listen on.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control" type="u" tp:type="Socket_Access_Control">
+ <tp:docstring>
+ The type of access control the connection manager should apply to
+ the socket.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Access_Control_Param" type="v">
+ <tp:docstring>
+ A parameter for the access control type, to be interpreted as
+ specified in the documentation for the Socket_Access_Control enum.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address" type="v">
+ <tp:docstring>
+ The address on which the connection manager will listen for
+ connections to this tube. The client should not attempt to connect
+ to the address until the tube is open.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given tube ID is invalid or does not refer to a stream
+ tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given address type or access-control mechanism is not supported.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="TubeStateChanged" tp:name-for-bindings="Tube_State_Changed">
+ <tp:docstring>
+ Emitted when the state of a tube changes.
+ </tp:docstring>
+ <arg name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube that changed state.
+ </tp:docstring>
+ </arg>
+ <arg name="State" type="u" tp:type="Tube_State">
+ <tp:docstring>
+ The new state of the tube; see the Tube_State enumeration.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="CloseTube" tp:name-for-bindings="Close_Tube">
+ <tp:docstring>
+ Close a tube.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube to close.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
+ </tp:possible-errors>
+ </method>
+
+ <signal name="TubeClosed" tp:name-for-bindings="Tube_Closed">
+ <tp:docstring>
+ Emitted when a tube has been closed. The ID of a closed tube is no
+ longer valid. The ID may later be reused for a new tube.
+ </tp:docstring>
+ <arg name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube that was closed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <!-- this tp:name-for-bindings is ugly, but compatible with
+ the code generation in telepathy-glib versions that did not use
+ tp:name-for-bindings -->
+ <method name="GetDBusTubeAddress"
+ tp:name-for-bindings="Get_D_Bus_Tube_Address">
+ <tp:docstring>
+ For a D-Bus tube, return a string describing the address of the
+ private bus.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube to get an address for.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="s" name="Address">
+ <tp:docstring>
+ The bus address.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The tube is not a D-Bus tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This tube is not in the "open" state.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <!-- this tp:name-for-bindings is ugly, but compatible with
+ the code generation in telepathy-glib versions that did not use
+ tp:name-for-bindings -->
+ <method name="GetDBusNames" tp:name-for-bindings="Get_D_Bus_Names">
+ <tp:docstring>
+ For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
+ between contact handles and their unique bus names on this tube.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube to get names for.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]"
+ name="DBus_Names">
+ <tp:docstring>
+ An array of structures, each containing a contact handle and a D-Bus
+ bus name.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The tube is not a multi-user D-Bus tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This tube is not in the "open" state.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <!-- this tp:name-for-bindings is ugly, but compatible with
+ the code generation in telepathy-glib versions that did not use
+ tp:name-for-bindings -->
+ <signal name="DBusNamesChanged" tp:name-for-bindings="D_Bus_Names_Changed">
+ <tp:docstring>
+ Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
+ participant opens or closes the tube.
+ </tp:docstring>
+ <arg name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube whose names have changed.
+ </tp:docstring>
+ </arg>
+ <arg name="Added" type="a(us)" tp:type="DBus_Tube_Member[]">
+ <tp:docstring>
+ Array of handles and D-Bus names of new participants.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ Array of handles of former participants.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="GetStreamTubeSocketAddress"
+ tp:name-for-bindings="Get_Stream_Tube_Socket_Address">
+ <tp:docstring>
+ For a stream tube, obtain the address of the socket used to
+ communicate over this tube.
+ </tp:docstring>
+ <arg direction="in" name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the stream tube to get the socket for.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address_Type" type="u" tp:type="Socket_Address_Type">
+ <tp:docstring>
+ The type of the listening address of the socket, as a member of
+ Socket_Address_Type.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Address" type="v">
+ <tp:docstring>
+ The listening address of the socket, as indicated by the
+ address_type.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The tube is not a stream tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This tube is not in the "open" state.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="StreamTubeNewConnection"
+ tp:name-for-bindings="Stream_Tube_New_Connection">
+ <tp:docstring>
+ Emitted on a stream tube when a participant opens a new connection
+ to its socket.
+ </tp:docstring>
+ <arg name="ID" type="u" tp:type="Tube_ID">
+ <tp:docstring>
+ The ID of the tube
+ </tp:docstring>
+ </arg>
+ <arg name="Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the participant who opened the new connection
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client.xml b/spec/Client.xml
new file mode 100644
index 0000000..19f6914
--- /dev/null
+++ b/spec/Client.xml
@@ -0,0 +1,122 @@
+<?xml version="1.0" ?>
+<node name="/Client"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.Client">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Telepathy clients use connection managers, the channel dispatcher
+ and optionally the account manager to provide useful
+ functionality.</p>
+
+ <p>User interface processes are the obvious example of Telepathy
+ clients, but they can provide other functionality, such as
+ address-book synchronization.</p>
+
+ <p>Every running or activatable process with a well-known
+ name of the form org.freedesktop.Telepathy.Client.<em>clientname</em>
+ should be probed by the channel dispatcher to discover its
+ capabilities. Each client is either an <em>observer</em>, an
+ <em>approver</em>, a <em>channel handler</em>, or some combination
+ of these.</p>
+
+ <tp:rationale>
+ <p>Activatable services (those with a D-Bus <code>.service</code>
+ file) must be supported so that we can run clients
+ in response to channel creation.</p>
+
+ <p>Non-activatable services (those that do not register a D-Bus
+ <code>.service</code> file for their well-known name, but do
+ request it at runtime) must be supported so that we can have
+ programs that process channels, but only if they are already
+ running - for instance, a full-screen media centre
+ application might do this.</p>
+ </tp:rationale>
+
+ <p>The client name, <em>clientname</em>, MUST be a non-empty string of
+ ASCII digits, letters, dots and/or underscores, starting with a
+ letter, and without sets of two consecutive dots or a dot
+ followed by a digit. For non-activatable services, it MAY contain a
+ part that is generated per instance at runtime.</p>
+
+ <tp:rationale>
+ <p>If each of a client Foo's instances should be able to manipulate
+ channels separately, the instance with unique name
+ <code>:1.25</code> might request a well-known name like
+ <code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p>
+
+ <p>(Note that well-known bus-name components may not start with a
+ digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p>
+ </tp:rationale>
+
+ <p>Each Client MUST export an object whose object path may be
+ determined by replacing '.' with '/' in the well-known name and
+ prepending '/'. This object represents its API as a Telepathy
+ client; the channel dispatcher will call its methods and read
+ its properties when appropriate.</p>
+
+ <p>As an optimization, activatable clients SHOULD install a file
+ <code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code>
+ containing a cached version of its immutable properties,
+ so that for most clients, the channel dispatcher can
+ just read a file to discover capabilities, instead of
+ having to service-activate the client immediately in order to fetch
+ its read-only properties. However, the D-Bus API is canonical, and
+ the channel dispatcher MUST support clients without such a file.</p>
+
+ <p>Non-activatable clients MAY install a <code>.client</code> file,
+ but there's not much point in them doing so.</p>
+
+ <p>The .client files MUST contain UTF-8 text with the same syntax
+ as
+ <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
+ Entry files</a> (although the allowed groups, keys and values differ).
+ Every <code>.client</code> file MUST contain a group whose name is
+ the name of this interface.</p>
+
+ <p>The groups, keys and values in the <code>.client</code> file are
+ defined by individual interfaces. Each interface that can usefully
+ cache information in the <code>.client</code> file SHOULD correspond
+ to a group with the same name.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the extra interfaces provided by this client.
+ This SHOULD include at least one of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p>
+
+ <p>In the <code>.client</code> file, this is represented by key
+ "<code>Interfaces</code>" in the group named after this interface.
+ The value of the key is a list of interface names each followed by
+ a semicolon (so it always ends with a semicolon unless it is empty),
+ i.e. a key of type "strings" as described in the Desktop Entry
+ specification.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
new file mode 100644
index 0000000..dd26303
--- /dev/null
+++ b/spec/Client_Approver.xml
@@ -0,0 +1,197 @@
+<?xml version="1.0" ?>
+<node name="/Client_Approver"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.Client.Approver">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Approvers are clients that notify the user that new channels have
+ been created by a contact, and allow the user to accept or reject
+ those channels. The new channels are represented by a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>
+ object, which is passed to the
+ <tp:member-ref>AddDispatchOperation</tp:member-ref> method.</p>
+
+ <tp:rationale>
+ <p>For instance, Empathy's tray icon, or the answer/reject window
+ seen when a Maemo device receives a VoIP call, should be
+ Approvers.</p>
+ </tp:rationale>
+
+ <p>Approvers can also select which channel handler will be used for the
+ channel, for instance by offering the user a list of possible
+ handlers rather than just an accept/reject choice.
+ However, the Channel Dispatcher must be able to prioritize
+ possible handlers on its own using some reasonable heuristic,
+ probably based on user configuration.</p>
+
+ <p>It is possible (and useful) to have an approver and
+ a channel handler in the same process; this is particularly useful
+ if a channel handler wants to claim responsibility for particular
+ channels itself.</p>
+
+ <p>All approvers are notified simultaneously. For instance, in a
+ desktop system, there might be one approver that displays a
+ notification-area icon, one that is part of a contact list
+ window and highlights contacts there, and one that is part
+ of a full-screen media player.</p>
+
+ <p>Any approver can approve the handling of a channel dispatch operation
+ with a particular channel handler by calling the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref>
+ method. Approvers can also attempt to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref>
+ channels; if this succeeds, the approver may handle the channels
+ itself (if it is also a Handler), or close the channels in order to
+ reject them.</p>
+
+ <p>At the D-Bus level, there is no "reject" operation: approvers wishing
+ to reject channels SHOULD call the Claim method, then (if it succeeds)
+ close the channels in any way they see fit.</p>
+
+ <p>The first approver to reply gets its decision acted on; any other
+ approvers that reply at approximately the same time will get a D-Bus
+ error, indicating that the channel has already been dealt with.</p>
+
+ <p>Approvers should usually prompt the user and ask for
+ confirmation, rather than dispatching the channel to a handler
+ straight away.</p>
+ </tp:docstring>
+
+ <property name="ApproverChannelFilter"
+ tp:name-for-bindings="Approver_Channel_Filter"
+ type="aa{sv}" access="read" tp:type="Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specification of the channels in which this approver is
+ interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref>
+ method should be called by the channel dispatcher whenever at least
+ one of the channels in a channel dispatch operation matches this
+ description.</p>
+
+ <p>This property works in exactly the same way as the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref>
+ property. In particular, it cannot change while the approver process
+ continues to own the corresponding Client bus name.</p>
+
+ <p>In the .client file, it is represented in the
+ same way as ObserverChannelFilter, but the group has the same
+ name as this interface and the keys start with
+ ApproverChannelFilter instead of ObserverChannelFilter.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="AddDispatchOperation"
+ tp:name-for-bindings="Add_Dispatch_Operation">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when a ChannelDispatchOperation
+ in which the approver has registered an interest is created,
+ or when the approver starts up while such channel dispatch
+ operations already exist.</p>
+
+ <p>The channel dispatcher SHOULD call this method on all approvers
+ at the same time. If an approver returns an error from this method,
+ the approver is assumed to be faulty.</p>
+
+ <p>If no approvers return from this method
+ successfully (including situations where there are no matching
+ approvers at all), the channel dispatcher SHOULD consider this
+ to be an error, and recover by dispatching the channel to the
+ most preferred handler.</p>
+
+ <tp:rationale>
+ Processes that aren't approvers (or don't at least ensure that there
+ is some approver) probably shouldn't be making connections
+ anyway, so there should always be at least one approver running.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channels" direction="in"
+ type="a(oa{sv})" tp:type="Channel_Details[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The initial value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Channels</tp:dbus-ref>
+ property, containing the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ to be dispatched and their properties.</p>
+
+ <tp:rationale>
+ <p>This can't be signalled to the approver through the Properties
+ parameter of this method, because Channels is not an immutable
+ property.</p>
+ </tp:rationale>
+
+ <p>This argument always contains all of the channels in the channel
+ dispatch operation, even if not all of them actually match
+ the <tp:member-ref>ApproverChannelFilter</tp:member-ref>.</p>
+
+ <tp:rationale>
+ <p>This seems the least bad way to handle such a situation;
+ see the discussion on
+ <a href="http://bugs.freedesktop.org/show_bug.cgi?id=21090">bug
+ #21090</a>.</p>
+ </tp:rationale>
+
+ <p>The actual channels to be dispatched may reduce as channels are
+ closed: this is signalled by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.ChannelLost</tp:dbus-ref>.
+ </p>
+
+ <p>Approvers SHOULD connect to ChannelLost and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>.
+ (if desired) before returning from AddDispatchOperation, since
+ those signals are guaranteed not to be emitted until after all
+ AddDispatchOperation calls have returned (with success or failure)
+ or timed out.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="DispatchOperation" type="o" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>
+ to be processed.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map" direction="in">
+ <tp:docstring>
+ <p>Properties of the channel dispatch operation. The keys MUST be
+ fully qualified D-Bus property names. This MUST NOT include
+ properties that could change, SHOULD include as many properties as
+ possible given that constraint, and MUST include at least the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">PossibleHandlers</tp:dbus-ref>
+ properties.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
new file mode 100644
index 0000000..3a922e8
--- /dev/null
+++ b/spec/Client_Handler.xml
@@ -0,0 +1,337 @@
+<?xml version="1.0" ?>
+<node name="/Client_Handler"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.Client.Handler">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Handlers are the user interface for a channel. They turn an abstract
+ Telepathy channel into something the user wants to see, like a text
+ message stream or an audio and/or video call.</p>
+
+ <p>For its entire lifetime, each channel on a connection known to the
+ channel dispatcher is either being processed by the channel dispatcher,
+ or being handled by precisely one Handler.</p>
+
+ <p>Because each channel is only handled by one Handler, handlers may
+ perform actions that only make sense to do once, such as acknowledging
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ messages, doing the actual streaming for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channels with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface, or transferring the file in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">FileTransfer</tp:dbus-ref>
+ channels.</p>
+
+ <p>When a new incoming channel (one with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
+ = FALSE) is offered to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
+ by the channel dispatcher, it also offers the Approvers a list of all
+ the running or activatable handlers whose
+ <tp:member-ref>HandlerChannelFilter</tp:member-ref> property
+ (possibly as cached in the .client file) indicates that they
+ are able to handle the channel. The Approvers can choose one of
+ those channel handlers to handle the channel.</p>
+
+ <p>When a new outgoing channel (one with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
+ = TRUE) appears, the channel dispatcher passes it to an appropriate
+ channel handler automatically.
+ </p>
+
+ </tp:docstring>
+
+ <property name="HandlerChannelFilter"
+ tp:name-for-bindings="Handler_Channel_Filter"
+ type="aa{sv}" access="read" tp:type="Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specification of the channels that this channel handler can
+ deal with. It will be offered to approvers as a potential
+ channel handler for bundles that contain only suitable channels,
+ or for suitable channels that must be handled separately.</p>
+
+ <p>This property works in exactly the same way as the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.ObserverChannelFilter</tp:dbus-ref>
+ property. In particular, it cannot change while the handler process
+ continues to own the corresponding Client bus name.</p>
+
+ <p>In the .client file, it is represented in the
+ same way as ObserverChannelFilter, but the group has the same
+ name as this interface and the keys start with
+ HandlerChannelFilter instead of ObserverChannelFilter.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, channels destined for this handler are automatically
+ handled, without invoking approvers.</p>
+
+ <tp:rationale>
+ <p>The intended usage is to allow a client handling one channel to
+ pick up closely related channels. Suppose a client capable of
+ handling both Text and StreamedMedia,
+ <code>org.freedesktop.Telepathy.Client.Empathy</code>, is
+ handling a StreamedMedia channel. That client can take a second
+ well-known bus name, say
+ <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>,
+ and configure an object at
+ <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code>
+ with BypassApproval = TRUE,
+ whose <tp:member-ref>HandlerChannelFilter</tp:member-ref>
+ matches closely related Text channels by their Bundle property.</p>
+ </tp:rationale>
+
+ <p>For service-activatable handlers, this property should be specified
+ in the handler's <tt>.client</tt> file as follows:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler]
+BypassApproval=true
+</pre>
+ </tp:docstring>
+ </property>
+
+ <tp:simple-type name="Handler_Capability_Token" type="s"
+ array-name="Handler_Capability_Token_List">
+ <tp:docstring>
+ A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
+ and an identifier for a capability defined by that interface. The
+ capability identifier SHOULD be in lower case. If an interface
+ references an external specification which is case-insensitive (such
+ as MIME), then names from that specification MUST be normalized to
+ lower-case before providing them to this Telepathy API, so that
+ implementations can safely rely on simple byte-by-byte comparison.
+
+ <tp:rationale>
+ These aren't D-Bus core Properties, and we want them to look visibly
+ different.
+ </tp:rationale>
+
+ <p>So far, all client capabilities are defined by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="Capabilities" tp:name-for-bindings="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The set of additional capabilities supported by this handler.
+ This describes things like support for streamed media codecs and
+ NAT traversal mechanisms: see the Contact Capabilities
+ interface for more details.</p>
+
+ <p>For handlers that have a <code>.client</code> file, the
+ channel dispatcher may discover this property from the
+ <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code>
+ group; for each capability, that group contains a key
+ whose name is the capability, with value <code>true</code>.
+ Keys with other values SHOULD NOT appear in this group.</p>
+
+ <p>For instance, the <code>.client</code> file for a streamed media
+ handler that supports ICE-UDP NAT traversal, Speex audio,
+ and Theora and H264 video might contain this group:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler.Capabilities]
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
+</pre>
+
+ <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref>
+ property, this property cannot change while the Handler owns its
+ Client bus name. However, the <code>.client</code> file, if any,
+ can change (due to upgrades or installation of pluggable codecs),
+ and the capabilities really supported by the handler might not
+ exactly match what is cached in the <code>.client</code> file.</p>
+
+ <tp:rationale>
+ <p>The client file is installed statically and is intended to list
+ codecs etc. that the handler guarantees it can support (e.g. by
+ having a hard dependency on them), whereas the running handler
+ process might be able to find additional codecs.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="HandleChannels" tp:name-for-bindings="Handle_Channels">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when this client should handle these
+ channels, or when this client should present channels that it is already
+ handling to the user (e.g. bring them into the foreground).</p>
+
+ <tp:rationale>
+ <p>Clients are expected to know what channels they're already handling,
+ and which channel object path corresponds to which window or tab.
+ This can easily be done using a hash table keyed by channels' object
+ paths.</p>
+ </tp:rationale>
+
+ <p>This method can raise any D-Bus error. If it does, the
+ handler is assumed to have failed or crashed, and the channel
+ dispatcher MUST recover in an implementation-specific way; it MAY
+ attempt to dispatch the channels to another handler, or close the
+ channels.</p>
+
+ <p>If closing the channels, it is RECOMMENDED that the channel
+ dispatcher attempts to close the channels using
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>,
+ but resorts to calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
+ (if available) or ignoring the channel (if not) if the same handler
+ repeatedly fails to handle channels.</p>
+
+ <p>After HandleChannels returns successfully, the client process is
+ considered to be responsible for the channel until it its unique
+ name disappears from the bus.</p>
+
+ <tp:rationale>
+ <p>If a process has multiple Client bus names - some temporary and
+ some long-lived - and drops one of the temporary bus names in order
+ to reduce the set of channels that it will handle, any channels
+ that it is already handling should remain unaffected.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the channels are associated. The
+ well-known bus name to use is that of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Connection" type="o" direction="in">
+ <tp:docstring>
+ The Connection with which the channels are associated. The
+ well-known bus name to use can be derived from this object
+ path by removing the leading '/' and replacing all subsequent
+ '/' by '.'.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channels" type="a(oa{sv})" direction="in"
+ tp:type="Channel_Details[]">
+ <tp:docstring>
+ The channels and their immutable properties. Their well-known
+ bus name is the same as that of the Connection.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Requests_Satisfied" type="ao" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requests satisfied by these channels.</p>
+
+ <tp:rationale>
+ <p>If the handler implements Requests, this tells it
+ that these channels match previous <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
+ calls that it may have received.</p>
+
+ <p>There can be more than one, if they were EnsureChannel
+ requests.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="User_Action_Time" type="t" direction="in">
+ <tp:docstring>
+ The time at which user action occurred, or 0 if this channel
+ is to be handled for some reason not involving user action.
+ Handlers SHOULD use this for focus-stealing prevention,
+ if applicable.
+ This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type>
+ but is unsigned for historical reasons.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Handler_Info" type="a{sv}" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about these channels. Currently defined
+ keys are:</p>
+
+ <dl>
+ <dt><code>request-properties</code> - a{oa{sv}}</dt>
+ <dd>A map from <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ paths listed in <var>Requests_Satisfied</var> to
+ <tp:type>Qualified_Property_Value_Map</tp:type>s containing
+ namespaced immutable properties of each request.</dd>
+ </dl>
+
+ <p>When more keys are defined for this dictionary, all will be
+ optional; handlers MAY safely ignore any entry in this
+ dictionary.</p>
+ </tp:docstring>
+ </arg>
+
+ <!-- FIXME: invent a way to say "any error is possible" in spec markup -->
+ </method>
+
+ <property name="HandledChannels" tp:name-for-bindings="Handled_Channels"
+ type="ao" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the channels that this process is currently handling.</p>
+
+ <p>There is no change notification.</p>
+
+ <tp:rationale>
+ <p>This property exists for state recovery - it makes it possible
+ for channel handling to survive a ChannelDispatcher crash.</p>
+
+ <p>If the channel dispatcher is automatically replaced, the
+ replacement can discover all Handlers by looking for the Client
+ well-known bus names, and discover which channels they are
+ currently handling. Once this has been done, all unhandled
+ channels can be re-dispatched, and the only issue visible to
+ the user is that unhandled channels that they have already
+ approved might be sent back to Approvers.</p>
+ </tp:rationale>
+
+ <p>The value of this property SHOULD be the same for all Client
+ instances that share a unique bus name, and SHOULD include all
+ channels that are being handled, even if they were conceptually
+ handled by a different Client instance.</p>
+
+ <tp:rationale>
+ <p>Otherwise, when a process released a temporary Client name,
+ channels that it handled because of that Client name would no
+ longer be state-recoverable.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Handler_Future.xml b/spec/Client_Handler_Future.xml
new file mode 100644
index 0000000..4c1a8b7
--- /dev/null
+++ b/spec/Client_Handler_Future.xml
@@ -0,0 +1,88 @@
+<?xml version="1.0" ?>
+<node name="/Client_Handler_Future"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.Client.Handler.FUTURE"
+ tp:causes-havoc="a staging area for future Handler functionality">
+ <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface contains functionality which we intend to incorporate
+ into the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ interface in future. It should be considered to
+ be conceptually part of the core Handler interface, but without
+ API or ABI guarantees.</p>
+ </tp:docstring>
+
+ <property name="BypassObservers" tp:name-for-bindings="Bypass_Observers"
+ type="b" access="read">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, channels destined for this handler are not passed to
+ observers for observing.</p>
+
+ <tp:rationale>
+ <p>This is useful in use-cases where the handler doesn't want anyone
+ observing the channel - for example, because channels it handles
+ shouldn't be logged.</p>
+ </tp:rationale>
+
+ <p>For service-activatable handlers, this property should be specified
+ in the handler's <tt>.client</tt> file as follows:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler]
+BypassObservers=true
+</pre>
+ </tp:docstring>
+ </property>
+
+ <property name="RelatedConferencesBypassApproval"
+ tp:name-for-bindings="Related_Conferences_Bypass_Approval"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, channels destined for this handler that have the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference</tp:dbus-ref> interface, with a channel that
+ was previously handled by the same client process in their
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Conference"
+ >InitialChannels</tp:dbus-ref> property, should bypass the
+ approval stage. In effect, this is a weaker form of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client.Handler"
+ >BypassApproval</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>It would be reasonable for a user interface to accept
+ invitations to continuations of an existing channel automatically,
+ or not; this is a matter of UI policy.</p>
+
+ <p>It's somewhat complex for an Approver to keep track of which
+ channels are being handled by a particular Handler, but
+ the Channel Dispatcher already has to track this, so it's
+ useful for the channel dispatcher to assist here.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml
new file mode 100644
index 0000000..3cecfce
--- /dev/null
+++ b/spec/Client_Interface_Requests.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" ?>
+<node name="/Client_Interface_Requests"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.Client.Interface.Requests">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Client.Handler"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface can be implemented by a Handler to be notified about
+ requests for channels that it is likely to be asked to handle.</p>
+ </tp:docstring>
+
+ <method name="AddRequest" tp:name-for-bindings="Add_Request">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the ChannelDispatcher to indicate that channels have been
+ requested, and that if the request is successful, they will probably
+ be handled by this Handler. The ChannelDispatcher SHOULD only
+ call this method on one handler per request.</p>
+
+ <tp:rationale>
+ <p>This allows the UI to start preparing to handle the channels
+ in advance (e.g. render a window with an "in progress" message),
+ improving perceived responsiveness.</p>
+
+ <p>The use of "probably" is because you can't necessarily tell from
+ a channel request which handler will handle particular channels.
+ A reasonable heuristic would be to match the request against the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>,
+ and respect the preferred handler (if any).</p>
+ </tp:rationale>
+
+ <p>If the request succeeds and is given to the expected Handler,
+ the Requests_Satisfied parameter to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ can be used to match the channel to a previous AddRequest call.</p>
+
+ <tp:rationale>
+ <p>This lets the UI direct the channels to the window that it
+ already opened.</p>
+ </tp:rationale>
+
+ <p>If the request fails, the expected handler is notified by the
+ channel dispatcher calling its
+ <tp:member-ref>RemoveRequest</tp:member-ref> method.</p>
+
+ <tp:rationale>
+ <p>This lets the UI close the window or display the error.</p>
+ </tp:rationale>
+
+ <p>The channel dispatcher SHOULD remember which handler was notified,
+ and if the channel request succeeds, it SHOULD dispatch the channels
+ to the expected handler, unless the channels do not match that
+ handler's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>.
+ If the channels are not dispatched to the expected handler, the
+ handler that was expected is notified by the channel dispatcher
+ calling its <tp:member-ref>RemoveRequest</tp:member-ref> method
+ with the NotYours error.</p>
+
+ <tp:rationale>
+ <p>Expected handling is for the UI to close the window it
+ previously opened.</p>
+ </tp:rationale>
+
+ <p>Handlers SHOULD NOT return an error from this method; errors
+ returned from this method SHOULD NOT alter the channel dispatcher's
+ behaviour.</p>
+
+ <tp:rationale>
+ <p>Calls to this method are merely a notification.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Request" type="o" direction="in">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object, which MUST have been returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatcher">CreateChannel</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
+ before this method is called.
+
+ <tp:rationale>
+ See those methods for the rationale of this ordering.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map" direction="in">
+ <tp:docstring>
+ <p>Some of the properties of the ChannelRequest. To avoid race
+ conditions, this dictionary MUST NOT include properties whose
+ values could subsequently change. It SHOULD include as many
+ properties as possible, given that constraint.</p>
+
+ <p>In particular, the properties <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref>
+ MUST be included, and <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
+ MUST be included if implemented.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="RemoveRequest"
+ tp:name-for-bindings="Remove_Request">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the ChannelDispatcher to indicate that a request
+ previously passed to <tp:member-ref>AddRequest</tp:member-ref>
+ has failed and should be disregarded.</p>
+
+ <p>Handlers SHOULD NOT return an error from this method; errors
+ returned from this method SHOULD NOT alter the channel dispatcher's
+ behaviour.</p>
+
+ <tp:rationale>
+ <p>Calls to this method are merely a notification.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Request" type="o" direction="in">
+ <tp:docstring>
+ The request that failed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the D-Bus error with which the request failed.</p>
+
+ <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>,
+ this indicates that the request succeeded, but all the resulting
+ channels were given to some other handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s" direction="in">
+ <tp:docstring>
+ Any message supplied with the D-Bus error.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
new file mode 100644
index 0000000..01fee8b
--- /dev/null
+++ b/spec/Client_Observer.xml
@@ -0,0 +1,379 @@
+<?xml version="1.0" ?>
+<node name="/Client_Observer"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp: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.Client.Observer">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Observers monitor the creation of new channels. This
+ functionality can be used for things like message logging.
+ All observers are notified simultaneously.</p>
+
+ <p>Observers SHOULD NOT modify the state of a channel except
+ via user interaction.</p>
+
+ <tp:rationale>
+ <p>We want Observer UIs for file transfer channels (a progress
+ bar for the transfer) to be able to have a Cancel button.</p>
+ </tp:rationale>
+
+ <p>Observers MUST NOT carry out actions that exactly one process
+ must take responsibility for (e.g. acknowledging Text
+ messages, or carrying out the actual transfer in a file transfer
+ channel).</p>
+
+ <tp:rationale>
+ <p>Since arbitrarily many observers can be activated for
+ each channel, it would not make sense for observers to do things
+ that can only be done by one process (acknowledging
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ messages, carrying out streaming for
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channels, doing the actual data transfer for file transfers,
+ setting up the out-of-band connection for Tubes). The
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ is responsible for such tasks.</p>
+
+ <p>Handlers MAY, of course, delegate responsibility for these
+ tasks to other processes (including those run as observers),
+ but this MUST be done explicitly via a request from the Handler
+ to the Observer.</p>
+ </tp:rationale>
+
+ <p>Whenever a collection of new channels is signalled, the channel
+ dispatcher will notify all running or activatable observers whose
+ <tp:member-ref>ObserverChannelFilter</tp:member-ref> property
+ (possibly as cached in the .client file) indicates that they are
+ interested in some of the channels.</p>
+
+ <p>Observers are activated for all channels in which they have
+ registered an interest - incoming, outgoing or automatically created -
+ although of course the ObserverChannelFilter property can be set
+ to filter on the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
+ property.</p>
+
+ <p>Because it might take time for an observer to become ready (for
+ instance, a Text logger needs to wait until pending messages have been
+ downloaded), the channel dispatcher must wait (up to some timeout) for
+ all observers to return from
+ <tp:member-ref>ObserveChannels</tp:member-ref> before letting anything
+ destructive happen. Destructive things (e.g. acknowledging messages)
+ are defined to be done by handlers, therefore HandleWith and Claim
+ aren't allowed to succeed until all observers are ready.</p>
+ </tp:docstring>
+
+ <property name="ObserverChannelFilter"
+ tp:name-for-bindings="Observer_Channel_Filter"
+ type="aa{sv}" access="read" tp:type="Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A specification of the channels in which this observer is
+ interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method
+ should be called by the channel dispatcher whenever any of the new
+ channels in a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal match this description.</p>
+
+ <p>Only certain D-Bus types have useful semantics for matching like this,
+ so only certain types are allowed:</p>
+
+ <dl>
+ <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt>
+ <dd>Matched by numeric value, regardless of type (e.g. 42 as a
+ 16-bit signed integer 'n' is considered equal to 42 as a 32-bit
+ unsigned integer 'u')</dd>
+
+ <dt>Booleans (b)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ <dt>Strings (s)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ <dt>Object paths (o)</dt>
+ <dd>Matched by equality in the obvious way; not considered equal to any
+ other type</dd>
+
+ </dl>
+
+ <p>This property never changes while the observer process owns its
+ Client bus name. For activatable processes, the filter can change
+ due to an upgrade - the channel dispatcher SHOULD observe changes to
+ .client files using a mechanism like inotify.</p>
+
+ <tp:rationale>
+ <p>Not allowing this property to change is a simplification,
+ particularly for activatable processes (we reject the possibility
+ that a process with a .client file, when activated, has a filter
+ that differs from what its .client file said).</p>
+
+ <p>If an Observer wants to add extra channels to its list of
+ interests at runtime, it can register an additional Client bus name
+ (for instance, the org.freedesktop.Telepathy.Client.Empathy process
+ with unique name :1.42 could additionally register
+ org.freedesktop.Telepathy.Client.Empathy._1_42) with additional
+ filters. To remove those filters, it can release the bus name;
+ it could even re-claim the bus name immediately, with different
+ filters.</p>
+
+ <p>The same principle is applied to Approvers and Handlers.</p>
+ </tp:rationale>
+
+ <p>For observers that have a .client file, the channel dispatcher
+ may discover this property from keys of the form
+ "<code><em>propertyname</em> <em>type</em></code>",
+ in groups in the .client file whose name is the name of this
+ interface followed by <code>.ObserverChannelFilter</code>,
+ a space and an ASCII decimal number starting from 0.</p>
+
+ <p>Values in the .client file are encoded in exactly the same way as
+ the <code>default-<em>p</em></code> keys in .manager files, as
+ described in the <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface (but note that not all
+ types supported in .manager files can appear in .client files).</p>
+
+ <p>For instance, a .client file for an observer that is only interested
+ in Text channels, with CONTACT or ROOM handles, that were requested by
+ a local client:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client]
+Interfaces=org.freedesktop.Telepathy.Client.Observer;
+
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+org.freedesktop.Telepathy.Channel.Requested b=true
+
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=2
+org.freedesktop.Telepathy.Channel.Requested b=true
+</pre>
+
+ </tp:docstring>
+ </property>
+
+ <property name="Recover" tp:name-for-bindings="Recover" type="b"
+ access="read">
+ <tp:added version="0.19.4">
+ When using telepathy-mission-control, version 5.4.0 or later is
+ needed for this property to be useful.
+ </tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, upon the startup of this observer, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref>
+ will be called for every already existing channel matching
+ its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
+
+ <p>When an activatable client having this property disappears from the
+ bus and there are channels matching its ObserverChannelFilter,
+ ObserveChannels will be called immediately to reactivate it
+ again. Such clients should specify this property in their
+ <tt>.client</tt> file as follows:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Observer]
+Recover=true
+</pre>
+
+ <tp:rationale>
+ <p>This means that if an activatable Observer crashes, it will
+ be restarted as soon as possible; while there is an unavoidable
+ possibility that it will miss some events during this process
+ (particularly <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ messages), this window of event loss is kept to a minimum.</p>
+
+ <p>Non-activatable observers can't take advantage of this
+ mechanism, but setting this property on a non-activatable
+ observer does allow it to "catch up" on channels that are
+ currently active at the time that it starts up.</p>
+ </tp:rationale>
+
+ <p>When the ObserveChannels method is called due to observer recovery,
+ the <var>Observer_Info</var> dictionary will contain one extra item
+ mapping the key <code>"recovering"</code> to <code>True</code>.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by the channel dispatcher when channels in which the
+ observer has registered an interest are announced in a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal.</p>
+
+ <p>If the same NewChannels signal announces some channels that match
+ the filter, and some that do not, then only a subset of the channels
+ (those that do match the filter) are passed to this method.</p>
+
+ <p>If the channel dispatcher will split up the channels from a single
+ NewChannels signal and dispatch them separately (for instance
+ because no installed Handler can handle all of them), it will call
+ ObserveChannels several times.</p>
+
+ <p>The observer MUST NOT return from this method call until it is ready
+ for a handler for the channel to run (which may change the channel's
+ state).</p>
+
+ <tp:rationale>
+ <p>The channel dispatcher must wait for observers to start up,
+ to avoid the following race: text channel logger (observer) gets
+ ObserveChannels, text channel handler gets
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ channel handler starts up faster and acknowledges messages,
+ logger never sees those messages.</p>
+ </tp:rationale>
+
+ <p>The channel dispatcher SHOULD NOT change its behaviour based on
+ whether this method succeeds or fails: there are no defined D-Bus
+ errors for this method, and if it fails, this only indicates that
+ an Observer is somehow broken.</p>
+
+ <tp:rationale>
+ <p>The expected error response in the channel dispatcher is to
+ log a warning, and otherwise continue as though this method
+ had succeeded.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the channels are associated. The
+ well-known bus name to use is that of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Connection" type="o" direction="in">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ with which the channels are associated. The
+ well-known bus name to use can be derived from this object
+ path by removing the leading '/' and replacing all subsequent
+ '/' by '.'.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"
+ direction="in">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ and their properties. Their well-known bus names are all the same as
+ that of the Connection.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Dispatch_Operation" type="o" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The path to the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>
+ for these channels, or the special value '/' if there is no
+ ChannelDispatchOperation (because the channels were requested, not
+ incoming).</p>
+
+ <p>If the Observer calls <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">HandleWith</tp:dbus-ref>
+ on the dispatch operation, it MUST be careful to avoid deadlock,
+ since these methods cannot return until the Observer has returned
+ from <tp:member-ref>ObserveChannels</tp:member-ref>.</p>
+
+ <tp:rationale>
+ <p>This allows an Observer to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Claim</tp:dbus-ref>
+ a set of channels without having to match up calls to this method
+ with calls to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Requests_Satisfied" type="ao" direction="in">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>s
+ satisfied by these channels.
+
+ <tp:rationale>
+ If the same process is an Observer and a Handler, it can be useful
+ to be given this information as soon as possible (it will also
+ be passed to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler.HandleChannels</tp:dbus-ref>).
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Observer_Info" type="a{sv}" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about these channels. Currently defined
+ keys are:</p>
+
+ <dl>
+ <dt><code>recovering</code> - b</dt>
+ <dd><code>True</code> if ObserveChannels was called for an existing
+ channel (due to the <tp:member-ref>Recover</tp:member-ref>
+ property being <code>True</code>); <code>False</code> or omitted
+ otherwise.
+
+ <tp:rationale>
+ This allows observers to distinguish between new channels (the normal
+ case), and existing channels that were given to the observer in order
+ to catch up on previous events (perhaps after a previous instance of
+ the same observer crashed).
+ </tp:rationale>
+ </dd>
+
+ <dt><code>request-properties</code> - a{oa{sv}}</dt>
+ <dd>A map from <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ paths listed in <var>Requests_Satisfied</var> to
+ <tp:type>Qualified_Property_Value_Map</tp:type>s containing
+ namespaced immutable properties of each request.</dd>
+ </dl>
+
+ <p>All defined keys for this dictionary are optional;
+ observers MAY safely ignore any entry in this dictionary.</p>
+ </tp:docstring>
+ </arg>
+
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection.xml b/spec/Connection.xml
new file mode 100644
index 0000000..51ec1ab
--- /dev/null
+++ b/spec/Connection.xml
@@ -0,0 +1,1293 @@
+<?xml version="1.0" ?>
+<node name="/Connection"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ >
+ <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2005-2009 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">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Requests"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/>
+
+ <tp:struct name="Channel_Info" array-name="Channel_Info_List">
+ <tp:deprecated version="0.17.23"/>
+ <tp:docstring>A struct representing a channel, as returned by
+ ListChannels on the Connection interface.</tp:docstring>
+ <tp:member type="o" name="Channel">
+ <tp:docstring>The object path of the channel, which is on the
+ same bus name as the connection</tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type">
+ <tp:docstring>The channel's type</tp:docstring>
+ </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 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,
+ or 0 if there is no associated handle</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="Connect" tp:name-for-bindings="Connect">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the connection be established. This will be done
+ asynchronously and errors will be returned by emitting
+ <tp:member-ref>StatusChanged</tp:member-ref> signals.</p>
+
+ <p>Calling this method on a Connection that is already connecting
+ or connected is allowed, and has no effect.</p>
+ </tp:docstring>
+ </method>
+
+ <method name="Disconnect" tp:name-for-bindings="Disconnect">
+ <tp:docstring>
+ Request that the connection be closed. This closes the connection if
+ it's not already in DISCONNECTED state, and destroys the connection
+ object.
+ </tp:docstring>
+ </method>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ access="read" type="as" tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The set of optional interfaces supported by this connection.
+ Before the connection status changes to CONNECTED,
+ this property may change at any time, but it is guaranteed that
+ interfaces will only be added, not removed. After the connection
+ status changes to CONNECTED, this property 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:added version="0.19.2">Clients SHOULD fall back
+ to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this
+ property is not supported.</tp:added>
+ </property>
+
+ <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
+ <arg direction="out" type="as" tp:type="DBus_Interface[]"
+ name="Interfaces">
+ <tp:docstring>
+ The value of the <tp:member-ref>Interfaces</tp:member-ref> property
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Returns the set of optional interfaces supported by this
+ connection. See <tp:member-ref>Interfaces</tp:member-ref> for more
+ details.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <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" tp:name-for-bindings="Get_Protocol">
+ <arg direction="out" type="s" tp:type="Protocol" name="Protocol">
+ <tp:docstring>
+ A string identifier for the protocol
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Get the protocol this connection is using.
+ </tp:docstring>
+ </method>
+
+ <signal name="SelfHandleChanged"
+ tp:name-for-bindings="Self_Handle_Changed">
+ <tp:docstring>
+ Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
+ changes. If the connection
+ is not yet in the CONNECTED state, this signal is not guaranteed
+ to be emitted.
+ </tp:docstring>
+ <tp:added version="0.17.10">Clients MAY assume that if the
+ SelfHandle property exists, this signal will be emitted when
+ necessary.</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" tp:name-for-bindings="Self_Handle"
+ type="u" tp:type="Contact_Handle" access="read">
+ <tp:docstring>
+ 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
+ <tp:member-ref>SelfHandleChanged</tp:member-ref> signal.
+ If the connection is not yet in the CONNECTED state, the value of
+ this property MAY be zero.
+ </tp:docstring>
+ <tp:added version="0.17.10">For compatibility with older
+ versions, clients should fall back to calling the
+ <tp:member-ref>GetSelfHandle</tp:member-ref>
+ method.</tp:added>
+ </property>
+
+ <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
+ <arg direction="out" type="u" tp:type="Contact_Handle"
+ name="Self_Handle">
+ <tp:docstring>
+ The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Returns the value of the SelfHandle property. Change notification
+ is via the SelfHandleChanged signal.
+ </tp:docstring>
+ <tp:deprecated version="0.17.10">Use GetAll to get the
+ SelfHandle property (and all other Connection properties)
+ instead.</tp:deprecated>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="Status" tp:name-for-bindings="Status"
+ access="read" type="u" tp:type="Connection_Status">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The current status of the connection. Change notification is via
+ the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p>
+
+ <p>If retrieval of property succeeds and yields the value Disconnected,
+ this indicates that the connection has not yet been established.
+ If connection has been attempted and failed, the Connection object
+ SHOULD be removed from the bus entirely, meaning that retrieval of
+ this property SHOULD fail.</p>
+ </tp:docstring>
+ <tp:added version="0.19.2">Clients SHOULD fall back
+ to calling <tp:member-ref>GetStatus</tp:member-ref> if this
+ property is not supported.</tp:added>
+ </property>
+
+ <method name="GetStatus" tp:name-for-bindings="Get_Status">
+ <arg direction="out" type="u" tp:type="Connection_Status"
+ name="Status">
+ <tp:docstring>
+ The value of the <tp:member-ref>Status</tp:member-ref> property
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Get the current status as defined in the
+ <tp:member-ref>StatusChanged</tp:member-ref> signal.
+ </tp:docstring>
+ </method>
+
+ <method name="HoldHandles" tp:name-for-bindings="Hold_Handles">
+ <tp:changed version="0.21.6">If
+ <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ this method no longer does anything.</tp:changed>
+ <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>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ which SHOULD always be the case in this version of telepathy-spec,
+ this method does nothing and returns successfully, unless
+ the given handle type or any of the given handles is invalid.</p>
+
+ <p>In older connection managers, this method
+ notifies the connection manger that your client is holding a copy
+ of handles which may not be in use in any existing channel or
+ list, and were not obtained by using the
+ <tp:member-ref>RequestHandles</tp:member-ref> method. For
+ example, a handle observed in an emitted signal, or displayed
+ somewhere in the UI that is not associated with a channel. The
+ connection manager must not deallocate a handle where any clients
+ have used this method to indicate it is in use until the
+ <tp:member-ref>ReleaseHandles</tp:member-ref>
+ method is called, or the clients disappear from the bus.</p>
+
+ <p>Note that HoldHandles is idempotent - calling it multiple times
+ is equivalent to calling it once. If a handle is "referenced" by
+ several components which share a D-Bus unique name, the client
+ should perform reference counting internally, and only call
+ 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">
+ <tp:docstring>
+ The handle type is invalid
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ One of the given handles is not valid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="InspectHandles" tp:name-for-bindings="Inspect_Handles">
+ <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
+ <tp:docstring>
+ The type of handle to be inspected
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Handles" type="au" tp:type="Handle[]">
+ <tp:docstring>
+ An array of integer handles of this type
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="as" name="Identifiers">
+ <tp:docstring>
+ An array of identifiers corresponding to the given handles, in the same order.
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Return a string representation for a number of handles of a given
+ type.
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The handle type is invalid
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ One of the given handles is not valid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="ListChannels" tp:name-for-bindings="List_Channels">
+ <tp:deprecated version="0.17.23">Use the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.Channels</tp:dbus-ref>
+ property instead.
+ </tp:deprecated>
+
+ <arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"
+ name="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" tp:name-for-bindings="New_Channel">
+ <tp:deprecated version="0.17.23">Connection managers MUST still
+ emit this signal, but clients SHOULD listen for the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.NewChannels</tp:dbus-ref>
+ signal instead.
+ </tp:deprecated>
+
+ <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, 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 no handle is specified
+ </tp:docstring>
+ </arg>
+
+ <arg name="Suppress_Handler" type="b">
+ <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 <tp:member-ref>RequestChannel</tp:member-ref> 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.
+ </tp:docstring>
+ </signal>
+
+ <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles">
+ <tp:changed version="0.21.6">If
+ <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ this method no longer does anything.</tp:changed>
+ <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>
+ <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ which SHOULD always be the case in this version of telepathy-spec,
+ this method does nothing and returns successfully, unless
+ the given handle type or any of the given handles is invalid.</p>
+
+ <p>In older connection managers, this method
+ explicitly notifies 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
+ <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The handle type is invalid
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ One of the given handles is not valid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestChannel" tp:name-for-bindings="Request_Channel">
+ <tp:deprecated version="0.17.23">Use
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.CreateChannel</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
+ instead. Connection managers MAY implement RequestChannel by
+ raising NotImplemented, or implement fewer types of channel via
+ this API.</tp:deprecated>
+
+ <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 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
+ Handle_Type_None
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Suppress_Handler" type="b">
+ <tp:docstring>
+ <p>Clients SHOULD always set this to true.</p>
+
+ <tp:rationale>
+ <p>The historical meaning was that clients that did not
+ intend to take responsibility for displaying the channel to
+ the user could set this to FALSE, in which case the channel
+ dispatcher would launch an appropriate channel handler.</p>
+
+ <p>However, clients whose functionality relies on having a
+ working channel dispatcher should obtain that functionality by
+ calling methods on the channel dispatcher, so that they will
+ get an appropriate error if the channel dispatcher is missing
+ or not working.</p>
+
+ <p>The channel dispatcher itself should set this to true too,
+ so that it will ignore the
+ <tp:member-ref>NewChannel</tp:member-ref> signal that results
+ from the creation of the channel. It can then dispatch the
+ channel returned from this method to an
+ appropriate handler.</p>
+
+ <p>So, there is no sensible use-case for setting this to false,
+ and setting it to false can result in unhandled channels (in
+ the case where clients assume that a channel dispatcher is
+ present, but it isn't).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="o" name="Object_Path">
+ <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
+ handle_type and handle. The handle_type and handle may both be
+ zero to request the creation of a new, empty channel, which may
+ or may not be possible, depending on the protocol and channel
+ type.</p>
+
+ <p>On success, the returned channel will always be of the requested
+ type (i.e. implement the requested channel-type interface).</p>
+
+ <p>If a new, empty channel is requested, on success the returned
+ channel will always be an "anonymous" channel for which the type
+ and handle are both zero.</p>
+
+ <p>If a channel to a contact, room etc. is requested, on success, the
+ returned channel may either be a new or existing channel to
+ the requested entity (i.e. its
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ properties are the
+ requested handle type and handle), or a newly created "anonymous"
+ channel associated with the requested handle in some
+ implementation-specific way.</p>
+
+ <p>For example, for a contact handle, the returned channel
+ might be "anonymous", but implement the groups interface and have
+ the requested contact already present among the members.</p>
+
+ <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"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Unknown channel type
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ The given handle does not exist or cannot be created
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested channel type cannot be created with the given handle
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because contact doesn't
+ have the required capabilities.
+ </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>
+
+ <tp:enum name="Handle_Type" type="u">
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ A "null" handle type used to indicate the absence of a handle.
+ When a handle type and a handle appear as a pair, if the handle
+ type is zero, the handle must also be zero.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Contact" value="1">
+ <tp:docstring>
+ A contact
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Room" value="2">
+ <tp:docstring>
+ A chat room
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="List" value="3">
+ <tp:docstring>
+ A server-generated contact list (see Channel.Interface.Group)
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Group" value="4">
+ <tp:docstring>
+ A user-defined contact list (see Channel.Interface.Group)
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:simple-type name="Handle" type="u" array-name="Handle_List">
+ <tp:docstring>An unsigned 32-bit integer representing a
+ handle</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Contact_Handle" type="u"
+ array-name="Contact_Handle_List">
+ <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"
+ array-name="Room_Handle_List">
+ <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"
+ array-name="List_Handle_List">
+ <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"
+ array-name="Group_Handle_List">
+ <tp:docstring>An unsigned 32-bit integer representing a handle of type
+ Handle_Type_Group</tp:docstring>
+ </tp:simple-type>
+
+ <method name="RequestHandles" tp:name-for-bindings="Request_Handles">
+ <tp:changed version="0.21.6">If
+ <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ this method no longer has its reference-counting effect.</tp:changed>
+ <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="Identifiers" type="as">
+ <tp:docstring>
+ An array of identifiers of entities to request handles for
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="au" tp:type="Handle[]"
+ name="Handles">
+ <tp:docstring>
+ An array of integer handle numbers in the same order as the given identifiers.
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request several handles from the connection manager which represent a
+ number of contacts, rooms or server-stored lists on the service.</p>
+
+ <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true,
+ which SHOULD always be the case in this version of telepathy-spec,
+ the handles remain valid until the connection disconnects.</p>
+
+ <p>The implementation of this method in older connection managers
+ must record that these handles are in use by the
+ client who invokes this method, and must not deallocate the handles
+ until the client disconnects from the bus or calls the
+ <tp:member-ref>ReleaseHandles</tp:member-ref>
+ method. Where the identifier refers to an entity that already has a
+ handle in this connection manager, this handle should be returned
+ instead. The handle number 0 must not be returned by the connection
+ manager.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ The given identifier does not identify a valid entity of the given
+ type.
+
+ <tp:rationale>
+ For instance, an XMPP connection would raise this error for
+ identifiers with type Handle_Type_Room that do not contain
+ exactly one '@' character, that contain spaces, and so on.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The given handle type is not valid, or is not implemented on this
+ connection.
+
+ <tp:rationale>
+ For instance, a connection to a protocol that doesn't have
+ chat rooms would raise this error for room handles, and all CMs
+ would raise this error for Handle_Type_None.
+ </tp:rationale>
+ </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>
+ The connection is fully connected and all methods are available.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connecting" value="1">
+ <tp:docstring>
+ <tp:member-ref>Connect</tp:member-ref> has been called but the
+ connection has not yet been established. Some methods may fail
+ until the connection has been established.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Disconnected" value="2">
+ <tp:docstring>
+ If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or
+ <tp:member-ref>Status</tp:member-ref>, it indicates that connection
+ has not yet been attempted. If seen in a
+ <tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates
+ that the connection has failed; the Connection object SHOULD be
+ removed from D-Bus immediately, and all subsequent method calls
+ SHOULD fail.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Connection_Status_Reason" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A reason why the status of the connection changed. Apart from
+ Requested, the values of this enumeration only make sense as
+ reasons why the status changed to Disconnected.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None_Specified" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There is no reason set for this state change. Unknown status
+ reasons SHOULD be treated like this reason.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.<tp:error-ref>Disconnected</tp:error-ref></code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Requested" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is in response to a user request. Changes to the
+ Connecting or Connected status SHOULD always indicate this reason;
+ changes to the Disconnected status SHOULD indicate this reason
+ if and only if the disconnection was requested by the user.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Network_Error" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was an error sending or receiving on the network socket.</p>
+
+ <p>When the status changes from Connecting to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
+ or some more specific error.</p>
+
+ <p>When the status changes from Connected to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
+ or some more specific error.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Authentication_Failed" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The username or password was invalid.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Encryption_Error" value="4">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was an error negotiating SSL on this connection, or
+ encryption was unavailable and require-encryption was set when the
+ connection was created.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code>
+ if encryption was not available at all, or
+ <code>org.freedesktop.Telepathy.Error.EncryptionError</code>
+ if encryption failed.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Name_In_Use" value="5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>In general, this reason indicates that the requested account
+ name or other identification could not be used due to conflict
+ with another connection. It can be divided into three cases:</p>
+
+ <ul>
+ <li>If the status change is from Connecting to Disconnected
+ and the 'register' parameter to RequestConnection was present
+ and true, the requested account could not be created on the
+ server because it already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
+ </li>
+
+ <li>If the status change is from Connecting to Disconnected
+ but the 'register' parameter is absent or false, the connection
+ manager could not connect to the specified account because
+ a connection to that account already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
+
+ <tp:rationale>
+ In some protocols, like XMPP (when connecting with the same
+ JID and resource as an existing connection), the existing
+ connection "wins" and the new one fails to connect.
+ </tp:rationale>
+ </li>
+
+ <li>If the status change is from Connected to Disconnected,
+ the existing connection was automatically disconnected because
+ a new connection to the same account (perhaps from a different
+ client or location) was established.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
+
+ <tp:rationale>
+ In some protocols, like MSNP (when connecting twice with the
+ same Passport), the new connection "wins" and the
+ existing one is automatically disconnected.
+ </tp:rationale>
+ </li>
+ </ul>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Not_Provided" value="6">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server did not provide a SSL certificate.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Untrusted" value="7">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate is signed by an untrusted certifying
+ authority. This error SHOULD NOT be used to represent a self-signed
+ certificate: use the more specific Cert_Self_Signed reason for
+ that.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Expired" value="8">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate has expired.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Expired</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Not_Activated" value="9">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate is not yet valid.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate did not match its hostname.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate does not have the expected
+ fingerprint.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Self_Signed" value="12">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate is self-signed.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.SelfSigned</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Other_Error" value="13">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There was some other error validating the server's SSL
+ certificate.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Revoked" value="14">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate has been revoked.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Revoked</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Insecure" value="15">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The server's SSL certificate uses an insecure algorithm,
+ or is cryptographically weak.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.Insecure</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Cert_Limit_Exceeded" value="16">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The length in bytes of the server certificate, or the depth of the
+ sever certificate chain exceed the limits imposed by the crypto
+ library.</p>
+
+ <p>When disconnected for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cert.LimitExceeded</code>
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <signal name="ConnectionError" tp:name-for-bindings="Connection_Error">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when an error occurs that renders this connection unusable.
+ </p>
+
+ <p>Whenever this signal is emitted, it MUST immediately be followed by
+ a <tp:member-ref>StatusChanged</tp:member-ref> signal with status
+ Connection_Status_Disconnected and an appropriate reason
+ code.</p>
+
+ <p>Connection managers SHOULD emit this signal on disconnection, but
+ need not do so. Clients MUST support connection managers that emit
+ StatusChanged(Disconnected, ...) without first emitting
+ ConnectionError.</p>
+
+ <tp:rationale>
+ <p>This signal provides additional information about the reason
+ for disconnection. The reason for connection is always
+ straightforward - it was requested - so it does not need further
+ explanation. However, on errors, it can be useful to provide
+ additional information.</p>
+
+ <p>The <tp:type>Connection_Status_Reason</tp:type> is not given
+ here, since it will be signalled in
+ <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client
+ implementation would be to store the information given by this
+ signal until StatusChanged is received, at which point the
+ information given by this signal can be used to supplement the
+ StatusChanged signal.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring>
+ The name of a D-Bus error describing the error that occurred,
+ which may correspond to a
+ <tp:type>Connection_Status_Reason</tp:type>, or may be a more
+ specific Telepathy error
+ (such as
+ <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>
+ for Connection_Status_Reason_Network_Error)
+ or a protocol-specific or connection-manager-specific error in a
+ suitable namespace.
+
+ <tp:rationale>
+ For instance, a SIP connection manager could signal
+ "402 Payment Required" as an error in a
+ connection-manager-specific namespace, or a link-local
+ XMPP implementation that used Avahi could provide the error
+ given to it by the avahi-daemon.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about the error, which may include
+ the following well-known keys:</p>
+
+ <dl>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
+ <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd>
+ </dl>
+
+ </tp:docstring>
+ </arg>
+
+ </signal>
+
+ <signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
+ <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:contact-attribute name="contact-id" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
+ this is always present in the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
+ whether it was explicitly requested or not.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <method name="AddClientInterest" tp:name-for-bindings="Add_Client_Interest">
+ <tp:added version="0.21.3"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Register a client's interest in notifications related to one or
+ more interfaces.</p>
+
+ <p>Groups of notifications are identified by a token which is either
+ a D-Bus interface name, or a string that starts with a D-Bus
+ interface name. The meaning of each token is given by that D-Bus
+ interface, which MUST define it in its documentation.</p>
+
+ <tp:rationale>
+ <p>Initially, all interests are in entire interface, but allowing
+ other strings allows subscription to part of an interface; for
+ instance, an interest in ...MailNotification/count could track
+ the number of messages without caring about their detailed
+ content.</p>
+ </tp:rationale>
+
+ <p>For each token with which this method interacts, the
+ Connection tracks an "interest count" (like a reference count) for
+ each unique bus name that has called this method. When a client
+ calls this method, for each token, the interest count for its
+ unique bus name is incremented; when
+ <tp:member-ref>RemoveClientInterest</tp:member-ref> is called,
+ all interest counts for that unique bus name are decremented.
+ If the unique bus name leaves the bus (for instance, if the
+ client crashes or exits), all interest counts for that unique bus
+ name are set to zero.</p>
+
+ <p>The Connection can then use these reference counts to
+ avoid subscribing to protocol-level notifications unless at least
+ one client has a non-zero interest count for the relevant
+ token.</p>
+
+ <tp:rationale>
+ <p>This method exists to reduce memory and network overhead when
+ there is no active subscription.</p>
+
+ <p>One situation where this is useful is <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface"
+ >Location</tp:dbus-ref>: on XMPP, location updates are received
+ over PEP. If the Connection advertises the
+ <code>geoloc+notify</code> capability, it will be sent location
+ updates for all contacts. To avoid consuming resources for this,
+ the connection should avoid advertising that capability until
+ a client has expressed an interest in contacts' locations.</p>
+
+ <p>Another example of a protocol that benefits from this method is
+ the Google XMPP Mail Notification extension, which can be used
+ to implement <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface"
+ >MailNotification</tp:dbus-ref>. In this protocol, the CM
+ receives a notification that something has changed, but to get
+ more information, the CM must request this information. Knowing
+ that nobody is currently interested in this information, the CM
+ can avoid generating useless network traffic. Similarly, the CM
+ may free the list of unread messages to reduce memory overhead.</p>
+ </tp:rationale>
+
+ <p>If this method is called for an interface that might require
+ protocol-level subscription, but the connection cannot set up
+ that subscription yet (for instance because the
+ <tp:member-ref>Status</tp:member-ref> is not Connected yet), the
+ Connection MUST remember the client's interest, and attempt to
+ subscribe to the appropriate protocol feature when this becomes
+ possible.</p>
+
+ <p>Clients MAY ignore any errors raised by this method; it is intended
+ to be called with the reply ignored.</p>
+
+ <tp:rationale>
+ <p>The only reason it could fail is if it's unimplemented, in which
+ case the only thing the client can usefully do is to proceed as if
+ it had succeeded.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Tokens" type="as" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interfaces or parts of interfaces in which to register an
+ interest, represented by either a
+ <tp:type>DBus_Interface</tp:type>, or a string prefixed with a
+ <tp:type>DBus_Interface</tp:type>.</p>
+
+ <p>If the Connection does not support one of these tokens, this
+ is not considered to be an error; the unsupported token is
+ simply ignored.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="RemoveClientInterest"
+ tp:name-for-bindings="Remove_Client_Interest">
+ <tp:added version="0.21.3"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Release an interest registered using
+ <tp:member-ref>AddClientInterest</tp:member-ref>. See that
+ method's documentation for details.</p>
+
+ <p>Clients MAY ignore any errors raised by this method; it is intended
+ to be called with the reply ignored.</p>
+
+ <tp:rationale>
+ <p>The only reasons it could fail are if it's unimplemented, or if
+ the client's reference-counting is wrong and it has tried to
+ remove a client interest that it did not add. In both cases,
+ there's nothing the client could do about it.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Tokens" type="as" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interfaces or parts of interfaces that were previously passed to
+ <tp:member-ref>AddClientInterest</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <property name="HasImmortalHandles"
+ tp:name-for-bindings="Has_Immortal_Handles"
+ access="read" type="b">
+ <tp:added version="0.21.6"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if handles last for the whole lifetime of the Connection.
+ This SHOULD be the case in all connection managers, but clients
+ MUST interoperate with older connection managers
+ (which reference-count handles).</p>
+ </tp:docstring>
+ </property>
+
+ <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
+ receive channels of differing types (such as text channels or streaming
+ media channels) which are used to carry out further communication.</p>
+
+ <p>In order to allow Connection objects to be discovered by new clients,
+ the object path and well-known bus name MUST be of the form
+ <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
+ and
+ <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
+ where:</p>
+
+ <ul>
+ <li><em>cmname</em> is the same
+ <tp:type>Connection_Manager_Name</tp:type> that appears
+ in the connection manager's object path and well-known bus name</li>
+ <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>,
+ but with "-" replaced with "_" to get a valid
+ object path/bus name</li>
+ <li><em>account</em> is some non-empty sequence of ASCII letters,
+ digits and underscores not starting with a digit</li>
+ </ul>
+
+ <p><em>account</em> SHOULD be formed such that any valid distinct
+ connection instance on this protocol has a distinct name. This
+ might be formed by including the server name followed by the user
+ name (escaped via some suitable mechanism like telepathy-glib's
+ tp_escape_as_identifier() function to preserve uniqueness); on
+ protocols where connecting multiple times is permissable, a
+ per-connection identifier might be necessary to ensure
+ uniqueness.</p>
+
+ <p>Clients MAY parse the object path to determine the connection
+ manager name and the protocol, but MUST NOT attempt to parse the
+ <em>account</em> part. Connection managers MAY use any unique string
+ for this part.</p>
+
+ <p>As well as the methods and signatures below, arbitrary interfaces may be
+ provided by the Connection object to represent extra connection-wide
+ functionality, such as the Connection.Interface.SimplePresence 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 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
+ immutable <em>handles</em>, which are unsigned non-zero integers which are
+ valid only for the lifetime of the connection object, and are used
+ throughout the protocol where these entities are represented, allowing
+ simple testing of equality within clients.</p>
+
+ <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
+ ambiguous. Connection manager implementations should reference count these
+ handles to determine if they are in use either by any active clients or any
+ open channels, and may deallocate them when this ceases to be true. Clients
+ may request handles of a given type and identifier with the
+ <tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
+ identifier with the <tp:member-ref>InspectHandles</tp:member-ref>
+ method, keep handles from being released with
+ <tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
+ longer storing handles with
+ <tp:member-ref>ReleaseHandles</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <tp:changed version="0.17.10">Previously, the account part of
+ Connection bus names/object paths was allowed to have more than one
+ component (i.e. contain dots or slashes), resulting in Connection
+ bus names and object paths with more than 7 components. We now restrict
+ Connection bus names/object paths to have exactly 7
+ components.</tp:changed>
+
+ <tp:changed version="0.17.23">The Requests and Contacts interfaces
+ are now mandatory. Their functionality will be merged into the main
+ Connection interface at some point in future.</tp:changed>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Future.xml b/spec/Connection_Future.xml
new file mode 100644
index 0000000..6b5291e
--- /dev/null
+++ b/spec/Connection_Future.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" ?>
+<node name="/Connection_FUTURE"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ >
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.FUTURE"
+ tp:causes-havoc='experimental'>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <method name="EnsureSidecar" tp:name-for-bindings="Ensure_Sidecar">
+ <tp:added version="0.19.0">(as a draft)</tp:added>
+
+ <arg direction="in" name="Main_Interface" type="s"
+ tp:type="DBus_Interface">
+ <tp:docstring>
+ The "primary" interface implemented by an object attached
+ to a connection. For example, a Gabble plugin implementing
+ fine-grained control of XEP-0016 privacy lists might expose an object
+ implementing <tt>com.example.PrivacyLists</tt>.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Path" type="o">
+ <tp:docstring>The object path of the sidecar, exported by the same bus
+ name as the Connection to which it is attached.</tp:docstring>
+ </arg>
+ <arg direction="out" name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>Immutable properties of the sidecar.</tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request an object with a particular interface providing additional
+ connection-specific functionality, together with its immutable
+ properties. These will often be implemented by plug-ins to the
+ connection managers; for example, support for an XMPP XEP for which
+ no generic Telepathy interface exists might be implemented by a
+ Gabble plugin exposing a sidecar with a particular interface.</p>
+
+ <p>This method may be called at any point during the lifetime of a
+ connection, even before its <tp:type>Connection_Status</tp:type>
+ changes to Connected. It MAY take a long time to
+ return—perhaps it needs to wait for a connection to be established
+ and for all the services supported by the server to be discovered
+ before determining whether necessary server-side support is
+ available—so callers SHOULD override the default method timeout (25
+ seconds) with a much higher value (perhaps even MAX_INT32, meaning
+ “no timeout” in recent versions of libdbus).</p>
+
+ <tp:rationale>
+ <p>There is an implicit assumption that any connection
+ manager plugin will only want to export one “primary” object per
+ feature it implements, since there is a one-to-one mapping between
+ interface and object. This is reasonable since Sidecars are
+ (intended to be) analogous to extra interfaces on the connection,
+ providing once-per-connection shared functionality; it also makes
+ client code straightforward (look up the interface you care about
+ in a dictionary, build a proxy object from the value). More
+ “plural” plugins are likely to want to implement new types of
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>
+ instead.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The requested sidecar is not implemented by this connection manager,
+ or a necessary server-side component does not exist. (FIXME: split
+ these two errors out? Then again, once we list the guaranteed and
+ possible sidecars on a Protocol object, clients can tell the
+ difference themselves, because they shouldn't be calling this in the
+ first case.)
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ A server-side component needed by the requested sidecar reported it
+ is currently too busy, or did not respond for some
+ implementation-defined time. The caller may wish to try again later.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.Cancelled">
+ <tp:docstring>
+ The connection was disconnected while the sidecar was being set up.
+ </tp:docstring>
+ </tp:error>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/Connection_Interface_Addressing.xml b/spec/Connection_Interface_Addressing.xml
new file mode 100644
index 0000000..497c6d0
--- /dev/null
+++ b/spec/Connection_Interface_Addressing.xml
@@ -0,0 +1,258 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2010 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 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.Addressing.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/>
+ <tp:added version="0.19.12">(as draft)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface deals with the multiple address types that can
+ refer to the same contact, such as vCard fields and URIs.</p>
+
+ <p>It can be used to retrieve contacts with a specific addresses
+ through <tp:member-ref>GetContactsByVCardField</tp:member-ref> and
+ <tp:member-ref>GetContactsByURI</tp:member-ref>, as well as
+ defining the various addressing methods for a given contact
+ through this interface's contact attributes.</p>
+ </tp:docstring>
+
+ <method name="GetContactsByVCardField"
+ tp:name-for-bindings="Get_Contacts_By_VCard_Field">
+ <arg direction="in" name="Field" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard field of the addresses we are requesting. The
+ field name SHOULD be in lower case. Supported
+ fields can be found in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p>
+
+ <p>The <code>url</code> vCard field MUST NOT appear here; see
+ <tp:member-ref>GetContactsByURI</tp:member-ref> instead.</p>
+
+ <tp:rationale>
+ <p>In practice, protocols have a limited set of URI
+ schemes that make sense to resolve as a contact.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Addresses" type="as">
+ <tp:docstring>
+ The addresses to get contact handles for. The address types
+ should match the given vCard field.
+ </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>Attributes from this interface and from
+ <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref>
+ are always returned, and need not be requested
+ explicitly.</p>
+
+ <p>The behavior of this parameter is similar to the same
+ parameter in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts"
+ 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 addresses 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>Requested addresses that cannot be satisfied MUST be ommitted
+ from the mapping.</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>),
+ and the vCard field used for requesting the contact in
+ <code>org.freedesktop.Telepathy.Connection.Interface.ContactInfo/info</code>.
+ </p>
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request contacts and retrieve their attributes using a given field
+ in their vCards.</p>
+
+ <p>The connection manager should record that these handles are in
+ use by the client who invokes this method, and must not
+ deallocate the handles until the client disconnects from the
+ bus or calls the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref>
+ method.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetContactsByURI"
+ tp:name-for-bindings="Get_Contacts_By_URI">
+ <arg direction="in" name="URIs" type="as">
+ <tp:docstring>
+ The URI addresses to get contact handles for. Supported
+ schemes can be found in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableURISchemes</tp:dbus-ref>.
+ </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>Attributes from this interface and from
+ <tp:dbus-ref>org.freedesktop.Telepathy.Connection</tp:dbus-ref>
+ are always returned, and need not be requested
+ explicitly.</p>
+
+ <p>The behavior of this parameter is similar to the same
+ parameter in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Contacts.GetContactAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="a{ua{sv}}" name="Requested_Contacts"
+ 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 addresses 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>Requested URIs that cannot be satisfied MUST be ommitted
+ from the mapping.</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:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request contacts and retrieve their attributes using URI addresses.</p>
+
+ <p>The connection manager should record that these handles are in
+ use by the client who invokes this method, and must not
+ deallocate the handles until the client disconnects from the
+ bus or calls the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.ReleaseHandles</tp:dbus-ref>
+ method.</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:mapping name="VCard_Field_Address_Map" array-name="">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A mapping of vCard fields and addresses that repreent
+ the given contact.</p>
+ </tp:docstring>
+ <tp:member type="s" name="VCard_Field"/>
+ <tp:member type="s" name="Address"/>
+ </tp:mapping>
+
+ <tp:contact-attribute name="addresses" type="a{ss}"
+ tp:type="VCard_Field_Address_Map">
+ <tp:docstring>
+ The various vCard addresses that identify this contact.
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="uris" type="as">
+ <tp:docstring>
+ The various URI addresses that identify this contact.
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="requested-address" type="(ss)"
+ tp:type="Requested_Address">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact's address, as it was requested
+ through <tp:member-ref>GetContactsByVCardField</tp:member-ref>. This
+ attribute MUST be ommitted if the contact was not retrieved
+ through <tp:member-ref>GetContactsByVCardField</tp:member-ref>.</p>
+ <tp:rationale>
+ <p>When retrieving more than one contact
+ through <tp:member-ref>GetContactsByVCardField</tp:member-ref>,
+ there needs to be a way to map the given contact back o the
+ original request.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="requested-uri" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact's URI, as it was requested through
+ <tp:member-ref>GetContactsByURI</tp:member-ref>. This
+ attribute MUST be ommitted if the contact was not retrieved
+ through <tp:member-ref>GetContactsByURI</tp:member-ref>.</p>
+ <tp:rationale>
+ <p>When retrieving more than one contact
+ through <tp:member-ref>GetContactsByURI</tp:member-ref>,
+ there needs to be a way to map the given contact back o the
+ original request.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:struct name="Requested_Address" array-name="">
+ <tp:docstring>
+ The address that has been requested by
+ <tp:member-ref>GetContactsByVCardField</tp:member-ref> or
+ <tp:member-ref>GetContactsByURI</tp:member-ref>.
+ </tp:docstring>
+
+ <tp:member name="Field" type="s">
+ <tp:docstring>
+ The vCard field used in <tp:member-ref>GetContactsByVCardField</tp:member-ref>.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Address" type="s">
+ <tp:docstring>
+ The address that was requested.
+ </tp:docstring>
+ </tp:member>
+
+ </tp:struct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
new file mode 100644
index 0000000..9675771
--- /dev/null
+++ b/spec/Connection_Interface_Aliasing.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Aliasing" 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) 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.Aliasing">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:mapping name="Alias_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are contact handles and whose
+ values are aliases.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="s" name="Alias"/>
+ </tp:mapping>
+
+ <tp:struct name="Alias_Pair" array-name="Alias_Pair_List">
+ <tp:docstring>
+ A pair (contact handle, alias) as seen in the
+ <tp:member-ref>AliasesChanged</tp:member-ref> signal.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="s" name="Alias"/>
+ </tp:struct>
+
+ <signal name="AliasesChanged" tp:name-for-bindings="Aliases_Changed">
+ <arg name="Aliases" type="a(us)" tp:type="Alias_Pair[]">
+ <!-- FIXME: if we break API, this could be an Alias_Map, a{us} -->
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array containing structs of:
+ <ul>
+ <li>the handle representing the contact</li>
+ <li>the new alias</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal emitted when a contact's alias (or that of the user) is changed.
+ </tp:docstring>
+ </signal>
+ <tp:flags name="Connection_Alias_Flags" value-prefix="Connection_Alias_Flag" type="u">
+ <tp:flag suffix="User_Set" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The aliases of contacts on this connection may be changed by the
+ user of the service, not just by the contacts themselves. This is
+ the case on Jabber, for instance.</p>
+ <p>It is possible that aliases can be changed by the contacts too -
+ which alias takes precedence is not defined by this
+ specification, and depends on the server and/or connection manager
+ implementation.</p>
+ <p>This flag only applies to the aliases of "globally valid" contact
+ handles. At this time, clients should not expect to be able to
+ change the aliases corresponding to any channel-specific
+ handles. If this becomes possible in future, a new flag will
+ be defined.</p>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+ <method name="GetAliasFlags" tp:name-for-bindings="Get_Alias_Flags">
+ <arg direction="out" type="u" tp:type="Connection_Alias_Flags"
+ name="Alias_Flags">
+ <tp:docstring>
+ An integer with a bitwise OR of flags from ConnectionAliasFlags
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Return a bitwise OR of flags detailing the behaviour of aliases on this
+ connection.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+ <method name="RequestAliases" tp:name-for-bindings="Request_Aliases">
+ <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="as" name="Aliases">
+ <tp:docstring>
+ A list of aliases in the same order as the contact handles
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request the value of several contacts' aliases at once.
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
+ <method name="GetAliases" tp:name-for-bindings="Get_Aliases">
+ <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" name="Aliases">
+ <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 contact identifier
+ (i.e. the string corresponding to the handle) 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" tp:name-for-bindings="Set_Aliases">
+ <arg direction="in" name="Aliases" type="a{us}" tp:type="Alias_Map">
+ <tp:docstring>
+ A dictionary mapping integer handles of contacts
+ to strings of the new alias to set.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the alias of the given contact be changed. Success will be
+ indicated by emitting an <tp:member-ref>AliasesChanged</tp:member-ref>
+ 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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>).
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:contact-attribute name="alias" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetAliases</tp:member-ref>
+ (always present with some value, possibly the
+ same as Connection/contact-id, if information from the
+ Aliasing interface was requested)
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface on connections to support protocols where contacts have an
+ alias which they can change at will. Provides a method for the user to set
+ their own alias, and a signal which should be emitted when a contact's
+ alias is changed or first discovered.</p>
+
+ <p>On connections where the user is allowed to set aliases for contacts and
+ store them on the server, the <tp:member-ref>GetAliasFlags</tp:member-ref>
+ method will have the CONNECTION_ALIAS_FLAG_USER_SET flag set, and the
+ <tp:member-ref>SetAliases</tp:member-ref> method may be called on contact
+ handles other than the user themselves.</p>
+
+ <p>Aliases are intended to be used as the main displayed name for the
+ contact, where available.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml
new file mode 100644
index 0000000..704263c
--- /dev/null
+++ b/spec/Connection_Interface_Anonymity.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Anonymity"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity">
+ <tp:added version="0.19.7">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface to support anonymity settings on a per-connection basis.
+ This defines what personal identifying information a remote contact
+ may or may not see. For example, GSM might use this for CLIR, while
+ SIP might use this for privacy service requests.</p>
+ </tp:docstring>
+
+ <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u">
+ <tp:docstring>
+ <p>Flags for the various types of anonymity modes. These modes are solely to
+ inform the CM of the desired anonymous settings. It is up to the
+ CM to determine whether the anonymity modes should be handled within
+ the CM itself, or whether the network that a CM might be talking to
+ should be enforcing anonymity.</p>
+
+ <p>CMs MAY support only a subset of these modes, and specific
+ connections MAY support none at all.</p>
+ </tp:docstring>
+
+ <tp:flag value="1" suffix="Client_Info">
+ <tp:docstring>
+ <p>Obscure any information that provides user identification,
+ user-agent identification or personal details. Examples of this
+ information might be GSM CallerID, SIP from address, various
+ informational email headers, etc.</p>
+
+ <p>The CM should scrub/replace any of this information before
+ passing messages or data onto the network. Note that a CM which
+ has the option of obscuring the information at the CM or privacy
+ service level would choose both (anonymity services are opaque
+ to clients of this interface).</p>
+
+ <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
+ If they are set, the CM MUST respect Client_Info and ignore
+ Show_Client_Info.</p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag value="2" suffix="Show_Client_Info">
+ <tp:docstring>
+ <p>Explicitly request showing of client information. In connection
+ context, this can be used to override service default. In channel
+ context, this overrides connection anonymity modes.</p>
+
+ <tp:rationale>
+ <p>In GSM, it's possible to have CLIR enabled by default, and
+ explicitly suppress CLIR for a single phone call.</p>
+ </tp:rationale>
+
+ <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
+ If they are set, the CM MUST respect Client_Info and ignore
+ Show_Client_Info. The CM MAY set both Client_Info and Show_Client_Info
+ in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate
+ its support for explicitly hiding and publicising client information.
+ </p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag value="4" suffix="Network_Info">
+ <tp:docstring>
+ <p>Obscure any originating IP address information, contact URIs,
+ and anonymize all traffic involved with sending/receiving any
+ media streams or call content.
+ Examples of this include the "headers" portions of
+ <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as
+ well as the History-Info (described in
+ <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>)
+ for a SIP CM.</p>
+
+ <p>This SHOULD have the effect of hiding address information from
+ the remote contact (ie, the contact cannot know what IP address
+ the session is originated from). Obviously the network still needs
+ to be able to route information between contacts, so this provides
+ no guarantees of what can be seen by intermediaries.</p>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="SupportedAnonymityModes" type="u" access="read"
+ tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes">
+ <tp:docstring>
+ The anonymity modes supported by the CM for this connection. Once
+ Connection.Status has moved to Connected, this property MUST NOT change.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityMandatory" type="b" access="readwrite"
+ tp:name-for-bindings="Anonymity_Mandatory"
+ tp:is-connection-parameter='yeah'>
+ <tp:docstring>
+ <p>This specifies whether or not the anonymity settings MUST be respected
+ by the CM and any intermediaries between the local and remote contacts.
+ If this is set to true but anonymity settings cannot be followed, then
+ the session MUST be denied with a
+ <code>org.freedesktop.Telepathy.Error.<tp:error-ref>WouldBreakAnonymity</tp:error-ref></code>
+ error.
+ Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref>
+ SHOULD also set this property first (rather than accepting the CM's
+ default value).</p>
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+ access="readwrite" tp:name-for-bindings="Anonymity_Modes"
+ tp:is-connection-parameter='yeah'>
+ <tp:docstring>
+ <p>The currently enabled anonymity modes for the connection. Setting
+ has the effect of requesting new modes for the connection, and may
+ raise an error if the unsupported modes are set. Successfully changing
+ the modes will result in emission of
+ <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ An unsupported mode was supplied. Supported modes are specified
+ in the SupportedAnonymityModes property, and this should be
+ checked prior to setting AnonymityModes.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </property>
+
+ <signal name="AnonymityModesChanged"
+ tp:name-for-bindings="Anonymity_Modes_Changed">
+ <tp:docstring>
+ Emitted when the anonymity mode has changed.
+ </tp:docstring>
+
+ <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags">
+ <tp:docstring>
+ The new anonymity modes for this connection.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
new file mode 100644
index 0000000..3b9290e
--- /dev/null
+++ b/spec/Connection_Interface_Avatars.xml
@@ -0,0 +1,516 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Avatars" 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-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
+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.Avatars">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:simple-type name="Avatar_Token" type="s"
+ array-name="Avatar_Token_List">
+ <tp:changed version="0.17.16">strengthened uniqueness requirements
+ so (CM name, protocol, token) is unique; previously only
+ (our Account, remote contact identifier, token) was required to be
+ unique</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An opaque token chosen by the connection manager, representing
+ a particular avatar.</p>
+
+ <tp:rationale>
+ <p>Because avatars can be relatively large images, most protocols
+ provide a way to detect whether an old avatar is still valid,
+ or whether an avatar has changed, without pushing the actual
+ avatar data to all clients.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST choose these tokens in a way that
+ makes it highly unlikely that two different avatars with the same
+ connection manager and protocol will have the same token.</p>
+
+ <tp:rationale>
+ <p>This means that clients MAY use the triple
+ (<tp:type>Connection_Manager_Name</tp:type>,
+ <tp:type>Protocol</tp:type>, avatar token) as a key for
+ their avatar cache. For instance, an avatar for a
+ telepathy-gabble Jabber contact might be stored in a file
+ .../gabble/jabber/4e199b4a1c40b497a95fcd1cd896351733849949.png.</p>
+ </tp:rationale>
+
+ <p>For instance, some protocols (like XMPP) identify avatars by a
+ hash of the avatar data; in this case, the hash can be used as the
+ avatar token.</p>
+
+ <p>Some protocols identify avatars by the timestamp of the last
+ change to the avatar; in these protocols it would be necessary for
+ the connection manager to encode both the timestamp and the
+ contact's identifier into the avatar token in order to ensure
+ uniqueness.</p>
+
+ <p>This token SHOULD be kept short and reasonably suitable for use
+ in a filename, but MAY contain any UTF-8 character (so clients using
+ avatar tokens in filenames MUST be prepared to escape characters
+ that are not valid in filenames). Connection managers for protocols
+ where tokens would otherwise become inconveniently large or contain
+ many unsuitable characters SHOULD hash the identifying data to
+ generate the token.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <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"/>
+ <tp:member type="s" tp:type="Avatar_Token" name="Token"/>
+ </tp:mapping>
+
+ <signal name="AvatarUpdated" tp:name-for-bindings="Avatar_Updated">
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact whose avatar has changed
+ </tp:docstring>
+ </arg>
+ <arg name="New_Avatar_Token" tp:type="Avatar_Token" type="s">
+ <tp:docstring>
+ Unique token for their new avatar
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ 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
+ <tp:member-ref>RequestAvatars</tp:member-ref>.
+ </tp:docstring>
+ </signal>
+
+ <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved">
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact whose avatar has been retrieved
+ </tp:docstring>
+ </arg>
+ <arg name="Token" tp:type="Avatar_Token" type="s">
+ <tp:docstring>
+ The token corresponding to the avatar
+ </tp:docstring>
+ </arg>
+ <arg name="Avatar" type="ay">
+ <tp:docstring>
+ An array of bytes containing the image data
+ </tp:docstring>
+ </arg>
+ <arg name="Type" type="s">
+ <tp:docstring>
+ A string containing the image MIME type (eg image/jpeg), or empty if
+ unknown
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the avatar for a contact has been retrieved.
+ </tp:docstring>
+ </signal>
+
+ <property name="SupportedAvatarMIMETypes"
+ tp:name-for-bindings="Supported_Avatar_MIME_Types"
+ type="as" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ An array of supported MIME types (e.g. "image/jpeg").
+ Clients MAY assume that the first type in this array is preferred.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarHeight"
+ tp:name-for-bindings="Minimum_Avatar_Height"
+ type="u" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ The minimum height in pixels of an avatar on this protocol, which MAY
+ be 0.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarWidth"
+ tp:name-for-bindings="Minimum_Avatar_Width"
+ type="u" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ The minimum width in pixels of an avatar on this protocol, which MAY
+ be 0.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarHeight"
+ tp:name-for-bindings="Recommended_Avatar_Height"
+ type="u" access="read">
+ <tp:added version="0.17.22"/>
+ <tp:docstring>
+ The recommended height in pixels of an avatar on this protocol, or 0 if
+ there is no preferred height.
+ This property cannot change after the Connection goes to the Connected
+ state.
+
+ <tp:rationale>
+ In XMPP a recommended width is given by the protocol specification;
+ in proprietary protocols, using the same avatar size as the
+ proprietary client is likely to lead to the best display to other
+ users.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarWidth"
+ tp:name-for-bindings="Recommended_Avatar_Width"
+ type="u" access="read">
+ <tp:added version="0.17.22"/>
+ <tp:docstring>
+ The recommended width in pixels of an avatar on this protocol, or 0 if
+ there is no preferred width.
+ This property cannot change after the Connection goes to the Connected
+ state.
+
+ <tp:rationale>
+ The rationale is the same as for
+ <tp:member-ref>RecommendedAvatarHeight</tp:member-ref>.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarHeight"
+ tp:name-for-bindings="Maximum_Avatar_Height"
+ type="u" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ The maximum height in pixels of an avatar on this protocol, or 0 if
+ there is no limit.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarWidth"
+ tp:name-for-bindings="Maximum_Avatar_Width"
+ type="u" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ The maximum width in pixels of an avatar on this protocol, or 0 if
+ there is no limit.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarBytes"
+ tp:name-for-bindings="Maximum_Avatar_Bytes"
+ type="u" access="read">
+ <tp:added version="0.17.22">Fall back to calling
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref> if getting this
+ property fails.</tp:added>
+ <tp:docstring>
+ The maximum size in bytes of an avatar on this protocol, or 0 if
+ there is no limit.
+ This property cannot change after the Connection goes to the Connected
+ state.
+ </tp:docstring>
+ </property>
+
+ <method name="GetAvatarRequirements"
+ tp:name-for-bindings="Get_Avatar_Requirements">
+ <tp:deprecated version="0.17.22">Use GetAll to retrieve the
+ D-Bus properties on this interface, falling back to this method
+ on failure.</tp:deprecated>
+ <arg direction="out" type="as" name="MIME_Types">
+ <tp:docstring>
+ An array of supported MIME types (eg image/jpeg)
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="q" name="Min_Width">
+ <tp:docstring>
+ The minimum image width in pixels
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="q" name="Min_Height">
+ <tp:docstring>
+ The minimum image height in pixels
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="q" name="Max_Width">
+ <tp:docstring>
+ The maximum image width in pixels, or 0 if there is no limit
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="q" name="Max_Height">
+ <tp:docstring>
+ The maximum image height in pixels, or 0 if there is no limit
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="u" name="Max_Bytes">
+ <tp:docstring>
+ The maximum image size in bytes, or 0 if there is no limit
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get the required format of avatars on this connection.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetAvatarTokens" tp:name-for-bindings="Get_Avatar_Tokens">
+ <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="as" name="Tokens" tp:type="Avatar_Token[]">
+ <tp:docstring>
+ An array of avatar tokens or empty strings (if no avatar is set) in the
+ same order as the given array of contact handles
+ </tp:docstring>
+ </arg>
+ <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens
+ instead.</tp:deprecated>
+ <tp:docstring>
+ Get the unique tokens for all of the given contacts' avatars.
+
+ Using this method in new Telepathy clients is deprecated; use
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead.
+ </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.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetKnownAvatarTokens"
+ tp:name-for-bindings="Get_Known_Avatar_Tokens">
+ <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}" name="Tokens" tp:type="Avatar_Token_Map">
+ <tp:docstring>
+ A dictionary of handles mapped to avatar tokens, containing only
+ the known avatar tokens.
+ </tp:docstring>
+ </arg>
+ <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. 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"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestAvatar" tp:name-for-bindings="Request_Avatar">
+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact to request the avatar for
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="ay" name="Data">
+ <tp:docstring>
+ An array of bytes containing the image data
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="s" name="MIME_Type">
+ <tp:docstring>
+ A string containing the image MIME type (eg image/jpeg), or empty if
+ unknown
+ </tp:docstring>
+ </arg>
+ <tp:deprecated version="0.15.5">Use RequestAvatars
+ instead.</tp:deprecated>
+ <tp:docstring>
+ Request the avatar for a given contact. Using this method in new
+ Telepathy clients is deprecated; use RequestAvatars instead.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The contact does not currently have an avatar.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestAvatars" tp:name-for-bindings="Request_Avatars">
+ <arg direction="in" name="Contacts" type="au"
+ tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The contacts to retrieve avatars for
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request avatars for a number of contacts. The
+ <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for
+ each avatar retrieved. If the handles are valid but retrieving an
+ avatar fails (for any reason, including the contact not having an
+ avatar) the AvatarRetrieved signal is not emitted for that contact.
+ </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="SetAvatar" tp:name-for-bindings="Set_Avatar">
+ <arg direction="in" name="Avatar" type="ay">
+ <tp:docstring>
+ An array of bytes representing the avatar image data
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="MIME_Type" type="s">
+ <tp:docstring>
+ A string representing the image MIME type
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="s" name="Token" tp:type="Avatar_Token">
+ <tp:docstring>
+ The string token of the new avatar
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Set a new avatar image for this connection. The avatar image must
+ respect the requirements obtained by
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref>.
+ </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.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="ClearAvatar" tp:name-for-bindings="Clear_Avatar">
+ <tp:added version="0.15.0" />
+ <tp:docstring>
+ Remove the avatar image for this connection.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-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:member-ref>GetKnownAvatarTokens</tp:member-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.
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for requesting avatars for contacts on a given connection,
+ receiving notification when avatars are changed, and publishing your own
+ avatar.</p>
+
+ <p>Avatars are identified by a string, the <tp:type>Avatar_Token</tp:type>,
+ which represents a particular avatar. Tokens MUST be chosen by the
+ connection manager in such a way that the triple
+ (<tp:type>Connection_Manager_Name</tp:type>, <tp:type>Protocol</tp:type>,
+ <tp:type>Avatar_Token</tp:type>) uniquely identifies an avatar.
+ An empty token means that an avatar has not been set for this contact, and
+ a changed token implies the contact's avatar has changed, but the strings
+ should otherwise be considered opaque by clients.</p>
+
+ <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+ to request the tokens for the
+ avatars of all the contacts it is interested in when it connects. The
+ avatars can then be requested using
+ <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts. Clients
+ should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and
+ request a new copy of
+ the avatar when a contacts' avatar token changes. Clients should cache the
+ token and data of each contact's avatar between connections, to avoid
+ repeatedly retrieving the same avatar.</p>
+
+ <p>To publish an avatar, a client should use
+ <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets
+ the requirements returned by the
+ <tp:member-ref>GetAvatarRequirements</tp:member-ref>
+ function. On some protocols the avatar is stored on the server, so setting
+ 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 using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; 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 <tp:member-ref>ClearAvatar</tp:member-ref> method.
+ This method can safely be used even if there is no avatar for this
+ connection.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Balance.xml b/spec/Connection_Interface_Balance.xml
new file mode 100644
index 0000000..76f9040
--- /dev/null
+++ b/spec/Connection_Interface_Balance.xml
@@ -0,0 +1,111 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Balance"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.Balance">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.19.0">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>In many real-time communication services the user can pay for certain
+ services, typically calls to the
+ <abbr title="Public Switched Telephone Network">PSTN</abbr>,
+ in advance. In (at least) Skype, it's possible to query the current
+ balance in a machine-readable way.</p>
+ </tp:docstring>
+
+ <tp:struct name="Currency_Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An amount of money in a specified currency. For example,
+ 3.21 British pounds would conventionally be represented by
+ (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>,
+ <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by
+ (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>,
+ <var>Currency</var> = <tt>"GBP"</tt>) in a service that records
+ balance in units of 0.001 pounds.</p>
+
+ <p>As a special case, if <var>Amount</var> = <tt>0</tt>,
+ <var>Scale</var> = <tt>2**32 - 1</tt> (i.e. the largest possible
+ 32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this
+ indicates an unknown amount.</p>
+ </tp:docstring>
+
+ <tp:member type="i" name="Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The amount, expressed as a fixed-point number with decimal scale
+ defined by the <var>Scale</var> field; for instance, an
+ <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of
+ <tt>2</tt> represents 12.34 in the currency unit given by the
+ <var>Currency</var> field.</p>
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Scale">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The decimal scale for the fixed point value of the
+ <var>Amount</var> field, defining the number of rightmost decimal
+ digits from the integer value which form the fractional part of the
+ resulting currency value.</p>
+
+ <p>As well as defining the interpretation of <var>Amount</var>, user
+ interfaces may use this value to determine the precision with which
+ to display the amount.</p>
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Currency">
+ <tp:docstring>
+ The currency code represented by this amount, which SHOULD be an
+ international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>,
+ or <tt>"JPY"</tt> if possible. An empty string can be used to
+ indicate that the currency is not known.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="AccountBalance" tp:name-for-bindings="Account_Balance"
+ access="read" type="(ius)" tp:type="Currency_Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The user's balance on the account corresponding to this <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
+ A negative amount may be possible on some services, and indicates
+ that the user owes money to the service provider.</p>
+
+ <p>On initial connection, this property may have an unknown
+ value, represented by <var>Amount</var> = <tt>0</tt>,
+ <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit
+ unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="BalanceChanged" tp:name-for-bindings="Balance_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the user's balance has changed.</p>
+ </tp:docstring>
+
+ <arg name="Balance" type="(ius)" tp:type="Currency_Amount">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The new value of the <tp:member-ref>AccountBalance</tp:member-ref>
+ property.</p>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
new file mode 100644
index 0000000..8e5eb33
--- /dev/null
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -0,0 +1,254 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Capabilities" 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) 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.Capabilities">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections where it is possible to know what channel
+ 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
+ <tp:member-ref>AdvertiseCapabilities</tp:member-ref> 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>
+
+ <tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
+ instead.</tp:deprecated>
+ <tp:changed version="0.19.8">Connection managers implementing
+ Capabilities MUST implement ContactCapabilities too.</tp:changed>
+
+ <tp:flags name="Connection_Capability_Flags"
+ value-prefix="Connection_Capability_Flag" type="u">
+ <tp:flag suffix="Create" value="1">
+ <tp:docstring>
+ The given channel type and handle can be given to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
+ 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
+ <tp:member-ref>AdvertiseCapabilities</tp:member-ref> on the
+ Capabilities interface.</tp:docstring>
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
+ <tp:member type="u" name="Type_Specific_Flags"/>
+ </tp:struct>
+
+ <tp:struct name="Contact_Capability" array-name="Contact_Capability_List">
+ <tp:docstring>A struct (contact handle, channel type, generic flags,
+ type-specific flags) representing a capability posessed by a contact,
+ as returned by <tp:member-ref>GetCapabilities</tp:member-ref> on the
+ Capabilities interface.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
+ <tp:member type="u" tp:type="Connection_Capability_Flags"
+ name="Generic_Flags"/>
+ <tp:member type="u" name="Type_Specific_Flags"/>
+ </tp:struct>
+
+ <tp:struct name="Capability_Change" array-name="Capability_Change_List">
+ <tp:docstring>A struct (contact handle, channel type, old generic flags,
+ new generic flags, old type-specific flags, new type-specific flags)
+ representing a change to one of a contact's capabilities, as seen in the
+ <tp:member-ref>CapabilitiesChanged</tp:member-ref> signal on the
+ Capabilities interface.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
+ <tp:member type="u" tp:type="Connection_Capability_Flags"
+ name="Old_Generic_Flags"/>
+ <tp:member type="u" tp:type="Connection_Capability_Flags"
+ name="New_Generic_Flags"/>
+ <tp:member type="u" name="Old_Type_Specific_Flags"/>
+ <tp:member type="u" name="New_Type_Specific_Flags"/>
+ </tp:struct>
+
+ <method name="AdvertiseCapabilities"
+ tp:name-for-bindings="Advertise_Capabilities">
+ <arg direction="in" name="Add" type="a(su)" tp:type="Capability_Pair[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structures containing:
+ <ul>
+ <li>a string channel type</li>
+ <li>a bitwise OR of type specific capability flags</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Remove" type="as" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ An array of D-Bus interface names of channel types to remove
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a(su)" tp:type="Capability_Pair[]"
+ name="Self_Capabilities">
+ <tp:docstring>
+ An array of structures describing the current capabilities containing:
+ <ul>
+ <li>a string channel type</li>
+ <li>a bitwise OR of type specific capability flags</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Used by user interfaces to indicate which channel types they are able
+ to handle on this connection. Because these may be provided by
+ different client processes, this method accepts channel types to add
+ and remove from the set already advertised on this connection. The type
+ of advertised capabilities (create versus invite) is protocol-dependent
+ and hence cannot be set by the this method. In the case of a client
+ adding an already advertised channel type but with new channel type
+ specific flags, the connection manager should simply add the new flags
+ to the set of advertised capabilities.</p>
+
+ <p>Upon a successful invocation of this method, the
+ <tp:member-ref>CapabilitiesChanged</tp:member-ref>
+ signal will be emitted for the user's own handle ( <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>)
+ 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
+ which are still provided by another client.</p>
+
+ <p>On connections managed by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>,
+ this method SHOULD NOT be used by clients other than the
+ ChannelDispatcher itself.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="CapabilitiesChanged"
+ tp:name-for-bindings="Capabilities_Changed">
+ <arg name="Caps" type="a(usuuuu)" tp:type="Capability_Change[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structures containing:
+ <ul>
+ <li>an integer handle representing the contact</li>
+ <li>a string channel type</li>
+ <li>a bitwise OR of the contact's old generic capability flags</li>
+ <li>a bitwise OR of the contact's new generic capability flags</li>
+ <li>a bitwise OR of the contact's old type specific capability flags</li>
+ <li>a bitwise OR of the contact's new type specific capability flags</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <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" tp:name-for-bindings="Get_Capabilities">
+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+ <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[]"
+ name="Contact_Capabilities">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structures containing:
+ <ul>
+ <li>an integer handle representing the contact</li>
+ <li>a string channel type</li>
+ <li>a bitwise OR of generic capability flags for the type</li>
+ <li>a bitwise OR of type specific capability flags for the type</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ 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 and is not zero
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:contact-attribute name="caps"
+ type="a(usuu)" tp:type="Contact_Capability[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetCapabilities</tp:member-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.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml
new file mode 100644
index 0000000..99a3602
--- /dev/null
+++ b/spec/Connection_Interface_Cellular.xml
@@ -0,0 +1,131 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Cellular"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular">
+ <tp:added version="0.19.8">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface is for various cellular things (GSM and/or CDMA) that
+ aren't really applicable to other protocols.</p>
+ </tp:docstring>
+
+ <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period"
+ type="u" access="readwrite"
+ tp:is-connection-parameter='yup'>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Define how long should the service centre try message delivery before
+ giving up, failing delivery and deleting the message. A value of 0
+ means to use the service centre's default period.</p>
+
+ <p>The value specified is in seconds. Note that various protocols or
+ implementations may round the value up (eg. to a minute or hour
+ precision). The maximum validity period may vary depending on
+ protocol or provider.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="OverrideMessageServiceCentre"
+ tp:name-for-bindings="Override_Message_Service_Centre"
+ type="b" access="readwrite"
+ tp:is-connection-parameter='can i get a hell yeah?'>
+ <tp:added version='0.19.12'>Previously, as an undocumented
+ feature, setting <tp:member-ref>MessageServiceCentre</tp:member-ref>
+ to the empty string caused the SIM's default SMSC to be used.</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <code>True</code>, SMSes will be sent via the service centre
+ specified by <tp:member-ref>MessageServiceCentre</tp:member-ref>. If
+ <code>False</code>, the SIM's default SMSC will be used, ignoring the
+ value of MessageServiceCentre.</p>
+
+ <tp:rationale>
+ <p>It could be desirable for a configuration interface to remember
+ the user's previous choice of custom SMSC, even if it's not in use.
+ This boolean allows that choice to be saved as an account parameter
+ by Mission Control, rather than the UI needing to save it elsewhere
+ to be restored if the user wants to reactivate it.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre"
+ type="s" access="readwrite"
+ tp:is-connection-parameter='HELL YEAH!!!'>
+ <tp:changed version='0.19.12'>This property's value is now
+ ignored unless
+ <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is
+ <code>True</code>.</tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+
+ <p>Address for the messaging service centre. Typically (as is the case
+ for GSM's SMSC), it's the ISDN / telephony address (ie. a phone
+ number). If
+ <tp:member-ref>OverrideMessageServiceCentre</tp:member-ref> is
+ <code>False</code>, this property's value should be ignored by the CM
+ in favour of the SIM's default SMSC.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The International Mobile Subscriber Identifier, if it exists. This
+ would originate from a SIM card. If the IMSI is unknown, this will
+ contain an empty string ("").</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed">
+ <tp:docstring>
+ Emitted when the IMSI for the connection changes. This sort of thing
+ is rare, but could happen on cellular phones that allow hot-swapping
+ of SIM cards. In the case of SIM swapping, this signal would be
+ emitted twice; the first time while the SIM is being ejected (with an
+ empty string), and the second time after a new SIM has been inserted
+ (assuming that the IMSI can be determined from the new SIM).
+ </tp:docstring>
+
+ <arg name="IMSI" type="s">
+ <tp:docstring>
+ The new IMSI value. This may be an empty string in the case where
+ the IMSI is being reset or removed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="MessageReducedCharacterSet"
+ tp:name-for-bindings="Message_Reduced_Character_Set"
+ type="b" access="readwrite"
+ tp:is-connection-parameter='no... just kidding! yes!'>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Determines whether SMSes containing characters that do not fit into
+ a 7‐bit GSM character set should be sent as UCS‐2, or lossily
+ recoded. If <code>False</code> (which SHOULD be the default),
+ messages will be sent with no loss of fidelity (at the potential
+ financial cost of using twice as many SMSes); if <code>True</code>,
+ the message will be recoded in an implementation‐specific way to fit
+ into a country‐specific GSM reduced character set.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml
new file mode 100644
index 0000000..9790856
--- /dev/null
+++ b/spec/Connection_Interface_Client_Types.xml
@@ -0,0 +1,218 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Client_Types"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ClientTypes">
+ <tp:added version="0.21.1">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface on connections to support protocols which allows users to
+ subscribe to the client types of their contacts.</p>
+
+ <p>One can connect to instant messaging networks on a huge variety of
+ devices, from PCs, to phones to consoles. It can be useful for users
+ to know what kind of device a contact is using so that he or she
+ can decide not to send that big file or start a video chat. This
+ interface exposes exactly this information for clients to display.</p>
+
+ <p>The client types are represented in strings, using the values
+ <a href="http://xmpp.org/registrar/disco-categories.html#client">
+ documented by the XMPP registrar</a> with some additional types
+ added for other protocols. A contact can set one or more client types
+ so this interface returns a list of strings to denote client types
+ for a contact. The well-known client types to be used are:</p>
+
+ <ul>
+ <li>bot</li>
+ <li>console (minimal non-GUI client used on dumb terminals or
+ text-only screens, <strong>not</strong> a games console)</li>
+ <li>handheld</li>
+ <li>pc</li>
+ <li>phone</li>
+ <li>web</li>
+<!-- Excluding these two because there's been no conclusion regarding my mail
+ to standards@xmpp.org about adding these two to their list:
+
+ <li>sms (the client is not actually an instant messaging client
+ but all messages sent to this contact will be delivered as SMSs)</li>
+ <li>game (a gaming device)</li>
+-->
+ </ul>
+
+ <p>If the empty list is given as the client types, this means that
+ details about the contact's client types are unknown. If there are
+ multiple resources of a contact online at one point in time, the
+ client types of the most available resource will be returned. In
+ other words, the returned client types are those for the resource whose
+ presence will be retreived using the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface.</p>
+
+ <p>For example, if a contact has two resources:</p>
+
+ <ul>
+ <li>their phone, with presence "available"; and</li>
+ <li>their pc, with presence "busy";</li>
+ </ul>
+
+ <p>then the methods in this interface will return an array (with
+ one element: "phone") as the client types because that is the more
+ available resource. If at some later time the contact's phone's presence
+ changes to "away", the
+ <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will
+ notify that the contact's client types attribute has changed from
+ ["phone"] to ["pc"],
+ because "busy" is a more available presence than "away".</p>
+
+ </tp:docstring>
+
+ <tp:mapping name="Contact_Client_Types">
+ <tp:docstring>
+ A mapping from contact handle to client types.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+ <tp:docstring>
+ A contact.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="as" name="Client_Types" tp:type="Contact_Client_Type[]">
+ <tp:docstring>
+ The contact's client types as documented earlier in this interface.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types">
+ <tp:docstring>
+ Return the client types of the given contacts, if they are
+ already known. If any of the given contacts' client types are
+ not known, request their current client types, but return
+ immediately without waiting for a reply; if a reply with a
+ non-empty client type array is later received for those
+ contacts, the
+ <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will
+ be emitted for them.
+
+ <tp:rationale>
+ This method is appropriate for "lazy" client type finding, for instance
+ displaying the client types (if available) of everyone in your contact
+ list.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The contacts whose client types should be returned or signalled.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Client_Types" type="a{uas}"
+ tp:type="Contact_Client_Types">
+ <tp:docstring>
+ The contacts' client types, if already known. Contacts whose client
+ types are not already known are omitted from the mapping; contacts known
+ to have no client type information appear in the mapping with an empty
+ list.
+ </tp:docstring>
+ </arg>
+
+ <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="RequestClientTypes" tp:name-for-bindings="Request_Client_Types">
+ <tp:docstring>
+ Return the current client types of the given contact. If necessary, make
+ a request to the server for up-to-date information, and wait for a
+ reply.
+
+ <tp:rationale>
+ This method is appropriate for use in a "Contact Information..."
+ dialog; it can be used to show progress information (while waiting
+ for the method to return), and can distinguish between various error
+ conditions.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact whose client types should be returned.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Client_Types" type="as"
+ tp:type="Contact_Client_Type[]">
+ <tp:docstring>
+ The contact's client types. It MAY be empty, indicating that no client
+ type information was found.
+ </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.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
+ <tp:docstring>
+ The requested contact does not allow the local user to see their
+ client type information.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated">
+ <tp:docstring>
+ Emitted when a contact's client types change or become known.
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact.
+ </tp:docstring>
+ </arg>
+ <arg name="Client_Types" type="as" tp:type="Contact_Client_Type[]">
+ <tp:docstring>
+ The contact's client types, or an empty list to indicate that nothing
+ is known about the contact's client types.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:contact-attribute name="client-types" type="as"
+ tp:type="Contact_Client_Type[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same mapping that would be returned by
+ <tp:member-ref>GetClientTypes</tp:member-ref> for this contact.
+ Omitted from the result if the contact's client types are not
+ known.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:simple-type name="Contact_Client_Type" type="s"
+ array-name="Contact_Client_Type_List">
+ <tp:docstring>A string representing a single client type of a
+ contact.</tp:docstring>
+ </tp:simple-type>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml
new file mode 100644
index 0000000..31343de
--- /dev/null
+++ b/spec/Connection_Interface_Communication_Policy.xml
@@ -0,0 +1,163 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Communication_Policy"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+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.
+
+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
+Library General Public License for more details.
+
+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.
+ </tp:license>
+
+ <interface
+ name="org.freedesktop.Telepathy.Connection.Interface.CommunicationPolicy.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.21.1">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ This interface supports controlling which contacts are allowed
+ to initiate text chats, incoming calls, and other forms of
+ communication as supported by the underlying protocol. The
+ policies supported for different communication methods on this
+ connection are listed in the
+ <tp:member-ref>SupportedPolicies</tp:member-ref> property. The
+ current configuration is held in
+ <tp:member-ref>ActivePolicies</tp:member-ref>; it can be modified
+ using <tp:member-ref>SetPolicy</tp:member-ref>, and changes
+ are signalled by <tp:member-ref>PolicyChanged</tp:member-ref>.
+ </p>
+ </tp:docstring>
+
+ <tp:mapping name="Active_Policies_Map">
+ <tp:docstring>
+ A mapping of communication methods (channel types), and their
+ associated policy.
+ </tp:docstring>
+
+ <tp:member type="s" tp:type="DBus_Interface" name="Channel_Type">
+ <tp:docstring>
+ The channel interface with the policy.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="(uv)" tp:type="Access_Control" name="Active_Policy">
+ <tp:docstring>
+ The active policy for this channel type.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="SupportedPolicies"
+ tp:name-for-bindings="Supported_Policies" access="read"
+ type="a(asau)" tp:type="Supported_Policy[]">
+ <tp:docstring>
+ The communication policies supported by this connection.
+ </tp:docstring>
+ </property>
+
+ <property name="ActivePolicies" tp:name-for-bindings="Active_Policies"
+ access="read" type="a{s(uv)}" tp:type="Active_Policies_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The active communication policies on this
+ connection. Communication methods that are not in this
+ mapping are considered open.</p>
+
+ <p>For example, to allow incoming calls only from contacts
+ buddy list, and to allow text messages from anyone,
+ the policy would look like this:</p>
+
+ <pre>
+{
+ 'org.freedesktop.Telepathy.Channel.Type.Text' : Access_Control_Type_Open,
+ 'org.freedesktop.Telepathy.Channel.Type.Call' : Access_Control_Type_Publish_List
+}
+ </pre>
+
+ <p>Changes to this property are signalled by
+ <tp:member-ref>PolicyChanged</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="SetPolicy" tp:name-for-bindings="Set_Policy">
+ <tp:docstring>
+ Set a policy for a communication method (channel
+ type). Depending on the server or protocol, more than one
+ communication method could be bound to the same policy, if
+ calling this method on one channel type changes the policy on
+ another channel type, the <tp:member-ref>PolicyChanged</tp:member-ref>
+ signal that would follow would include all the channel types
+ that have an altered policy.
+ </tp:docstring>
+ <arg name="Channel_Type" direction="in" type="s"
+ tp:type="DBus_Interface">
+ <tp:docstring>
+ The channel type to set the policy for.
+ </tp:docstring>
+ </arg>
+ <arg name="Policy" direction="in" type="(uv)"
+ tp:type="Access_Control">
+ <tp:docstring>
+ The policy to set for this channel.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="PolicyChanged" tp:name-for-bindings="Policy_Changed">
+ <tp:docstring>
+ <tp:member-ref>ActivePolicies</tp:member-ref> has
+ changed. This occurs when the server unilaterally changed the
+ policy or <tp:member-ref>SetPolicy</tp:member-ref> has been
+ called.
+ </tp:docstring>
+ <arg name="Changed_Policies" type="a{s(uv)}"
+ tp:type="Active_Policies_Map">
+ <tp:docstring>
+ A subset of the active policies that have changed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:struct name="Supported_Policy" array-name="Supported_Policy_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The communication methods (channel types), and the policies
+ that can be applied to them. This is server and protocol
+ dependant.</p>
+
+ <p>Grouped channel types will always have the same policy applied
+ to them.</p>
+
+ <tp:rationale>
+ Different protocols have different limitations to the
+ granularity of communication policies. One protocol might be
+ able to set a different policy for VoIP calls and text chat,
+ while another protocol might only be able to set one policy
+ to both VoIP and text chat.
+ </tp:rationale>
+ </tp:docstring>
+ <tp:member type="as" tp:type="DBus_Interface[]"
+ name="Channel_Types">
+ <tp:docstring>
+ A list of channel interfaces that support these policies.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="au" tp:type="Access_Control_Type[]"
+ name="Supported_Policies">
+ <tp:docstring>
+ A list of supported policies.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ </interface>
+</node>
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
new file mode 100644
index 0000000..fb13c37
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -0,0 +1,306 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2005, 2006, 2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2005, 2006, 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
+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.ContactCapabilities">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.17.28">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Contact capabilities describe the channel classes which may be
+ created with a given contact in advance of attempting to create a
+ channel. Each capability represents a commitment by the
+ connection manager that it will ordinarily be able to create a channel
+ with a contact when given a request with the properties defined by the
+ channel class.</p>
+
+ <p>Capabilities pertain to particular contact handles, and represent
+ activities such as having a text chat, a voice call with the user or a
+ stream tube of a defined type.</p>
+
+ <p>This interface also enables user interfaces to notify the connection
+ manager what capabilities to advertise for the user to other contacts.
+ This is done by using the
+ <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p>
+
+ <tp:rationale>
+ <p>XMPP is a major user of this interface: XMPP contacts will not,
+ in general, be callable using VoIP unless they advertise suitable
+ Jingle capabilities.</p>
+
+ <p>Many other protocols also have some concept of capability flags,
+ which this interface exposes in a protocol-independent way.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:struct name="Handler_Capabilities"
+ array-name="Handler_Capabilities_List">
+ <tp:docstring>
+ A structure representing the capabilities of a single client.
+ </tp:docstring>
+
+ <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name">
+ <tp:docstring>
+ For implementations of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client</tp:dbus-ref>
+ interface, the well-known bus name name of the client; for any other
+ process, any other reversed domain name that uniquely identifies it.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Channel_Classes" type="aa{sv}"
+ tp:type="String_Variant_Map[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of channel classes that can be handled by this client.
+ This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ property.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of client capabilities supported by this client, to be
+ used by the connection manager to determine what capabilities to
+ advertise. This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Alter the connection's advertised capabilities to include
+ the intersection of the given clients' capabilities with what the
+ connection manager is able to implement.</p>
+
+ <p>On connections managed by the ChannelDispatcher, processes other
+ than the ChannelDispatcher SHOULD NOT call this method, and the
+ ChannelDispatcher SHOULD use this method to advertise the
+ capabilities of all the registered <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>
+ implementations.On connections not managed by the ChannelDispatcher,
+ clients MAY use this method directly, to indicate the channels they
+ will handle and the extra capabilities they have.</p>
+
+ <p>Upon a successful invocation of this method, the connection manager
+ will only emit the
+ <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
+ for the user's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">SelfHandle</tp:dbus-ref>
+ if, in the underlying protocol, the new capabilities are distinct
+ from the previous state.</p>
+
+ <tp:rationale>
+ <p>The connection manager will essentially intersect the provided
+ capabilities and the channel classes it implements. Therefore,
+ certain properties which are never fixed for a channel class
+ (such as the target handle, or the Parameters property of a tube
+ channel) will almost certainly not be advertised.</p>
+ </tp:rationale>
+
+ <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 appropriate
+ capabilities. Doing so MUST NOT fail.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Handler_Capabilities" type="a(saa{sv}as)"
+ tp:type="Handler_Capabilities[]">
+ <tp:docstring>
+ <p>The capabilities of one or more clients.</p>
+
+ <p>For each client in the given list, any capabilities previously
+ advertised for the same client name are discarded, then replaced by
+ the capabilities indicated.</p>
+
+ <p>As a result, if a client becomes unavailable, this method SHOULD
+ be called with a <tp:type>Handler_Capabilities</tp:type> structure
+ containing its name, an empty list of channel classes, and an
+ empty list of capabilities. When this is done, the connection
+ manager SHOULD free all memory associated with that client name.</p>
+
+ <tp:rationale>
+ <p>This method takes a list of clients so that
+ when the channel dispatcher first calls it (with a list of all
+ the Handlers that are initially available), the changes can be
+ made atomically, with only one transmission of updated
+ capabilities to the network. Afterwards, the channel dispatcher
+ will call this method with a single-element list every time
+ a Handler becomes available or unavailable.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST ignore any channel classes and client
+ capabilities for which there is no representation in the protocol
+ or no support in the connection manager.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetContactCapabilities"
+ tp:name-for-bindings="Get_Contact_Capabilities">
+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of contact handles for this connection.</p>
+
+ <p>The handle zero MUST NOT be included in the request.</p>
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a{ua(a{sv}as)}"
+ tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from contact handles to lists of requestable channel
+ classes, representing the channel requests that are expected
+ to succeed for that contact.</p>
+
+ <p>Contacts listed among Handles whose capabilities are unknown
+ SHOULD be omitted from this map; contacts known to have an empty
+ set of capabilities SHOULD be included in the keys of this map,
+ with an empty array as the corresponding value.</p>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Returns an array of requestable channel classes for the given
+ contact handles, representing the channel requests that are
+ expected to succeed.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <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. Zero is always invalid.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="ContactCapabilitiesChanged"
+ tp:name-for-bindings="Contact_Capabilities_Changed">
+ <arg name="caps" type="a{ua(a{sv}as)}"
+ tp:type="Contact_Capabilities_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ All the capabilities of the contacts
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Announce that there has been a change of capabilities on the
+ given handles. A single signal can be emitted for several
+ contacts.</p>
+
+ <tp:rationale>
+ <p>The underlying protocol can get several contacts' capabilities at
+ the same time.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </signal>
+
+ <tp:mapping name="Contact_Capabilities_Map"
+ array-name="Contact_Capabilities_Map_List">
+ <tp:docstring>A mapping from contact handle to their capabilities.
+ </tp:docstring>
+ <tp:member type="u" name="Key" tp:type="Contact_Handle">
+ <tp:docstring>
+ A contact handle.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="a(a{sv}as)" name="Value"
+ tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact's capabilities. These should be represented
+ in the same way as in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref>,
+ except that they may have more fixed properties or fewer allowed
+ properties, to represent contacts who do not have all the
+ capabilities of the connection.</p>
+
+ <p>In particular, requestable channel classes for channels with
+ target handle type Contact MUST list <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> among their fixed properties when
+ they appear here, and clients MAY assume that this will be the
+ case.</p>
+
+ <tp:rationale>
+ <p>This matches the initial implementations - service-side in
+ telepathy-gabble, and client-side in telepathy-qt4 - and means
+ that clients can use exactly the same code to interpret
+ RequestableChannelClasses and contact capabilities.</p>
+ </tp:rationale>
+
+ <p>Channel classes with target handle type Handle_Type_Contact
+ indicate that a request that matches the channel class, and also
+ either has the contact's handle as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandle</tp:dbus-ref> or the contact's identifier as
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel"
+ >TargetID</tp:dbus-ref>, can be expected to succeed. Connection
+ managers SHOULD NOT include the TargetHandle or TargetID as a
+ fixed property in contact capabilities.</p>
+
+ <tp:rationale>
+ <p>This makes one channel class sufficient to describe requests via
+ TargetHandle or TargetID, and is necessary in order to allow
+ clients to interpret RequestableChannelClasses and contact
+ capabilities with the same code.</p>
+ </tp:rationale>
+
+ <p>Channel classes with target handle type Handle_Type_Room or
+ Handle_Type_None indicate that if a channel matching the channel
+ class is created, then inviting the contact to that channel
+ can be expected to succeed.</p>
+
+ <tp:rationale>
+ <p>To support room-based XMPP protocols like
+ <a href="http://telepathy.freedesktop.org/wiki/Muji">Muji</a>
+ and MUC Tubes, it's necessary to be able to discover who can be
+ invited to a given room channel; most XMPP contacts won't
+ support being invited into a Muji conference call, at least
+ in the short to medium term.</p>
+ </tp:rationale>
+
+ <p>No interpretation is defined for channel classes with any other
+ target handle type, or for channel classes that do not fix a
+ target handle type, in this version of the Telepathy
+ specification.</p>
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:contact-attribute name="capabilities"
+ type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetContactCapabilities</tp:member-ref>.
+ 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.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml
new file mode 100644
index 0000000..5282a82
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Groups.xml
@@ -0,0 +1,549 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.ContactGroups">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
+ <tp:added version="0.21.0">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections in which contacts can be placed in
+ user-defined groups.</p>
+
+ <p>The most basic functionality of this interface is to list and monitor
+ a contact's set of groups. To do this, use the
+ <tp:member-ref>GroupsChanged</tp:member-ref> signal, and the
+ <tp:token-ref>groups</tp:token-ref> contact attribute (this should
+ usually be done by connecting to the GroupsChanged signal, then
+ calling <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref> with this interface
+ included in the Interfaces argument). Simple user interfaces can
+ limit themselves to displaying that information, and ignore the rest
+ of this interface: to ensure that this works,
+ <tp:member-ref>GroupsChanged</tp:member-ref> is emitted for every
+ change, even if that change could be inferred from another signal
+ such as <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+
+ <p>Looking at contacts' lists of groups is sufficient to present a
+ user interface resembling XMPP's data model, in which groups behave
+ like tags applied to contacts, and so an empty group cannot exist
+ or is not interesting. However, some protocols model groups as
+ objects in their own right. User interfaces may either track
+ the set of groups via the <tp:member-ref>Groups</tp:member-ref>
+ property and the <tp:member-ref>GroupsCreated</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals, or ignore
+ this extra information.</p>
+
+ <p>Similarly, in some protocols it is possible to rename a group as
+ a single atomic operation. Simpler user interfaces will
+ see the new name being created, the old name being removed, and the
+ members moving to the new name, via the signals described above.
+ More advanced user interfaces can optionally distinguish between an
+ atomic rename and a create/remove pair, and display renamed groups
+ differently, by monitoring the
+ <tp:member-ref>GroupRenamed</tp:member-ref> signal.</p>
+
+ <p>This interface also provides various methods to manipulate
+ user-defined groups, which can be expected to work if
+ <tp:member-ref>GroupStorage</tp:member-ref> is not None.</p>
+
+ <p>Depending on the protocol, some methods might be implemented by
+ more than one protocol operation; for instance, in a
+ "contact-centric" protocol like XMPP,
+ <tp:member-ref>SetContactGroups</tp:member-ref> is a single
+ protocol operation and <tp:member-ref>SetGroupMembers</tp:member-ref>
+ requires a protocol operation per contact, whereas in a more
+ "group-centric" protocol it might be the other way around. User
+ interfaces SHOULD call whichever method most closely resembles the
+ way in which the user's action was represented in the UI, and
+ let the connection manager deal with the details.</p>
+ </tp:docstring>
+
+ <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups"
+ access="read" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if each contact can be in at most one group; false if each
+ contact can be in many groups.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="GroupStorage" tp:name-for-bindings="Group_Storage"
+ type="u" tp:type="Contact_Metadata_Storage_Type" access="read">
+ <tp:docstring>
+ <p>Indicates the extent to which contacts' groups can be set and
+ stored.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:contact-attribute name="groups" type="as">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The names of groups of which a contact is a member.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>GroupsChanged</tp:member-ref>; clients can also
+ get extra context for group membership changes by receiving
+ <tp:member-ref>GroupRenamed</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed">
+ <tp:docstring>
+ Emitted when contacts' groups change.
+ </tp:docstring>
+
+ <arg name="Contact" type="au" tp:type="Contact_Handle">
+ <tp:docstring>The relevant contacts.</tp:docstring>
+ </arg>
+
+ <arg name="Added" type="as">
+ <tp:docstring>The names of groups to which the contacts were
+ added.</tp:docstring>
+ </arg>
+
+ <arg name="Removed" type="as">
+ <tp:docstring>The names of groups from which the contacts were
+ removed.</tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Groups" type="as" access="read"
+ tp:name-for-bindings="Groups">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The names of all groups that currently exist. This may be a
+ larger set than the union of all contacts' <code>groups</code>
+ contact attributes, if the connection allows groups to be
+ empty.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>GroupsCreated</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref>; clients can also
+ distinguish between a create/remove pair and a renamed group by
+ receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p>
+
+ <p>This property's value is not meaningful until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> has become Success.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created">
+ <tp:docstring>
+ Emitted when new, empty groups are created. This will often be
+ followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that
+ add some members.
+ </tp:docstring>
+
+ <arg name="Names" type="as">
+ <tp:docstring>The names of the new groups.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a group is renamed, in protocols where this can
+ be distinguished from group creation, removal and membership
+ changes.</p>
+
+ <p>Immediately after this signal is emitted,
+ <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the
+ creation of a group with the new name, and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> MUST signal the
+ removal of a group with the old name.</p>
+
+ <tp:rationale>
+ <p>Emitting these extra signals, in this order, means that clients
+ that are interested in the set of groups that exist (but treat a
+ rename and a create/remove pair identically) can ignore the
+ GroupRenamed signal entirely.</p>
+ </tp:rationale>
+
+ <p>If the group was not empty, immediately after those signals are
+ emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ that the members of that group were removed from the old name
+ and added to the new name.</p>
+
+ <p>On connection managers where groups behave like tags, renaming a
+ group MAY be signalled as a set of
+ <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsRemoved</tp:member-ref> and
+ <tp:member-ref>GroupsChanged</tp:member-ref> signals, instead of
+ emitting this signal.</p>
+
+ <tp:rationale>
+ <p>On protocols like XMPP, another resource "renaming a group" is
+ indistinguishable from changing contacts' groups individually.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Old_Name" type="s">
+ <tp:docstring>The old name of the group.</tp:docstring>
+ </arg>
+
+ <arg name="New_Name" type="s">
+ <tp:docstring>The new name of the group.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when one or more groups are removed. If they had members at
+ the time that they were removed, then immediately after this signal
+ is emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ that their members were removed.</p>
+
+ <tp:rationale>
+ <p>Emitting the signals in this order allows for two modes of
+ operation. A client interested only in a contact's set of groups
+ can ignore <tp:member-ref>GroupsRemoved</tp:member-ref> and rely
+ on the <tp:member-ref>GroupsChanged</tp:member-ref> signal that
+ will follow; a more elaborate client wishing to distinguish between
+ all of a group's members being removed, and the group itself
+ being removed, can additionally watch for
+ <tp:member-ref>GroupsRemoved</tp:member-ref> and use it to
+ disambiguate.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Names" type="as">
+ <tp:docstring>The names of the groups.</tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given contact to the given groups (creating new groups
+ if necessary), and remove them from all other groups.</p>
+
+ <tp:rationale>
+ <p>This is the easiest and most correct way to implement user
+ interfaces that display a single contact with a list of groups,
+ resulting in a user expectation that when they apply the changes,
+ the contact's set of groups will become exactly what was
+ displayed.</p>
+ </tp:rationale>
+
+ <p>If the user is removed from a group of which they were the only
+ member, the group MAY be removed automatically.</p>
+
+ <tp:rationale>
+ <p>In protocols like XMPP where groups behave like tags, a group
+ with no members has no protocol representation.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
+ <tp:docstring>The contact to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Groups" type="as" direction="in">
+ <tp:docstring>The set of groups which the contact should be
+ in.</tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref>
+ is true and the list of groups has more than one
+ member.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given members to the given group (creating it if necessary),
+ and remove all other members.</p>
+
+ <tp:rationale>
+ <p>This is the easiest and most correct way to implement user
+ interfaces that display a single group with a list of contacts,
+ resulting in a user expectation that when they apply the changes,
+ the groups's set of members will become exactly what was
+ displayed.</p>
+ </tp:rationale>
+
+ <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
+ this will also remove each member from their previous group.</p>
+
+ <p>If the user is removed from a group of which they were the only
+ member, the group MAY be removed automatically.</p>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members for the group. If this set is
+ empty, this method MAY remove the group.</tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AddToGroup" tp:name-for-bindings="Add_To_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given members to the given group, creating it if
+ necessary.</p>
+
+ <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
+ this will also remove each member from their previous group.</p>
+
+ <tp:rationale>
+ <p>This is good for user interfaces in which you can edit groups
+ via drag-and-drop.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members to include in the group.</tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove the given members from the given group.</p>
+
+ <tp:rationale>
+ <p>This is good for user interfaces in which you can edit groups
+ via drag-and-drop.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter. If it does not exist, then it has
+ no members by definition, so this method SHOULD return
+ successfully.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members to remove from the group. It is not
+ an error to remove members who are already not in the group.
+ If there are no members left in the group afterwards, the group MAY
+ itself be removed.</tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveGroup" tp:name-for-bindings="Remove_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove all members from the given group, then remove the group
+ itself. If the group already does not exist, this method SHOULD
+ return successfully.</p>
+
+ <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to remove.</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>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RenameGroup" tp:name-for-bindings="Rename_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Rename the given group.</p>
+
+ <p>On protocols where groups behave like tags, this is an API
+ short-cut for adding all of the group's members to a group with
+ the new name, then removing the old group.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients can't perform this operation atomically, even
+ if the connection could.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >ContactListState</tp:dbus-ref> changes to Success.
+ If the ContactListState is Failure, this method SHOULD raise the
+ same error as
+ <tp:dbus-ref namespace="ofdT.Connection.Interface.ContactList"
+ >GetContactListAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Old_Name" type="s" direction="in">
+ <tp:docstring>The group to rename.</tp:docstring>
+ </arg>
+
+ <arg name="New_Name" type="s" direction="in">
+ <tp:docstring>The new name for the group.</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>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist">
+ <tp:docstring>Raised if there is no group with that
+ name.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>Raised if there is already a group with the new
+ name.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet"/>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
new file mode 100644
index 0000000..527d325
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -0,0 +1,550 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Info" 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.ContactInfo">
+ <tp:added version="0.19.4">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List">
+ <tp:member type="s" name="Field_Name">
+ <tp:docstring>
+ The name of the field; this is the lowercased name of a vCard field.
+ For example, a field representing a contact's address would be named
+ "adr".
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="as" name="Parameters">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of vCard type parameters applicable to this field, with their
+ values. The type parameter names, and any values that are
+ case-insensitive in vCard, MUST be in lower case. For example, a
+ contact's preferred home address would have parameters
+ 'type=home' and 'type=pref'.</p>
+
+ <tp:rationale>
+ The type parameter 'type' is likely to be the most common, but
+ there can be others, such as 'language=en'.
+ </tp:rationale>
+
+ <p>Characters which are required to be escaped in vCard type
+ parameters should not be escaped in this list. For instance,
+ a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become
+ ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p>
+
+ <tp:rationale>
+ This avoids Telepathy UIs having to understand the escaping and
+ unescaping rules for vCards. The type parameter name is not
+ allowed (by RFC 2425) to contain an '=' character, so no ambiguity
+ is introduced.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="as" name="Field_Value">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For unstructured vCard fields (such as 'fn', a formatted name
+ field), a single-element array containing the field's value.</p>
+
+ <p>For structured fields (such as 'adr', an address field), an array
+ corresponding to the semicolon-separated elements of the field (with
+ empty strings for empty elements).</p>
+
+ <p>A vCard field with multiple comma-separated values, such as
+ 'nickname', should be represented by several
+ <tp:type>Contact_Info_Field</tp:type>s.</p>
+
+ <p>Characters which are required to be escaped in vCard values, such as
+ semi-colons and newlines, should not be escaped in this list (e.g. if
+ a value contains a newline, the data passed over D-Bus should
+ contain a literal newline character).</p>
+
+ <tp:rationale>
+ An earlier draft of this interface split structured vCard fields
+ into multiple Telepathy-level fields; for example, 'n' became
+ 'family-name', 'given-name', etc. But under this representation,
+ omitting empty components leads to difficulty identifying where one
+ name ends and another begins. Consider the fields ['given-name',
+ 'honorific-suffixes', 'family-name', 'honorific-prefixes']: does
+ this represent two 'n' fields, or one with incorrect component
+ ordering?
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Represents one piece of information about a contact, as modelled by
+ a single vCard field. Of the fields defined in RFC 2426, common
+ examples include:</p>
+
+ <dl>
+ <dt>fn</dt>
+ <dd>The contact's full name, formatted to their liking</dd>
+
+ <dt>n</dt>
+ <dd>The contact's full name, divided into five parts: family name,
+ given name, additional names, honorific prefixes, and honorific
+ suffixes</dd>
+
+ <dt>org</dt>
+ <dd>The contact's organisation, divided into the organization's name
+ possibly followed by one or more organizational unit names.</dd>
+
+ <dt>adr</dt>
+ <dd>A street address for the contact, divided into seven components:
+ post office box, extended address, street address, locality (e.g.,
+ city), region (e.g., state or province), the postal code, and the
+ country name.</dd>
+
+ <dt>label</dt>
+ <dd>A free-form street address for the contact, formatted as a
+ single value (with embedded newlines where necessary) suitable for
+ printing on an address label</dd>
+
+ <dt>tel</dt>
+ <dd>A telephone number for the contact.</dd>
+
+ <dt>email</dt>
+ <dd>An email address for the contact.</dd>
+ </dl>
+
+ <p>For example, the following vCard:</p>
+
+ <pre>
+ BEGIN:vCard
+ VERSION:3.0
+ FN:Wee Ninja
+ N;LANGUAGE=ja:Ninja;Wee;;;-san
+ ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
+ ;CB2 1SJ;UK
+ LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ
+ TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753
+ EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
+ EMAIL;TYPE=INTERNET:wee.ninja@example.com
+ URL:http://www.thinkgeek.com/geektoys/plush/8823/
+ NICKNAME:HR Ninja,Enforcement Ninja
+ END:vCard</pre>
+
+ <p>would be represented by (in Python-like syntax):</p>
+
+ <pre>
+[
+ ('fn', [], ['Wee Ninja']),
+ ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
+ ('org', [], ['Collabora, Ltd.', 'Management Division',
+ 'Human Resources; Company Policy Enforcement']),
+ ('adr', ['type=work','type=postal','type=parcel'],
+ ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+ ('label', ['type=work','type=postal','type=parcel'],
+ ['''11 Kings Parade
+ Cambridge
+ Cambridgeshire
+ UK
+ CB2 1SJ''']),
+ ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+ ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+ ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
+ ('email', ['type=internet'], ['wee.ninja@example.com']),
+ ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+ ('nickname', [], ['HR Ninja']),
+ ('nickname', [], ['Enforcement Ninja'])
+]</pre>
+ </tp:docstring>
+ </tp:struct>
+
+ <tp:mapping name="Contact_Info_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are contact handles and whose
+ values are contact information..</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="a(sasas)" tp:type="Contact_Info_Field[]"
+ name="Contact_Info"/>
+ </tp:mapping>
+
+ <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed">
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact whose info has changed.
+ </tp:docstring>
+ </arg>
+ <arg name="ContactInfo" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of fields representing information about this contact.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a contact's information has changed or been received for
+ the first time on this connection.
+ </tp:docstring>
+ </signal>
+
+ <method name="GetContactInfo"
+ tp:name-for-bindings="Get_Contact_Info">
+ <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" name="ContactInfo" type="a{ua(sasas)}"
+ tp:type="Contact_Info_Map">
+ <tp:docstring>
+ A dictionary mapping contact handles to information, whose keys are
+ the subset of the requested list of handles for which information was
+ cached.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request information on several contacts at once. This SHOULD only
+ return cached information, omitting handles for which no information is
+ cached from the returned map.
+ </tp:docstring>
+ </method>
+
+ <method name="RefreshContactInfo"
+ tp:name-for-bindings="Refresh_Contact_Info">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ Integer handles for contacts.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Retrieve information for the given contact, requesting it from the
+ network if an up-to-date version is not cached locally. This method
+ SHOULD return immediately, emitting
+ <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts'
+ updated contact information is returned.
+
+ <tp:rationale>
+ This method allows a client with cached contact information to
+ update its cache after a number of days.
+ </tp:rationale>
+ </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="RequestContactInfo"
+ tp:name-for-bindings="Request_Contact_Info">
+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for a contact.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Contact_Info" type="a(sasas)"
+ tp:type="Contact_Info_Field[]">
+ <tp:docstring>
+ Information about that contact.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Retrieve information for a contact, requesting it from the network if
+ it is not cached locally.
+
+ <tp:rationale>
+ This method is appropriate for an explicit user request to show
+ a contact's information; it allows a UI to wait for the contact
+ info to be returned.
+ </tp:rationale>
+ </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:docstring>
+ The contact's information could not be retrieved.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="SetContactInfo" tp:name-for-bindings="Set_Contact_Info">
+ <tp:docstring>
+ Set new contact information for this connection, replacing existing
+ information. This method is only suppported if
+ <tp:member-ref>ContactInfoFlags</tp:member-ref> contains
+ <code>Can_Set</code>, and may only be passed fields conforming to
+ <tp:member-ref>SupportedFields</tp:member-ref>.
+ </tp:docstring>
+ <arg direction="in" name="ContactInfo" type="a(sasas)"
+ tp:type="Contact_Info_Field[]">
+ <tp:docstring>
+ The new information to be set.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Setting your own information is not supported on this protocol.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The supplied fields do not match the restrictions specified by
+ <tp:member-ref>SupportedFields</tp:member-ref>.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:flags name="Contact_Info_Flags" value-prefix="Contact_Info_Flag"
+ type="u">
+ <tp:docstring>
+ Flags defining the behaviour of contact information on this protocol.
+ Some protocols provide no information on contacts without an explicit
+ request; others always push information to the connection manager as
+ and when it changes.
+ </tp:docstring>
+
+ <tp:flag suffix="Can_Set" value="1">
+ <tp:docstring>
+ Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is
+ supported on this connection.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Push" value="2">
+ <tp:docstring>
+ Indicates that the protocol pushes all contacts' information to the
+ connection manager without prompting. If set,
+ <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted
+ whenever contacts' information changes.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:simple-type name="VCard_Field" type="s">
+ <tp:docstring>
+ A string naming a field in a vCard, such as "fn" or "adr". Although
+ these are case-insensitive in RFC 2425, in Telepathy they MUST be
+ normalized to lower case. In the terminology of RFC 2425 this is
+ called a "type name", and corresponds to the "name" production given
+ in the ABNF.
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="VCard_Type_Parameter" type="s"
+ array-name="VCard_Type_Parameter_List">
+ <tp:docstring>
+ A type parameter as defined by RFC 2426, such as "type=cell" or
+ "language=en".
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="ContactInfoFlags" type="u" access="read"
+ tp:type="Contact_Info_Flags" tp:name-for-bindings="Contact_Info_Flags">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An integer representing the bitwise-OR of flags on this
+ connection.</p>
+
+ <p>This property MAY change, without change notification, at any time
+ before the connection moves to status Connection_Status_Connected.
+ It MUST NOT change after that point.</p>
+
+ <tp:rationale>
+ <p>Some XMPP servers, like Facebook Chat, do not allow the vCard to
+ be changed (and so would not have the Can_Set flag). Whether the
+ user's server is one of these cannot necessarily be detected until
+ quite late in the connection process.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </property>
+
+ <tp:struct name="Field_Spec" array-name="Field_Specs">
+ <tp:docstring>A struct describing a vCard field, with parameters, that
+ may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this
+ Connection.</tp:docstring>
+
+ <tp:member type="s" name="Name" tp:type="VCard_Field">
+ <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring>
+ </tp:member>
+
+ <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]">
+ <tp:docstring>The set of vCard type parameters which may be set on this
+ field. If this list is empty and the
+ Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type
+ parameters may be used.</tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags">
+ <tp:docstring>Flags describing the behaviour of this
+ field.</tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" name="Max">
+ <tp:docstring>Maximum number of instances of this field which may be
+ set. MAXUINT32 is used to indicate that there is no
+ limit.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="SupportedFields" type="a(sasuu)" tp:type="Field_Spec[]"
+ access="read" tp:name-for-bindings="Supported_Fields">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of field specifications describing the kinds of fields which may
+ be passed to <tp:member-ref>SetContactInfo</tp:member-ref>. The empty
+ list indicates that arbitrary vCard fields are permitted. This
+ property SHOULD be the empty list, and be ignored by clients, if
+ <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the
+ Can_Set flag.</p>
+
+ <p>For example, a protocol in which arbitrary vCards were stored
+ as-is would set this property to the
+ empty list. A protocol whose notion of contact information is one
+ each of personal phone number, mobile phone number, location, email
+ address and date of birth, with no attributes allowed on each piece
+ of information, would set this property to (in Python-like
+ syntax):</p>
+
+ <pre>
+[
+ ('tel', ['type=home'], Parameters_Exact, 1),
+ ('tel', ['type=cell'], Parameters_Exact, 1),
+ ('adr', [], Parameters_Exact, 1),
+ ('bday', [], Parameters_Exact, 1),
+ ('email', ['type=internet'], Parameters_Exact, 1),
+]</pre>
+
+ <p>A protocol which allows users to specify up to four phone numbers,
+ which may be labelled as personal and/or mobile, would set this
+ property to
+ <code>[ ('tel', ['type=home', 'type=cell'], 0, 4), ]</code>.</p>
+
+ <tp:rationale>
+ <p>Studying existing IM protocols shows that in practice protocols
+ allow either a very restricted set of fields (such as MSN, which
+ seems to correspond roughly to the largest example above), or
+ something mapping 1:1 to a large subset of vCard (such as XMPP's
+ XEP-0054).</p>
+ </tp:rationale>
+
+ <p>This property MAY change, without change notification, at any time
+ before the connection moves to status Connection_Status_Connected.
+ It MUST NOT change after that point.</p>
+
+ <tp:rationale>
+ <p>Some XMPP servers, like Google Talk, only allow a small subset of
+ the "vcard-temp" protocol. Whether the user's server is one of
+ these cannot be detected until quite late in the connection
+ process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Contact_Info_Field_Flags"
+ value-prefix="Contact_Info_Field_Flag" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Flags describing the behaviour of a vCard field.
+ </tp:docstring>
+ <tp:flag suffix="Parameters_Exact" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If present, exactly the parameters indicated must be set on this
+ field; in the case of an empty list of parameters, this implies that
+ parameters may not be used.</p>
+
+ <p>If absent, and the list of allowed parameters is non-empty,
+ any (possibly empty) subset of that list may be
+ used.</p>
+
+ <p>If absent, and the list of allowed parameters is empty,
+ any parameters may be used.</p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Overwritten_By_Nickname" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Indicates that this field will be overwritten when the user's alias
+ is changed with <tp:dbus-ref
+ namespace="ofdT.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
+ or when the Account's <tp:dbus-ref
+ namespace="ofdT.Account">Nickname</tp:dbus-ref>
+ is updated. Clients that allow the editing of the Alias and the
+ ContactInfo in the same location should hide fields with this flag.</p>
+ <tp:rationale>
+ <p>If a client allowed the user to edit both the nickname and the
+ ContactInfo field at the same time, the user could set them to two
+ different values even though they map to the same property. This
+ would result in surprising behavior where the second value would
+ win over the first.</p>
+ </tp:rationale>
+ <p>In addition to hiding this field when editing ContactInfo together
+ with the user's nickname, it is recommended that clients call
+ <tp:member-ref>SetContactInfo</tp:member-ref> before setting the
+ user's nickname.</p>
+ <tp:rationale>
+ <p>This ensures that if the user changes the nickname, the correct
+ value will get set even if the stale nickname is mistakenly sent
+ along with <tp:member-ref>SetContactInfo</tp:member-ref>.</p>
+ </tp:rationale>
+ <p>If used, this flag typically appears on either the 'nickname' or
+ 'fn' field.</p>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for requesting information about a contact on a given
+ connection. Information is represented as a list of
+ <tp:type>Contact_Info_Field</tp:type>s forming a
+ structured representation of a vCard (as defined by RFC 2426), using
+ field names and semantics defined therein.</p>
+
+ <p>On some protocols, information about your contacts is pushed to you,
+ with change notification; on others, like XMPP, the client must
+ explicitly request the avatar, and has no way to tell whether it has
+ changed without retrieving it in its entirety. This distinction is
+ exposed by <tp:member-ref>ContactInfoFlags</tp:member-ref> containing
+ the Push flag.</p>
+
+ <p>On protocols with the Push flag set, UIs can connect to
+ <tp:member-ref>ContactInfoChanged</tp:member-ref>, call
+ <tp:member-ref>GetContactInfo</tp:member-ref> once at login for the set
+ of contacts they are interested in, and then be sure they will receive
+ the latest contact info. On protocols like XMPP, clients can do the
+ same, but will receive (at most) opportunistic updates if the info is
+ retrieved for other reasons. Clients may call
+ <tp:member-ref>RequestContactInfo</tp:member-ref> or
+ <tp:member-ref>RefreshContactInfo</tp:member-ref> to force a contact's
+ info to be updated, but MUST NOT do so unless this is either in
+ response to direct user action, or to refresh their own cache after a
+ number of days.</p>
+
+ <tp:rationale>
+ <p>We don't want clients to accidentally cause a ridiculous amount of
+ network traffic.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:contact-attribute name="info"
+ type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same value that would be returned by
+ <tp:member-ref>GetContactInfo</tp:member-ref> for this contact.
+ Omitted from the result if the contact's info
+ is not known.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
new file mode 100644
index 0000000..033c64d
--- /dev/null
+++ b/spec/Connection_Interface_Contact_List.xml
@@ -0,0 +1,1085 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 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.ContactList">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.21.0">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections that have any concept of a list of
+ known contacts (roster, buddy list, friends list etc.)</p>
+
+ <tp:rationale>
+ <p>On many protocols, there's a server-side roster (as in XMPP),
+ or a set of server-side lists that can be combined to form a
+ roster (as in MSN).</p>
+
+ <p>In some protocols (like link-local XMPP), while there might not be
+ any server or roster, it's possible to list "nearby" contacts.</p>
+
+ <p>In Telepathy 0.20 and older, we represented contact lists as a
+ collection of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type"
+ >ContactList</tp:dbus-ref> channels. This is remarkably difficult to
+ work with in practice - every client that cares about contact lists
+ has to take the union of some hard-to-define set of these
+ channels - and conflicts with the idea that channels that cannot
+ be dispatched to a handler should be closed.</p>
+ </tp:rationale>
+
+ <p>The list of contacts is not exposed as a D-Bus property; it can be
+ fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ </p>
+
+ <tp:rationale>
+ <p>In some protocols, such as XMPP, the contact list may not be
+ available immediately. The
+ <tp:member-ref>GetContactListAttributes</tp:member-ref> method
+ will fail until the contact list is available.
+ Using a method also allows extra attributes to be retrieved at
+ the same time.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:enum name="Contact_List_State" type="u">
+ <tp:docstring>
+ The progress made in retrieving the contact list.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>The connection has not started to retrieve the contact
+ list. If <tp:member-ref>GetContactListAttributes</tp:member-ref> is
+ called in this state, it will raise NotYet.</tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Waiting" value="1">
+ <tp:docstring>The connection has started to retrieve the contact
+ list, but has not yet succeeded or failed.
+ If <tp:member-ref>GetContactListAttributes</tp:member-ref> is called
+ in this state, it will raise NotYet.</tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Failure" value="2">
+ <tp:docstring>
+ <p>The connection has tried and failed to retrieve the contact
+ list. If <tp:member-ref>GetContactListAttributes</tp:member-ref>
+ is called in this state, it will immediately raise an error
+ indicating the reason for failure.</p>
+
+ <p>The connection manager SHOULD try again to obtain the contact
+ list, if appropriate for the protocol. If it succeeds later,
+ the <tp:member-ref>ContactListState</tp:member-ref> MUST advance
+ to Success.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Success" value="3">
+ <tp:docstring>The connection has successfully retrieved the contact
+ list. If <tp:member-ref>GetContactListAttributes</tp:member-ref>
+ is called in this state, it will return successfully.</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="ContactListState" tp:name-for-bindings="Contact_List_State"
+ type="u" tp:type="Contact_List_State" access="read">
+ <tp:docstring>
+ The progress made in retrieving the contact list.
+ Change notification is via
+ <tp:member-ref>ContactListStateChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="ContactListStateChanged"
+ tp:name-for-bindings="Contact_List_State_Changed">
+ <tp:docstring>
+ Emitted when <tp:member-ref>ContactListState</tp:member-ref>
+ changes.
+ </tp:docstring>
+
+ <arg name="Contact_List_State" type="u" tp:type="Contact_List_State">
+ <tp:docstring>
+ The new value of <tp:member-ref>ContactListState</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="GetContactListAttributes"
+ tp:name-for-bindings="Get_Contact_List_Attributes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Return some contact attributes for a list of contacts
+ associated with the user. This list MUST include at least:</p>
+
+ <ul>
+ <li>all contacts whose <tp:token-ref>subscribe</tp:token-ref>
+ attribute is not No</li>
+ <li>all contacts whose <tp:token-ref>publish</tp:token-ref>
+ attribute is not No</li>
+ </ul>
+
+ <p>but MAY contain other contacts.</p>
+
+ <tp:rationale>
+ <p>For instance, on XMPP, all contacts on the roster would appear
+ here even if they have subscription="none", unless there's
+ reason to believe the user does not want to see them (such as
+ having been blocked).</p>
+ </tp:rationale>
+
+ <p>This list does not need to contain every visible contact: for
+ instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
+ here. Blocked contacts SHOULD NOT appear here, unless they still
+ have a non-<tt>No</tt> <tp:token-ref>subscribe</tp:token-ref> or
+ <tp:token-ref>publish</tp:token-ref> attribute
+ for some reason.</p>
+
+ <tp:rationale>
+ <p>It's reasonable to assume that blocked contacts should not be
+ visible to the user unless they specifically go looking for them,
+ at least in protocols like XMPP where blocking a contact
+ suppresses presence.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <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. Equivalent to the corresponding argument
+ to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref>,
+ except that if this list does not contain the ContactList
+ interface itself, it is treated as though that interface was also
+ requested.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Hold" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, all handles that appear as keys in the result have been
+ held on behalf of the calling process, as if by a call to
+ <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>.
+ (If <tp:dbus-ref namespace="ofdT.Connection"
+ >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the
+ case in all new connection managers, this has no effect.)</p>
+ </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,
+ equivalent to the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref>.</p>
+
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The <tp:member-ref>ContactListState</tp:member-ref> is
+ None or Waiting. In particular, this error is raised if the
+ <tp:dbus-ref namespace="ofdT.Connection">Status</tp:dbus-ref>
+ is not yet Connection_Status_Connected.</p>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:enum name="Subscription_State" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An enumeration indicating whether presence subscription is denied,
+ denied but pending permission, or allowed. The exact semantics
+ vary according to where this type is used: see the
+ <tp:token-ref>subscribe</tp:token-ref> and
+ <tp:token-ref>publish</tp:token-ref> contact attributes for
+ details.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>The presence subscription state is
+ unknown.</tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="No" value="1">
+ <tp:docstring>Presence information cannot be seen, and either the
+ subscription state Removed_Remotely does not apply, or it is
+ not known whether that state applies.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Removed_Remotely" value="2">
+ <tp:docstring>Presence information cannot be seen because the
+ remote contact took action: either the local user's request to
+ see the remote contact's presence was denied, or the remote
+ contact requested to see the local user's presence but then
+ cancelled their request.</tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Ask" value="3">
+ <tp:docstring>Presence information cannot be seen. Permission
+ to see presence information has been requested, and the request
+ has not yet been declined or accepted.</tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Yes" value="4">
+ <tp:docstring>Presence information can be seen.</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:contact-attribute name="subscribe"
+ type="u" tp:type="Subscription_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If this attribute on a contact is Yes, this connection can
+ expect to receive their presence, along with any other information
+ that has the same access control.</p>
+
+ <tp:rationale>
+ <p>This is subscription="from" or subscription="both" in XMPP,
+ the "forward list" on MSN, or the contact being "added to
+ the local user's buddy list" in ICQ, for example.</p>
+ </tp:rationale>
+
+ <p>If this attribute is not Yes, the local user cannot generally
+ expect to receive presence from this contact. Their presence status
+ as returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
+ is likely to be (Unknown, "unknown", ""), unless the local user
+ can temporarily see their presence for some other reason (for
+ instance, on XMPP, contacts seen in chatrooms will temporarily
+ have available presence).</p>
+
+ <p>If this attribute is Ask, this indicates that the local user has
+ asked to receive the contact's presence at some time. It is
+ implementation-dependent whether contacts' subscribe attributes
+ can remain set to Ask, or are reset to No, when the connection
+ disconnects.</p>
+
+ <tp:rationale>
+ <p>Some protocols store the fact that we wishes to see a contact's
+ presence; on these protocols, this attribute can remain Ask
+ indefinitely. On other protocols, only contacts who have been
+ asked during the current session will ever have Ask status.</p>
+ </tp:rationale>
+
+ <p>If this attribute is Removed_Remotely, this indicates that the
+ local user has asked to receive the contact's presence at some time,
+ but the remote contact has rejected that request, and a local
+ user interface has not yet acknowledged this. It is
+ implementation-dependent whether contacts' subscribe attributes can
+ remain set to Removed_Remotely, or are reset to No, when the
+ connection disconnects.</p>
+
+ <p>After notifying the user, user interfaces MAY acknowledge a change
+ to <tt>subscribe</tt>=Removed_Remotely by calling either
+ <tp:member-ref>Unsubscribe</tp:member-ref> or
+ <tp:member-ref>RemoveContacts</tp:member-ref>, which will set
+ <tt>subscribe</tt> to No (and perhaps remove the contact). This
+ allows user interfaces to detect that the user has been notified
+ about the rejected request.</p>
+
+ <p>This attribute's value will be Unknown or omitted until the
+ <tp:member-ref>ContactListState</tp:member-ref> has changed to
+ Success.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="publish"
+ type="u" tp:type="Subscription_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If this attribute on a contact is Yes, the local user's presence
+ is published to that contact, along with any other information that
+ shares an access-control mechanism with presence (depending on
+ protocol, server configuration and/or user configuration, this may
+ include avatars, "rich presence" such as location, etc.).</p>
+
+ <tp:rationale>
+ <p>This is subscription="to" or subscription="both" in XMPP,
+ the "reverse list" on MSN, or the state of "being added to
+ the contact's buddy list" in ICQ, for example.</p>
+ </tp:rationale>
+
+ <p>If this attribute is not Yes, the
+ local user's presence is not published to that contact; however,
+ if it is Ask, the contact has requested that the local user's
+ presence is made available to them.</p>
+
+ <p>It is implementation-dependent whether contacts' <tt>publish</tt>
+ attributes can remain set to Ask, or are reset to No, when the
+ connection disconnects.</p>
+
+ <tp:rationale>
+ <p>Some protocols store the fact that a contact wishes to see our
+ presence; on these protocols, this attribute can remain Ask
+ indefinitely. On other protocols, only contacts who have asked
+ during the current session will ever have Ask status.</p>
+ </tp:rationale>
+
+ <p>If this attribute is Removed_Remotely, this indicates that the
+ remote contact has asked to receive the user's presence at some time,
+ but has then cancelled that request before a response was given by
+ the local user. User interfaces MAY reset <tt>publish</tt> from
+ Removed_Remotely to No, by calling either
+ <tp:member-ref>Unpublish</tp:member-ref> or
+ <tp:member-ref>RemoveContacts</tp:member-ref>.</p>
+
+ <p>If multiple factors affect whether a contact can receive the local
+ user's presence, this attribute SHOULD reflect the overall
+ result. For instance, an XMPP contact with subscription="to" or
+ subscription="both", but who has been blocked via
+ <a href="http://xmpp.org/extensions/xep-0016.html">XEP-0016 Privacy
+ Lists</a>, SHOULD have publish=No.</p>
+
+ <p>This attribute's value will be Unknown or omitted until the
+ <tp:member-ref>ContactListState</tp:member-ref> has changed to
+ Success.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="publish-request" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the <tp:token-ref>publish</tp:token-ref> attribute is Ask, an
+ optional message that was sent by the contact asking to receive the
+ local user's presence; omitted if none was given.</p>
+
+ <tp:rationale>
+ <p>If the contact asking to receive our presence is also using
+ Telepathy, this is the message they supplied as the Message
+ argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>Otherwise, this SHOULD be omitted.</p>
+
+ <p>This attribute will also be omitted until the
+ <tp:member-ref>ContactListState</tp:member-ref> has changed to
+ Success.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <property name="ContactListPersists"
+ tp:name-for-bindings="Contact_List_Persists" type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, presence subscriptions (in both directions) on this
+ connection are stored by the server or other infrastructure.</p>
+
+ <tp:rationale>
+ <p>XMPP, MSN, ICQ, etc. all behave like this.</p>
+ </tp:rationale>
+
+ <p>If false, presence subscriptions on this connection are not
+ stored.</p>
+
+ <tp:rationale>
+ <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record
+ of subscriptions, as described below. In link-local XMPP,
+ subscriptions are implicit (everyone on the local network receives
+ presence from everyone else) so nothing is ever stored.</p>
+ </tp:rationale>
+
+ <p>If <tp:member-ref>CanChangeContactList</tp:member-ref>
+ is true, Telepathy clients (e.g. user interfaces or address books)
+ MAY keep a record of permission to publish and requests to subscribe
+ locally, and attempt to restore it for each Connection. If
+ ContactListPersists is false, clients MAY do this for all contacts;
+ if ContactListPersists is true, clients SHOULD NOT change the state
+ of contacts that were not changed locally.</p>
+
+ <tp:rationale>
+ <p>In SIMPLE (SIP), ContactListPersists is false, but
+ CanChangeContactList is true. Presence will not be received
+ unless clients renew any subscriptions they have for each
+ connection, in the way described. There is no server-side storage,
+ so clients have no alternative but to maintain independent contact
+ lists.</p>
+
+ <p>In protocols like XMPP and MSN, it may be useful for clients to
+ queue up subscription requests or removals made while offline and
+ process them next time the connection is online. However, clients
+ should only replay the changes, rather than resetting the contact
+ list to match a stored copy, to avoid overwriting changes that
+ were made on the server.</p>
+ </tp:rationale>
+
+ <p>Clients that replay requests like this SHOULD do so by calling
+ AuthorizePublication to pre-approve publication of presence to the
+ appropriate contacts, followed by RequestSubscription to request the
+ appropriate contacts' presences.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Contact_Metadata_Storage_Type" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Values of this enumeration indicate the extent to which metadata
+ such as aliases and group memberships can be stored for the contacts
+ on a particular connection.</p>
+
+ <p>On some protocols, certain metadata (for instance, contact aliases)
+ can only be stored for contacts on the contact list, or contacts
+ with a particular contact list state.</p>
+
+ <p>To make it easier to deal with such protocols, if clients set
+ metadata on a contact who is not in the required state, the
+ Connection MUST cache the metadata for the duration of the session.
+ If clients request the attributes of that contact after the
+ appropriate "set" method has returned successfully, the Connection
+ MUST return the new (cached) value.</p>
+
+ <p>If the contact is later placed in the required state to store
+ metadata (for instance, if subscription to the contact's presence
+ is requested, on a protocol like MSN where the alias has storage type
+ Subscribed_Or_Pending), the connection MUST store the cached
+ metadata at that time.</p>
+
+ <tp:rationale>
+ <p>If the Connection didn't cache changes in this way, a client
+ intending to change the alias on MSN would have to wait until
+ the server acknowledged the subscription request; in the meantime,
+ other clients would still display the old alias.</p>
+ </tp:rationale>
+
+ <p>The only exception to that general rule is that if the Connection
+ cannot store particular metadata at all (i.e. the
+ storage type is None), it MUST reject attempts to set it.</p>
+
+ <tp:rationale>
+ <p>If the implementation knows that metadata can't be stored at
+ all, it's useful to report that, which can be done
+ synchronously. In general, user interfaces should detect
+ storage type None and not display editing controls at all.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This connection cannot store this type of metadata at all, and
+ attempting to do so will fail with NotImplemented.</p>
+
+ <tp:rationale>
+ <p>Link-local XMPP can't store aliases or group memberships at
+ all, and subscription and presence states are implicit (all
+ contacts on the local network have subscribe = publish = Yes
+ and no other contacts exist).</p>
+
+ <p>As of April 2010, the XMPP server for Facebook Chat provides a
+ read-only view of the user's Facebook contacts, so it could also
+ usefully have this storage type.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Subscribed_Or_Pending" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This type of metadata can only be stored permanently for contacts
+ whose subscribe attribute is Ask or Yes.</p>
+
+ <tp:rationale>
+ <p>Contact aliases and groups on MSN have this behaviour.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Subscribed" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This type of metadata can only be stored permanently for contacts
+ whose subscribe attribute is Yes.</p>
+
+ <tp:rationale>
+ <p>No service with this behaviour is currently known, but it's a
+ stricter form of Subscribed_Or_Pending.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Anyone" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The user can set this metadata for any valid contact identifier,
+ whether or not they have any presence subscription relationship
+ to it, and it will be stored on their contact list.</p>
+
+ <tp:rationale>
+ <p>Contact aliases and groups on XMPP have this behaviour; it
+ is possible to put a contact in a group, or assign an alias
+ to them, without requesting that presence be shared.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Contact_Subscriptions" array-name="">
+ <tp:docstring>
+ A single contact's subscribe, publish and publish-request attributes.
+ </tp:docstring>
+
+ <tp:member name="Subscribe" type="u" tp:type="Subscription_State">
+ <tp:docstring>
+ The new value of the contact's "subscribe" attribute.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Publish" type="u" tp:type="Subscription_State">
+ <tp:docstring>
+ The new value of the contact's "publish" attribute.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Publish_Request" type="s">
+ <tp:docstring>
+ The new value of the contact's "publish-request" attribute,
+ or the empty string if that attribute would be omitted.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Contact_Subscription_Map" array-name="">
+ <tp:docstring>
+ A map from contacts to their subscribe, publish and publish-request
+ attributes.
+ </tp:docstring>
+
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact's handle.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions">
+ <tp:docstring>
+ The contact's subscribe, publish and publish-request attributes.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="ContactsChangedWithID"
+ tp:name-for-bindings="Contacts_Changed_With_ID">
+ <tp:added version="0.21.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the contact list becomes available, when contacts'
+ basic stored properties change, when new contacts are added to the
+ list that would be returned by
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>,
+ or when contacts are removed from that list.</p>
+
+ <tp:rationale>
+ <p>This provides change notification for that list, and for
+ contacts' <tp:token-ref>subscribe</tp:token-ref>,
+ <tp:token-ref>publish</tp:token-ref> and
+ <tp:token-ref>publish-request</tp:token-ref> attributes.</p>
+ </tp:rationale>
+
+ <p>Connection managers SHOULD also emit this signal when a contact
+ requests that the user's presence is published to them, even if
+ that contact's <tp:token>publish</tp:token> attribute is already
+ Ask and the <tp:token>publish-request</tp:token> has not changed.</p>
+
+ <tp:rationale>
+ <p>If the same contact sends 10 identical requests, 10 identical
+ signals should be emitted.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
+ <tp:docstring>
+ The new <tp:token-ref>subscribe</tp:token-ref>,
+ <tp:token-ref>publish</tp:token-ref> and
+ <tp:token-ref>publish-request</tp:token-ref> attributes of all the
+ contacts that have been added, and all the contacts for which those
+ attributes have changed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Identifiers" type="a{us}" tp:type="Handle_Identifier_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The identifiers of the contacts in the <var>Changes</var> map.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Removals" type="a{us}" tp:type="Handle_Identifier_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The contacts that have been removed from the list that would be
+ returned by
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ This also implies that they have subscribe = No and publish = No;
+ contacts MUST NOT be listed both here and in <var>Changes</var>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ContactsChanged"
+ tp:name-for-bindings="Contacts_Changed">
+ <tp:deprecated version="0.21.8">Connection managers MUST still
+ emit this signal, but clients SHOULD listen for the
+ <tp:member-ref>ContactsChangedWithID</tp:member-ref> signal in
+ addition, and ignore this signal after ContactsChangedWithID has been
+ emitted at least once.
+ </tp:deprecated>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted immediately after
+ <tp:member-ref>ContactsChangedWithID</tp:member-ref>, under the same
+ circumstances.</p>
+
+ <p>If clients receive this signal without first receiving a
+ corresponding <tp:member-ref>ContactsChangedWithID</tp:member-ref>,
+ they MUST assume that only this signal will be emitted.</p>
+ </tp:docstring>
+
+ <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
+ <tp:docstring>
+ The same as the corresponding argument to
+ <tp:member-ref>ContactsChangedWithID</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Removals" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The same as the corresponding argument to
+ <tp:member-ref>ContactsChangedWithID</tp:member-ref>, except that it
+ only includes handles and not identifiers.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CanChangeContactList" type="b" access="read"
+ tp:name-for-bindings="Can_Change_Contact_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, presence subscription and publication can be changed
+ using the
+ <tp:member-ref>RequestSubscription</tp:member-ref>,
+ <tp:member-ref>AuthorizePublication</tp:member-ref> and
+ <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p>
+
+ <p>If false, all of those methods will always fail; they SHOULD raise
+ the error org.freedesktop.Telepathy.Error.NotImplemented.</p>
+
+ <tp:rationale>
+ <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is
+ implicitly published to everyone in the local subnet, so the user
+ cannot control their presence publication.</p>
+ </tp:rationale>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given contacts allow the local user to
+ subscribe to their presence, i.e. that their subscribe attribute
+ becomes Yes.</p>
+
+ <p>Connection managers SHOULD NOT attempt to enforce a
+ mutual-subscription policy (i.e. when this method is called, they
+ should not automatically allow the contacts to see the local user's
+ presence). User interfaces that require mutual subscription
+ MAY call <tp:member-ref>AuthorizePublication</tp:member-ref>
+ at the same time as this method.</p>
+
+ <tp:rationale>
+ <p>Whether to enforce mutual subscription is a matter of policy,
+ so it is left to the user interface and/or the server.</p>
+ </tp:rationale>
+
+ <p>Before calling this method on a connection where <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
+ >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag,
+ user interfaces SHOULD obtain, from the user, an alias to
+ identify the contact in future, and store it using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
+ >SetAliases</tp:dbus-ref>.</p>
+
+ <p>The user MAY be
+ prompted using the contact's current self-assigned nickname, or
+ something derived from the contact's (presumably self-assigned)
+ identifier, as a default, but these names chosen by the contact
+ SHOULD NOT be used without user approval.</p>
+
+ <tp:rationale>
+ <p>This is a generalization of
+ <a href="http://xmpp.org/extensions/xep-0165.html"
+ >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>)
+ to protocols other than XMPP. A reasonable user interface for
+ this, as used in many XMPP clients, is to have a text entry
+ for the alias adjacent to the text entry for the identifier
+ to add.</p>
+ </tp:rationale>
+
+ <p>For contacts with subscribe=Yes, this method has no effect.
+ It MUST return successfully if all contacts are in this state.</p>
+
+ <p>For contacts with subscribe=Ask, this method SHOULD send a new
+ request, with the given message, if allowed by the underlying
+ protocol.</p>
+
+ <p>For contacts with subscribe=No or subscribe=Rejected, this method
+ SHOULD request that the contact allows the local user to subscribe
+ to their presence; in general, this will change their publish
+ attribute to Ask (although it could change directly to Yes in some
+ situations).</p>
+
+ <p>Any state changes that immediately result from this request MUST
+ be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
+ before this method returns.</p>
+
+ <tp:rationale>
+ <p>This makes it easy for user interfaces to see what practical
+ effect this method had.</p>
+ </tp:rationale>
+
+ <p>If the remote contact accepts the request, their subscribe
+ attribute will later change from Ask to Yes.</p>
+
+ <p>If the remote contact explicitly rejects the request (in protocols
+ that allow this), their subscribe attribute will later change from
+ Ask to Rejected.</p>
+
+ <p>If the subscription request is cancelled by the local user, the
+ contact's subscribe attribute will change from Ask to No.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
+ If the <tp:member-ref>ContactListState</tp:member-ref> changes to
+ Failure, this method SHOULD raise the same error as
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to whom requests are to be sent.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An optional plain-text message from the user, to send to those
+ contacts with the subscription request. The
+ <tp:member-ref>RequestUsesMessage</tp:member-ref> property
+ indicates whether this message will be used or ignored.</p>
+
+ <p>Clients SHOULD NOT send a non-empty message without first giving
+ the user an opportunity to edit it.</p>
+
+ <tp:rationale>
+ <p>These messages are typically presented to the remote contact
+ as if the user had typed them, so as a minimum, the user should be
+ allowed to see what the UI will be saying on their behalf.</p>
+ </tp:rationale>
+
+ <p>Connections where this message is not useful MUST still allow it to
+ be non-empty.</p>
+ </tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotYet">
+ <tp:docstring>
+ The <tp:member-ref>ContactListState</tp:member-ref> is None
+ or Waiting.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action, because
+ <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="RequestUsesMessage" type="b" access="read"
+ tp:name-for-bindings="Request_Uses_Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, the Message parameter to
+ <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be
+ significant, and user interfaces SHOULD prompt the user for a
+ message to send with the request; a message such as "I would like
+ to add you to my contact list", translated into the local user's
+ language, might make a suitable default.</p>
+
+ <tp:rationale>
+ <p>This matches user expectations in XMPP and ICQ, for instance.</p>
+ </tp:rationale>
+
+ <p>If false, the parameter is ignored; user interfaces SHOULD avoid
+ prompting the user, and SHOULD pass an empty string to
+ RequestSubscription.</p>
+
+ <tp:rationale>
+ <p><em>FIXME: is there any such protocol?</em></p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="AuthorizePublication"
+ tp:name-for-bindings="Authorize_Publication">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For each of the given contacts, request that the local user's
+ presence is sent to that contact, i.e. that their publish attribute
+ becomes Yes.</p>
+
+ <p>Connection managers SHOULD NOT attempt to enforce a
+ mutual-subscription policy (i.e. when this method is called, they
+ should not automatically request that the contacts allow the user to
+ subscribe to their presence). User interfaces that require mutual
+ subscription MAY call
+ <tp:member-ref>RequestSubscription</tp:member-ref> at the same time
+ as this method.</p>
+
+ <tp:rationale>
+ <p>Whether to enforce mutual subscription is a matter of policy,
+ so it is left to the user interface and/or the server.</p>
+ </tp:rationale>
+
+ <p>For contacts with publish=Yes, this method has no effect; it
+ MUST return successfully if all contacts given have this state.</p>
+
+ <p>For contacts with publish=Ask, this method accepts the
+ contact's request to see the local user's presence, changing
+ their publish attribute from Ask to Yes.</p>
+
+ <p>For contacts with publish=No, if the protocol allows it, this
+ method allows the contacts to see the local user's presence even
+ though they have not requested it, changing their publish attribute
+ from No to Yes. Otherwise, it merely records the fact that
+ presence publication to those contacts is allowed; if any of
+ those contacts ask to receive the local user's presence
+ later in the lifetime of the connection, the connection SHOULD
+ immediately allow them to do so, changing their publish
+ attribute directly from No to Yes.</p>
+
+ <tp:rationale>
+ <p>This makes it easy to implement the common UI policy that if
+ the user attempts to subscribe to a contact's presence, requests
+ for reciprocal subscription are automatically approved.</p>
+ </tp:rationale>
+
+ <p>Any state changes that immediately result from this request MUST
+ be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
+ before this method returns.</p>
+
+ <tp:rationale>
+ <p>This makes it easy for user interfaces to see what practical
+ effect this method had.</p>
+ </tp:rationale>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
+ If the <tp:member-ref>ContactListState</tp:member-ref> changes to
+ Failure, this method SHOULD raise the same error as
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to authorize.</p>
+ </tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action, because
+ <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
+ <tp:docstring>
+ The <tp:member-ref>ContactListState</tp:member-ref> is None
+ or Waiting.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove the given contacts from the contact list entirely. It is
+ protocol-dependent whether this works, and under which
+ circumstances.</p>
+
+ <p>If possible, this method SHOULD set the contacts' subscribe and
+ publish attributes to No, remove any stored aliases for those
+ contacts, and remove the contacts from the result of
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+
+ <p>This method SHOULD succeed even if it was not possible to carry out
+ the request entirely or for all contacts (for instance, if there is an
+ outstanding request to subscribe to the contact's presence, and it's
+ not possible to cancel such requests). However, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns, so that clients can interpret the result.</p>
+
+ <tp:rationale>
+ <p>User interfaces removing a contact from the contact list are
+ unlikely to want spurious failure notifications resulting from
+ limitations of a particular protocol. However, emitting the
+ signals first means that if a client does want to check exactly
+ what happened, it can wait for the method to return (while
+ applying change-notification signals to its local cache of the
+ contact list's state), then consult its local cache of the
+ contact list's state to see whether the contact is still there.</p>
+ </tp:rationale>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
+ If the <tp:member-ref>ContactListState</tp:member-ref> changes to
+ Failure, this method SHOULD raise the same error as
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
+ <tp:docstring>
+ The <tp:member-ref>ContactListState</tp:member-ref> is None
+ or Waiting.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to set the given contacts' subscribe attribute to No,
+ i.e. stop receiving their presence.</p>
+
+ <p>For contacts with subscribe=Ask, this attempts to cancel
+ an earlier request to subscribe to the contact's presence; for
+ contacts with subscribe=Yes, this attempts to
+ unsubscribe from the contact's presence.</p>
+
+ <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
+ SHOULD succeed even if it was not possible to carry out the request
+ entirely or for all contacts; however, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
+ If the <tp:member-ref>ContactListState</tp:member-ref> changes to
+ Failure, this method SHOULD raise the same error as
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Unpublish" tp:name-for-bindings="Unpublish">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to set the given contacts' publish attribute to No,
+ i.e. stop sending presence to them.</p>
+
+ <p>For contacts with publish=Ask, this method explicitly rejects the
+ contact's request to subscribe to the user's presence; for
+ contacts with publish=Yes, this method attempts to prevent the
+ user's presence from being received by the contact.</p>
+
+ <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
+ SHOULD succeed even if it was not possible to carry out the request
+ entirely or for all contacts; however, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns.</p>
+
+ <p>This method SHOULD NOT be called until the
+ <tp:member-ref>ContactListState</tp:member-ref> changes to Success.
+ If the <tp:member-ref>ContactListState</tp:member-ref> changes to
+ Failure, this method SHOULD raise the same error as
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeContactList</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYet">
+ <tp:docstring>
+ The <tp:member-ref>ContactListState</tp:member-ref> is None
+ or Waiting.
+ </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_Contacts.xml b/spec/Connection_Interface_Contacts.xml
new file mode 100644
index 0000000..1020190
--- /dev/null
+++ b/spec/Connection_Interface_Contacts.xml
@@ -0,0 +1,191 @@
+<?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>
+ </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
+ <tp:member-ref>GetContactAttributes</tp:member-ref>, 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:name-for-bindings="Contact_Attribute_Interfaces">
+ <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:name-for-bindings="Get_Contact_Attributes">
+ <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>Connection managers SHOULD ignore interfaces requested which they
+ do not support (i.e. those not mentioned in the
+ <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>
+ property.)</p>
+
+ <tp:rationale>
+ <p>This simplifies client-side code. Clients which care may
+ distinguish between unsupported interfaces (e.g. this Connection
+ does not support Avatars), and interfaces on which no information
+ is known for these contacts (e.g. we don't know the avatar tokens
+ of any of the contacts, so we omitted them all) by inspecting
+ <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>.</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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">AliasesChanged</tp:dbus-ref>).</p>
+
+ <tp:rationale>
+ For instance, an XMPP connection manager could download vCards
+ in response to a request for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref>
+ attributes.
+ </tp:rationale>
+ </tp:docstring>
+ <tp:changed version="0.19.2">
+ requesting information for interfaces not mentioned in
+ <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> is no
+ longer an error. Be aware that older connection managers may still
+ consider this an error.
+ </tp:changed>
+ </arg>
+
+ <arg direction="in" name="Hold" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, all handles that appear as keys in the result have been
+ held on behalf of the calling process, as if by a call to
+ <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>.
+ (If <tp:dbus-ref namespace="ofdT.Connection"
+ >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the
+ case in all new connection managers, this has no effect.)</p>
+
+ <tp:rationale>
+ <p>For further round-trip avoidance.</p>
+ </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:possible-errors>
+ </method>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml
new file mode 100644
index 0000000..e5457b1
--- /dev/null
+++ b/spec/Connection_Interface_Forwarding.xml
@@ -0,0 +1,346 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Forwarding"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 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.Forwarding.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This connection interface is for protocols that are capable of
+ signaling to remote contacts that incoming communication channels
+ should be instead sent to a separate contact. This might apply to
+ things such as call forwarding, for example.</p>
+
+ <p>In some cases, a CM may register forwarding rules with an external
+ service; in those cases, it will never see the incoming channel, and
+ the forwarding will happen automatically.</p>
+
+ <p>In other cases, the CM will handle the forwarding itself. When an
+ incoming channel is detected, the status of the local user will
+ determine whether or not a forwarding rule is matched. For some
+ rules, this MAY happen immediately (ie, if the user is Busy); for
+ others, there MAY be a timeout (in seconds) that must expire
+ before the forwarding rule is matched (the timeout is specified
+ by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p>
+
+ <p>Once a forwarding rule is matched and any necessary timeouts have
+ expired, the CM can forward the incoming channel to the specified
+ handle. If for whatever reason the remote handle does not accept
+ the channel AND the CM supports multiple forwarding entries AND
+ any necessary timeouts have expired (specified by the next entry
+ in the list), the CM can forward the incoming channel to the next
+ handle in the entry list. This continues until the list is
+ exhausted, or the incoming channel is accepted.</p>
+
+ <p>Note that the rule matches are only for the first entry in the
+ in the forwarding rule list. Once the incoming channel has been
+ forwarded, the next entry in the list (assuming one exists and
+ the contact that the channel has been forwarded to does not respond
+ after any necessary timeouts) is used regardless of the status of
+ the forwarded channel. The initial match rule might have been
+ Busy, whereas the contact that the channel has been forwarded to
+ might be offline. Even in this case, the Busy list is still
+ traversed until the channel is handled (or there are no more
+ forwarding entries in the list).</p>
+
+ <p>For example, assuming the following dict for Forwarding_Rules:</p>
+ <pre>
+ ForwardingRules = {
+ Busy: ( initial-timeout: 30, [
+ (handle: 3, timeout: 15),
+ (handle: 5, timeout: 20)
+ ]),
+ NoReply: ( initial-timeout: 15, [
+ (handle: 5, timeout: 30),
+ (handle: 3, timeout: 20)
+ ])
+ }</pre>
+
+ <p>We can imagine a scenario where an incoming channel is detected,
+ the media stream is available (ie, not Busy),
+ and the local user is online. While the CM is waiting for the local user to
+ accept the channel, it looks at NoReply's first timeout value. After 15s if
+ the local user hasn't accepted, the CM forwards the channel to Handle #5. The
+ CM then waits 30s for Handle #5 to accept the channel. If after 30s it does
+ not, the CM forwards the incoming channel to Handle #3, which will have
+ 20s to accept the channel.</p>
+
+ <p>When an unanswered <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> call is
+ forwarded, both the contact and the self handle should be removed from
+ the group with the self handle as the actor, and
+ <tp:type>Channel_Group_Change_Reason</tp:type> <code>No_Answer</code> or
+ <code>Busy</code>, as appropriate. For <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels, the
+ <tp:type>Call_State_Change_Reason</tp:type> <code>Forwarded</code>
+ should be used.</p>
+ </tp:docstring>
+
+ <tp:enum name="Forwarding_Condition" type="u">
+ <tp:docstring>
+ The various forwarding conditions that are supported by this interface.
+ In general, the conditions should not overlap; it should be very clear
+ which rule would be chosen given a CM's behavior with an incoming
+ channel. The exception to this is Unconditional,
+ which will override all other rules.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="Unconditional">
+ <tp:docstring>
+ Incoming channels should always be forwarded. Note that setting this
+ will override any other rules. If not set, other rules will
+ be checked when an incoming communication channel is detected.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Busy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The incoming channel should be forwarded if a busy signal is
+ detected. What defines "Busy" is CM-specific (perhaps a single
+ resource is already in use, or a user's status is set to Busy
+ <tp:type>Connection_Presence_Type</tp:type>).</p>
+
+ <p>If initial timeout is specified for Busy condition and call
+ waiting is not supported by the service, the timeout will be
+ ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="No_Reply">
+ <tp:docstring>
+ The incoming channel should be forwarded if the local user doesn't
+ accept it within the specified amount of time.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="3" suffix="Not_Reachable">
+ <tp:docstring>
+ The incoming channel should be forwarded if the user is offline.
+ This could be a manual setting (the user has chosen to set their
+ presence to offline or invisible) or something specified by the
+ underlying network (the user is not within range of a cell tower).
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Forwarding_Rule_Entry"
+ array-name="Forwarding_Rule_Entry_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A forwarding rule entry. These MAY be chained together
+ for CMs that support chaining of forwards (in other words,
+ a forwarding rule may have multiple entries; if the contact
+ in the first entry doesn't respond, the incoming channel
+ might be forwarded to the contact in the second entry).</p>
+
+ <p>For CMs and protocols that don't support chaining of
+ entries, only the first entry would be used.</p>
+ </tp:docstring>
+
+ <tp:member type="u" name="Timeout">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The length of time (in seconds) to wait the contact to respond
+ to the forwarded channel. This MAY be ignored by the CM if it
+ isn't supported by the underlying network/protocol for the
+ specific status of the remote contact (for example, a GSM call
+ that is forwarded may return Not_Reachable immediately without
+ waiting for the timeout value to expire).</p>
+
+ <p>A value of 0 means the condition can match immediately. A
+ value of MAX_UINT32 means that the CM's default should be
+ used.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle">
+ <tp:docstring>
+ The contact to forward an incoming channel to. If the handle
+ doesn't point to anything (e.g. points to a phone number that
+ doesn't exist), the entry SHOULD be skipped.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Forwarding_Rule_Chain">
+ <tp:docstring>
+ A chain of forwarding rules and an initial timeout after which
+ the rules are applied.
+ </tp:docstring>
+
+ <tp:member type="u" name="InitialTimeout">
+ <tp:docstring>Initial timeout for the rule.</tp:docstring>
+ </tp:member>
+
+ <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>The forwarding targets (an array of type
+ <tp:type>Forwarding_Rule_Entry</tp:type>).
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Forwarding_Rule_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are forwarding conditions and
+ whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs.
+ </tp:docstring>
+
+ <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
+ <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain"
+ name="Rule_Chain" />
+ </tp:mapping>
+
+ <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are forwarding conditions and
+ whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
+ for the condition.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
+ <tp:member type="u" name="Chain_Length" />
+ </tp:mapping>
+
+ <property name="SupportedForwardingConditions" type="a{uu}" access="read"
+ tp:type="Supported_Forwarding_Conditions_Map"
+ tp:name-for-bindings="Supported_Forwarding_Conditions">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map of forwarding conditions supported on this connection to
+ maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
+ supported for the specific condition.</p>
+
+ <tp:rationale>
+ <p>When forwarding is done by the provider, different providers
+ might support different chain sizes, or provider and local
+ implementation chain sizes might differ.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ForwardingRules" type="a{u(ua(uu))}" access="read"
+ tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The current forwarding rules that are enabled for this connection.
+ Forwarding rules each contain an array of type
+ <tp:type>Forwarding_Rule_Entry</tp:type>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ForwardingRuleChanged"
+ tp:name-for-bindings="Forwarding_Rule_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p>
+
+ <p>By the time this is emitted, the property MUST have been updated
+ with the new rules being active. If any protocol/network
+ requests must be made, they should be completed before the signal
+ is emitted.</p>
+ </tp:docstring>
+
+ <arg name="Condition" type="u" tp:type="Forwarding_Condition">
+ <tp:docstring>
+ The condition of the forwarding rule that's been changed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Timeout" type="u">
+ <tp:docstring>
+ The new initial timeout for the rule.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>
+ The new (and as of the emission of the signal, currently active)
+ forwards. The order is relevant; those at the lowest array index
+ are used first.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule">
+ <tp:docstring>
+ Update the forwarding rules.
+ </tp:docstring>
+
+ <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The forwarding rule to override. Note that this SHOULD not affect
+ other rules; setting a rule that overrides others (such as
+ Forwarding_Rule_Unconditional) will not modify other rules. This
+ means that when a client sets Forwarding_Rule_Busy and then
+ temporarily sets Forwarding_Rule_Unconditional, the
+ Forwarding_Rule_Busy rule will retain settings after
+ Forwarding_Rule_Unconditional, has been unset.</p>
+
+ <p>If the CM has no choice but to adjust multiple rules after a call
+ to this function (ie, due to the network or protocol forcing such
+ behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref>
+ signals for each changed rule. The order of the signals is
+ implementation-dependent, with the only requirement that the
+ last signal is for the rule that was originally requested to have
+ been changed (e.g. if Unconditional automatically modifies
+ Busy and NoReply, three
+ separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the
+ last signal being for Forwarding_Rule_Unconditional).</p>
+
+ <p>Each forwarding condition will occur no more than once in
+ the rule array. Setting a rule will overwrite the old rule
+ with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>
+ The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to
+ activate for the rule. An empty array will effectively disable the
+ rule.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>
+ The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>).
+ This is the list of entries that is being replaced with the call to
+ <tp:member-ref>SetForwardingRule</tp:member-ref>.
+ </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.NotAvailable">
+ <tp:docstring>
+ The specified Condition is not supported by this connection,
+ or the number of chained
+ <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should
+ be checked prior to calling
+ <tp:member-ref>SetForwardingRule</tp:member-ref>.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ A Handle that has been supplied is invalid.
+ </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_Keepalive.xml b/spec/Connection_Interface_Keepalive.xml
new file mode 100644
index 0000000..9f4ac68
--- /dev/null
+++ b/spec/Connection_Interface_Keepalive.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Keepalive"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ 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.Keepalive.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.21.2">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Most messaging protocols allow the client to send periodic
+ content-less pings to the server when the connection is otherwise idle,
+ to reassure both itself and the server that its connection is still
+ alive. Depending on the nature of the network connection, and the
+ device running the client, the desired interval between such pings may
+ vary.</p>
+
+ <tp:rationale>
+ <p>For instance, on a mobile handset connected via 3G,
+ overly-frequent keepalives can drain the battery through needlessly
+ waking up the radio, and a relatively high interval is appropiate. By
+ contrast, a desktop computer is less likely to be asleep in the first
+ place, and users expect dropped connections to be noticed as soon as
+ possible.</p>
+ </tp:rationale>
+
+ <p>This interface provides a
+ <tp:member-ref>KeepaliveInterval</tp:member-ref> property which
+ controls the frequency of keepalive pings, if any. Connection managers
+ implementing this property should also include it in <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy'>Protocol.Parameters</tp:dbus-ref>
+ with the <code>DBus_Property</code> flag, allowing the desired value to
+ be stored in <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy'>Account.Parameters</tp:dbus-ref>
+ and passed onto the connection by the account manager.</p>
+ </tp:docstring>
+
+ <property name="KeepaliveInterval" type="u" access="readwrite"
+ tp:name-for-bindings="Keepalive_Interval"
+ tp:is-connection-parameter='och aye'>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time in seconds between pings sent to the server to ensure that
+ the connection is still alive, or <tt>0</tt> to disable such
+ pings.</p>
+
+ <p>This property (and parameter) supersedes the older
+ <tt>keepalive-interval</tt>
+ <tp:type>Connection_Parameter_Name</tp:type>.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
new file mode 100644
index 0000000..fe54923
--- /dev/null
+++ b/spec/Connection_Interface_Location.xml
@@ -0,0 +1,464 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Location"
+ 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.Connection.Interface.Location">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface on connections to support protocols which allow users to
+ publish their current geographical location, and subscribe to the
+ current location of their contacts.</p>
+
+ <p>This interface is geared strongly towards automatic propagation and
+ use of this information, so focuses on latitude, longitude and
+ altitude which can be determined by GPS, although provision is also
+ included for an optional human-readable description of locations. All
+ co-ordinate information is required to be relative to the WGS84
+ datum.</p>
+
+ <p>The information published through this interface is intended to have
+ the same scope as presence information, so will normally be made
+ available to those individuals on the user's "publish" contact list.
+ Even so, user interfaces should not automatically publish location
+ information without the consent of the user, and it is recommended
+ that an option is made available to reduce the accuracy of the
+ reported information to allow the user to maintain their privacy.</p>
+
+ <p>Location information is represented using the terminology of XMPP's
+ <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a>
+ or the XEP-0080-derived
+ <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where
+ possible.</p>
+
+ <p>Clients of this interface SHOULD register an interest in it by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.AddClientInterest</tp:dbus-ref> with an argument
+ containing the name of this interface,
+ before calling any Location method. If they do so, they SHOULD also call
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.RemoveClientInterest</tp:dbus-ref> after use to allow
+ the CM to release resources associated with this interface.</p>
+ </tp:docstring>
+
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
+ <tp:enum name="Location_Accuracy_Level" type="i">
+ <tp:docstring>
+ A location accuracy level. This should be kept in sync with
+ GeoclueAccuracyLevel in the Geoclue project.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ The accuracy is unspecified.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Country" value="1">
+ <tp:docstring>
+ The location indicates the contact's country.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Region" value="2">
+ <tp:docstring>
+ The location indicates the contact's region within a country.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Locality" value="3">
+ <tp:docstring>
+ The location indicates the contact's locality within a region
+ (e.g. the correct city).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Postal_Code" value="4">
+ <tp:docstring>
+ The location indicates the correct postal code.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Street" value="5">
+ <tp:docstring>
+ The location indicates the correct street.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Detailed" value="6">
+ <tp:docstring>
+ The location's accuracy is given by the accuracy key.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ -->
+
+ <tp:mapping name="Location">
+ <tp:docstring>
+ A user's location, represented as an extensible mapping.
+ </tp:docstring>
+
+ <tp:member name="Key" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+
+ <p>Civic addresses are represented by the following well-known
+ keys (all of which have string values), which should be kept in
+ sync with those used in XEP-0080 and in the Geoclue project:</p>
+
+ <ul>
+ <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country
+ code, e.g. "us", "gb", "fr"</li>
+ <li>country - s: a country name in unspecified locale, e.g.
+ "USA"</li>
+ <li>region - s: an administrative region of the nation, such as a
+ state or province</li>
+ <li>locality - s: a locality within the administrative region, such
+ as a town or city</li>
+ <li>area - s: a named area such as a campus or neighborhood</li>
+ <li>postalcode - s: a code used for postal delivery</li>
+ <li>street - s: a thoroughfare within the locality, or a crossing of
+ two thoroughfares</li>
+ </ul>
+
+ <p>The following address keys are defined in XEP-0080 but not by
+ Geoclue, and are also allowed:</p>
+
+ <ul>
+ <li>building - s: a specific building on a street or in an area</li>
+ <li>floor - s: a particular floor in a building</li>
+ <li>room - s: a particular room in a building</li>
+ <li>text - s: any more specific information, e.g.
+ "Northwest corner of the lobby"</li>
+ <li>description - s: A natural-language name for or description of
+ the location, e.g. "Bill's house"</li>
+ <li>uri - s: a URI representing the location or pointing to more
+ information about it</li>
+ </ul>
+
+ <p>Since the previous strings have data intended to be read by users,
+ the language used should be stated using:</p>
+
+ <ul>
+ <li>language - s: a specific language or locale of location
+ information in a format compatible to RFC 4646. Note that UTF-8
+ is the only allowed encoding, e.g. "en" or "fr-CA".</li>
+ </ul>
+
+ <p>Positions are represented by the following well-known keys:</p>
+
+ <ul>
+ <li>lat - d: latitude in decimal degrees north, -90 to +90,
+ relative to the WGS-84 datum
+ <tp:rationale>
+ This is from XEP-0080; the XEP allows use of a different
+ datum, but recommends this one. We enforce sanity by requiring
+ a consistent datum: a minimal compliant implementation of this
+ specification in terms of XEP-0080 would simply ignore the
+ &lt;lat&gt; and &lt;lon&gt; elements if &lt;datum&gt; exists
+ and has a value other than WGS-84, while an advanced
+ implementation might correct for the different datum.
+ </tp:rationale>
+ </li>
+ <li>lon - d: Longitude in decimal degrees east, -180 to +180,
+ relative to the WGS-84 datum
+ <tp:rationale>
+ Same rationale as 'lat'
+ </tp:rationale>
+ </li>
+ <li>alt - d: altitude in metres above sea level (negative
+ if below sea level)
+ <tp:rationale>
+ This is from XEP-0080
+ </tp:rationale>
+ </li>
+
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
+ <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>):
+ an indication of accuracy, which SHOULD be omitted if it would be
+ Location_Accuracy_Level_None or
+ Location_Accuracy_Level_Detailed
+ <tp:rationale>
+ This is a struct field in GeoClue; the name is new in this
+ specification, and was chosen in an attempt to avoid clashing
+ with any future XEP-0080 terminology.
+ </tp:rationale>
+ </li>
+ -->
+
+ <li>accuracy - d: horizontal position error in metres if
+ known
+ <tp:rationale>
+ This is from XEP-0080
+ </tp:rationale>
+ </li>
+ </ul>
+
+ <p>Velocities are represented by the following well-known keys:</p>
+
+ <ul>
+ <li>speed - d: speed in metres per second
+ <tp:rationale>
+ This is from XEP-0080
+ </tp:rationale>
+ </li>
+ <li>bearing - d: direction of movement in decimal degrees,
+ where North is 0 and East is 90
+ <tp:rationale>
+ This is from XEP-0080, and is equivalent to the struct field
+ called "direction" in GeoClue
+ </tp:rationale>
+ </li>
+ </ul>
+
+ <p>Other well-known keys:</p>
+
+ <ul>
+ <li>timestamp - x (<tp:type>Unix_Timestamp64</tp:type>): the time
+ that the contact was at this location, in seconds since
+ 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC)
+ <tp:rationale>
+ XEP-0080 uses an ISO 8601 string for this, but a number of
+ seconds since the epoch is probably easier to work with.
+ </tp:rationale>
+ </li>
+ </ul>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Value" type="v">
+ <tp:docstring>
+ The value corresponding to the well-known key.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:mapping name="Contact_Locations" type="a{ua{sv}}">
+ <tp:docstring>
+ A map from contacts to their locations.
+ </tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact</tp:docstring>
+ </tp:member>
+ <tp:member name="Location" type="a{sv}" tp:type="Location">
+ <tp:docstring>The contact's location, which MAY be empty to indicate
+ that the contact's location is unknown</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="GetLocations" tp:name-for-bindings="Get_Locations">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Return the current locations of the given contacts, if they are
+ already known. If any of the given contacts' locations are not known,
+ request their current locations, but return immediately without waiting
+ for a reply; if a reply with a non-empty location is later received
+ for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref>
+ signal will be emitted for them.</p>
+
+ <tp:rationale>
+ <p>This method is appropriate for "lazy" location finding, for instance
+ displaying the location (if available) of everyone in your contact
+ list.</p>
+ </tp:rationale>
+
+ <p>For backwards compatibility, if this method is called by a client
+ whose "interest count" for this interface, as defined by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.AddClientInterest</tp:dbus-ref>, is zero, the
+ Connection SHOULD behave as if AddClientInterest had been called for
+ this interface just before that method call. Clients that do not
+ explicitly call AddClientInterest SHOULD NOT call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.RemoveClientInterest</tp:dbus-ref> either.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The contacts whose locations should be returned or signalled.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Locations" type="a{ua{sv}}"
+ tp:type="Contact_Locations">
+ <tp:docstring>
+ The contacts' locations, if already known. Contacts whose locations
+ are not already known are omitted from the mapping; contacts known
+ to have no location information appear in the mapping with an empty
+ Location dictionary.
+ </tp:docstring>
+ </arg>
+
+ <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="RequestLocation" tp:name-for-bindings="Request_Location">
+ <tp:docstring>
+ Return the current location of the given contact. If necessary, make
+ a request to the server for up-to-date information, and wait for a
+ reply.
+
+ <tp:rationale>
+ This method is appropriate for use in a "Contact Information..."
+ dialog; it can be used to show progress information (while waiting
+ for the method to return), and can distinguish between various error
+ conditions.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact whose location should be returned.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Location" type="a{sv}" tp:type="Location">
+ <tp:docstring>
+ The contact's location. It MAY be empty, indicating that no location
+ information was found.
+ </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.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
+ <tp:docstring>
+ The requested contact does not allow the local user to see their
+ location information.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated">
+ <tp:docstring>
+ Emitted when a contact's location changes or becomes known.
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact
+ </tp:docstring>
+ </arg>
+ <arg name="Location" type="a{sv}" tp:type="Location">
+ <tp:docstring>
+ The contact's location, or empty to indicate that nothing is known
+ about the contact's location.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetLocation" tp:name-for-bindings="Set_Location">
+ <tp:docstring>
+ Set the local user's own location.
+ </tp:docstring>
+
+ <arg direction="in" name="Location" type="a{sv}">
+ <tp:docstring>
+ The location to advertise. If the user wants to obscure their
+ exact location by reducing the precision or accuracy, clients
+ MUST do this themselves, rather than relying on the connection
+ manager to do so. Clients that interact with more than one
+ connection SHOULD advertise the same reduced-accuracy location
+ to all of them, so that contacts cannot obtain an undesirably
+ accurate location by assuming that random errors have been added
+ and averaging the locations advertised on multiple connections.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The user's server does not support publishing their own location.
+ If it is possible to determine this ahead of time, the
+ <code>Can_Set</code> flag will not be set in
+ <tp:member-ref>SupportedLocationFeatures</tp:member-ref>.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="LocationAccessControlTypes" type="au" access="read"
+ tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types">
+ <tp:docstring>The types of access control that are supported by this
+ connection.</tp:docstring>
+ </property>
+
+ <property name="LocationAccessControl" type="(uv)" access="readwrite"
+ tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control">
+ <tp:docstring>The current access control mechanism and settings
+ for this connection. Before publishing location for the first time,
+ if this has not been set by a client, implementations SHOULD
+ set it to be as restrictive as possible (an empty whitelist, if
+ supported).</tp:docstring>
+ </property>
+
+ <property name="SupportedLocationFeatures"
+ tp:name-for-bindings="Supported_Location_Features"
+ type="u" tp:type="Location_Features" access="read">
+ <tp:added version="0.19.6"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Indicates the Location features supported by this connection. This
+ property MAY be undefined before <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref>
+ becomes <code>Connected</code>, but MUST remain constant thereafter.
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature">
+ <tp:flag suffix="Can_Set" value="1">
+ <tp:docstring>
+ Indicates that setting your own location with
+ <tp:member-ref>SetLocation</tp:member-ref> is supported on this
+ connection.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Flags describing the Location features which may be supported on any
+ given connection.
+ </tp:docstring>
+ </tp:flags>
+
+ <tp:contact-attribute name="location"
+ type="a{sv}" tp:type="Location">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same mapping that would be returned by
+ <tp:member-ref>GetLocations</tp:member-ref> for this contact.
+ Omitted from the result if the contact's location
+ is not known.</p>
+
+ <p>For backwards compatibility, if contact attributes that include
+ this interface are requested
+ by a client whose "interest count" for this interface, as defined by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.AddClientInterest</tp:dbus-ref>, is zero, the
+ Connection SHOULD behave as if AddClientInterest was called for this
+ interface just before that request. Clients that do not explicitly
+ call AddClientInterest SHOULD NOT call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.RemoveClientInterest</tp:dbus-ref> either.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
new file mode 100644
index 0000000..395e101
--- /dev/null
+++ b/spec/Connection_Interface_Mail_Notification.xml
@@ -0,0 +1,624 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Mail_Notification"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ >
+ <tp:copyright> Copyright (C) 2007 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
+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
+Library 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.MailNotification">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.21.3">(as stable API)</tp:added>
+
+ <tp:client-interest>
+ <tp:docstring>
+ A client MUST notify interest in this feature before it will be
+ enabled.
+ </tp:docstring>
+ </tp:client-interest>
+
+ <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" >
+ <tp:flag suffix="Supports_Unread_Mail_Count" value="1">
+ <tp:docstring>
+ This Connection provides the number of unread e-mails (or e-mail
+ threads) in the main folder of your e-mail account, as the
+ <tp:member-ref>UnreadMailCount</tp:member-ref> property. The
+ connection manager will update this value by emitting the
+ <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Supports_Unread_Mails" value="2">
+ <tp:docstring>
+ This Connection provides a detailed list of unread e-mails, as the
+ <tp:member-ref>UnreadMails</tp:member-ref> property. If this flag
+ is set, <tt>Supports_Unread_Mail_Count</tt> MUST be set, and
+ <tt>Emits_Mails_Received</tt> MUST NOT be set.
+ The Connection will update the list by emitting the
+ <tp:member-ref>UnreadMailsChanged</tp:member-ref> signals.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Emits_Mails_Received" value="4">
+ <tp:docstring>
+ This Connection emits the <tp:member-ref>MailsReceived</tp:member-ref>
+ signal, which provides details about newly arrived e-mails but does
+ not maintain their read/unread status afterwards. This flag MUST NOT
+ be combined with <tt>Supports_Unread_Mails</tt>.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Supports_Request_Inbox_URL" value="8">
+ <tp:docstring>
+ This Connection can provide a URL (with optional POST data) to
+ open the the inbox of the e-mail account in a web-based client, via
+ the <tp:member-ref>RequestInboxURL</tp:member-ref> method.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Supports_Request_Mail_URL" value="16">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This Connection can provide a URL (with optional POST data) to open
+ a specific mail in a web-based client, via the
+ <tp:member-ref>RequestMailURL</tp:member-ref> method. This feature
+ is not useful unless either Emits_Mails_Received or
+ Supports_Unread_Mails is set.</p>
+
+ <p>If this flag is not set, clients SHOULD fall back to using
+ <tp:member-ref>RequestInboxURL</tp:member-ref> if available.</p>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Thread_Based" value="32">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Each <tp:type>Mail</tp:type> represents a thread of e-mails, which
+ MAY have more than one sender.</p>
+
+ <tp:rationale>
+ <p>Google Talk notifies users about new mail in terms of unread
+ threads, rather than unread e-mails.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:docstring>
+ <p>Flags representing capabilities provided by a connection manager.
+ Those values can be used as bitfield. Some flags depend on, or
+ conflict with, each other.</p>
+
+ <p>Connections SHOULD implement as many of these features as the
+ underlying protocol allows, preferring to implement
+ Supports_Unread_Mails instead of Emits_Mails_Received if both are
+ possible.</p>
+ </tp:docstring>
+ </tp:flags>
+
+ <tp:enum name="HTTP_Method" type="u">
+ <tp:enumvalue suffix="Get" value="0">
+ <tp:docstring>
+ Use the GET method when opening the URL.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Post" value="1">
+ <tp:docstring>
+ Use the POST method when opening the URL. Refer to
+ <tp:type>HTTP_Post_Data</tp:type> for more details.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:docstring>
+ The HTTP Method with which to request a URL.
+ </tp:docstring>
+ </tp:enum>
+
+ <tp:struct name="HTTP_Post_Data" array-name="HTTP_Post_Data_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A pair (key, value) representing POST data compatible with the
+ application/x-www-form-urlencoded MIME type. The strings MUST be
+ valid UTF-8 strings, and the characters used in the key MUST obey
+ the requirements of the
+ <a href="http://www.w3.org/TR/html401/types.html#type-cdata">
+ HTML CDATA type</a>. The value MUST NOT be
+ encoded with HTML entities.</p>
+
+ <p>For example, if the POST data should contain a key "less-than" with value
+ "&lt;", and a key "percent" with value "%", this should be represented as
+ two HTTP_Post_Data structures, ("less-than", "&lt;") and ("percent", "%"),
+ resulting in a POST request whose request body is "less-than=&amp;lt;&amp;percent=%25".
+ If a client passes this to a browser by writing it into an HTML form, it
+ could do so by representing it as:</p>
+
+ <pre>
+ &lt;input type="hidden" name="less-than"&gt;&amp;lt;&lt;/input&gt;
+ &lt;input type="hidden" name="percent"&gt;%&lt;/input&gt;
+ </pre>
+
+ <tp:rationale>
+ <p>This data can be used to generate a HTML file that will
+ automatically load the URL with appropriate POST data, in which case
+ the client MUST convert any characters that are special within HTML
+ into HTML entities. Alternatively, it can be used in an API that will
+ instruct the browser how to load the URL (like the Netscape Plug-in
+ API), in which case the client MUST escape
+ <a href="http://www.ietf.org/rfc/rfc1738.txt">characters that are
+ reserved in URLs</a>, if appropriate for that API.</p>
+
+ <p>An array of pairs is used instead of a map from keys to values,
+ because it's valid to repeat keys in both HTML and
+ x-www-form-urlencoded data.</p>
+ </tp:rationale>
+ </tp:docstring>
+ <tp:member type="s" name="Key">
+ <tp:docstring>The key, corresponding to a HTML control
+ name</tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Value">
+ <tp:docstring>The value</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Mail_Address" array-name="Mail_Address_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A pair (name, address) representing an e-mail address,
+ such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At
+ least one of name and address MUST be provided. A missing element will
+ be represented by the empty string.</p>
+ <tp:rationale>
+ <p>The CM should provide as much information as possible, but not all
+ protocols provide both the displayed name and the address. (If a
+ protocol doesn't provide either, it should omit the appropriate
+ field from the <tp:type>Mail</tp:type> entirely.)</p>
+ </tp:rationale>
+ </tp:docstring>
+ <tp:member type="s" name="Name">
+ <tp:docstring>The displayed name corresponding to the e-mail
+ address</tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Address">
+ <tp:docstring>The actual e-mail address</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Mail_URL">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A structure containing the required information to open a web-based
+ e-mail UI, without needing re-authentication (if possible).</p>
+
+ <p>Because the URL and POST data frequently contain short-lived
+ credential tokens, a new URL should be requested (by calling one of
+ the methods that returns a Mail_URL) for each visit to the web-based
+ UI, and the URL should be visited soon after it is returned.</p>
+ </tp:docstring>
+ <tp:member type="s" name="URL">
+ <tp:docstring>
+ The URL to which to send a request.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Method" tp:type="HTTP_Method">
+ <tp:docstring>
+ The HTTP method of the request.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="a(ss)" name="Post_Data" tp:type="HTTP_Post_Data[]">
+ <tp:docstring>
+ An array of name-value pairs containing the POST data to use when
+ opening the URL. This MUST be an empty array if the Method is not
+ POST.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Mail" array-name="Mail_List">
+ <tp:docstring>
+ An extensible map representing a mail, or (on protocols where
+ <tt>Thread_Based</tt> appears in
+ <tp:member-ref>MailNotificationFlags</tp:member-ref>) a thread of
+ mails. All keys are optional where not otherwise stated; however, at
+ least one of "senders" and "subject" must be included.
+ </tp:docstring>
+
+ <tp:member type="s" name="Key">
+ <tp:docstring>
+ <p>A key providing information about the mail or thread. Well-known
+ keys are as follows:</p>
+
+ <dl>
+ <dt>id &#8212; s</dt>
+ <dd>
+ <p>A unique ID for this e-mail. CMs with
+ <tt>Supports_Unread_Mails</tt> set in
+ <tp:member-ref>MailNotificationFlags</tp:member-ref> MUST provide
+ this key in each <tp:type>Mail</tp:type>.</p>
+
+ <p>If provided, the ID SHOULD be unique to a Mail at least until
+ that mail is removed with the
+ <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal
+ (in protocols with <tt>Supports_Unread_Emails</tt>), or
+ unique for the duration of a session (otherwise).</p>
+
+ <tp:rationale>
+ <p>In protocols with Supports_Unread_Mails, this key is used to
+ indicate which mail was removed. In protocols without that
+ feature, it's impossible to tell when a mail has been removed
+ (and hence how long the identifier will remain valid for use
+ with <tp:member-ref>RequestMailURL</tp:member-ref>).</p>
+ </tp:rationale>
+ </dd>
+
+ <dt>url-data &#8212; any type</dt>
+ <dd>An opaque identifier (typically a string or list of strings)
+ provided to the Connection when calling
+ <tp:member-ref>RequestMailURL</tp:member-ref>,
+ containing information used by the Connection to build the URL.
+ </dd>
+
+ <dt>senders &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+ <dd>
+ An array of sender display name and e-mail address pairs. Note that
+ only e-mails represented as a thread can have multiple senders.
+ </dd>
+
+ <dt>to-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+ <dd>
+ An array of display name and e-mail address pairs representing
+ the recipients.
+ </dd>
+
+ <dt>cc-addresses &#8212; a(ss) (<tp:type>Mail_Address</tp:type>)</dt>
+ <dd>
+ An array of display name and e-mail address pairs representing
+ the carbon-copy recipients.
+ </dd>
+
+ <dt>sent-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+ <dd>A UNIX timestamp indicating when the message was sent, or for
+ a thread, when the most recent message was sent.
+ </dd>
+
+ <dt>received-timestamp &#8212; x (<tp:type>Unix_Timestamp64</tp:type>)</dt>
+ <dd>A UNIX timestamp indicating when the message was received, or for
+ a thread, when the most recent message was received.
+ </dd>
+
+ <dt>has-attachments &#8212; b</dt>
+ <dd>If true, this mail has attachments.</dd>
+
+ <dt>subject &#8212; s</dt>
+ <dd>
+ The subject of the message. This MUST be encoded in UTF-8.
+ </dd>
+
+ <dt>content-type &#8212; s</dt>
+ <dd>
+ <p>The MIME type of the message content. Two types are currently
+ supported: "text/plain" for plain text, and "text/html" for a
+ HTML document. If omitted, "text/plain" MUST be assumed.
+ Regardless of MIME type, the content MUST be valid UTF-8 (which
+ may require that the Connection transcodes it from a legacy
+ encoding).</p>
+
+ <tp:rationale>
+ <p>All strings on D-Bus must be UTF-8.</p>
+ </tp:rationale>
+ </dd>
+
+ <dt>truncated &#8212; b</dt>
+ <dd>
+ If true, the content is only a partial message; if false or
+ omitted, the content is the entire message.
+ </dd>
+
+ <dt>content &#8212; s</dt>
+ <dd>
+ The body of the message, possibly truncated, encoded as appropriate
+ for "content-type".
+ </dd>
+
+ <dt>folder &#8212; s</dt>
+ <dd>
+ The name of the folder containing this e-mails.
+ If omitted, the inbox SHOULD be assumed.
+ </dd>
+ </dl>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Value" type="v">
+ <tp:docstring>The value, of whatever type is appropriate for the
+ key.</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="MailNotificationFlags" type="u" access="read"
+ tp:type="Mail_Notification_Flags"
+ tp:name-for-bindings="Mail_Notification_Flags">
+ <tp:docstring>
+ Integer representing the bitwise-OR of supported features for e-mails
+ notification on this server. This property MUST NOT change after the
+ Connection becomes CONNECTED.
+
+ <tp:rationale>
+ This property indicates the behavior and availability
+ of the other properties and signals within this interface. A
+ connection manager that cannot at least set one of the flags
+ in the <tp:type>Mail_Notification_Flags</tp:type>
+ SHOULD NOT provide this interface.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="UnreadMailCount" type="u" access="read"
+ tp:name-for-bindings="Unread_Mail_Count">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The number of unread messages in the Inbox. Change notification is
+ via <tp:member-ref>UnreadMailsChanged</tp:member-ref>.</p>
+
+ <p>This property is only useful if <tt>Supports_Unread_Mail_Count</tt>
+ is set in the <tp:member-ref>MailNotificationFlags</tp:member-ref>;
+ otherwise, it MUST be zero.</p>
+
+ <p>If <tt>Thread_Based</tt> appears in the
+ <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property
+ counts the number of threads, not the number of mails.</p>
+
+ <p>Note that this count MAY be bigger than the number of items in
+ <tp:member-ref>UnreadMails</tp:member-ref>. See
+ <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]"
+ tp:name-for-bindings="Unread_Mails" access="read">
+ <tp:docstring>
+ <p>An array of unread <tp:type>Mail</tp:type>s. Change notification is
+ via <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property
+ is only useful if <tt>Supports_Unread_Mails</tt> is set in
+ <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it
+ MUST be an empty list.</p>
+ <p>The array size MAY be shorter than
+ <tp:member-ref>UnreadMailCount</tp:member-ref>.</p>
+ <tp:rationale>
+ <p>Some servers may limits the amount of detailed e-mails sent. This
+ can significantly reduce the network traffic for large inbox. For
+ this reason, it is normal that
+ <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal
+ to the size of this array.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="MailAddress" type="s"
+ tp:name-for-bindings="Mail_Address" access="read">
+ <tp:docstring>
+ A string representing the e-mail address of the account. The CMs MUST
+ provide this information.
+ <tp:rationale>
+ In close integration of MailNotification with other e-mail services,
+ the e-mail address can be used has a unique identifier for the
+ account. Possible integration could be between Telepathy and
+ Evolution where the e-mail address is the common information in
+ both interfaces.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="MailsReceived" tp:name-for-bindings="Mails_Received">
+ <arg name="Mails" type="aa{sv}" tp:type="Mail[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of <tp:type>Mail</tp:type>s. Those e-mail MUST NOT have
+ the "id" key.</p>
+
+ <tp:rationale>
+ <p>On connections that emit this signal, it's impossible to tell
+ when a mail has been removed, and hence when "id" has become
+ invalid.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Emitted when new e-mails messages arrive to the inbox associated with
+ this connection. This signal is used for protocols that are not able
+ to maintain the <tp:member-ref>UnreadMails</tp:member-ref> list, but
+ do provide real-time notification about newly arrived e-mails. It MUST
+ NOT be emitted unless <tt>Emits_Mails_Received</tt> is set in
+ <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+ </tp:docstring>
+ </signal>
+
+ <signal name="UnreadMailsChanged"
+ tp:name-for-bindings="Unread_Mails_Changed">
+ <arg name="Count" type="u">
+ <tp:docstring>
+ Number of unread messages in the inbox (the new value of
+ <tp:member-ref>UnreadMailCount</tp:member-ref>).
+ </tp:docstring>
+ </arg>
+ <arg name="Mails_Added" type="aa{sv}" tp:type="Mail[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of <tp:type>Mail</tp:type> that are being added or updated
+ in <tp:member-ref>UnreadMails</tp:member-ref>.</p>
+
+ <tp:rationale>
+ <p>Mails may be updated when the URL information (URL and POST data)
+ have changed, or senders were added or removed from an e-mail
+ thread.</p>
+ </tp:rationale>
+
+ <p>If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+ MUST be empty, even if Count has increased.</p>
+ </tp:docstring>
+ </arg>
+ <arg name="Mails_Removed" type="as">
+ <tp:docstring>
+ A list of e-mail IDs that are being removed from
+ <tp:member-ref>UnreadMails</tp:member-ref>.
+ If the <tt>Supports_Unread_Mails</tt> flag is not set, this list
+ MUST be empty, even if Count has decreased.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when <tp:member-ref>UnreadMails</tp:member-ref> or
+ <tp:member-ref>UnreadMailCount</tp:member-ref> have changed. It MUST
+ NOT be emited if <tt>Supports_Unread_Mail_Count</tt> flag is not set
+ in <tp:member-ref>MailNotificationFlags</tp:member-ref>.</p>
+
+ <p><tt>Mails_Added</tt> and
+ <tt>Mails_Removed</tt> MUST be empty if the
+ <tt>Supports_Unread_Mails</tt> flag is not set.</p>
+ </tp:docstring>
+ </signal>
+
+ <method name="RequestInboxURL"
+ tp:name-for-bindings="Request_Inbox_URL">
+ <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
+ <tp:docstring>
+ A struture containing a URL and optional additional data to open a
+ webmail client, without re-authentication if possible.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ This method creates and returns a URL and an optional POST data that
+ allow opening the Inbox folder of a webmail account. This URL MAY
+ contain tokens with a short lifetime, so clients SHOULD request a new
+ URL for each visit to the webmail interface. This method is implemented
+ only if the <tt>Supports_Request_Inbox_URL</tt> flag is set in
+ <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+
+ <tp:rationale>
+ We are not using properties here because the tokens are unsuitable
+ for sharing between clients, and network round-trips may be required
+ to obtain the information that leads to authentication free webmail
+ access.
+ </tp:rationale>
+ </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.NotImplemented"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestMailURL"
+ tp:name-for-bindings="Request_Mail_URL">
+ <arg direction="in" name="ID" type="s">
+ <tp:docstring>
+ The mail's <tt>id</tt> as found in the <tp:type>Mail</tp:type>
+ structure, or the empty string if no <tt>id</tt> key was provided.
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="URL_Data" type="v">
+ <tp:docstring>
+ Whatever <tt>url-data</tt> was found in the <tp:type>Mail</tp:type>
+ structure, or the boolean value False (D-Bus type 'b') if no
+ <tt>url-data</tt> was provided in the Mail.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="URL" type="(sua(ss))" tp:type="Mail_URL" >
+ <tp:docstring>
+ A struture that contains a URL and optional additional data to open a
+ webmail client, without re-authentication if possible.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ This method creates and returns a URL and optional POST data that
+ allow opening a specific mail in a webmail interface. This
+ method is implemented only if <tt>Supports_Request_Mail_URL</tt> flag
+ is set in <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+ <tp:rationale>
+ See <tp:member-ref>RequestInboxURL</tp:member-ref> for design
+ rationale.
+ </tp:rationale>
+ </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.NotImplemented"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface to support receiving notifications about a e-mail
+ account associated with this connection.</p>
+
+ <p>In protocols where this is possible, this interface also allows the
+ connection manager to provide the necessary information for clients
+ to open a web-based mail client without having to re-authenticate.</p>
+
+ <p>To use this interface, a client MUST first subscribe by passing the
+ name of this interface to the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.AddClientInterest</tp:dbus-ref> method. The subscription
+ mechanic aims at reducing network traffic and memory footprint in the
+ situation where nobody is currently interesting in provided
+ information. When done with this interface, clients SHOULD call
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.RemoveClientInterest</tp:dbus-ref> to allow the CM to
+ release resources.</p>
+
+ <p>Protocols have various different levels of Mail Notification support.
+ To describe the level of support, the interface provides a property
+ called <tp:member-ref>MailNotificationFlags</tp:member-ref>.
+ Not all combinations are valid; protocols can be divided into four
+ categories as follows.</p>
+
+ <p>Connections to the most capable protocols, such as Google's XMPP Mail
+ Notification extension, have the Supports_Unread_Mails flag (this
+ implies that they must also have Supports_Unread_Mail_Count, but not
+ Emits_Mails_Received). On these connections, clients
+ requiring change notification MUST monitor the
+ <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+ either recover the initial state from the
+ <tp:member-ref>UnreadMails</tp:member-ref> property (if they require
+ details other than the number of mails) or the
+ <tp:member-ref>UnreadMailCount</tp:member-ref> property (if they
+ are only interested in the number of unread mails). The
+ <tp:member-ref>MailsReceived</tp:member-ref> signal is never emitted
+ on these connections, so clients that will display a short-term
+ notification for each new mail MUST do so in response to emission of
+ the <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal.</p>
+
+ <p>The most common situation, seen in protocols like MSN and Yahoo, is
+ that the number of unread mails is provided and kept up-to-date,
+ and a separate notification is emitted with some details of each new
+ mail. This is a combination of the following two features, and clients
+ SHOULD implement one or both as appropriate for their requirements.</p>
+
+ <p>On protocols that have the Emits_Mails_Received flag (which implies
+ that they do not have Supports_Unread_Mails), the CM does not keep
+ track of any mails; it simply emits a notification whenever new mail
+ arrives. Those events may be used for short term display (like a
+ notification popup) to inform the user. No protocol is known to support
+ only this feature, but it is useful for integration with libraries that
+ that do not implement tracking of the number of mails. Clients
+ requiring these notifications MUST monitor the
+ <tp:member-ref>MailsReceived</tp:member-ref> signal on any connections
+ with this flag.</p>
+
+ <p>On protocols that have the Supports_Unread_Mail_Count flag but not
+ the Supports_Unread_Mails flag, clients cannot display complete
+ details of unread email, but can display an up-to-date count of the
+ <em>number</em> of unread mails. To do this, they must monitor the
+ <tp:member-ref>UnreadMailsChanged</tp:member-ref> signal, and
+ retrieve the initial state from the
+ <tp:member-ref>UnreadMailCount</tp:member-ref> property.</p>
+
+ <p>
+ Orthogonal features described by the
+ <tp:member-ref>MailNotificationFlags</tp:member-ref> property include the
+ RequestSomethingURL methods, which are used to obtain URLs allowing
+ clients to open a webmail client. Connections SHOULD support as many
+ of these methods as possible.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml
new file mode 100644
index 0000000..571bf6d
--- /dev/null
+++ b/spec/Connection_Interface_Power_Saving.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Power_Saving"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ >
+ <tp:copyright> Copyright © 2007-2010 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
+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
+Library 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.PowerSaving">
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some protocols support mechanisms for reducing bandwidth usage—and
+ hence power usage, on mobile devices—when the user is not directly
+ interacting with their IM client. For instance, Google Talk's XMPP
+ server supports queueing incoming presence updates at the client's
+ instruction; the client can instruct the server to deliver all
+ outstanding presence updates at a later time. This interface may be
+ used to instruct the connection manager to enable and disable such
+ protocol-level features when a screensaver is activated, the device
+ screen is locked, and so on, by calling the
+ <tp:member-ref>SetPowerSaving</tp:member-ref> method.</p>
+
+ <p>Enabling power saving SHOULD NOT change behaviour in any way
+ that is noticable to a user not actively interacting with their client.
+ For example, delaying presence updates somewhat is unlikely to be
+ noticed by a user not staring at their device waiting for a contact to
+ come online; on the other hand, requesting that the server queue
+ incoming messages would be noticable by the user, so is not an
+ acceptable effect of calling
+ <tp:member-ref>SetPowerSaving</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <method name="SetPowerSaving" tp:name-for-bindings="Set_Power_Saving">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Turn power saving mode on or off.</p>
+
+ <tp:rationale>
+ <p>Depending on the device's activity level, the
+ connection can have its power saving mode turned on or off.</p>
+ </tp:rationale>
+
+ <p>Errors raised by this method indicate that power saving could not be
+ enabled, which SHOULD NOT generally be treated as fatal.</p>
+
+ <tp:rationale>
+ If the CM cannot switch modes, either because of the
+ protocol (<code>NotImplemented</code>), or because of the service
+ (<code>NotAvailable</code>), Mission Control (or whoever manages this)
+ should be made aware. The error could be ignored or, in the extreme,
+ be fascist and disconnect the account.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Activate" type="b">
+ <tp:docstring>
+ <code>True</code> if protocol-level power saving features should be
+ activated; <code>False</code> if they should be de-activated.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The current connection has no power saving features.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="PowerSavingActive" type="b" access="read"
+ tp:name-for-bindings="Power_Saving_Active">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p><code>True</code> if protocol-level power saving features are
+ currently activated. This property can be changed using the
+ <tp:member-ref>SetPowerSaving</tp:member-ref> method; change
+ notifications is via the
+ <tp:member-ref>PowerSavingChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="PowerSavingChanged"
+ tp:name-for-bindings="Power_Saving_Changed">
+ <arg name="Active" type="b">
+ <tp:docstring>
+ The new state of the power saving feature.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The <tp:member-ref>PowerSavingActive</tp:member-ref>
+ property changed.
+ </tp:docstring>
+ </signal>
+ </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
new file mode 100644
index 0000000..8a344d4
--- /dev/null
+++ b/spec/Connection_Interface_Presence.xml
@@ -0,0 +1,346 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Presence" 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) 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.Presence">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/>
+
+ <tp:mapping name="Multiple_Status_Map">
+ <tp:docstring>Mapping used in
+ <tp:type>Last_Activity_And_Statuses</tp:type> and passed to
+ <tp:member-ref>SetStatus</tp:member-ref>, representing a collection of
+ statuses. Use of this mapping with more than one member is
+ deprecated.</tp:docstring>
+ <tp:member type="s" name="Status"/>
+ <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
+ </tp:mapping>
+ <tp:struct name="Last_Activity_And_Statuses" array-name="">
+ <tp:docstring>Structure representing a contact's presence, containing
+ a last-activity time (deprecated) and a Multiple_Status_Map.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/>
+ <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map"
+ name="Statuses"/>
+ </tp:struct>
+ <tp:mapping name="Contact_Presences">
+ <tp:docstring>Mapping returned by
+ <tp:member-ref>GetPresence</tp:member-ref> and signalled by
+ <tp:member-ref>PresenceUpdate</tp:member-ref>, where the keys are
+ contacts and the values represent their presences.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact"/>
+ <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses"
+ name="Presence"/>
+ </tp:mapping>
+ <tp:struct name="Status_Spec" array-name="">
+ <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/>
+ <tp:member type="b" name="May_Set_On_Self"/>
+ <tp:member type="b" name="Exclusive"/>
+ <tp:member type="a{ss}" tp:type="String_String_Map"
+ name="Parameter_Types"/>
+ </tp:struct>
+ <tp:mapping name="Status_Spec_Map">
+ <tp:member type="s" name="Identifier"/>
+ <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/>
+ </tp:mapping>
+
+ <method name="AddStatus" tp:name-for-bindings="Add_Status">
+ <arg direction="in" name="Status" type="s">
+ <tp:docstring>
+ The string identifier of the desired status
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring>
+ A dictionary of optional parameter names mapped to their variant-boxed values
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that a single presence status is published for the user, along
+ with any desired parameters. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
+ </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.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <method name="ClearStatus" tp:name-for-bindings="Clear_Status">
+ <tp:docstring>
+ Request that all of a user's presence statuses be removed. Be aware
+ that this request may simply result in the statuses being replaced by a
+ default available status. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
+ </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.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <method name="GetPresence" tp:name-for-bindings="Get_Presence">
+ <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(ua{sa{sv}})}"
+ tp:type="Contact_Presences">
+ <tp:docstring>
+ Presence information in the same format as for the
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signal
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get presence previously emitted by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts.
+ Data is returned in the same structure as the PresenceUpdate signal.
+ Using this method in favour of
+ <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that
+ it will not wake up each client connected to the PresenceUpdate signal.
+ </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.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+ <method name="GetStatuses" tp:name-for-bindings="Get_Statuses">
+ <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map"
+ name="Available_Statuses">
+ <tp:docstring>
+ A dictionary of string identifiers mapped to a struct for each status, containing:
+ <ul>
+ <li>a type value from one of the values above</li>
+ <li>a boolean to indicate if this status may be set on yourself</li>
+ <li>a boolean to indicate if this is an exclusive status which you
+ may not set alongside any other</li>
+ <li>a dictionary of valid optional string argument names mapped to
+ their types</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get a dictionary of the valid presence statuses for this connection.
+ This is only available when online because only some statuses will
+ be available on some servers.
+ </tp:docstring>
+ <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="PresenceUpdate" tp:name-for-bindings="Presence_Update">
+ <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences">
+ <tp:docstring>
+ A dictionary of contact handles mapped to a struct containing
+ a UNIX timestamp of the last activity time (in UTC), and
+ a dictionary mapping the contact's current status identifiers to
+ a dictionary of optional parameter names mapped to their
+ variant-boxed values
+ </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, or when the presence requested by
+ <tp:member-ref>RequestPresence</tp:member-ref> is available.
+ </tp:docstring>
+ </signal>
+ <method name="RemoveStatus" tp:name-for-bindings="Remove_Status">
+ <arg direction="in" name="Status" type="s">
+ <tp:docstring>
+ The string identifier of the status not to publish anymore for the user
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the given presence status is no longer published for the
+ user. Changes will be indicated by
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As
+ with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may
+ actually result in it being replaced by a default available status.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>The status requested is not currently set</tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="RequestPresence" tp:name-for-bindings="Request_Presence">
+ <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>
+ <tp:docstring>
+ Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref>
+ signal will be emitted when they are received. This is not the same as
+ subscribing to the presence of a contact, which must be done using the
+ 'subscription' <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>,
+ and on some protocols presence information may not be available unless
+ a subscription exists.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The presence of the requested contacts is not reported to this connection
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="SetLastActivityTime"
+ tp:name-for-bindings="Set_Last_Activity_Time">
+ <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp">
+ <tp:docstring>
+ A UNIX timestamp of the user's last activity time (in UTC)
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the recorded last activity time for the user be updated on
+ the server.
+ </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.NotImplemented">
+ <tp:docstring>
+ This protocol has no concept of idle time
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="SetStatus" tp:name-for-bindings="Set_Status">
+ <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map">
+ <tp:docstring>
+ A dictionary mapping status identifiers to dictionaries, which
+ map optional parameter names to their variant-boxed values
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the user's presence be changed to the given statuses
+ and desired parameters. Changes will be reflected by
+ <tp:member-ref>PresenceUpdate</tp:member-ref>
+ signals being emitted.</p>
+
+ <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+ is Offline, Error or Unknown MUST NOT be passed to this
+ function. Connection managers SHOULD reject these statuses.</p>
+
+ <tp:rationale>
+ <p>The same rationale as for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
+ applies.</p>
+ </tp:rationale>
+
+ <p>On certain protocols, this method may be
+ called on a newly-created connection which is still in the
+ DISCONNECTED state, and will sign on with the requested status.
+ If the requested status is not available after signing on,
+ NotAvailable will be returned and the connection will remain
+ offline, or if the protocol does not support signing on with
+ a certain status, Disconnected will be returned.</p>
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:deprecated version="0.17.21">Client implementations
+ SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ instead.</tp:deprecated>
+ <tp:changed version="0.17.23">Connection managers implementing
+ Presence MUST implement SimplePresence too.</tp:changed>
+
+ <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
+ <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
+ which may have arbitrary key/value parameters. Valid statuses are defined
+ per connection, and a list of them can be obtained with the
+ <tp:member-ref>GetStatuses</tp:member-ref> method.</p>
+
+ <p>(The SimplePresence interface which replaces this one restricts
+ presences to one status per contact, with an optional message, which is
+ in practice all that was implemented on this interface.)</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 well-known values defined by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface SHOULD be used where possible</p>
+
+ <p>As well as these well-known status identifiers, every status also has a
+ numerical type value chosen from
+ <tp:type>Connection_Presence_Type</tp:type> which can be used by the client
+ to classify even unknown statuses into different fundamental types.</p>
+
+ <p>These numerical types exist so that even if a client does not understand
+ the string identifier being used, and hence cannot present the presence to
+ the user to set on themselves, it may display an approximation of the
+ presence if it is set on a contact.</p>
+
+ <p>The dictionary of variant types allows the connection manager to exchange
+ further protocol-specific information with the client. It is recommended
+ that the string (s) argument 'message' be interpreted as an optional
+ message which can be associated with a presence status.</p>
+
+ <p>If the connection has a 'subscribe' contact list,
+ <tp:member-ref>PresenceUpdate</tp:member-ref> signals should be emitted to
+ indicate changes of contacts on this list, and should also be emitted for
+ changes in your own presence. Depending on the protocol, the signal may
+ also be emitted for others such as people with whom you are communicating,
+ and any user interface should be updated accordingly.</p>
+
+ <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> may
+ only succeed on contacts on your 'subscribe' list, and other contacts will
+ cause a PermissionDenied error. On protocols where there is no 'subscribe'
+ list, and RequestPresence succeeds, a client may poll the server
+ intermittently to update any display of presence information.</p>
+ </tp:docstring>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Privacy.xml b/spec/Connection_Interface_Privacy.xml
new file mode 100644
index 0000000..b89d968
--- /dev/null
+++ b/spec/Connection_Interface_Privacy.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Privacy" 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) 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.Privacy"
+ tp:causes-havoc='not well-tested'>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <method name="GetPrivacyMode" tp:name-for-bindings="Get_Privacy_Mode">
+ <arg direction="out" type="s">
+ <tp:docstring>
+ A string representing the current privacy mode
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Return the current privacy mode, which must be one of the values
+ returned by GetPrivacyModes.
+ </tp:docstring>
+ <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="GetPrivacyModes" tp:name-for-bindings="Get_Privacy_Modes">
+ <arg direction="out" type="as">
+ <tp:docstring>
+ An array of valid privacy modes for this connection
+ </tp:docstring>
+ </arg>
+ <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>
+ <dt>allow-all</dt><dd>any contact may initiate communication</dd>
+ <dt>allow-specified</dt><dd>only contacts on your 'allow' list may initiate communication</dd>
+ <dt>allow-subscribed</dt><dd>only contacts on your subscription list may initiate communication</dd>
+ </dl>
+ </tp:docstring>
+ </method>
+ <signal name="PrivacyModeChanged"
+ tp:name-for-bindings="Privacy_Mode_Changed">
+ <arg name="Mode" type="s">
+ <tp:docstring>
+ The current privacy mode
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the privacy mode is changed or the value has been
+ initially received from the server.
+ </tp:docstring>
+ </signal>
+ <method name="SetPrivacyMode" tp:name-for-bindings="Set_Privacy_Mode">
+ <arg direction="in" name="Mode" type="s">
+ <tp:docstring>
+ The desired privacy mode
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that the privacy mode be changed to the given value, which
+ must be one of the values returned by GetPrivacyModes. Success is
+ indicated by the method returning and the PrivacyModeChanged
+ signal being emitted.
+ </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.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring>
+ An interface to support getting and setting privacy modes to configure
+ situations such as not being contactable by people who are not on your
+ subscribe list. If this interface is not implemented, the default can be
+ presumed to be allow-all (as defined in GetPrivacyModes).
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml
new file mode 100644
index 0000000..d08b748
--- /dev/null
+++ b/spec/Connection_Interface_Renaming.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Renaming" 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) 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.Renaming"
+ tp:causes-havoc='not well-tested'>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <signal name="Renamed" tp:name-for-bindings="Renamed">
+ <arg name="Original" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the original identifier
+ </tp:docstring>
+ </arg>
+ <arg name="New" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The handle of the new identifier
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the unique identifier of a contact on the server
+ changes.</p>
+
+ <p>Any channels associated with the contact's original handle will
+ continue to be to that handle, and so are no longer useful (unless
+ the contact renames back, or another contact connects with that
+ unique ID). Clients may open a similar channel associated with the
+ new handle to continue communicating with the contact.</p>
+
+ <p>For example, if a GUI client associates text
+ channels with chat windows, it should detach the old channel
+ from the chat window, closing it, and associate a channel to the
+ new handle with the same window.</p>
+
+ <p>If the contact's old handle is in any of the member lists of
+ a channel which has the groups interface, it will be removed from
+ the channel and the new handle will be added. The resulting
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>
+ signal must be emitted <em>after</em> the
+ <tp:member-ref>Renamed</tp:member-ref> signal; the reason should be
+ RENAMED.
+ </p>
+
+ <p>The handles may be either general-purpose or channel-specific.
+ If the original handle is general-purpose, the new handle must be
+ general-purpose; if the original handle is channel-specific, the
+ new handle must be channel-specific in the same channel.
+ </p>
+ </tp:docstring>
+ </signal>
+ <method name="RequestRename" tp:name-for-bindings="Request_Rename">
+ <arg direction="in" name="Identifier" type="s">
+ <tp:docstring>
+ The desired identifier
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the user's own identifier is changed on the server.
+ If successful, a <tp:member-ref>Renamed</tp:member-ref> signal will
+ be emitted for the current "self handle" as returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>.</p>
+ <p>It is protocol-dependent how the identifier that's actually
+ used will be derived from the supplied identifier; some sort of
+ normalization might take place.</p>
+ </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.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring>
+ An interface on connections to support protocols where the unique
+ identifiers of contacts can change. Because handles are immutable,
+ this is represented by a pair of handles, that representing the
+ old name, and that representing the new one.
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
new file mode 100644
index 0000000..2f233fa
--- /dev/null
+++ b/spec/Connection_Interface_Requests.xml
@@ -0,0 +1,628 @@
+<?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">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+
+ <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>
+
+ <p>If this interface is implemented on a connection, then
+ <tp:member-ref>NewChannels</tp:member-ref> MUST be emitted for
+ all new channels, even those created with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection"
+ >RequestChannel</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <tp:struct name="Channel_Details" array-name="Channel_Details_List">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+
+ <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>,
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>
+ and
+ <tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>.
+ </p>
+
+ <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:name-for-bindings="Create_Channel">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <tp:changed version="0.17.14">It is now guaranteed that
+ CreateChannel returns the channel before NewChannels announces it
+ (the reverse was previously guaranteed).</tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that an entirely new channel is 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, which MUST include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>.
+ 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 xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Channel object, which MUST NOT be signalled with
+ <tp:member-ref>NewChannels</tp:member-ref> until after this method
+ returns.</p>
+
+ <tp:rationale>
+ <p>This allows the requester to alter its handling of
+ NewChannels by knowing whether one of the channels satisfied
+ a request it made.</p>
+ </tp:rationale>
+ </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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The request matched the fixed properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> in
+ <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
+ allowed arguments did not make sense; for example, a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
+ was requested, but the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
+ property provided was not a valid DNS name.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.Offline">
+ <tp:docstring>
+ The requested channel cannot be created because the target is
+ offline.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested channel cannot be created, but in
+ principle, a similar request might succeed in future.
+ For instance, this might be because:</p>
+
+ <ul>
+ <li>a channel matching the request already exists and the
+ protocol requires that only one such channel can exist at a
+ time</li>
+ <li>a channel matching the request has already been requested
+ (by a previous call to CreateChannel,
+ <tp:member-ref>EnsureChannel</tp:member-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
+ or similar) and the protocol requires that only one such
+ channel can exist at a time</li>
+ </ul>
+ </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:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
+ <tp:added version="0.17.12"/>
+ <tp:changed version="0.17.14">It is now guaranteed that if
+ the channel was created by this call to EnsureChannel, it's returned
+ before NewChannels announces it (the reverse was previously
+ guaranteed).</tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that channels are ensured to exist.</p>
+
+ <tp:rationale>
+ <p>The connection manager is in the best position to determine which
+ existing channels could satisfy which requests.</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, with the same
+ semantics as the corresponding parameter to
+ <tp:member-ref>CreateChannel</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Yours" direction="out" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If false, the caller of EnsureChannel MUST assume that some
+ other process is handling this channel; if true, the caller of
+ EnsureChannel SHOULD handle it themselves or delegate it to another
+ client.</p>
+
+ <p>If the creation of a channel makes several calls to EnsureChannel
+ (and no other requests) successful, exactly one of those calls MUST
+ return a true value for this argument.</p>
+
+ <p>If the creation of a channel makes other requests successful,
+ the value returned for this argument MUST be such that exactly
+ one of the clients making requests ends up responsible for the
+ channel. In particular, if
+ <tp:member-ref>CreateChannel</tp:member-ref> returns a channel
+ <em>C</em>, any EnsureChannel calls that also return <em>C</em>
+ MUST return a false value for this argument.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Channel" direction="out" type="o">
+ <tp:docstring>
+ The Channel object. If it was created as a result of this method
+ call, it MUST NOT be signalled by
+ <tp:member-ref>NewChannels</tp:member-ref> until after this method
+ returns.
+
+ <tp:rationale>
+ <p>This allows the requester to alter its handling of
+ NewChannels by knowing whether one of the channels satisfied
+ a request it made.</p>
+ </tp:rationale>
+ </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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.TargetID</tp:dbus-ref>).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The request matched the fixed properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> in
+ <tp:member-ref>RequestableChannelClasses</tp:member-ref>, but the
+ allowed arguments did not make sense; for example, a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">RoomList</tp:dbus-ref>
+ was requested, but the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.RoomList">Server</tp:dbus-ref>
+ property provided was not a valid DNS name.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
+ <tp:docstring>
+ The requested channel cannot be created because the requested
+ contact is using a client that lacks a particular feature.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.Offline">
+ <tp:docstring>
+ The requested channel cannot be created because the target is
+ offline.
+ </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.
+ </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:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="NewChannels" tp:name-for-bindings="New_Channels">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <tp:changed version="0.17.14">Added a guarantee of ordering
+ relative to NewChannel</tp:changed>
+
+ <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 <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ channel can be created as a side-effect.</p>
+ </tp:rationale>
+
+ <p>Every time NewChannels is emitted, it MUST be followed by
+ a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal for each channel.</p>
+
+ <tp:rationale>
+ <p>The double signal emission is for the benefit of older Telepathy
+ clients, which won't be listening for NewChannels.</p>
+
+ <p>The more informative NewChannels signal comes first so that
+ clients that did not examine the connection to find
+ out whether Requests is supported will see the more informative
+ signal for each channel first, and then ignore the less
+ informative signal because it announces a new channel of which
+ they are already aware.</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" tp:name-for-bindings="Channels"
+ type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <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:name-for-bindings="Channel_Closed">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <tp:docstring>
+ Emitted when a channel is closed and hence disappears from the
+ <tp:member-ref>Channels</tp:member-ref> property.
+
+ <tp:rationale>
+ This is redundant with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>
+ 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" array-name="Channel_Class_List">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <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:added version="0.17.11">(as stable API)</tp:added>
+ <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>
+
+ <p>Interface designers SHOULD avoid introducing fixed properties
+ whose types are not serializable in a <code>.manager</code>
+ file.</p>
+
+ <tp:rationale>
+ <p>Connection managers with a fixed property that is not
+ serializable cannot have a complete <code>.manager</code>
+ file.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+
+ <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:name-for-bindings="Requestable_Channel_Classes">
+ <tp:added version="0.17.11">(as stable API)</tp:added>
+ <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_Resources.xml b/spec/Connection_Interface_Resources.xml
new file mode 100644
index 0000000..716089c
--- /dev/null
+++ b/spec/Connection_Interface_Resources.xml
@@ -0,0 +1,212 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Resources"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Resources.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.21.1">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface on connections to show contact attributes for
+ specific resources of a contact, if the protocol supports
+ multiple resources. Resources are most common in XMPP, hence the
+ name of this interface, but they are also present in MSN, where
+ they are called points of presence.</p>
+
+ <p>When a client requests some attribute of a contact using its
+ handle on the connection, the CM uses an algorithm to choose the
+ most appropriate resource for the job. If there is only one
+ resource, then the choice is obvious. If, however, there is more
+ than one resource connected at any one time, the CM either
+ aggregates all appropriate information to return (in the case of
+ capabilities), or chooses one specific resource (in the case of
+ presence).</p>
+
+ <p>Resources in XMPP have names, and it can be extremely useful
+ for the user to be able to know which resources of a contact are
+ online, providing the names are human-readable. Before now,
+ resources have not been exposed in Telepathy, but this interface
+ attempts to change this.</p>
+
+ <p>When using this interface, it is a little like using the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface"
+ >Contacts</tp:dbus-ref> interface, but only resource-specific
+ attributes are ever returned. The resource-specific contact
+ attributes are decided on by the CM, but XMPP's are listed
+ below:</p>
+
+ <ul>
+ <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li>
+ <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li>
+ <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/client-types</tp:dbus-ref></li>
+ </ul>
+
+ </tp:docstring>
+
+ <method name="GetResources" tp:name-for-bindings="Get_Resources">
+ <tp:docstring>
+ Return the resource information of the given contacts. If any
+ of the contact attributes for specific resources of the given
+ contacts' are not known return immediately without waiting for
+ a reply.
+ </tp:docstring>
+
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The contacts whose resource attributes should be returned.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Resources" type="a{ua{sa{sv}}}"
+ tp:type="Resources_Attributes_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contacts' resources and the contact attributes specific
+ to each resource. 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>For every contact handle passed into this method, it is
+ guaranteed that there will be a key in the returned map
+ that corresponds to said handle. If there is no information
+ regarding the contact the resource information map will be
+ empty.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:enum name="Resources_Human_Readability" type="u">
+ <tp:enumvalue suffix="Never" value="0">
+ <tp:docstring>
+ The resource string is never human-readable.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Maybe" value="1">
+ <tp:docstring>
+ The resource string might be human-readable.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="ResourcesHumanReadable" type="u" access="read"
+ tp:type="Resources_Human_Readability"
+ tp:name-for-bindings="Resources_Human_Readable">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref>
+ are human readable or not.</p>
+
+ <p>If the connection manager knows that all resource names are
+ automatically generated, then the resource strings mean
+ nothing to the user. Showing these strings in the UI would
+ be confusing, so by setting this to
+ Resources_Human_Readability_Never, the UI is advised not to
+ show resources.</p>
+
+ <p>If on the other hand, all resources are set to nice names
+ (such as "office" or "home") then it might be wise to expose
+ these strings in the UI, so this property would be set to
+ Resources_Human_Readability_Maybe. This is the case in XMPP --
+ most resources are set in a way that the user can deduce some
+ information from them. The absence of an Always enum value is
+ because in the case of XMPP, the resource string could be
+ partially human-readable (as on Google Talk, where a resource
+ of "home" is changed by the server to a unique string like
+ "home_1234fdec") or not at all human-readable.</p>
+
+ </tp:docstring>
+ </property>
+
+ <signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated">
+ <tp:docstring>
+ Emitted when a contact has a resource added or removed, or any
+ contact attribute for any resource changes.
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact.
+ </tp:docstring>
+ </arg>
+ <arg name="Resources" tp:type="Resource_Information_Map"
+ type="a{sa{sv}}">
+ <tp:docstring>
+ The contact's resource information. All resource information
+ is given, not just the details which have changed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:mapping name="Resource_Information_Map">
+ <tp:docstring>
+ A map of a contact's resources to their resource-specific
+ information.
+ </tp:docstring>
+
+ <tp:member name="Key" type="s">
+ <tp:docstring>
+ <p>The name of the resource.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Contact_Attributes" type="a{sv}"
+ tp:type="Single_Contact_Attributes_Map">
+ <tp:docstring>
+ A map of contact attributes whose data is specific to this
+ resource.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:mapping name="Resources_Attributes_Map">
+ <tp:docstring>Mapping returned by
+ <tp:member-ref>GetResources</tp:member-ref>, representing a
+ collection of Contacts, their resources, and their
+ resource-specific contact 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{sa{sv}}" tp:type="Resource_Information_Map"
+ name="Resources">
+ <tp:docstring>
+ A map of the contact's resources to their resource-specific
+ information.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:contact-attribute name="resources" type="a{sa{sv}}"
+ tp:type="Resource_Information_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same mapping that would be returned by
+ <tp:member-ref>GetResources</tp:member-ref> for this contact.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml
new file mode 100644
index 0000000..b135c04
--- /dev/null
+++ b/spec/Connection_Interface_Service_Point.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ServicePoint">
+ <tp:added version="0.19.7">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections whose channels may be able to indicate
+ specific they are connected to some form
+ of service station. For example, when
+ dialing 9-1-1 in the US, a GSM modem/network will recognize that as
+ an emergency call, and inform higher levels of the stack that the
+ call is being handled by an emergency service. In this example,
+ the call is handled by a Public Safety Answering Point (PSAP) which is labeled
+ as "urn:service:sos". Other networks and protocols may handle this
+ differently while still using this interface.</p>
+ </tp:docstring>
+
+ <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List">
+ <tp:member type="(us)" tp:type="Service_Point" name="Service_Point">
+ <tp:docstring>
+ The service point.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="as" name="Service_IDs">
+ <tp:docstring>
+ A list of IDs that are mapped to this service. This is provided as
+ a convenience for the UIs, but the preferred method for
+ requesting channel to a service is by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint">InitialServicePoint</tp:dbus-ref>
+ property in a channel request.
+ </tp:docstring>
+ </tp:member>
+ <tp:docstring>
+ <p>Description of a service point and IDs which are mapped to it.</p>
+
+ <p>An example Service Point info for GSM emergency calls (callable
+ through "911" and "112") could look like:</p>
+
+<pre>
+ ServicePointInfo = (
+ Service_Point: (
+ Service_Point_Type: 1 (Emergency),
+ Service_Point: "urn:service:sos"
+ ),
+ Service_IDs: [ "911", "112" ]
+ )
+</pre>
+ </tp:docstring>
+ </tp:struct>
+
+ <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points"
+ type="a((us)as)" tp:type="Service_Point_Info[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The list of all (known) service points.
+ </tp:docstring>
+ </property>
+
+ <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed">
+ <arg name="Service_Points" type="a((us)as)" tp:type="Service_Point_Info[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The new value of
+ <tp:member-ref>KnownServicePoints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the list of known service points (or their IDs) has
+ changed.
+ </tp:docstring>
+ </signal>
+
+ <tp:struct name="Service_Point">
+ <tp:docstring>A service point.</tp:docstring>
+ <tp:member type="u" name="Service_Point_Type"
+ tp:type="Service_Point_Type">
+ <tp:docstring>
+ The service type.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Service">
+ <tp:docstring>
+ String representation of the service point. The representation is
+ service specific; it may be a 'service' Uniform Resource Name as
+ specified by <a
+ href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>,
+ or may be in some other form. Empty, unused or unknown value is
+ represented by "".
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:enum name="Service_Point_Type" type="u">
+ <tp:docstring>
+ The various types of service points a channel might connect to.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="None">
+ <tp:docstring>
+ The channel is not communicating with a service point, or it is not
+ known whether it is communicating with a service point (e.g. an
+ ordinary call).
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Emergency">
+ <tp:docstring>
+ The service point is a generic emergency point.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Counseling">
+ <tp:docstring>
+ The service point is some kind of counseling service (ie, mental health
+ or child-services counseling).
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ </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..7788161
--- /dev/null
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -0,0 +1,634 @@
+<?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 "Ar Gael" (which they don't
+ understand anyway).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Simple_Contact_Presences">
+ <tp:docstring>
+ Mapping returned by <tp:member-ref>GetPresences</tp:member-ref>
+ and signalled by <tp:member-ref>PresencesChanged</tp:member-ref>,
+ indicating the presence of a number of contacts.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Contact">
+ <tp:docstring>
+ A contact
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="(uss)" tp:type="Simple_Presence" name="Presence">
+ <tp:docstring>
+ The contact's presence
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <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" tp:name-for-bindings="Set_Presence">
+ <arg direction="in" name="Status" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string identifier of the desired status. Possible status
+ identifiers are defined in the
+ <tp:member-ref>Statuses</tp:member-ref> property.</p>
+
+ <p>Clients MUST NOT set a status whose string value they do not
+ recognise, even if its presence type in Statuses
+ matches what the user requested.</p>
+
+ <tp:rationale>
+ <p>Suppose a protocol has statuses that include 'phone' (of type
+ BUSY) and 'in-a-meeting' (of type BUSY), but there is no
+ generic 'busy' status.</p>
+
+ <p>If the user requests "Busy" status from a menu, a
+ client author might be tempted to pick an arbitrary status
+ that has type BUSY. However, on this protocol, neither of
+ the choices would be appropriate, and incorrect information
+ about the user would be conveyed.</p>
+ </tp:rationale>
+
+ <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+ is Offline, Error or Unknown MUST NOT be passed to this
+ function. Connection managers SHOULD reject these statuses.</p>
+
+ <tp:rationale>
+ <p>To go offline, call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref>
+ instead. The "error" and "unknown" statuses make no sense.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Status_Message" type="s">
+ <tp:docstring>
+ The status message associated with the current status.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the presence status and status message are published for
+ the connection. Changes will be indicated by
+ <tp:member-ref>PresencesChanged</tp:member-ref>
+ signals being emitted.</p>
+
+ <p>This method may be called on a newly-created connection while it
+ is still in the DISCONNECTED state, to request that when the
+ connection connects, it will do so with the selected status.</p>
+
+ <p>In DISCONNECTED state the
+ <tp:member-ref>Statuses</tp:member-ref>
+ property will indicate which statuses are allowed to be set
+ while DISCONNECTED (none, if the Connection Manager doesn't allow
+ this). This value MUST NOT be cached, as the set of allowed
+ presences might change upon connecting.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="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" tp:name-for-bindings="Get_Presences">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of the contacts whose presence should be obtained.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" name="Presence" type="a{u(uss)}"
+ tp:type="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
+ <tp:member-ref>PresencesChanged</tp:member-ref> for the given
+ contacts. Data is returned in the same structure as the
+ PresencesChanged signal; no additional network requests are made.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="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" tp:name-for-bindings="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 are
+ available on this connection, and the values are the corresponding
+ presence types.</p>
+
+ <p>While the connection is in the DISCONNECTED state, it contains
+ the set of presence statuses allowed to be set before connecting.
+ The connection manager will attempt to set the appropriate status
+ when the connection becomes connected, but cannot necessarily
+ guarantee it. The available statuses cannot change until the
+ connection status changes, so there is no change notification.</p>
+
+ <p>While the connection is in the CONNECTED state, this property
+ contains the set of presence statuses which are actually available
+ on this protocol. This set is constant for the remaining lifetime
+ of the connection, so again, there is no change notification.</p>
+
+ <p>While the connection is in the CONNECTING state, the value of
+ this property is undefined and SHOULD NOT be used. It can change
+ at any time without notification (in particular, any cached values
+ from when the connection was in the DISCONNECTED or CONNECTING
+ state MUST NOT be assumed to still be correct when the state has
+ become CONNECTED).</p>
+
+ <p>This property MUST include the special statuses "unknown" and
+ "error" if and only if the connection manager can emit them
+ as a contact's status.</p>
+
+ <tp:rationale>
+ For instance, connection managers for local-xmpp (XEP-0174) would
+ omit "unknown" since there is no such concept.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="PresencesChanged" tp:name-for-bindings="Presences_Changed">
+ <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:enum name="Connection_Presence_Type" type="u">
+ <tp:enumvalue suffix="Unset" value="0">
+ <tp:docstring>
+ An invalid presence type used as a null value. This value MUST NOT
+ appear in the <tp:member-ref>Statuses</tp:member-ref> property,
+ or in the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Presence">GetStatuses</tp:dbus-ref>
+ on the deprecated <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+ interface.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring>
+ Offline
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Available" value="2">
+ <tp:docstring>
+ Available
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Away" value="3">
+ <tp:docstring>
+ Away
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Extended_Away" value="4">
+ <tp:docstring>
+ Away for an extended time
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Hidden" value="5">
+ <tp:docstring>
+ Hidden (invisible)
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Busy" value="6">
+ <tp:added version="0.17.0"/>
+ <tp:docstring>
+ Busy, Do Not Disturb.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Unknown" value="7">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Unknown, unable to determine presence for this contact, for example
+ if the protocol only allows presence of subscribed contacts.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="8">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Error, an error occurred while trying to determine presence. The
+ message, if set, is an error from the server.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Access_Control_Type" type="u"
+ array-name="Access_Control_Type_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A type for communication access control. These control
+ policies are used in
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">CommunicationPolicy.DRAFT</tp:dbus-ref>
+ as well as most rich presence interfaces.</p>
+
+ <p>New interfaces should use this type, and NOT
+ <tp:type>Rich_Presence_Access_Control_Type</tp:type>.</p>
+ </tp:docstring>
+ <tp:enumvalue suffix="Whitelist" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Only allow contacts that are in a certain whitelist.</p>
+
+ <p>The associated variant
+ in <tp:type>Access_Control</tp:type> is a list of
+ <tp:type>Contact_Handle</tp:type> representing
+ the whitelist, with signature <code>au</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Publish_List" value="1">
+ <tp:docstring>
+ Allow contacts in the user's 'publish' list. The associated
+ variant in <tp:type>Access_Control</tp:type> is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Group" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Only allow contacts that are in a certain group.</p>
+
+ <p>The associated variant in <tp:type>Access_Control</tp:type> is a
+ <tp:type>Group_Handle</tp:type> representing the permitted
+ group.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="3">
+ <tp:docstring>
+ Allow all contacts. The associated
+ variant in <tp:type>Access_Control</tp:type> is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Subscribe_Or_Publish_List" value="4">
+ <tp:docstring>
+ Allow all contacts in the user's 'subscribe' or 'publish'
+ list. The associated variant in <tp:type>Access_Control</tp:type> is
+ ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Closed" value="5">
+ <tp:docstring>
+ Forbid all contacts. The associated variant in
+ <tp:type>Access_Control</tp:type> is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Not_Understood" value="6">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The access control rule is too complex to be represented
+ in the current Telepathy API. The associated variant is
+ meaningless. Setting this mode is never valid; the
+ connection manager MUST raise an error if this is attempted.</p>
+
+ <tp:rationale>
+ XEP-0016 Privacy Lists can easily produce access control
+ mechanisms that can't be expressed in a simpler API. We
+ need to be able to at least indicate that fact.
+ </tp:rationale>
+
+ <p>The associated variant in <tp:type>Access_Control</tp:type> is
+ ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Rich_Presence_Access_Control_Type" type="u"
+ array-name="Rich_Presence_Access_Control_Type_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A type of access control for Rich_Presence_Access_Control.
+ For most types, the exact access control is given by an associated
+ variant.</p>
+
+ <tp:rationale>
+ <p>These are the access control types from XMPP publish/subscribe
+ (XEP-0060).</p>
+ </tp:rationale>
+
+ <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>
+ uses this for historical reasons, new interfaces will use
+ <tp:type>Access_Control_Type</tp:type>.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Whitelist" value="0">
+ <tp:docstring>
+ The associated variant is a list of contacts (signature 'au',
+ Contact_Handle[]) who can see the extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Publish_List" value="1">
+ <tp:docstring>
+ All contacts in the user's 'publish' contact list can see the
+ extended presence information. The associated variant is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Group" value="2">
+ <tp:docstring>
+ The associated variant is a handle of type Group (signature 'u',
+ Group_Handle) representing a group of contacts who can see the
+ extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="3">
+ <tp:docstring>
+ Anyone with access to the service can see the extended presence
+ information.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Access_Control">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An access control mode for extended presence items like geolocation.
+ This type isn't actually used by the SimplePresence interface, but
+ it's included here so it can be referenced by rich presence
+ interfaces.</p>
+
+ <p>New interfaces should use this type, and NOT
+ <tp:type>Rich_Presence_Access_Control</tp:type>.</p>
+ </tp:docstring>
+
+ <tp:member name="Type" type="u" tp:type="Access_Control_Type">
+ <tp:docstring>
+ The type of access control to apply.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Detail" type="v">
+ <tp:docstring>
+ Any additional information required by the Type. The required
+ type and semantics are defined for each
+ <tp:type>Access_Control_Type</tp:type>.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Rich_Presence_Access_Control">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An access control mode for extended presence items like geolocation.
+ This type isn't actually used by the SimplePresence interface, but
+ it's included here so it can be referenced by rich presence interfaces
+ such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>.</p>
+
+ <p><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>
+ uses this for historical reasons, new interfaces will use
+ <tp:type>Access_Control_Type</tp:type>.</p>
+ </tp:docstring>
+
+ <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
+ <tp:docstring>
+ The type of access control to apply.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Detail" type="v">
+ <tp:docstring>
+ Any additional information required by the Type. The required
+ type and semantics are defined for each
+ <tp:type>Rich_Presence_Access_Control_Type</tp:type>.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:contact-attribute name="presence"
+ type="(uss)" tp:type="Simple_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same struct that would be returned by
+ <tp:member-ref>GetPresences</tp:member-ref>
+ (always present with some value if information from the
+ SimplePresence interface was requested)</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface is for services which have a concept of presence which
+ can be published for yourself and monitored on your contacts.</p>
+
+ <p>Presence on an individual (yourself or one of your contacts) is
+ modelled as a status and a status message. Valid statuses are defined
+ per connection, and a list of those that can be set on youself
+ can be obtained from the
+ <tp:member-ref>Statuses</tp:member-ref>
+ property.</p>
+
+ <p>Each status has an arbitrary string identifier which should have an
+ agreed meaning between the connection manager and any client which is
+ expected to make use of it. The following well-known values should be
+ used where possible to allow clients to identify common choices:</p>
+
+ <table>
+ <tr>
+ <th>status identifier</th>
+ <th>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
+ <tp:type>Connection_Presence_Type</tp:type> which can be
+ used by the client to classify even unknown statuses into different
+ fundamental types.</p>
+
+ <p>These numerical types exist so that even if a client does not
+ understand the string identifier being used, and hence cannot present
+ the presence to the user to set on themselves, it may display an
+ approximation of the presence if it is set on a contact.</p>
+
+ <p>As well as the normal status identifiers, there are two special ones
+ that may be present: 'unknown' with type Unknown and 'error' with type
+ Error. 'unknown' indicates that it is impossible to determine the
+ presence of a contact at this time, for example because it's not on the
+ 'subscribe' list and the protocol only allows one to determine the
+ presence of contacts you're subscribed to. 'error' indicates that there
+ was a failure in determining the status of a contact.</p>
+
+ <p>If the connection has a 'subscribe' contact list,
+ <tp:member-ref>PresencesChanged</tp:member-ref>
+ signals should be emitted to indicate changes of contacts on this list,
+ and should also be emitted for changes in your own presence. Depending
+ on the protocol, the signal may also be emitted for others such as
+ people with whom you are communicating, and any user interface should
+ be updated accordingly.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
new file mode 100644
index 0000000..d75d866
--- /dev/null
+++ b/spec/Connection_Manager.xml
@@ -0,0 +1,614 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Manager" 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-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
+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.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" array-name="Protocol_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An instant messaging protocol. It must consist only of ASCII
+ letters, digits and hyphen/minus signs (U+002D "-"), and must start
+ with a letter. Where possible, this SHOULD be
+ chosen from the following well-known values:</p>
+
+ <ul>
+ <li>aim - AOL Instant Messenger (OSCAR or TOC)</li>
+ <li>gadugadu - Gadu-Gadu</li>
+ <li>groupwise - Novell Groupwise</li>
+ <li>icq - ICQ (OSCAR)</li>
+ <li>irc - Internet Relay Chat (RFC 1459, 2810-2813)</li>
+ <li>jabber - XMPP (RFC 3920, 3921) or Jabber</li>
+ <li>local-xmpp - Link-local XMPP (XEP-0174) (Bonjour, Salut)</li>
+ <li>msn - MSNP (Windows Live Messenger)</li>
+ <li>myspace - MySpaceIM</li>
+ <li>mxit - MXit</li>
+ <li>napster - Napster</li>
+ <li>qq - Tencent QQ</li>
+ <li>sametime - IBM Lotus Sametime</li>
+ <li>silc - SILC</li>
+ <li>sip - Session Initiation Protocol (SIP), with or without
+ SIMPLE support</li>
+ <li>skype - Skype</li>
+ <li>tel - telephony (the
+ <abbr title="Public Switched Telephone Network">PSTN</abbr>,
+ including GSM, CDMA and fixed-line telephony)</li>
+ <li>trepia - Trepia</li>
+ <li>yahoo - YMSG (Yahoo! Messenger)</li>
+ <li>yahoojp - Japanese version of YMSG</li>
+ <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">
+ <tp:docstring>A struct representing an allowed parameter, as returned
+ by GetParameters on the ConnectionManager interface.</tp:docstring>
+ <tp:member type="s" name="Name">
+ <tp:docstring>A string parameter name</tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Conn_Mgr_Param_Flags" name="Flags">
+ <tp:docstring>A bitwise OR of the parameter flags</tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="DBus_Signature" name="Signature">
+ <tp:docstring>A string containing the D-Bus type signature
+ for this parameter</tp:docstring>
+ </tp:member>
+ <tp:member type="v" name="Default_Value">
+ <tp:docstring>The default value (if the Has_Default flag is not
+ present, there is no default and this takes some dummy value,
+ which SHOULD be of the appropriate D-Bus type)</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:flags name="Conn_Mgr_Param_Flags" value-prefix="Conn_Mgr_Param_Flag" type="u">
+ <tp:flag suffix="Required" value="1">
+ <tp:docstring>
+ This parameter is required for connecting to the server.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Register" value="2">
+ <tp:docstring>
+ This parameter is required for registering an account on the
+ server.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Has_Default" value="4">
+ <tp:docstring>
+ This parameter has a default value, which is returned in
+ GetParameters; not providing this parameter is equivalent to
+ 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:flag suffix="DBus_Property" value="16">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This parameter is also a D-Bus property on the resulting
+ <tp:dbus-ref
+ namespace="ofdT">Connection</tp:dbus-ref>; a
+ parameter named <code>com.example.Duck.Macaroni</code> with this
+ flag corresponds to the <code>Macaroni</code> property on the
+ <code>com.example.Duck</code> interface. Its value can be queried
+ and possibly changed on an existing Connection using methods on the
+ <code>org.freedesktop.DBus.Properties</code> interface.</p>
+
+ <p>When a parameter with this flag is changed with <tp:dbus-ref
+ namespace="ofdT">Account.UpdateParameters</tp:dbus-ref>, the
+ account manager will attempt to update its value on any running
+ connections. Thus, clients generally do not need to directly access
+ or update the connection property; instead, they SHOULD manipulate
+ <tp:dbus-ref namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>This allows runtime-configurable options to be stored and
+ maintained by the <tp:dbus-ref
+ namespace='ofdT'>AccountManager</tp:dbus-ref>, without needing to
+ invent a separate account preference for “properties that should
+ be set on the connection as soon as it is created”. It was
+ originally invented to manage <tp:dbus-ref
+ namespace='ofdT.Connection.Interface'>Cellular</tp:dbus-ref>
+ preferences.</p>
+ </tp:rationale>
+ </tp:docstring>
+ <tp:added version="0.17.16"/>
+ </tp:flag>
+ </tp:flags>
+
+ <method name="GetParameters" tp:name-for-bindings="Get_Parameters">
+ <arg direction="in" name="Protocol" type="s" tp:type="Protocol">
+ <tp:docstring>
+ The required protocol name
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="a(susv)" tp:type="Param_Spec[]"
+ name="Parameters">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of structs representing possible parameters.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get a list of the parameters which must or may be provided to the
+ <tp:member-ref>RequestConnection</tp:member-ref> method when connecting
+ to the given protocol,
+ or registering (the boolean &quot;register&quot; parameter is available,
+ and set to true).
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The requested protocol is not supported by this manager
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:mapping name="Protocol_Properties_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from protocol identifiers supported by a connection
+ manager to the immutable properties of the corresponding
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Protocol</tp:dbus-ref> objects.</p>
+ </tp:docstring>
+
+ <tp:member name="Protocol" type="s" tp:type="Protocol">
+ <tp:docstring>A protocol name</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>The immutable properties of the corresponding
+ Protocol object</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="Protocols" tp:name-for-bindings="Protocols"
+ access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from protocol identifiers supported by this connection
+ manager to the immutable properties of the corresponding
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Protocol</tp:dbus-ref> objects.</p>
+
+ <tp:rationale>
+ <p>Providing the immutable properties here means that
+ when the API of Protocol objects has been finalized,
+ most clients will only need one D-Bus round trip to interrogate
+ the ConnectionManager about all its protocols.</p>
+ </tp:rationale>
+
+ <p>If this map is empty or missing, clients SHOULD fall back to
+ calling <tp:member-ref>ListProtocols</tp:member-ref> and
+ <tp:member-ref>GetParameters</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="ListProtocols" tp:name-for-bindings="List_Protocols">
+ <arg direction="out" type="as" tp:type="Protocol[]" name="Protocols">
+ <tp:docstring>
+ The keys of the <tp:member-ref>Protocols</tp:member-ref> map.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get a list of protocol identifiers that are implemented by this
+ connection manager.
+ </tp:docstring>
+ </method>
+
+ <signal name="NewConnection" tp:name-for-bindings="New_Connection">
+ <arg name="Bus_Name" type="s" tp:type="DBus_Bus_Name">
+ <tp:docstring>
+ The D-Bus service where the connection object can be found
+ </tp:docstring>
+ </arg>
+ <arg name="Object_Path" type="o">
+ <tp:docstring>
+ The object path of the Connection object on this service
+ </tp:docstring>
+ </arg>
+ <arg name="Protocol" type="s" tp:type="Protocol">
+ <tp:docstring>
+ The identifier for the protocol this connection uses
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object
+ is created.
+ </tp:docstring>
+ </signal>
+
+ <method name="RequestConnection" tp:name-for-bindings="Request_Connection">
+ <arg direction="in" name="Protocol" type="s" tp:type="Protocol">
+ <tp:docstring>
+ The protocol identifier
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ A dictionary mapping parameter names to values of the appropriate
+ type, as indicated by <tp:member-ref>GetParameters</tp:member-ref>
+ and the well-known list of names and value types documented on the
+ <tp:type>Connection_Parameter_Name</tp:type> type.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="s" tp:type="DBus_Bus_Name" name="Bus_Name">
+ <tp:docstring>
+ A D-Bus service name where the new Connection object can be found
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="o" name="Object_Path">
+ <tp:docstring>
+ The D-Bus object path to the Connection on this service
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ object representing a given account on a given
+ protocol with the given parameters. The method returns the bus name
+ and the object path where the new Connection object can be found,
+ which should have the status of Connection_Status_Disconnected, to
+ allow signal handlers to be attached before connecting is started
+ with the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref>
+ method.</p>
+
+ <p>The parameters which must and may be provided in the parameters
+ dictionary can be discovered with the
+ <tp:member-ref>GetParameters</tp:member-ref> method. These
+ parameters, their types, and their default values may be cached
+ in files so that all available connection managers do not need to be
+ started to discover which protocols are available.</p>
+
+ <p>To request values for these parameters from the user, a client must
+ have prior knowledge of the meaning of the parameter names, so the
+ well-known names and types defined by the
+ <tp:type>Connection_Parameter_Name</tp:type> type should be used where
+ appropriate.</p>
+
+ <p>Connection manager authors SHOULD avoid introducing parameters
+ whose default values would not be serializable in a
+ <code>.manager</code> file.</p>
+
+ <tp:rationale>
+ <p>The same serialization format is used in Mission Control
+ to store accounts.</p>
+ </tp:rationale>
+
+ <p>Every successful RequestConnection call will cause the emission of a
+ <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly
+ created connection. The
+ requester can use the returned object path and service name
+ independently of the emission of that signal. In that case this signal
+ emission is most useful for, e.g. other processes that are monitoring
+ the creation of new connections.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The requested protocol is not supported by this manager
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested connection already appears to exist
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ Unrecognised connection parameters
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:simple-type name="Connection_Parameter_Name" type="s">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Well-known connection parameter names, along with their expected
+ type. Where possible, connection managers should use names and types
+ from this list in the <tp:dbus-ref
+ namespace='ofdT.Protocol'>Parameters</tp:dbus-ref> that may be passed
+ to <tp:member-ref>RequestConnection</tp:member-ref>.</p>
+
+ <dl>
+ <dt>account (s)</dt>
+ <dd>The identifier for the user's account on the server</dd>
+
+ <dt>server (s)</dt>
+ <dd>A fully qualified domain name or numeric IPv4 or IPv6 address.
+ Using the fully-qualified domain name form is recommended whenever
+ possible. If this parameter is specified and the account for that
+ protocol also specifies a server, this parameter should override
+ that in the user id.</dd>
+
+ <dt>port (q)</dt>
+ <dd>A TCP or UDP port number. If this parameter is specified and the
+ account for that protocol also specifies a port, this parameter
+ should override that in the account.</dd>
+
+ <dt>password (s)</dt>
+ <dd>A password associated with the account.</dd>
+
+ <dt>require-encryption (b)</dt>
+ <dd>Require encryption for this connection. A connection should fail
+ to connect if require-encryption is set and an encrypted connection
+ is not possible.</dd>
+
+ <dt>register (b)</dt>
+ <dd>This account should be created on the server if it does not
+ already exist.</dd>
+
+ <dt>ident (s)</dt>
+ <dd>The local username to report to the server if necessary, such as
+ in IRC.</dd>
+
+ <dt>fullname (s)</dt>
+ <dd>The user's full name if the service requires this when
+ authenticating or registering.</dd>
+
+ <dt>stun-server (s)</dt>
+ <dd>The IP address or FQDN of a STUN server to use for NAT traversal,
+ without any ":port" suffix.</dd>
+
+ <dt>stun-port (q)</dt>
+ <dd>The UDP port number on the stun-server to use for STUN. Only
+ significant if the stun-server is also supplied.</dd>
+
+ <dt>keepalive-interval (u)</dt>
+ <dd>
+ <p>The time in seconds between pings sent to the server to ensure
+ that the connection is still alive, or <tt>0</tt> to disable such
+ pings.</p>
+
+ <p>This parameter is superseded by the <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Keepalive.DRAFT'>KeepaliveInterval</tp:dbus-ref>
+ property, which can be updated on an already-established
+ connection as well as being specified when requesting the
+ connection. Clients SHOULD provide that parameter instead, if
+ allowed; new connection managers SHOULD implement it in
+ preference to this one.</p>
+ </dd>
+ </dl>
+
+ <p>The following well-known parameter names correspond to D-Bus
+ properties, and thus their <tp:type>Conn_Mgr_Param_Flags</tp:type>
+ should include DBus_Property. See that flag for more details on this
+ kind of parameter.</p>
+
+ <tp:list-dbus-property-parameters/>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="Interfaces" tp:name-for-bindings="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>
+
+ <p>Connection managers with a non-empty list of Interfaces MUST
+ represent them in the <code>.manager</code> file, if they have one,
+ as an <code>Interfaces</code> key in the
+ group headed <code>[ConnectionManager]</code>, whose value is a list
+ of strings each followed by a semicolon.</p>
+ </tp:docstring>
+ <tp:added version="0.17.8"/>
+ </property>
+
+ <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> (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>
+ where <em>cmname</em> is its connection manager name. If it makes sense
+ to start the connection manager using D-Bus service activation, it
+ must register that well-known name for service activation by installing
+ a .service file.</p>
+
+ <p>Clients can list the running connection managers by calling the
+ ListNames method on the D-Bus daemon's org.freedesktop.DBus interface
+ and looking for names matching the above pattern; they can list the
+ activatable connection managers by calling ListActivatableNames, and
+ they should usually combine the two lists to get a complete list of
+ running or activatable connection managers.</p>
+
+ <p>When the connection manager is running, it must have an object
+ implementing the ConnectionManager interface at the object path
+ <code>/org/freedesktop/Telepathy/ConnectionManager/<em>cmname</em></code>.
+ </p>
+
+ <p>Connection managers' capabilities can be determined dynamically by
+ calling their <tp:member-ref>ListProtocols</tp:member-ref> method, then
+ for each protocol of interest, calling
+ <tp:member-ref>GetParameters</tp:member-ref> to discover the required and
+ optional parameters.
+ However, since it is inefficient to activate all possible connection
+ managers on the system just to find out what they can do, there
+ is a standard mechanism to store static information about CMs in
+ ".manager files".</p>
+
+ <p>To look up a connection manager's supported protocols, clients
+ should search the data directories specified by
+ <a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">the
+ freedesktop.org XDG Base Directory Specification</a> ($XDG_DATA_HOME,
+ defaulting to $HOME/.local/share if unset, followed by
+ colon-separated paths from $XDG_DATA_DIRS, defaulting to
+ /usr/local/share:/usr/share if unset) for the first file named
+ <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>The <code>.manager</code> file SHOULD have a group headed
+ <code>[ConnectionManager]</code>, containing a key
+ <code>Interfaces</code> representing
+ <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings
+ each followed by a semicolon (the "localestrings" type from the Desktop
+ Entry Specification).</p>
+
+ <p>The <code>[ConnectionManager]</code> group SHOULD NOT contain keys
+ <code>ObjectPath</code> or <code>BusName</code>. If it does, they MUST
+ be ignored.</p>
+
+ <tp:rationale>
+ <p>The object path and bus name are derivable from the connection
+ manager's name, which is part of the filename, so these keys are
+ redundant. They were required in very old versions of Telepathy.</p>
+ </tp:rationale>
+
+ <p>For each protocol name <em>proto</em> that would be returned by
+ ListProtocols, the .manager file contains a group
+ headed <code>[Protocol <em>proto</em>]</code>. For each parameter
+ <em>p</em> that would be returned by GetParameters(<em>proto</em>), the
+ .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:</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>
+ <li><code>dbus-property</code>, corresponding
+ to Conn_Mgr_Param_Flag_DBus_Property</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.
+ If this key exists, it sets the default, and also sets the flag
+ Conn_Mgr_Param_Flag_Has_Default. The default value is formatted
+ according to the D-Bus signature as follows:</p>
+
+ <dl>
+ <dt>s (string)</dt>
+ <dd>The UTF-8 string, with the standard backslash escape
+ sequences supported by the Desktop Entry Specification
+ (the "localestring" type from the Desktop Entry Specification)</dd>
+ <dt>o (object path)</dt>
+ <dd>The object path as an ASCII string</dd>
+ <dt>b (boolean)</dt>
+ <dd>"true" (case-insensitively) or "1" means True, "false"
+ (case-insensitively) or "0" means False; when writing a file,
+ "true" and "false" SHOULD be used</dd>
+ <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt>
+ <dd>ASCII decimal integer</dd>
+ <dt>n, i, x (16-, 32-, 64-bit signed integer)</dt>
+ <dd>ASCII decimal integer, optionally prefixed with "-"</dd>
+ <dt>d (double-precision floating point)</dt>
+ <dd>ASCII decimal number</dd>
+ <dt>as (array of string)</dt>
+ <dd>A sequence of UTF-8 strings each followed by a semicolon, with
+ any semicolons they contain escaped with a backslash
+ (the "localestrings" type from the Desktop Entry Specification)</dd>
+ </dl>
+
+ <p>Currently, no other D-Bus signatures are allowed to have default values,
+ but clients parsing the .manager file MUST ignore defaults
+ that they cannot parse, and treat them as if the
+ <code>default-<em>p</em></code> key was not present at all.</p>
+
+ <p>It is not required that a connection manager be able to support multiple
+ protocols, or even multiple connections. When a connection is made, a
+ service name where the connection object can be found is returned. A
+ manager which can only make one connection may then remove itself from its
+ 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>
+ <tp:changed version="0.17.16">Prior to version 0.17.16 the serialization
+ of string arrays (signature 'as') was not defined</tp:changed>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Debug.xml b/spec/Debug.xml
new file mode 100644
index 0000000..70a82e9
--- /dev/null
+++ b/spec/Debug.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" ?>
+<node name="/Debug"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2009 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Debug">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for providing debug messages.</p>
+
+ <p>This interface is primarily provided by one object per
+ service, at the path <tt>/org/freedesktop/Telepathy/debug</tt>.</p>
+ </tp:docstring>
+
+ <property name="Enabled" type="b" access="readwrite"
+ tp:name-for-bindings="Enabled">
+ <tp:docstring>
+ TRUE if the <tp:member-ref>NewDebugMessage</tp:member-ref> signal
+ should be emitted when a new debug message is generated.
+ </tp:docstring>
+ </property>
+
+ <method name="GetMessages" tp:name-for-bindings="Get_Messages">
+ <tp:docstring>
+ Retrieve buffered debug messages. An implementation could have a
+ limit on how many message it keeps and so the array returned from
+ this method should not be assumed to be all of the messages in
+ the lifetime of the service.
+ </tp:docstring>
+
+ <arg direction="out" name="Messages" type="a(dsus)"
+ tp:type="Debug_Message[]">
+ <tp:docstring>
+ A list of debug messages.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="NewDebugMessage" tp:name-for-bindings="New_Debug_Message">
+ <tp:docstring>
+ Emitted when a debug messages is generated if the
+ <tp:member-ref>Enabled</tp:member-ref> property is set to TRUE.
+ </tp:docstring>
+
+ <arg name="time" type="d">
+ <tp:docstring>
+ Timestamp of the debug message.
+ </tp:docstring>
+ </arg>
+ <arg name="domain" type="s">
+ <tp:docstring>
+ Domain of the debug message, as described in the Debug_Message struct.
+ </tp:docstring>
+ </arg>
+ <arg name="level" type="u" tp:type="Debug_Level">
+ <tp:docstring>
+ Level of the debug message.
+ </tp:docstring>
+ </arg>
+ <arg name="message" type="s">
+ <tp:docstring>
+ The text of the debug message.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Debug_Level" type="u">
+ <tp:enumvalue suffix="Error" value="0">
+ <tp:docstring>
+ Log level for errors. Error messages are always fatal, resulting
+ in the service terminating after something completely
+ unexpected occurred.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Critical" value="1">
+ <tp:docstring>
+ Log level for critical messages. Critical messages are messages
+ that the service might predict and it is up to the service itself
+ to decide whether to terminate following a critical message.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Warning" value="2">
+ <tp:docstring>
+ Log level for warnings.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Message" value="3">
+ <tp:docstring>
+ Log level for messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Info" value="4">
+ <tp:docstring>
+ Log level for information messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Debug" value="5">
+ <tp:docstring>
+ Log level for debug messages.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Debug_Message" array-name="Debug_Message_List">
+ <tp:docstring>
+ A struct representing a debug message, as returned by
+ <tp:member-ref>GetMessages</tp:member-ref>.
+ </tp:docstring>
+
+ <tp:member type="d" name="Timestamp">
+ <tp:docstring>
+ Timestamp of the debug message. This is a double to allow
+ more accuracy in the time the message was logged.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="s" name="Domain">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Domain of the debug message. This is used to identify
+ the source of debug messages. For example, debug messages
+ from a connection manager could have this Domain struct
+ member be the name of the connection manager, and logs
+ from any helper library could have the name of the helper
+ library.</p>
+
+ <p>The domain could also contain a category as to where
+ the log message originated separated by a forward-slash.
+ For example, if a debug message was output in a connection
+ manager called "dummy", in the file-transfer code, this
+ Domain struct member might be <tt>dummy/file-transfer</tt>.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="u" tp:type="Debug_Level" name="Level">
+ <tp:docstring>
+ Level of the debug message. This states the severity of the
+ debug message.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member type="s" name="Message">
+ <tp:docstring>
+ The text of the debug message.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Media_Session_Handler.xml b/spec/Media_Session_Handler.xml
new file mode 100644
index 0000000..70aa750
--- /dev/null
+++ b/spec/Media_Session_Handler.xml
@@ -0,0 +1,81 @@
+<?xml version="1.0" ?>
+<node name="/Media_Session_Handler" 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) 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.Media.SessionHandler">
+ <method name="Error" tp:name-for-bindings="Error">
+ <arg direction="in" name="Error_Code" type="u"
+ tp:type="Media_Stream_Error"/>
+ <arg direction="in" name="Message" type="s"/>
+ <tp:deprecated version="0.13.4">
+ Use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media">StreamHandler.Error</tp:dbus-ref>
+ on each StreamHandler object instead.
+ </tp:deprecated>
+ <tp:docstring>
+ Informs the connection manager that an error occured in this session.
+ If used, the connection manager must terminate the session and all of
+ the streams within it, and may also emit a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">StreamError</tp:dbus-ref>
+ signal on the channel for each stream within the session.
+ </tp:docstring>
+ </method>
+ <signal name="NewStreamHandler" tp:name-for-bindings="New_Stream_Handler">
+ <arg name="Stream_Handler" type="o">
+ <tp:docstring>
+ The path of a new object implementing the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media">StreamHandler</tp:dbus-ref>
+ interface.
+ </tp:docstring>
+ </arg>
+ <arg name="ID" type="u">
+ <tp:docstring>
+ The unique ID of the new stream
+ </tp:docstring>
+ </arg>
+ <arg name="Media_Type" type="u" tp:type="Media_Stream_Type">
+ <tp:docstring>
+ Type of media that this stream should handle
+ </tp:docstring>
+ </arg>
+ <arg name="Direction" type="u" tp:type="Media_Stream_Direction">
+ <tp:docstring>
+ Direction of this stream
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when a new stream handler has been created for this
+ session.
+ </tp:docstring>
+ </signal>
+ <method name="Ready" tp:name-for-bindings="Ready">
+ <tp:docstring>
+ Inform the connection manager that a client is ready to handle
+ this session handler (i.e. that it has connected to the
+ <tp:member-ref>NewStreamHandler</tp:member-ref> signal and done any
+ other necessary setup).
+ </tp:docstring>
+ </method>
+ <tp:docstring>
+ An media session handler is an object that handles a number of synchronised
+ media streams.
+ </tp:docstring>
+ </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
new file mode 100644
index 0000000..123ea8b
--- /dev/null
+++ b/spec/Media_Stream_Handler.xml
@@ -0,0 +1,725 @@
+<?xml version="1.0" ?>
+<node name="/Media_Stream_Handler" 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-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
+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.Media.StreamHandler">
+
+ <tp:struct name="Media_Stream_Handler_Candidate"
+ array-name="Media_Stream_Handler_Candidate_List">
+ <tp:member type="s" name="Name"/>
+ <tp:member type="a(usuussduss)" name="Transports"
+ tp:type="Media_Stream_Handler_Transport[]"/>
+ </tp:struct>
+
+ <tp:struct name="Media_Stream_Handler_Transport"
+ array-name="Media_Stream_Handler_Transport_List">
+ <tp:member type="u" name="Component_Number"/>
+ <tp:member type="s" name="IP_Address"/>
+ <tp:member type="u" name="Port"/>
+ <tp:member type="u" tp:type="Media_Stream_Base_Proto" name="Protocol"/>
+ <tp:member type="s" name="Subtype"/>
+ <tp:member type="s" name="Profile"/>
+ <tp:member type="d" name="Preference_Value"/>
+ <tp:member type="u" tp:type="Media_Stream_Transport_Type"
+ name="Transport_Type"/>
+ <tp:member type="s" name="Username"/>
+ <tp:member type="s" name="Password"/>
+ </tp:struct>
+
+ <tp:struct name="Media_Stream_Handler_Codec"
+ array-name="Media_Stream_Handler_Codec_List">
+ <tp:docstring>
+ Information about a codec supported by a client or a peer's client.
+ </tp:docstring>
+
+ <tp:member type="u" name="Codec_ID">
+ <tp:docstring>
+ The codec's payload identifier, as per RFC 3551 (static or dynamic)
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Name">
+ <tp:docstring>The codec's name</tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Media_Stream_Type" name="Media_Type">
+ <tp:docstring>Type of stream this codec supports</tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Clock_Rate">
+ <tp:docstring>Sampling frequency in Hertz</tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Number_Of_Channels">
+ <tp:docstring>Number of supported channels</tp:docstring>
+ </tp:member>
+ <tp:member type="a{ss}" name="Parameters" tp:type="String_String_Map">
+ <tp:docstring>Codec-specific optional parameters</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
+ <tp:added version="0.17.22"/>
+ <tp:docstring>
+ The IP addresses of possible STUN servers to use for NAT traversal, as
+ dotted-quad IPv4 address literals or RFC2373 IPv6 address literals.
+ This property cannot change once the stream has been created, so there
+ is no change notification. The IP addresses MUST NOT be given as DNS
+ hostnames.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ to make life easier for streaming implementations.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="CreatedLocally" tp:name-for-bindings="Created_Locally"
+ type="b" access="read">
+ <tp:added version="0.17.22"/>
+ <tp:docstring>
+ True if we were the creator of this stream, false otherwise.
+ <tp:rationale>
+ This information is needed for some nat traversal mechanisms, such
+ as ICE-UDP, where the creator gets the role of the controlling agent.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="NATTraversal" tp:name-for-bindings="NAT_Traversal"
+ type="s" access="read">
+ <tp:added version="0.17.22"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The transport (NAT traversal technique) to be used for this
+ stream. Well-known values include:</p>
+
+ <dl>
+ <dt>none</dt>
+ <dd>Raw UDP, with or without STUN, should be used. If the
+ <tp:member-ref>STUNServers</tp:member-ref> property is non-empty,
+ STUN SHOULD be used.</dd>
+
+ <dt>stun</dt>
+ <dd>A deprecated synonym for 'none'.</dd>
+
+ <dt>gtalk-p2p</dt>
+ <dd>Google Talk peer-to-peer connectivity establishment should be
+ used, as implemented in libjingle 0.3.</dd>
+
+ <dt>ice-udp</dt>
+ <dd>Interactive Connectivity Establishment should be used,
+ as defined by the IETF MMUSIC working group.</dd>
+
+ <dt>wlm-8.5</dt>
+ <dd>The transport used by Windows Live Messenger 8.5 or later,
+ which resembles ICE draft 6, should be used.</dd>
+
+ <dt>wlm-2009</dt>
+ <dd>The transport used by Windows Live Messenger 2009 or later,
+ which resembles ICE draft 19, should be used.</dd>
+ </dl>
+
+ <p>This property cannot change once the stream has been created, so
+ there is no change notification.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RelayInfo" type="aa{sv}" access="read"
+ tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings describing TURN or Google relay servers
+ available for the client to use in its candidate gathering, as
+ determined from the protocol. Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code> - s</dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal. This MUST NOT
+ be a DNS hostname.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ and make life easier for streaming implementations.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>type</code> - s</dt>
+ <dd>
+ <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code>.</p>
+
+ <p>The precise meaning of this key depends on the
+ <tp:member-ref>NATTraversal</tp:member-ref> property: if
+ NATTraversal is <code>ice-udp</code>, <code>tls</code> means
+ TLS over TCP as referenced by ICE draft 19, and if
+ NATTraversal is <code>gtalk-p2p</code>, <code>tls</code> means
+ a fake SSL session over TCP as implemented by libjingle.</p>
+ </dd>
+
+ <dt><code>port</code> - q</dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code> - s</dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code> - s</dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code> - u</dt>
+ <dd>The component number to use this relay server for, as an
+ ASCII unsigned integer; if not included, this relay server
+ may be used for any or all components.
+
+ <tp:rationale>
+ In ICE draft 6, as used by Google Talk, credentials are only
+ valid once, so each component needs relaying separately.
+ </tp:rationale>
+ </dd>
+ </dl>
+
+ <tp:rationale>
+ <p>An equivalent of the gtalk-p2p-relay-token property on
+ MediaSignalling channels is not included here. The connection
+ manager should be responsible for making the necessary HTTP
+ requests to turn the token into a username and password.</p>
+ </tp:rationale>
+
+ <p>The type of relay server that this represents depends on
+ the value of the <tp:member-ref>NATTraversal</tp:member-ref>
+ property. If NATTraversal is ice-udp, this is a TURN server;
+ if NATTraversal is gtalk-p2p, this is a Google relay server;
+ otherwise, the meaning of RelayInfo is undefined.</p>
+
+ <p>If relaying is not possible for this stream, the list is empty.</p>
+
+ <p>This property cannot change once the stream has been created, so
+ there is no change notification.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="AddRemoteCandidate"
+ tp:name-for-bindings="Add_Remote_Candidate">
+ <arg name="Candidate_ID" type="s">
+ <tp:docstring>
+ String identifier for this candidate
+ </tp:docstring>
+ </arg>
+ <arg name="Transports" type="a(usuussduss)"
+ tp:type="Media_Stream_Handler_Transport[]">
+ <tp:docstring>
+ Array of transports for this candidate with fields,
+ as defined in NewNativeCandidate
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal emitted when the connection manager wishes to inform the
+ client of a new remote candidate.
+ </tp:docstring>
+ </signal>
+ <signal name="Close" tp:name-for-bindings="Close">
+ <tp:docstring>
+ Signal emitted when the connection manager wishes the stream to be
+ closed.
+ </tp:docstring>
+ </signal>
+ <method name="CodecChoice" tp:name-for-bindings="Codec_Choice">
+ <arg direction="in" name="Codec_ID" type="u"/>
+ <tp:docstring>
+ Inform the connection manager of codec used to receive data.
+ </tp:docstring>
+ </method>
+ <method name="Error" tp:name-for-bindings="Error">
+ <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error">
+ <tp:docstring>
+ ID of error, from the MediaStreamError enumeration
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ String describing the error
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform the connection manager that an error occured in this stream. The
+ connection manager should emit the StreamError signal for the stream on
+ the relevant channel, and remove the stream from the session.
+ </tp:docstring>
+ </method>
+ <tp:enum name="Media_Stream_Error" type="u">
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ An unknown error occured.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="EOS" value="1">
+ <tp:docstring>
+ The end of the stream was reached.
+ </tp:docstring>
+ <tp:deprecated version="0.17.27">
+ This error has no use anywhere. In Farsight 1 times, it was used to
+ indicate a GStreamer EOS (when the end of a file is reached). But
+ since this is for live calls, it makes no sense.
+ </tp:deprecated>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no common codecs between the local side
+ and the other particpants in the call. The possible codecs are not
+ signalled here: the streaming implementation is assumed to report
+ them in an implementation-dependent way, e.g. Farsight should use
+ GstMissingElement.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connection_Failed" value="3">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ A network connection for the Media could not be established or was
+ lost.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Network_Error" value="4">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the networking stack
+ (other than the connection failure).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="No_Codecs" value="5">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no installed codecs for this media type.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_CM_Behavior" value="6">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ The CM is doing something wrong.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Media_Error" value="7">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the media processing stack.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ <method name="NativeCandidatesPrepared"
+ tp:name-for-bindings="Native_Candidates_Prepared">
+ <tp:docstring>
+ Informs the connection manager that all possible native candisates
+ have been discovered for the moment.
+ </tp:docstring>
+ </method>
+ <method name="NewActiveCandidatePair"
+ tp:name-for-bindings="New_Active_Candidate_Pair">
+ <arg direction="in" name="Native_Candidate_ID" type="s"/>
+ <arg direction="in" name="Remote_Candidate_ID" type="s"/>
+ <tp:docstring>
+ Informs the connection manager that a valid candidate pair
+ has been discovered and streaming is in progress.
+ </tp:docstring>
+ </method>
+ <method name="NewActiveTransportPair"
+ tp:name-for-bindings="New_Active_Transport_Pair">
+ <arg direction="in" name="Native_Candidate_ID" type="s"/>
+ <arg direction="in" name="Native_Transport" type="(usuussduss)"
+ tp:type="Media_Stream_Handler_Transport"/>
+ <arg direction="in" name="Remote_Candidate_ID" type="s"/>
+ <arg direction="in" name="Remote_Transport" type="(usuussduss)"
+ tp:type="Media_Stream_Handler_Transport"/>
+ <tp:docstring>
+ <p>Informs the connection manager that a valid transport pair
+ has been discovered and streaming is in progress. Component
+ id MUST be the same for both transports and the pair is
+ only valid for that component.</p>
+
+ <tp:rationale>
+ <p>The connection manager might need to send the details of
+ the active transport pair (e.g. c and o parameters of SDP
+ body need to contain address of selected native RTP transport
+ as stipulated by RFC 5245). However, the candidate ID might
+ not be enough to determine these info if the transport was
+ found after <tp:member-ref>NativeCandidatesPrepared</tp:member-ref>
+ has been called (e.g. peer reflexive ICE candidate). </p>
+ </tp:rationale>
+
+ <p>This method must be called before
+ <tp:member-ref>NewActiveCandidatePair</tp:member-ref>.</p>
+
+ <tp:rationale>
+ <p>This way, connection managers supporting this method can
+ safely ignore subsequent
+ <tp:member-ref>NewActiveCandidatePair</tp:member-ref> call.</p>
+ </tp:rationale>
+
+ <p>Connection managers SHOULD NOT implement this method unless
+ they need to inform the peer about selected transports. As a
+ result, streaming implementations MUST NOT treat errors raised
+ by this method as fatal.</p>
+
+ <tp:rationale>
+ <p>Usually, connection managers only need to do one answer/offer
+ round-trip. However, some protocols give the possibility to
+ to send an updated offer (e.g. ICE defines such mechanism to
+ avoid some race conditions and to properly set the state of
+ gateway devices).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+ <tp:enum name="Media_Stream_Base_Proto" type="u">
+ <tp:enumvalue suffix="UDP" value="0">
+ <tp:docstring>UDP (User Datagram Protocol)</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="TCP" value="1">
+ <tp:docstring>TCP (Transmission Control Protocol)</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ <method name="NewNativeCandidate"
+ tp:name-for-bindings="New_Native_Candidate">
+ <arg direction="in" name="Candidate_ID" type="s">
+ <tp:docstring>
+ String identifier for this candidate
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Transports" type="a(usuussduss)"
+ tp:type="Media_Stream_Handler_Transport[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Array of transports for this candidate, with fields:
+ <ul>
+ <li>component number</li>
+ <li>IP address (as a string)</li>
+ <li>port</li>
+ <li>base network protocol (one of the values of MediaStreamBaseProto)</li>
+ <li>proto subtype (e.g. RTP)</li>
+ <li>proto profile (e.g. AVP)</li>
+ <li>our preference value of this transport (double in range 0.0-1.0
+ inclusive); 1 signals the most preferred transport</li>
+ <li>transport type, one of the values of MediaStreamTransportType</li>
+ <li>username if authentication is required</li>
+ <li>password if authentication is required</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform this MediaStreamHandler that a new native transport candidate
+ has been ascertained.
+ </tp:docstring>
+ </method>
+ <tp:enum name="Media_Stream_Transport_Type" type="u">
+ <tp:enumvalue suffix="Local" value="0">
+ <tp:docstring>
+ A local address
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Derived" value="1">
+ <tp:docstring>
+ An external address derived by a method such as STUN
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Relay" value="2">
+ <tp:docstring>
+ An external stream relay
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ <method name="Ready" tp:name-for-bindings="Ready">
+ <arg direction="in" name="Codecs" type="a(usuuua{ss})"
+ tp:type="Media_Stream_Handler_Codec[]">
+ <tp:docstring>
+ Locally-supported codecs.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform the connection manager that a client is ready to handle
+ this StreamHandler. Also provide it with info about all supported
+ codecs.
+ </tp:docstring>
+ </method>
+ <method name="SetLocalCodecs" tp:name-for-bindings="Set_Local_Codecs">
+ <arg name="Codecs" type="a(usuuua{ss})" direction="in"
+ tp:type="Media_Stream_Handler_Codec[]">
+ <tp:docstring>
+ Locally-supported codecs
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Used to provide codecs after Ready(), so the media client can go
+ ready for an incoming call and exchange candidates/codecs before
+ knowing what local codecs are available.</p>
+
+ <p>This is useful for gatewaying calls between two connection managers.
+ Given an incoming call, you need to call
+ <tp:member-ref>Ready</tp:member-ref> to get the remote codecs before
+ you can use them as the "local" codecs to place the outgoing call,
+ and hence receive the outgoing call's remote codecs to use as the
+ incoming call's "local" codecs.</p>
+
+ <p>In this situation, you would pass an empty list of codecs to the
+ incoming call's Ready method, then later call SetLocalCodecs on the
+ incoming call in order to respond to the offer.</p>
+ </tp:docstring>
+ </method>
+ <signal name="RemoveRemoteCandidate"
+ tp:name-for-bindings="Remove_Remote_Candidate">
+ <arg name="Candidate_ID" type="s">
+ <tp:docstring>
+ String identifier for remote candidate to drop
+ </tp:docstring>
+ </arg>
+ <tp:deprecated version="0.17.18">
+ There is no case where you want to release candidates (except
+ for an ICE reset, and there you'd want to replace then all,
+ using <tp:member-ref>SetRemoteCandidateList</tp:member-ref>).
+ </tp:deprecated>
+ <tp:docstring>
+ Signal emitted when the connection manager wishes to inform the
+ client that the remote end has removed a previously usable
+ candidate.
+
+ <tp:rationale>
+ It seemed like a good idea at the time, but wasn't.
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+ <signal name="SetActiveCandidatePair"
+ tp:name-for-bindings="Set_Active_Candidate_Pair">
+ <arg name="Native_Candidate_ID" type="s"/>
+ <arg name="Remote_Candidate_ID" type="s"/>
+ <tp:docstring>
+ Emitted by the connection manager to inform the client that a
+ valid candidate pair has been discovered by the remote end
+ and streaming is in progress.
+ </tp:docstring>
+ </signal>
+ <signal name="SetRemoteCandidateList"
+ tp:name-for-bindings="Set_Remote_Candidate_List">
+ <arg name="Remote_Candidates" type="a(sa(usuussduss))"
+ tp:type="Media_Stream_Handler_Candidate[]">
+ <tp:docstring>
+ A list of candidate id and a list of transports
+ as defined in NewNativeCandidate
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal emitted when the connection manager wishes to inform the
+ client of all the available remote candidates at once.
+ </tp:docstring>
+ </signal>
+ <signal name="SetRemoteCodecs" tp:name-for-bindings="Set_Remote_Codecs">
+ <arg name="Codecs" type="a(usuuua{ss})"
+ tp:type="Media_Stream_Handler_Codec[]">
+ <tp:docstring>
+ Codecs supported by the remote peer.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal emitted when the connection manager wishes to inform the
+ client of the codecs supported by the remote end.
+ If these codecs are compatible with the remote codecs, then the client
+ must call <tp:member-ref>SupportedCodecs</tp:member-ref>,
+ otherwise call <tp:member-ref>Error</tp:member-ref>.
+ </tp:docstring>
+ </signal>
+ <signal name="SetStreamPlaying" tp:name-for-bindings="Set_Stream_Playing">
+ <arg name="Playing" type="b"/>
+ <tp:docstring>
+ If emitted with argument TRUE, this means that the connection manager
+ wishes to set the stream playing; this means that the streaming
+ implementation should expect to receive data. If emitted with argument
+ FALSE this signal is basically meaningless and should be ignored.
+
+ <tp:rationale>
+ We're very sorry.
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+ <signal name="SetStreamSending" tp:name-for-bindings="Set_Stream_Sending">
+ <arg name="Sending" type="b"/>
+ <tp:docstring>
+ Signal emitted when the connection manager wishes to set whether or not
+ the stream sends to the remote end.
+ </tp:docstring>
+ </signal>
+ <signal name="StartTelephonyEvent"
+ tp:name-for-bindings="Start_Telephony_Event">
+ <arg name="Event" type="y" tp:type="DTMF_Event">
+ <tp:docstring>
+ A telephony event code.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that a telephony event (as defined by RFC 4733) is transmitted
+ over this stream until StopTelephonyEvent is called.
+ </tp:docstring>
+ </signal>
+ <signal name="StartNamedTelephonyEvent"
+ tp:name-for-bindings="Start_Named_Telephony_Event">
+ <tp:added version="0.21.2"/>
+ <arg name="Event" type="y" tp:type="DTMF_Event">
+ <tp:docstring>
+ A telephony event code as defined by RFC 4733.
+ </tp:docstring>
+ </arg>
+ <arg name="Codec_ID" type="u">
+ <tp:docstring>
+ The payload type to use when sending events. The value 0xFFFFFFFF
+ means to send with the already configured event type instead of using
+ the specified one.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that a telephony event (as defined by RFC 4733) is transmitted
+ over this stream until StopTelephonyEvent is called. This differs from
+ StartTelephonyEvent in that you force the event to be transmitted
+ as a RFC 4733 named event, not as sound. You can also force a specific
+ Codec ID.
+ </tp:docstring>
+ </signal>
+ <signal name="StartSoundTelephonyEvent"
+ tp:name-for-bindings="Start_Sound_Telephony_Event">
+ <tp:added version="0.21.2"/>
+ <arg name="Event" type="y" tp:type="DTMF_Event">
+ <tp:docstring>
+ A telephony event code as defined by RFC 4733.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Request that a telephony event (as defined by RFC 4733) is transmitted
+ over this stream until StopTelephonyEvent is called. This differs from
+ StartTelephonyEvent in that you force the event to be transmitted
+ as sound instead of as a named event.
+ </tp:docstring>
+ </signal>
+ <signal name="StopTelephonyEvent"
+ tp:name-for-bindings="Stop_Telephony_Event">
+ <tp:docstring>
+ Request that any ongoing telephony events (as defined by RFC 4733)
+ being transmitted over this stream are stopped.
+ </tp:docstring>
+ </signal>
+ <method name="StreamState" tp:name-for-bindings="Stream_State">
+ <arg direction="in" name="State" type="u" tp:type="Media_Stream_State"/>
+ <tp:docstring>
+ Informs the connection manager of the stream's current state, as
+ as specified in Channel.Type.StreamedMedia::ListStreams.
+ </tp:docstring>
+ </method>
+
+ <method name="SupportedCodecs" tp:name-for-bindings="Supported_Codecs">
+ <arg direction="in" name="Codecs" type="a(usuuua{ss})"
+ tp:type="Media_Stream_Handler_Codec[]">
+ <tp:docstring>
+ Locally supported codecs.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform the connection manager of the supported codecs for this session.
+ This is called after the connection manager has emitted SetRemoteCodecs
+ to notify what codecs are supported by the peer, and will thus be an
+ intersection of all locally supported codecs (passed to Ready)
+ and those supported by the peer.
+ </tp:docstring>
+ </method>
+
+ <method name="CodecsUpdated" tp:name-for-bindings="Codecs_Updated">
+ <arg direction="in" name="Codecs" type="a(usuuua{ss})"
+ tp:type="Media_Stream_Handler_Codec[]">
+ <tp:docstring>
+ Locally supported codecs, which SHOULD be the same as were previously
+ in effect, but possibly with different parameters.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Inform the connection manager that the parameters of the supported
+ codecs for this session have changed. The connection manager should
+ send the new parameters to the remote contact.
+
+ <tp:rationale>
+ This is required for H.264 and Theora, for example.
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <signal name="SetStreamHeld" tp:name-for-bindings="Set_Stream_Held">
+ <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:name-for-bindings="Hold_State">
+ <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:name-for-bindings="Unhold_Failure">
+ <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
+ available.
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
new file mode 100644
index 0000000..bc9c8b2
--- /dev/null
+++ b/spec/Properties_Interface.xml
@@ -0,0 +1,194 @@
+<?xml version="1.0" ?>
+<node name="/Properties_Interface" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2005-2007 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.Properties">
+
+ <tp:struct name="Property_Spec" array-name="Property_Spec_List">
+ <tp:docstring>A struct (property ID, property name, D-Bus signature,
+ flags) representing a property, as returned by ListProperties on the
+ Properties interface.</tp:docstring>
+ <tp:member type="u" name="Property_ID"/>
+ <tp:member type="s" name="Name"/>
+ <tp:member type="s" tp:type="DBus_Signature" name="Signature"/>
+ <tp:member type="u" tp:type="Property_Flags" name="Flags"/>
+ </tp:struct>
+
+ <tp:struct name="Property_Flags_Change"
+ array-name="Property_Flags_Change_List">
+ <tp:docstring>A struct (property ID, flags) representing a change to
+ a property's flags, as seen in the PropertyFlagsChanged signal on
+ the Properties interface.</tp:docstring>
+ <tp:member type="u" name="Property_ID"/>
+ <tp:member type="u" name="New_Flags"/>
+ </tp:struct>
+
+ <tp:simple-type name="Property_ID" type="u" array-name="Property_ID_List">
+ <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" tp:type="Property_ID" name="Identifier"/>
+ <tp:member type="v" name="Value"/>
+ </tp:struct>
+
+ <method name="GetProperties" tp:name-for-bindings="Get_Properties">
+ <tp:docstring>
+ Returns an array of (identifier, value) pairs containing the current
+ values of the given properties.
+ </tp:docstring>
+ <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[]"
+ name="Values">
+ <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of structs containing:</p>
+ <ul>
+ <li>integer identifiers</li>
+ <li>variant boxed values</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ Some property identifier requested is invalid
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
+ <tp:docstring>
+ Some property requested does not have the PROPERTY_FLAG_READ flag
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+ <method name="ListProperties" tp:name-for-bindings="List_Properties">
+ <tp:docstring>
+ Returns a dictionary of the properties available on this channel.
+ </tp:docstring>
+ <arg direction="out" type="a(ussu)" tp:type="Property_Spec[]"
+ name="Available_Properties">
+ <!-- XXX: if we're ever breaking API compatibility, make this
+ a{u(ssu)} ? -->
+ <tp:docstring>
+ An array of structs containing:
+ <ul>
+ <li>an integer identifier</li>
+ <li>a string property name</li>
+ <li>a string representing the D-Bus signature of this property</li>
+ <li>a bitwise OR of the flags applicable to this property</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ </method>
+ <signal name="PropertiesChanged" tp:name-for-bindings="Properties_Changed">
+ <tp:docstring>
+ Emitted when the value of readable properties has changed.
+ </tp:docstring>
+ <arg name="Properties" type="a(uv)" tp:type="Property_Value[]">
+ <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of structs containing:</p>
+ <ul>
+ <li>integer identifiers</li>
+ <li>variant boxed values</li>
+ </ul>
+ <p>The array should contain only properties whose values have
+ actually changed.</p>
+ </tp:docstring>
+ </arg>
+ </signal>
+ <signal name="PropertyFlagsChanged"
+ tp:name-for-bindings="Property_Flags_Changed">
+ <tp:docstring>
+ Emitted when the flags of some room properties have changed.
+ </tp:docstring>
+ <arg name="Properties" type="a(uu)" tp:type="Property_Flags_Change[]">
+ <!-- XXX: if we're ever breaking API compatibility, make this a{uu} -->
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of structs containing:</p>
+ <ul>
+ <li>integer identifiers</li>
+ <li>a bitwise OR of the current flags</li>
+ </ul>
+ <p>The array should contain only properties whose flags have actually
+ changed.</p>
+ </tp:docstring>
+ </arg>
+ </signal>
+ <method name="SetProperties" tp:name-for-bindings="Set_Properties">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Takes an array of (identifier, value) pairs containing desired
+ values to set the given properties. In the case of any errors, no
+ properties will be changed. When the changes have been acknowledged
+ by the server, the PropertiesChanged signal will be emitted.</p>
+
+ <p>All properties given must have the PROPERTY_FLAG_WRITE flag, or
+ PermissionDenied will be returned. If any variants are of the wrong
+ type, NotAvailable will be returned. If any given property identifiers
+ are invalid, InvalidArgument will be returned.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Properties" type="a(uv)"
+ tp:type="Property_Value[]">
+ <!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
+ <tp:docstring>
+ An array mapping integer property identifiers to boxed values
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <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:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for channels and other objects, to allow querying and setting
+ properties. ListProperties returns which properties are valid for
+ the given channel, including their type, and an integer handle used to
+ refer to them in GetProperties, SetProperties, and the PropertiesChanged
+ signal. The values are represented by D-Bus variant types, and are
+ accompanied by flags indicating whether or not the property is readable or
+ writable.</p>
+
+ <p>Each property also has a flags value to indicate what methods are
+ available. This is a bitwise OR of PropertyFlags values.</p>
+ </tp:docstring>
+ <tp:flags name="Property_Flags" value-prefix="Property_Flag" type="u">
+ <tp:flag suffix="Read" value="1">
+ <tp:docstring>The property can be read</tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Write" value="2">
+ <tp:docstring>The property can be written</tp:docstring>
+ </tp:flag>
+ </tp:flags>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
new file mode 100644
index 0000000..5e2c9b1
--- /dev/null
+++ b/spec/Protocol.xml
@@ -0,0 +1,485 @@
+<?xml version="1.0" ?>
+<node name="/Protocol"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Protocol">
+ <tp:added version="0.19.10">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An object representing a protocol for which this <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+ can create <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s.</p>
+
+ <p>Each Protocol object has the same well-known bus name as its parent
+ ConnectionManager. Its object path is formed by taking the
+ ConnectionManager's object path and appending '/', followed by the
+ <tp:type>Protocol</tp:type> name with any hyphen/minus '-' converted
+ to underscores '_'.</p>
+
+ <tp:rationale>
+ <p>This is the same as the representation of protocol names
+ in Account object paths, and in Connection object paths and bus
+ names. For instance, telepathy-gabble and telepathy-salut would
+ implement objects at
+ <code>/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber</code>
+ and
+ <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>,
+ respectively.</p>
+ </tp:rationale>
+
+ <p>If the ConnectionManager has a <tt>.manager</tt> file, each
+ Protocol's immutable properties must be represented in that file;
+ the representation is described as part of the documentation for
+ each property. For instance, a very simple ConnectionManager with one
+ Protocol might be represented like this:</p>
+
+<pre>
+[ConnectionManager]
+Interfaces=
+
+[Protocol example]
+Interfaces=
+ConnectionInterfaces=org.freedesktop.Telepathy.Connection.Interface.Requests;
+param-account=s required
+param-password=s required secret
+RequestableChannelClasses=text;
+VCardField=x-example
+EnglishName=Example
+Icon=im-example
+AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication;
+
+[text]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+</pre>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ access="read" type="as" tp:type="DBus_Interface[]"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of interfaces supported by this Protocol object.</p>
+
+ <p>This property should not be confused with
+ <tp:member-ref>ConnectionInterfaces</tp:member-ref>,
+ which refers to the interfaces of <em>connections</em> to this
+ protocol.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ (as described as part of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface) MUST cache this
+ property in the protocol's section of the <code>.manager</code>
+ file, using the key <code>Interfaces</code>. The corresponding value
+ is a list of D-Bus interface names, each followed by a semicolon.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Parameters" tp:name-for-bindings="Parameters"
+ access="read" type="a(susv)" tp:type="Param_Spec[]"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The parameters which must or may be provided to the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager"
+ >RequestConnection</tp:dbus-ref> method when connecting to the
+ given protocol.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ (as described as part of the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface) MUST cache this
+ property in the protocol's section of the <code>.manager</code>
+ file via keys of the form <code>param-<em>p</em></code> and
+ <code>default-<em>p</em></code>, as documented in the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> interface.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionInterfaces"
+ tp:name-for-bindings="Connection_Interfaces"
+ access="read" type="as" tp:type="DBus_Interface[]"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of interface names which might be in the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection"
+ >Interfaces</tp:dbus-ref> property of a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref> to this protocol. Whether a Connection
+ will have all, some or none of these interfaces depends on server
+ capabilities.</p>
+
+ <p>This property should not be confused with
+ <tp:member-ref>Interfaces</tp:member-ref>.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file, using the key
+ <code>ConnectionInterfaces</code>. The corresponding value
+ is a list of D-Bus interface names, each followed by a semicolon.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RequestableChannelClasses"
+ tp:name-for-bindings="Requestable_Channel_Classes"
+ access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of channel classes which might be requestable from a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref> to this protocol (i.e. they will,
+ or might, appear in the Connection's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref> property).</p>
+
+ <p>Whether a Connection will have all, some or none of these
+ requestable channel classes depends on server capabilities;
+ similarly, individual contacts are not guaranteed to support
+ all of these channel classes.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file, using the key
+ <code>RequestableChannelClasses</code>. The corresponding value
+ is a list of opaque strings, each followed by a semicolon; each
+ of those strings is the name of a group in the <code>.manager</code>
+ file which represents a channel class.</p>
+
+ <p>The names of the groups representing channel classes are not
+ significant, and MUST NOT be interpreted. When writing
+ <tt>.manager</tt> files, authors MAY choose mnemonic group names,
+ generate group names mechanically (e.g. with an incrementing
+ integer), or use some combination of these.</p>
+
+ <p>Each group representing a channel class has a key
+ <code>allowed</code> which is a list of D-Bus property names
+ representing allowed parameters. Any other keys that do not contain
+ a space MUST be ignored. Any key containing a space represents
+ a fixed property; the key has the form
+ "<code><em>propertyname</em> <em>type</em></code>", and the value
+ is encoded in the same way as for the <code>default-<em>p</em></code>
+ keys described in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >ConnectionManager</tp:dbus-ref> documentation.</p>
+
+ <p>Connection managers that have channel classes whose fixed
+ properties are not representable in this form SHOULD NOT have
+ <code>.manager</code> files.</p>
+
+ <p>For instance, this <code>.manager</code> file could represent
+ a connection manager that supports 1-1 Text messages and
+ StreamedMedia audio calls:</p>
+
+<pre>[Protocol jabber]
+param-account=s required
+param-password=s required
+RequestableChannelClasses=rcc0;rcc1;
+
+[rcc0]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;
+
+[rcc1]
+org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.StreamedMedia
+org.freedesktop.Telepathy.Channel.TargetHandleType u=1
+allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID;org.freedesktop.Telepathy.Channel.Type.StreamedMedia.InitialAudio;
+</pre>
+ </tp:docstring>
+ </property>
+
+ <property name="VCardField" tp:name-for-bindings="VCard_Field"
+ access="read" type="s" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the most common vCard field used for this protocol's
+ contact identifiers, normalized to lower case, or the empty string
+ if there is no such field.</p>
+
+ <p>For example, this would be <code>x-jabber</code> for
+ Jabber/XMPP (including Google Talk), or <code>tel</code> for
+ the <abbr title="Public Switched Telephone Network">PSTN</abbr>.</p>
+
+ <p>A more exhaustive list of addressable vCard fields can be found in
+ the Protocol's Addressing interface's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT">AddressableVCardFields</tp:dbus-ref>.</p>
+
+ <p>It is not necessarily valid to interpret contacts' identifiers
+ as values of this vCard field. For instance, telepathy-sofiasip
+ supports contacts whose identifiers are of the form
+ sip:jenny@example.com or tel:8675309, which would not normally
+ both be represented by any single vCard field. Arbitrary
+ handles/identifiers as vCard fields are represented
+ through the Connection's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Addressing.DRAFT</tp:dbus-ref>
+ contact attributes.</p>
+
+ <tp:rationale>
+ <p>This is taken from Mission Control profiles as used on Maemo 5.
+ One valid use of this field is to answer the question: given a
+ contact's vCard containing an X-JABBER field, how can you
+ communicate with the contact? By iterating through protocols
+ looking for an x-jabber VCardField, one can build up a list of
+ protocols that handle x-jabber, then offer the user a list of
+ accounts for those protocols and/or the option to create a new
+ account for one of those protocols.</p>
+ </tp:rationale>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file if it is non-empty, using the key
+ <code>VCardField</code>. The corresponding value
+ is a string, following the syntax of the "localestring" type from
+ the Desktop Entry Specification.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="EnglishName" tp:name-for-bindings="English_Name"
+ access="read" type="s" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the protocol in a form suitable for display to users,
+ such as "AIM" or "Yahoo!", or the empty string if none is
+ available.</p>
+
+ <p>This is effectively in the C locale (international English);
+ user interfaces requiring a localized protocol name SHOULD look
+ one up in their own message catalog based on either the Telepathy
+ <tp:type>Protocol</tp:type> name or this property, but SHOULD use
+ this English version as a fallback if no translated version can be
+ found.</p>
+
+ <tp:rationale>
+ <p>Many protocols are named after a company or product which isn't
+ translated in non-English locales. This also provides a fallback
+ display name, for UIs with no prior knowledge of a particular
+ protocol.</p>
+ </tp:rationale>
+
+ <p>If this property's value is empty, clients MAY fall back to using
+ the Telepathy <tp:type>Protocol</tp:type> name, possibly with its
+ capitalization adjusted.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file if it is non-empty, using the key
+ <code>EnglishName</code>. The corresponding value
+ is a string, following the syntax of the "localestring" type from
+ the Desktop Entry Specification.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Icon" tp:name-for-bindings="Icon"
+ access="read" type="s" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of an icon in the system's icon theme, such as "im-msn", or
+ the empty string.</p>
+
+ <tp:rationale>
+ <p>This can be used as a default if the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>
+ property is not set on an Account, or used by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>
+ to choose a default icon if none is set during account
+ creation.</p>
+ </tp:rationale>
+
+ <p>If this property's value is empty, clients MAY fall back to
+ generating a name based on the <tp:type>Protocol</tp:type> name.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file if it is non-empty, using the key
+ <code>Icon</code>. The corresponding value
+ is a string, following the syntax of the "localestring" type from
+ the Desktop Entry Specification.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="IdentifyAccount"
+ tp:name-for-bindings="Identify_Account">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Return a string which uniquely identifies the account to which the
+ given parameters would connect.</p>
+
+ <tp:rationale>
+ <p>For many protocols, this would return the well-known 'account'
+ parameter. However, for IRC the returned string would be composed
+ from the 'account' (i.e. nickname) and 'server' parameters.
+ AccountManager implementations can use this to form the
+ account-specific part of an Account's object path.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Parameters"
+ type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring>
+ A set of parameters as would be provided to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager"
+ >RequestConnection</tp:dbus-ref>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Account_ID" type="s">
+ <tp:docstring>
+ <p>An opaque string suitable for use as the account-specific part of
+ an <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Account</tp:dbus-ref>'s object path. This is not necessarily
+ globally unique, but should represent a "best-effort"
+ identification of the account.</p>
+
+ <tp:rationale>
+ <p>For a pathological case, consider a user signing in as
+ 'me@example.com' with 'server' set to either jabber1.example.com
+ or jabber2.example.com. Both of these should result in
+ me@example.com being returned from this method, even if the user
+ can actually be signed in to those two servers
+ simultaneously.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The IdentifyAccount method is not supported by this connection
+ manager. The caller SHOULD fall back to deriving identification
+ from the parameters.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="NormalizeContact"
+ tp:name-for-bindings="Normalize_Contact">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to normalize the given contact ID. Where possible, this
+ SHOULD return the same thing that would be returned by
+ InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection</tp:dbus-ref>.</p>
+
+ <p>If full normalization requires network activity or is otherwise
+ impossible to do without a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>,
+ this method SHOULD perform a best-effort normalization.</p>
+
+ <tp:rationale>
+ <p>One common example of a best-effort offline normalization
+ differing from the ideal normalization is XMPP.</p>
+
+ <p>On XMPP, contacts' JIDs should normally have the resource removed
+ during normalization, but for contacts in a MUC (chatroom), the
+ resource is an integral part of the JID - so the contact JID
+ alice@example.com/Empathy should normalize to alice@example.com,
+ but the in-MUC JID wonderland@conference.example.com/Alice should
+ normalize to itself.</p>
+
+ <p>While online, the connection manager has enough context to know
+ which chatrooms the user is in, and can infer from that whether
+ to remove resources, but the best-effort normalization performed
+ while offline does not have this context, so the best that can be
+ done is to remove the resource from all JIDs.</p>
+ </tp:rationale>
+
+ <p>This method MAY simply raise NotImplemented on some protocols.</p>
+
+ <tp:rationale>
+ <p>In link-local XMPP, you can't talk to someone who isn't present
+ on your local network, so normalizing identifiers in advance is
+ meaningless.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contact_ID" type="s">
+ <tp:docstring>
+ The identifier of a contact in this protocol
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Normalized_Contact_ID" type="s">
+ <tp:docstring>
+ The identifier of a contact in this protocol, normalized as much
+ as possible
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The NormalizeContact method is not supported by this connection
+ manager. The caller MAY recover by using the contact ID as-is.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="AuthenticationTypes"
+ tp:name-for-bindings="Authentication_Types" access="read" type="as"
+ tp:type="DBus_Interface[]" tp:immutable="yes">
+ <tp:added version="0.21.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of D-Bus interfaces which provide information as to
+ what kind of authentication channels can possibly appear
+ before the connection reaches the CONNECTED state.</p>
+
+ <p>These can either be channel types, or where the channel
+ type isn't enough information to be useful, interfaces
+ indicating a specific use of a channel type. For example,
+ <tp:dbus-ref namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref>
+ channels are obviously about TLS certificates so the channel
+ type would appear in this list. However, a
+ <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channel type alone does not explain enough about the authentication type
+ in use as it is merely a base for the channel interfaces that appear in
+ said channels. In this case, CMs should use the value of the
+ <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>
+ property in this list.</p>
+
+ <p>For example, if a protocol's
+ <tp:member-ref>AuthenticationTypes</tp:member-ref> contains
+ two values:</p>
+
+ <blockquote>
+ <pre>
+[ ...<tp:dbus-ref namespace="ofdT">Channel.Type.ServerTLSConnection</tp:dbus-ref>,
+ ...<tp:dbus-ref namespace="ofdT">Channel.Interface.SASLAuthentication</tp:dbus-ref> ]</pre></blockquote>
+
+ <p>This tells a client that before the connection status
+ reached CONNECTED, a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref>
+ could appear carrying a TLS certificate. It also tells the
+ client that before the connection status reaches CONNECTED, a
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
+ channel could also appear, where <tp:dbus-ref
+ namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>=<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>. A
+ hypothetical future Channel.Interface.Captcha interface would
+ also appear in this list if the CM might require the user
+ solve a captcha before connecting.</p>
+
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Protocol_Interface_Addressing.xml b/spec/Protocol_Interface_Addressing.xml
new file mode 100644
index 0000000..3722c3b
--- /dev/null
+++ b/spec/Protocol_Interface_Addressing.xml
@@ -0,0 +1,300 @@
+<?xml version="1.0" ?>
+<node name="/Protocol_Interface_Addressing"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface
+ name="org.freedesktop.Telepathy.Protocol.Interface.Addressing.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.12">(as draft)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for protocols that support multiple forms of
+ addressing contacts, for example through vCard addresses and URIs.</p>
+
+ <p>If the ConnectionManager has a <tt>.manager</tt> file, and it
+ supports this interface, the interface's immutable properties
+ must be represented in the file; the representation is described as
+ part of the documentation for each property.</p>
+
+ <p>For instance, a SIP connection manager might have the
+ following lines in the <tt>.manager</tt> file.</p>
+
+<pre>
+[Protocol sip]
+AddressableVCardFields=tel;x-sip;
+AddressableURISchemes=tel;sip;
+</pre>
+ </tp:docstring>
+
+ <property name="AddressableVCardFields"
+ tp:name-for-bindings="Addressable_VCard_Fields"
+ access="read" type="as">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard fields that can be used to request a contact with
+ normalized to lower case. If the <code>URL</code> vCard
+ field is addressable, a colon, followed by the supported URI
+ schemes will be concatenated.</p>
+
+ <p>For example: <code>["tel", "x-sip"]</code>.</p>
+
+ <p>The <code>url</code> vCard field MUST NOT appear here; see
+ <tp:member-ref>AddressableURISchemes</tp:member-ref> instead.</p>
+
+ <tp:rationale>
+ <p>In practice, protocols have a limited set of URI
+ schemes that make sense to resolve as a contact.</p>
+ </tp:rationale>
+
+ <p>This property should only be used when the connection is
+ offline. When it is connected the addressable fields should be
+ retrieved from the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s
+ TargetVCardField fixed-property instead.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file if it is non-empty, using the key
+ <code>AddressableVCardFields</code>. The corresponding value
+ is a list of strings, each followed with a semicolon and in the
+ syntax of the "localestring" type from the Desktop Entry
+ Specification.</p>
+
+ <p>Well-known vCard fields:</p>
+
+ <dl>
+ <dt><code>tel</code></dt>
+ <dd>The TEL vCard field. Used for phone numbers.</dd>
+ <dt><code>x-sip</code></dt>
+ <dd>The X-SIP vCard field. Used for SIP addresses.</dd>
+ <dt><code>x-aim</code></dt>
+ <dd>The X-AIM vCard field. Used for AIM user IDs.</dd>
+ <dt><code>x-icq</code></dt>
+ <dd>The X-ICQ vCard field. Used for ICQ UINs.</dd>
+ <dt><code>x-skype</code></dt>
+ <dd>The X-SKYPE vCard field. Used for Skype user names or
+ telephone numbers. There is also a X-SKYPE-USERNAME field,
+ but for Telepathy purposes, <code>x-skype</code> is preferred</dd>
+ <dt><code>x-groupwise</code></dt>
+ <dd>The X-GROUPWISE vCard field. Used for Groupwise contacts.</dd>
+ <dt><code>x-gadugadu</code></dt>
+ <dd>The X-GADUGADU vCard field. Used for Gadu-Gadu contacts.</dd>
+ <dt><code>x-jabber</code></dt>
+ <dd>The X-JABBER vCard field. Used for XMPP JIDs.</dd>
+ <dt><code>x-msn</code></dt>
+ <dd>The X-MSN vCard field. Used for MSN contacts.</dd>
+ <dt><code>x-yahoo</code></dt>
+ <dd>The X-YAHOO vCard field. Used for Yahoo! IDs.</dd>
+ </dl>
+
+ </tp:docstring>
+ </property>
+
+ <property name="AddressableURISchemes"
+ tp:name-for-bindings="Addressable_URI_Schemes"
+ access="read" type="as">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The URI schemes that are supported by this protocol.</p>
+
+ <p>For example: <code>["tel", "sip"]</code>.</p>
+
+ <p>This property should only be used when the connection is
+ offline. When it is connected the addressable URI schemes should be
+ retrieved from the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.RequestableChannelClasses</tp:dbus-ref>'s
+ TargetURIScheme fixed-property instead.</p>
+
+ <p>Connection managers with a <code>.manager</code> file
+ MUST cache this property in the protocol's section of the
+ <code>.manager</code> file if it is non-empty, using the key
+ <code>AddressableURISchemes</code>. The corresponding value
+ is a list of strings, each followed with a semicolon and in the
+ syntax of the "localestring" type from the Desktop Entry
+ Specification.</p>
+
+ <p>Well-known URI schemes:</p>
+
+ <dl>
+ <dt><code>sip</code></dt>
+ <dd>SIP protocol.
+ For example: <code>sip:julien@example.com</code>.</dd>
+ <dt><code>sips</code></dt>
+ <dd>Secure (encrypted) SIP protocol.
+ For example: <code>sips:julien@example.com</code>.</dd>
+ <dt><code>tel</code></dt>
+ <dd>Used for telephone numbers.
+ For example: <code>tel:+12065551234</code>.</dd>
+ <dt><code>xmpp</code></dt>
+ <dd>XMPP protocol.
+ For example: <code>xmpp:julien@example.com</code>.</dd>
+ <dt><code>msnim</code></dt>
+ <dd>For the purposes of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ the verb part is ignored, and SHOULD be <code>add</code>; the
+ <code>contact</code> field in the query string is used to
+ identify the contact.
+ For example: <code>msnim:add?contact=julien</code>.</dd>
+ <dt><code>aim</code></dt>
+ <dd>For the purposes of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ the verb part is ignored, and SHOULD be <code>addbuddy</code>; the
+ <code>screenname</code> field in the query string is used to
+ identify the contact.
+ For example: <code>aim:addbuddy?screenname=julien</code>.</dd>
+ <dt><code>skype</code></dt>
+ <dd>Skype protocol.
+ For example: <code>skype:julien</code>.</dd>
+ <dt><code>ymsgr</code></dt>
+ <dd>For the purposes of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Protocol.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Addressing.DRAFT</tp:dbus-ref>,
+ the verb part is ignored, and SHOULD be <code>addfriend</code>; the
+ query string is used to identify the contact.
+ For example: <code>ymsgr:addfriend?julien</code>.</dd>
+ <dt><code>gg</code></dt>
+ <dd>Gadu-Gadu protocol.
+ For example: <code>gg:julien</code>.</dd>
+ </dl>
+ </tp:docstring>
+ </property>
+
+ <method name="NormalizeVCardAddress"
+ tp:name-for-bindings="Normalize_VCard_Address">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to normalize the given vCard address. Where possible, this
+ SHOULD return an address that would appear in the
+ <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/addresses</code>
+ attribute for a contact on a connected
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
+ </p>
+
+ <p>If full normalization requires network activity or is otherwise
+ impossible to do without a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>,
+ this method SHOULD perform a best-effort normalization.</p>
+
+ <p>An example would be a vCard TEL field with a formatted
+ number in the form of <code>+1 (206) 555 1234</code>, this would be
+ normalized to <code>+12065551234</code>.</p>
+
+ <p>This method MAY simply raise NotImplemented on some
+ protocols, if it has no use.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="VCard_Field" type="s">
+ <tp:docstring>
+ The vCard field of the address we are normalizing. The
+ field name SHOULD be in lower case, and MUST appear in
+ <tp:member-ref>AddressableVCardFields</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="VCard_Address" type="s">
+ <tp:docstring>
+ The address to normalize.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Normalized_VCard_Address" type="s">
+ <tp:docstring>
+ The vCard address, normalized as much as possible.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The vCard field is not supported (it is not in
+ <tp:member-ref>AddressableVCardFields</tp:member-ref>).
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The address is syntactically incorrect.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="NormalizeURI"
+ tp:name-for-bindings="Normalize_URI">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to normalize the given contact URI. Where possible, this
+ SHOULD return an address that would appear in the
+ <code>org.freedesktop.Telepathy.Connection.Interface.Addressing.DRAFT/uris</code>
+ attribute for a contact on a connected
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>.
+ </p>
+
+ <p>If full normalization requires network activity or is otherwise
+ impossible to do without a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>,
+ this method SHOULD perform a best-effort normalization.</p>
+
+ <p>Example: <code>xmpp:eitan@EXAMPLE.COM</code> would be normalized to
+ <code>xmpp:eitan@example.com</code>.</p>
+
+ <p>This method MAY simply raise NotImplemented on some
+ protocols, if it has no use.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="URI" type="s">
+ <tp:docstring>
+ The URI to normalize. The URI's scheme (i.e. the part before
+ the first colon) MUST appear in
+ <tp:member-ref>AddressableURISchemes</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Normalized_URI" type="s">
+ <tp:docstring>
+ A URI, normalized as much as possible.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The URI scheme is not supported (it is not in
+ <tp:member-ref>AddressableURISchemes</tp:member-ref>).
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The URI is syntactically incorrect.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml
new file mode 100644
index 0000000..cd91351
--- /dev/null
+++ b/spec/Protocol_Interface_Avatars.xml
@@ -0,0 +1,157 @@
+<?xml version="1.0" ?>
+<node name="/Protocol_Interface_Avatars"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Protocol.Interface.Avatars">
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Protocol"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for protocols where it might be possible to set the
+ user's avatar, and the expected size limits and supported MIME types
+ are known before connecting.</p>
+
+ <tp:rationale>
+ <p>If the avatar requirements cannot be discovered while offline,
+ it's impossible to avoid setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Account</tp:dbus-ref>'s <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Avatar"
+ >Avatar</tp:dbus-ref> property to an unsupported avatar.</p>
+ </tp:rationale>
+
+ <p>Each property on this interface SHOULD be cached in the
+ <code>.manager</code> file, using a key of the same name as the
+ property in the <code>[Protocol <em>proto</em>]</code>
+ group. All properties are encoded in ASCII decimal in the obvious
+ way, except for
+ <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is
+ encoded as a sequence of strings each followed by a semicolon
+ (as for the "localestrings" type in the Desktop Entry
+ Specification).</p>
+
+ <p>For instance, an XMPP connection manager might have this
+ <code>.manager</code> file:</p>
+
+<pre>[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars;
+param-account=s required
+param-password=s required
+SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif;
+MinimumAvatarHeight=32
+RecommendedAvatarHeight=64
+MaximumAvatarHeight=96
+MinimumAvatarWidth=32
+RecommendedAvatarWidth=64
+MaximumAvatarWidth=96
+MaximumAvatarBytes=8192
+</pre>
+ </tp:docstring>
+
+ <property name="SupportedAvatarMIMETypes"
+ tp:name-for-bindings="Supported_Avatar_MIME_Types"
+ type="as" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarHeight"
+ tp:name-for-bindings="Minimum_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+</tp:docstring>
+ </property>
+
+ <property name="MinimumAvatarWidth"
+ tp:name-for-bindings="Minimum_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarHeight"
+ tp:name-for-bindings="Recommended_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="RecommendedAvatarWidth"
+ tp:name-for-bindings="Recommended_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarHeight"
+ tp:name-for-bindings="Maximum_Avatar_Height"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarWidth"
+ tp:name-for-bindings="Maximum_Avatar_Width"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+
+ <property name="MaximumAvatarBytes"
+ tp:name-for-bindings="Maximum_Avatar_Bytes"
+ type="u" access="read">
+ <tp:docstring>
+ The expected value of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref>
+ property on connections to this protocol.
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml
new file mode 100644
index 0000000..ddff332
--- /dev/null
+++ b/spec/Protocol_Interface_Presence.xml
@@ -0,0 +1,113 @@
+<?xml version="1.0" ?>
+<node name="/Protocol_Interface_Presence"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Protocol.Interface.Presence">
+ <tp:added version="0.21.3">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Protocol"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for protocols where it might be possible to set the
+ user's presence, and the supported presence types can be predicted
+ before connecting.</p>
+
+ <tp:rationale>
+ <p>This allows UIs to show or hide presence types that aren't
+ always supported, such as "invisible", while not online.</p>
+ </tp:rationale>
+
+ <p>The properties on this interface SHOULD be cached in the
+ <code>.manager</code> file, in the
+ <code>[Protocol <em>proto</em>]</code>
+ group. For each status <em>s</em> in
+ <tp:member-ref>Statuses</tp:member-ref>, that group should
+ contain a key of the form <code>status-<em>s</em></code> whose value
+ is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII
+ decimal integer, followed by a space-separated sequence of tokens
+ from the following set:</p>
+
+ <dl>
+ <dt>settable</dt>
+ <dd>If present, the user can set this status on themselves using
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"
+ >SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self
+ in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd>
+
+ <dt>message</dt>
+ <dd>If present, the user can set a non-empty message for this status;
+ this corresponds to Can_Have_Message in the
+ <tp:type>Simple_Status_Spec</tp:type> struct.</dd>
+ </dl>
+
+ <p>Unrecognised tokens MUST be ignored.</p>
+
+ <p>For instance, an XMPP connection manager might have this
+ <code>.manager</code> file:</p>
+
+<pre>[Protocol jabber]
+Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence;
+param-account=s required
+param-password=s required
+status-offline=1
+status-unknown=7
+status-error=8
+status-hidden=5 settable message
+status-xa=4 settable message
+status-away=3 settable message
+status-dnd=6 settable message
+status-available=2 settable message
+status-chat=2 settable message
+</pre>
+
+ <p>which corresponds to these property values (using a Python-like
+ syntax):</p>
+
+<pre>Statuses = {
+ 'offline': (OFFLINE, False, False),
+ 'unknown': (UNKNOWN, False, False),
+ 'error': (ERROR, False, False),
+ 'hidden': (HIDDEN, True, True),
+ 'xa': (EXTENDED_AWAY, True, True),
+ 'away': (AWAY, True, True),
+ 'dnd': (BUSY, True, True),
+ 'available': (AVAILABLE, True, True),
+ 'chat': (AVAILABLE, True, True),
+}
+</pre>
+ </tp:docstring>
+
+ <property name="Statuses"
+ tp:name-for-bindings="Statuses"
+ type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read">
+ <tp:docstring>
+ <p>The statuses that might appear in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.SimplePresence.Statuses</tp:dbus-ref>
+ property on a connection to this protocol that supports
+ SimplePresence. This property is immutable.</p>
+
+ <p>Depending on server capabilities, it is possible that not all
+ of these will actually appear on the Connection.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
diff --git a/spec/all.xml b/spec/all.xml
new file mode 100644
index 0000000..3123401
--- /dev/null
+++ b/spec/all.xml
@@ -0,0 +1,303 @@
+<tp:spec
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<tp:title>Telepathy D-Bus Interface Specification</tp:title>
+<tp:version>0.21.8</tp:version>
+
+<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
+<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+<tp:copyright>Copyright © 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>
+
+<tp:section name="Connection Managers">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ A Connection Manager is a factory for connections.
+ </p>
+ </tp:docstring>
+ <xi:include href="Connection_Manager.xml"/>
+ <xi:include href="Protocol.xml"/>
+ <xi:include href="Protocol_Interface_Addressing.xml"/>
+ <xi:include href="Protocol_Interface_Avatars.xml"/>
+ <xi:include href="Protocol_Interface_Presence.xml"/>
+
+ <tp:section name="Connection Object">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Connections represent active protocol sessions. There are a number of core
+ interfaces which all connections should implement, and a number of optional
+ interfaces which provide various functionality related to contacts and to
+ the connection itself.
+ </p>
+ </tp:docstring>
+ <xi:include href="Connection.xml"/>
+ <xi:include href="Connection_Future.xml"/>
+ <xi:include href="Connection_Interface_Contacts.xml"/>
+ <xi:include href="Connection_Interface_Requests.xml"/>
+
+ <tp:section name="Contact list interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ On protocols that support contact lists, these interface expose the user's
+ contact lists, along with presence subscription information and contact
+ list groups (if supported).
+ </p>
+ </tp:docstring>
+
+ <xi:include href="Connection_Interface_Contact_List.xml"/>
+ <xi:include href="Connection_Interface_Contact_Groups.xml"/>
+ </tp:section>
+
+ <tp:section name="Contact metadata interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ These optional Connection interfaces expose metadata about contacts on
+ this connection—from their current presence through to the type of client
+ they're connected with—and allow the local user to publish such metadata
+ back to their contacts.
+ </p>
+ </tp:docstring>
+
+ <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_Client_Types.xml"/>
+ <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
+ <xi:include href="Connection_Interface_Contact_Info.xml"/>
+ <xi:include href="Connection_Interface_Location.xml"/>
+ <xi:include href="Connection_Interface_Presence.xml"/>
+ <xi:include href="Connection_Interface_Renaming.xml"/>
+ <xi:include href="Connection_Interface_Resources.xml"/>
+ <xi:include href="Connection_Interface_Simple_Presence.xml"/>
+ </tp:section>
+
+ <tp:section name="Connection feature interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ These optional Connection interfaces expose protocol-specific features,
+ and allow configuring the running connection.
+ </p>
+ </tp:docstring>
+
+ <xi:include href="Connection_Interface_Addressing.xml"/>
+ <xi:include href="Connection_Interface_Anonymity.xml"/>
+ <xi:include href="Connection_Interface_Balance.xml"/>
+ <xi:include href="Connection_Interface_Cellular.xml"/>
+ <xi:include href="Connection_Interface_Communication_Policy.xml"/>
+ <xi:include href="Connection_Interface_Forwarding.xml"/>
+ <xi:include href="Connection_Interface_Keepalive.xml"/>
+ <xi:include href="Connection_Interface_Mail_Notification.xml"/>
+ <xi:include href="Connection_Interface_Power_Saving.xml"/>
+ <xi:include href="Connection_Interface_Service_Point.xml"/>
+ </tp:section>
+ </tp:section>
+
+ <xi:include href="Channel_Bundle.xml"/>
+
+ <tp:section name="Channel Object">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ A Channel is used by Telepathy to exchange data between local
+ applications and remote servers. A given connection will have many
+ channels, each one represented by a D-Bus object.
+ </p>
+ <p>
+ Each Channel has a type, represented by a D-Bus interface, and may
+ implement one or more additional interfaces from the list of channel
+ interfaces below.
+ </p>
+ </tp:docstring>
+ <xi:include href="Channel.xml"/>
+ <xi:include href="Channel_Future.xml"/>
+
+ <tp:section name="Channel Types">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Each Channel implements one of the following types:
+ </p>
+ </tp:docstring>
+ <xi:include href="Channel_Type_Call.xml"/>
+ <xi:include href="Channel_Type_Contact_List.xml"/>
+ <xi:include href="Channel_Type_Contact_Search.xml"/>
+ <xi:include href="Channel_Type_DBus_Tube.xml"/>
+ <xi:include href="Channel_Type_File_Transfer.xml"/>
+ <xi:include href="Channel_Type_Room_List.xml"/>
+ <xi:include href="Channel_Type_Server_Authentication.xml"/>
+ <xi:include href="Channel_Type_Server_TLS_Connection.xml"/>
+ <xi:include href="Channel_Type_Stream_Tube.xml"/>
+ <xi:include href="Channel_Type_Streamed_Media.xml"/>
+ <xi:include href="Channel_Type_Text.xml"/>
+ <xi:include href="Channel_Type_Tubes.xml"/>
+ </tp:section>
+
+ <tp:section name="Channel Interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ A Channel may also implement one or more of the following interfaces,
+ depending on its type. Some interfaces are only applicable to particular
+ channel types, while others may (in principle) appear on any type of
+ channel.
+ </p>
+ </tp:docstring>
+
+ <xi:include href="Channel_Interface_Addressing.xml"/>
+ <xi:include href="Channel_Interface_Anonymity.xml"/>
+ <xi:include href="Channel_Interface_Destroyable.xml"/>
+ <xi:include href="Channel_Interface_Group.xml"/>
+ <xi:include href="Channel_Interface_Password.xml"/>
+ <xi:include href="Channel_Interface_Room.xml"/>
+ <xi:include href="Channel_Interface_SASL_Authentication.xml"/>
+ <xi:include href="Channel_Interface_Securable.xml"/>
+ <xi:include href="Channel_Interface_Service_Point.xml"/>
+ <xi:include href="Channel_Interface_Tube.xml"/>
+
+ <tp:section name="Text-specific interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>These interfaces may only appear on channels of type <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>.</p>
+ </tp:docstring>
+
+ <xi:include href="Channel_Interface_Chat_State.xml"/>
+ <xi:include href="Channel_Interface_HTML.xml"/>
+ <xi:include href="Channel_Interface_Messages.xml"/>
+ <xi:include href="Channel_Interface_SMS.xml"/>
+ </tp:section>
+
+ <tp:section name="Streamed Media-related interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>These interfaces are only applicable to channels of type <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref>, with the
+ exception of the <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Hold</tp:dbus-ref> interface, which
+ may also appear on <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels.</p>
+ </tp:docstring>
+
+ <xi:include href="Channel_Interface_Call_State.xml"/>
+ <xi:include href="Channel_Interface_DTMF.xml"/>
+ <xi:include href="Channel_Interface_Hold.xml"/>
+ <xi:include href="Channel_Interface_Media_Signalling.xml"/>
+ </tp:section>
+
+ <tp:section name="Conference-related interfaces">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>These interfaces provide functionality for ad-hoc conference calls and
+ chat rooms. They are primarily intended for <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>, <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> and
+ <tp:dbus-ref namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref>
+ channels, but may also appear on other types of channel.</p>
+ </tp:docstring>
+
+ <xi:include href="Channel_Interface_Conference.xml"/>
+ <xi:include href="Channel_Interface_Splittable.xml"/>
+ <xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
+ </tp:section>
+ </tp:section>
+ </tp:section>
+
+ <tp:section name="Authentication Objects">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ A set of objects to be used for authentication purposes, such
+ as TLS certificates or handshakes for negotiating end-to-end
+ security.
+ </p>
+ </tp:docstring>
+ <xi:include href="Authentication_TLS_Certificate.xml"/>
+ </tp:section>
+
+ <tp:section name="Media">
+ <xi:include href="Media_Session_Handler.xml"/>
+ <xi:include href="Media_Stream_Handler.xml"/>
+ </tp:section>
+
+ <tp:section name="Calls">
+ <xi:include href="Call_Content.xml"/>
+ <xi:include href="Call_Content_Interface_Media.xml"/>
+ <xi:include href="Call_Content_Interface_Mute.xml"/>
+ <xi:include href="Call_Content_Codec_Offer.xml"/>
+ <xi:include href="Call_Stream.xml"/>
+ <xi:include href="Call_Stream_Interface_Media.xml"/>
+ <xi:include href="Call_Stream_Endpoint.xml"/>
+ </tp:section>
+
+ <tp:section name="Debugging">
+ <xi:include href="Debug.xml"/>
+ </tp:section>
+</tp:section>
+
+<tp:section name="The Account Manager">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The Account Manager is a desktop service that provides account configuration
+ and can manage the connection managers. In general, clients will use the
+ account manager to find out about instant messaging accounts and their
+ associated connections.
+ </p>
+ </tp:docstring>
+ <xi:include href="Account_Manager.xml"/>
+ <xi:include href="Account.xml"/>
+ <xi:include href="Account_Interface_Addressing.xml"/>
+ <xi:include href="Account_Interface_Avatar.xml"/>
+ <xi:include href="Account_Interface_Storage.xml"/>
+</tp:section>
+
+<tp:section name="The Channel Dispatcher">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The Channel Dispatcher is a desktop service whose purpose is to dispatch
+ incoming Telepathy Channels to the appropriate client (e.g. incoming text
+ chat, file transfer, tubes, etc.).
+ </p>
+ </tp:docstring>
+ <xi:include href="Channel_Dispatcher.xml"/>
+ <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/>
+ <xi:include href="Channel_Dispatch_Operation.xml"/>
+ <xi:include href="Channel_Request.xml"/>
+</tp:section>
+
+<tp:section name="Clients">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Clients should implement one or more of these interfaces to be able to
+ handle channels coming in from the Channel Dispatcher.
+ </p>
+ </tp:docstring>
+ <xi:include href="Client.xml"/>
+ <xi:include href="Client_Observer.xml"/>
+ <xi:include href="Client_Approver.xml"/>
+ <xi:include href="Client_Handler.xml"/>
+ <xi:include href="Client_Handler_Future.xml"/>
+ <xi:include href="Client_Interface_Requests.xml"/>
+
+ <xi:include href="Channel_Handler.xml"/>
+</tp:section>
+
+<xi:include href="Properties_Interface.xml"/>
+
+<xi:include href="errors.xml"/>
+<xi:include href="generic-types.xml"/>
+
+<!-- Never implemented, vague
+<xi:include href="Connection_Interface_Privacy.xml"/> -->
+<!-- Causes havoc, never implemented, unclear requirements
+<xi:include href="Channel_Interface_Transfer.xml"/> -->
+
+</tp:spec>
diff --git a/spec/errors.xml b/spec/errors.xml
new file mode 100644
index 0000000..eccbd09
--- /dev/null
+++ b/spec/errors.xml
@@ -0,0 +1,564 @@
+<?xml version="1.0" ?>
+<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The D-Bus errors used in Telepathy all start with
+ <code>org.freedesktop.Telepathy.Error.</code>. They are used in
+ D-Bus messages of type ERROR, and also as plain strings annotated with
+ the <tp:type>DBus_Error_Name</tp:type> type.</p>
+
+ <p>In principle, any method can raise any error (this is a general fact
+ of IPC). For instance, generic D-Bus errors starting with
+ <code>org.freedesktop.DBus.Error.</code> will occur in some
+ situations.</p>
+
+ <p>Telepathy methods can also raise implementation-specific errors to
+ indicate specialized failure conditions. For better interoperability,
+ if a suitable Telepathy error exists, it should be preferred.</p>
+
+ <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code>
+ is reserved for use by the D-Bus client implementation in telepathy-qt4,
+ which uses it to represent certain error situations that did not involve
+ a D-Bus ERROR message. These errors are defined and documented as part of
+ telepathy-qt4's C++ API, and should not be used on D-Bus.</p>
+ </tp:docstring>
+
+ <tp:error name="Network Error">
+ <tp:docstring>
+ Raised when there is an error reading from or writing to the network.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Implemented">
+ <tp:docstring>
+ Raised when the requested method, channel, etc is not available on this connection.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Invalid Argument">
+ <tp:docstring>
+ Raised when one of the provided arguments is invalid.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Available">
+ <tp:docstring>
+ Raised when the requested functionality is temporarily unavailable.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Permission Denied">
+ <tp:docstring>
+ The user is not permitted to perform the requested operation.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Disconnected">
+ <tp:docstring>
+ The connection is not currently connected and cannot be used.
+ This error may also be raised when operations are performed on a
+ Connection for which
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">StatusChanged</tp:dbus-ref>
+ has signalled status Disconnected for reason None.
+
+ <tp:rationale>
+ The second usage corresponds to None in the
+ <tp:type>Connection_Status_Reason</tp:type> enum; if a better reason
+ is available, the corresponding error should be used instead.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Invalid Handle">
+ <tp:docstring>
+ The handle specified is unknown on this channel or connection.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Channel.Banned">
+ <tp:docstring>
+ You are banned from the channel.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Channel.Full">
+ <tp:docstring>
+ The channel is full.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Channel.Invite Only">
+ <tp:docstring>
+ The requested channel is invite-only.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Yours">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested channel or other resource already exists, and another
+ user interface in this session is responsible for it.</p>
+
+ <p>User interfaces SHOULD handle this error unobtrusively, since it
+ indicates that some other user interface is already processing the
+ channel.</p>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cancelled">
+ <tp:docstring>
+ Raised by an ongoing request if it is cancelled by user request before
+ it has completed, or when operations are performed on an object which
+ the user has asked to close (for instance, a Connection where the user
+ has called Disconnect, or a Channel where the user has called Close).
+
+ <tp:rationale>
+ The second form can be used to correspond to the Requested member in
+ the <tp:type>Connection_Status_Reason</tp:type> enum, or to
+ to represent the situation where disconnecting a Connection,
+ closing a Channel, etc. has been requested by the user but this
+ request has not yet been acted on, for instance because the
+ service will only act on the request when it has finished processing
+ an event queue.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Authentication Failed">
+ <tp:docstring>
+ Raised when authentication with a service was unsuccessful.
+ <tp:rationale>
+ This corresponds to Authentication_Failed in the
+ <tp:type>Connection_Status_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Encryption Not Available">
+ <tp:docstring>
+ Raised if a user request insisted that encryption should be used,
+ but encryption was not actually available.
+
+ <tp:rationale>
+ This corresponds to part of Encryption_Error in the
+ <tp:type>Connection_Status_Reason</tp:type> enum. It's been separated
+ into a distinct error here because the two concepts that were part
+ of EncryptionError seem to be things that could reasonably appear
+ differently in the UI.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Encryption Error">
+ <tp:docstring>
+ Raised if encryption appears to be available, but could not actually be
+ used (for instance if SSL/TLS negotiation fails).
+ <tp:rationale>
+ This corresponds to part of Encryption_Error in the
+ <tp:type>Connection_Status_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Not Provided">
+ <tp:docstring>
+ Raised if the server did not provide a SSL/TLS certificate. This error
+ MUST NOT be used to represent the absence of a client certificate
+ provided by the Telepathy connection manager.
+ <tp:rationale>
+ This corresponds to Cert_Not_Provided in the
+ <tp:type>Connection_Status_Reason</tp:type> enum. That error
+ explicitly applied only to server SSL certificates, so this one
+ is similarly limited; having the CM present a client certificate
+ is a possible future feature, but it should have its own error
+ handling.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Untrusted">
+ <tp:docstring>
+ Raised if the server provided a SSL/TLS certificate signed by an
+ untrusted certifying authority. This error SHOULD NOT be used to
+ represent a self-signed certificate: see the Self Signed error for that.
+ <tp:rationale>
+ This corresponds to Cert_Untrusted in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Untrusted in the
+ <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum, with a clarification
+ to avoid ambiguity.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Expired">
+ <tp:docstring>
+ Raised if the server provided an expired SSL/TLS certificate.
+ <tp:rationale>
+ This corresponds to Cert_Expired in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Expired in
+ the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Not Activated">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that will become
+ valid at some point in the future.
+ <tp:rationale>
+ This corresponds to Cert_Not_Activated in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to
+ Not_Activated in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Fingerprint Mismatch">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that did not have
+ the expected fingerprint.
+ <tp:rationale>
+ This corresponds to Cert_Fingerprint_Mismatch in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to
+ Fingerprint_Mismatch in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Hostname Mismatch">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Raised if the server provided an SSL/TLS certificate that did not match
+ its hostname.</p>
+ <p>You MAY be able to get more details about the expected and certified
+ hostnames by looking up the 'expected-hostname' and 'certificate-hostname'
+ keys in the details map that came together with this error.</p>
+ <tp:rationale>
+ This corresponds to Cert_Hostname_Mismatch in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Hostname_Mismatch
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Self Signed">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that is self-signed
+ and untrusted.
+ <tp:rationale>
+ This corresponds to Cert_Self_Signed in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Self_Signed
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Revoked">
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that has been
+ revoked.
+ <tp:rationale>
+ This corresponds to Cert_Revoked in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Revoked
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Insecure">
+ <tp:added version="0.19.11"/>
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that uses an
+ insecure cipher algorithm or is cryptographically weak.
+ <tp:rationale>
+ This corresponds to Cert_Insecure in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Insecure
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Invalid">
+ <tp:added version="0.19.11"/>
+ <tp:docstring>
+ Raised if the server provided an SSL/TLS certificate that is
+ unacceptable in some way that does not have a more specific error.
+ <tp:rationale>
+ This corresponds to Cert_Other_Error in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Unknown
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Cert.Limit Exceeded">
+ <tp:added version="0.19.11"/>
+ <tp:docstring>
+ Raised if the length in bytes of the server certificate, or the depth of the
+ server certificate chain exceeds the limits imposed by the crypto
+ library.
+ <tp:rationale>
+ This corresponds to Cert_Limit_Exceeded in the
+ <tp:type>Connection_Status_Reason</tp:type> enum and to Limit_Exceeded
+ in the <tp:type>TLS_Certificate_Reject_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Capable">
+ <tp:docstring>
+ Raised when requested functionality is unavailable due to contact
+ not having required capabilities.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Offline">
+ <tp:docstring>
+ Raised when requested functionality is unavailable because a contact is
+ offline.
+
+ <tp:rationale>
+ This corresponds to Offline in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Channel.Kicked">
+ <tp:docstring>
+ Used to represent a user being ejected from a channel by another user,
+ for instance being kicked from a chatroom.
+
+ <tp:rationale>
+ This corresponds to Kicked in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Busy">
+ <tp:docstring>
+ Used to represent a user being removed from a channel because of a
+ "busy" indication. This error SHOULD NOT be used to represent a server
+ or other infrastructure being too busy to process a request - for that,
+ see ServerBusy.
+
+ <tp:rationale>
+ This corresponds to Busy in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="No Answer">
+ <tp:docstring>
+ Used to represent a user being removed from a channel because they did
+ not respond, e.g. to a StreamedMedia call.
+
+ <tp:rationale>
+ This corresponds to No_Answer in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Does Not Exist">
+ <tp:docstring>
+ Raised when the requested user does not, in fact, exist.
+
+ <tp:rationale>
+ This corresponds to Invalid_Contact in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum, but can also be
+ used to represent other things not existing (like chatrooms, perhaps).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Terminated">
+ <tp:docstring>
+ Raised when a channel is terminated for an unspecified reason. In
+ particular, this error SHOULD be used whenever normal termination of
+ a 1-1 StreamedMedia call by the remote user is represented as a D-Bus
+ error name.
+
+ <tp:rationale>
+ This corresponds to None in the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Refused">
+ <tp:docstring>
+ Raised when a connection is refused.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Failed">
+ <tp:docstring>
+ Raised when a connection can't be established.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Lost">
+ <tp:docstring>
+ Raised when a connection is broken.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Already Connected">
+ <tp:docstring>
+ Raised when the user attempts to connect to an account but they are
+ already connected (perhaps from another client or computer), and the
+ protocol or account settings do not allow this.
+
+ <tp:rationale>
+ XMPP can have this behaviour if the user chooses the same resource
+ in both clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Replaced">
+ <tp:docstring>
+ Raised by an existing connection to an account if it is replaced by
+ a new connection (perhaps from another client or computer).
+
+ <tp:rationale>
+ In MSNP, when connecting twice with the same Passport, the new
+ connection "wins" and the old one is automatically disconnected.
+ XMPP can also have this behaviour if the user chooses the same
+ resource in two clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Registration Exists">
+ <tp:docstring>
+ Raised during in-band registration if the server indicates that the
+ requested account already exists.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Service Busy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Raised if a server or some other piece of infrastructure cannot process
+ the request, e.g. due to resource limitations. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ This is not the same error as Busy, which indicates that a
+ <em>user</em> is busy.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Resource Unavailable">
+ <tp:docstring>
+ Raised if a request cannot be satisfied because a process local to the
+ user has insufficient resources. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ For instance, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ might raise this error for some or all channel requests if it has
+ detected that there is not enough free memory.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Would Break Anonymity">
+ <tp:added version="0.19.7"/>
+ <tp:docstring>
+ Raised if a request cannot be satisfied without violating an earlier
+ request for anonymity, and the earlier request specified that raising
+ an error is preferable to disclosing the user's identity (for instance
+ via <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref> or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Channel.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref>).
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Not Yet">
+ <tp:added version="0.19.12"/>
+ <tp:docstring>
+ Raised when the requested functionality is not yet available, but is
+ likely to become available after some time has passed.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Rejected">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ Raised when an incoming or outgoing <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is
+ rejected by the the receiver.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Picked Up Elsewhere">
+ <tp:added version="0.21.3"/>
+ <tp:docstring>
+ Raised when a call was terminated as a result of the local user
+ picking up the call on a different resource.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Service Confused">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ Raised when a server or other piece of infrastructure indicates an
+ internal error, or when a message that makes no sense is received from
+ a server or other piece of infrastructure.
+
+ <tp:rationale>
+ For instance, this is appropriate for XMPP's
+ <code>internal-server-error</code>, and is also appropriate if
+ you receive sufficiently inconsistent information from a server that
+ you cannot continue.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Confused">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ Raised if a server rejects protocol messages from a connection manager
+ claiming that they do not make sense, two local processes fail to
+ understand each other, or an apparently impossible situation is
+ reached.
+
+ <tp:rationale>
+ For instance, this would be an appropriate mapping for XMPP's
+ errors bad-format, invalid-xml, etc., which can't happen unless
+ the local (or remote) XMPP implementation is faulty. This is
+ also analogous to
+ <tp:type>Media_Stream_Error</tp:type>_Invalid_CM_Behavior,
+ <code>TP_DBUS_ERROR_INCONSISTENT</code> in telepathy-glib, and
+ <code>TELEPATHY_QT4_ERROR_INCONSISTENT</code> in telepathy-qt4.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 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>
+</tp:errors>
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
new file mode 100644
index 0000000..014f8ad
--- /dev/null
+++ b/spec/generic-types.xml
@@ -0,0 +1,215 @@
+<tp:generic-types
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:simple-type name="Unix_Timestamp" type="u">
+ <tp:docstring>An unsigned 32-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z)</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="Unix_Timestamp64" type="x">
+ <tp:docstring>An signed 64-bit integer representing time as the number
+ of seconds elapsed since the Unix epoch
+ (1970-01-01T00:00:00Z); negative for times before the epoch</tp:docstring>
+
+ <tp:rationale>The Text interface is the only user of Unix_Timestamp so
+ far, and we'd like to be Y2038 compatible in future
+ interfaces.</tp:rationale>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Bus_Name" type="s"
+ array-name="DBus_Bus_Name_List">
+ <tp:docstring>A string representing a D-Bus bus name - either a well-known
+ name like "org.freedesktop.Telepathy.MissionControl" or a unique name
+ like ":1.123"</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Well_Known_Name" type="s"
+ array-name="DBus_Well_Known_Name_List">
+ <tp:docstring>A string representing a D-Bus well-known
+ name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Unique_Name" type="s"
+ array-name="DBus_Unique_Name_List">
+ <tp:docstring>A string representing a D-Bus unique name, such as
+ ":1.123"</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Interface" type="s"
+ array-name="DBus_Interface_List">
+ <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_Error_Name" type="s">
+ <tp:docstring>An ASCII string representing a D-Bus error. This is
+ syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the
+ meaning is different.</tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="DBus_Signature" type="s">
+ <tp:docstring>A string representing a D-Bus signature
+ (the 'g' type isn't used because of poor interoperability, particularly
+ 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"
+ array-name="DBus_Qualified_Member_List">
+ <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"
+ array-name="Qualified_Property_Value_Map_List">
+ <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" array-name="String_Variant_Map_List">
+ <tp:docstring>A mapping from strings to variants representing extra
+ key-value pairs.</tp:docstring>
+ <tp:member type="s" name="Key"/>
+ <tp:member type="v" name="Value"/>
+ </tp:mapping>
+
+ <tp:mapping name="String_String_Map" array-name="String_String_Map_List">
+ <tp:docstring>A mapping from strings to strings representing extra
+ key-value pairs.</tp:docstring>
+ <tp:member type="s" name="Key"/>
+ <tp:member type="s" name="Value"/>
+ </tp:mapping>
+
+ <tp:struct name="Socket_Address_IP" array-name="Socket_Address_IP_List">
+ <tp:docstring>An IP address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>Either a dotted-quad IPv4 address literal as for
+ <tp:type>Socket_Address_IPv4</tp:type>, or an RFC2373 IPv6 address
+ as for <tp:type>Socket_Address_IPv6</tp:type>.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Address_IPv4">
+ <tp:docstring>An IPv4 address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal
+ numbers, each between 0 and 255 inclusive, e.g.
+ "192.168.0.1".</tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Address_IPv6">
+ <tp:docstring>An IPv6 address and port.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>An IPv6 address literal as specified by RFC2373
+ section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring>
+ </tp:member>
+ <tp:member type="q" name="Port">
+ <tp:docstring>The TCP or UDP port number.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Netmask_IPv4">
+ <tp:docstring>An IPv4 network or subnet.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>A dotted-quad IPv4 address literal: four ASCII decimal
+ numbers, each between 0 and 255 inclusive, e.g.
+ "192.168.0.1".</tp:docstring>
+ </tp:member>
+ <tp:member type="y" name="Prefix_Length">
+ <tp:docstring>The number of leading bits of the address that must
+ match, for this netmask to be considered to match an
+ address.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Socket_Netmask_IPv6">
+ <tp:docstring>An IPv6 network or subnet.</tp:docstring>
+ <tp:member type="s" name="Address">
+ <tp:docstring>An IPv6 address literal as specified by RFC2373
+ section 2.2, e.g. "2001:DB8::8:800:200C:4171".</tp:docstring>
+ </tp:member>
+ <tp:member type="y" name="Prefix_Length">
+ <tp:docstring>The number of leading bits of the address that must
+ match, for this netmask to be considered to match an
+ address.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:simple-type name="User_Action_Timestamp" type="x">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which an user action occurred. This type has the 2
+ following special values:</p>
+
+ <p>0: the action doesn't involve any user action. Clients
+ SHOULD avoid stealing focus when presenting the channel.</p>
+
+ <p>MAX_INT64: clients SHOULD behave as though the user action happened
+ at the current time, e.g. a client MAY request that its window gains
+ focus.
+ </p>
+
+ <tp:rationale>
+ <p>This can be used by clients that can't know the X server time like
+ command line applications for example.</p>
+ </tp:rationale>
+
+ <p>For all the other values it corresponds to the time of the user
+ action. Clients SHOULD use this for focus-stealing prevention,
+ if applicable.
+ Note that the time is dependant on the local
+ environment and so is not necessarily a wall-clock time.
+ For example in an X environment it's expected to be the X timestamp
+ of events.
+ This corresponds to the _NET_WM_USER_TIME property in
+ <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:mapping name="Object_Immutable_Properties_Map"
+ array-name="Object_Immutable_Properties_Map_List">
+ <tp:added version="0.19.12"/>
+ <tp:docstring>A mapping from object path to the immutable properties of
+ the object.</tp:docstring>
+ <tp:member type="o" name="Path">
+ <tp:docstring>
+ The object path of an object
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="a{sv}" name="Immutable_Properties" tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>
+ The immutable properties of the object
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+</tp:generic-types>
diff --git a/spec/template.xml b/spec/template.xml
new file mode 100644
index 0000000..7264720
--- /dev/null
+++ b/spec/template.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" ?>
+<node name="/Foo"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Foo.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.21.UNRELEASED">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Foo.</p>
+ </tp:docstring>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->