[telepathy-python/master] Upgrade to spec 0.17.26
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Thu Jun 11 09:45:26 PDT 2009
---
spec/Account.xml | 101 ++++-
spec/Account_Manager.xml | 108 ++++-
spec/Channel.xml | 6 +-
spec/Channel_Dispatch_Operation.xml | 158 +++++--
spec/Channel_Dispatcher.xml | 93 ++---
...Channel_Dispatcher_Interface_Operation_List.xml | 21 +-
spec/Channel_Future.xml | 2 +-
spec/Channel_Handler.xml | 15 +-
spec/Channel_Interface_Call_State.xml | 17 +-
spec/Channel_Interface_Group.xml | 87 +++-
spec/Channel_Interface_Hold.xml | 4 +-
spec/Channel_Interface_Media_Signalling.xml | 54 ++-
spec/Channel_Interface_Media_Signalling_Future.xml | 125 ++---
spec/Channel_Interface_Messages.xml | 7 +-
spec/Channel_Interface_Password.xml | 6 +-
spec/Channel_Interface_Tube.xml | 195 +++++++--
spec/Channel_Request.xml | 42 ++-
spec/Channel_Type_Contact_Search.xml | 482 ++++++++++++++++----
spec/Channel_Type_DBus_Tube.xml | 64 ++-
spec/Channel_Type_File_Transfer.xml | 20 +-
spec/Channel_Type_Room_List.xml | 8 +-
spec/Channel_Type_Stream_Tube.xml | 140 +++++-
spec/Channel_Type_Streamed_Media.xml | 179 +++++++-
spec/Channel_Type_Streamed_Media_Future.xml | 27 +-
spec/Channel_Type_Text.xml | 13 +-
spec/Channel_Type_Tubes.xml | 147 +------
spec/Client.xml | 9 +-
spec/Client_Approver.xml | 145 ++++--
spec/Client_Handler.xml | 174 +++----
spec/Client_Interface_Requests.xml | 171 +++++++
spec/Client_Observer.xml | 138 +++++--
spec/Connection.xml | 63 ++-
spec/Connection_Interface_Avatars.xml | 130 ++++++-
spec/Connection_Interface_Contact_Info.xml | 97 +++--
spec/Connection_Interface_Presence.xml | 195 ++-------
spec/Connection_Interface_Requests.xml | 18 +
spec/Connection_Interface_Simple_Presence.xml | 138 ++++++-
spec/Connection_Manager.xml | 2 +-
spec/Debug.xml | 166 +++++++
spec/Media_Session_Handler.xml | 25 +-
spec/Media_Stream_Handler.xml | 146 ++++++-
spec/Properties_Interface.xml | 4 +-
spec/all.xml | 208 ++++++---
spec/errors.xml | 39 ++-
spec/generic-types.xml | 80 +++-
45 files changed, 2958 insertions(+), 1111 deletions(-)
create mode 100644 spec/Client_Interface_Requests.xml
create mode 100644 spec/Debug.xml
diff --git a/spec/Account.xml b/spec/Account.xml
index 991dcbd..4b112cb 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp: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
@@ -282,19 +282,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- Change the value of the <tp:member-ref>Parameters</tp:member-ref>
- property. If any of the changed parameters'
- <tp:type>Conn_Mgr_Param_Flags</tp:type> include
- <code>DBus_Property</code>, the change will be applied 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>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 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>
- Migration tools that twiddle the settings of all accounts shouldn't
- cause an automatic disconnect and reconnect, probably. I could be
- persuaded otherwise, though. Or we could add a Reconnect() method.
+ <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>
@@ -303,12 +306,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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
@@ -319,6 +328,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</arg>
+ <arg name="Reconnect_Required" type="as" direction="out">
+ <tp:docstring>
+ A list of the names of parameters with changes that will not take
+ effect until the account is reconnected (this may be empty, e.g. if
+ all the parameters are D-Bus properties or parameters for which the
+ account manager has specific support). User interfaces that
+ require "instant apply" semantics MAY call
+ <tp:member-ref>Reconnect</tp:member-ref> in response to receiving
+ a non-empty list.
+ </tp:docstring>
+ </arg>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
@@ -427,7 +448,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
The actual presence. If the connection is not online, this should be
(Connection_Presence_Type_Offline, "", "").
If the connection is online but does not support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
interface, this should be (Connection_Presence_Type_Unset, "", "").
The account manager is expected to set this by observing signals
from the Connection.
@@ -459,6 +480,42 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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">
@@ -494,6 +551,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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_Manager.xml b/spec/Account_Manager.xml
index 98fe00d..9b54f5f 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account_Manager"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+ <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
@@ -127,12 +127,78 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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">
@@ -152,8 +218,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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.
+ 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
@@ -176,6 +243,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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>
@@ -183,12 +270,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
- <tp:docstring>The connection manager is not installed or does not
- implement that protocol.</tp:docstring>
+ <tp: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>The parameters provided omit a required argument
- or provide unsupported arguments.
+ <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>
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 7b4a7ad..2937680 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel" 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: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
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 7f61f6f..26d9b57 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Dispatch_Operation"
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: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
@@ -21,14 +21,14 @@
MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT"
- tp:causes-havoc="experimental">
+ <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 bundle of unrequested channels being announced to
+ representing a batch of unrequested channels being announced to
client
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref>
+ <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
@@ -52,9 +52,9 @@
<p>First, the channel dispatcher SHOULD construct a list of all the
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>s
+ 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.DRAFT">HandlerChannelFilter</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
@@ -62,15 +62,34 @@
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.DRAFT">BypassApproval</tp:dbus-ref>
- <code>= True</code> could handle the channels in the dispatch
+ 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.DRAFT">HandleChannels</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>
@@ -92,7 +111,7 @@
approver to claim the channels or request that they are handled.
See
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</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
@@ -142,11 +161,29 @@
</property>
<signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
- <tp:docstring>
- 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>.
+ <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">
@@ -161,20 +198,9 @@
<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.Errors.NotAvailable</code> MAY
+ <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>
-
- <p>FIXME: or should we invent a new OtherError for that purpose?</p>
-
- <p>FIXME: we need to specify errors for these situations:</p>
-
- <ul>
- <li>kicked from a chatroom</li>
- <li>outgoing call rejected</li>
- <li>outgoing call timed out</li>
- <li>incoming call terminated</li>
- </ul>
</tp:docstring>
</arg>
@@ -188,13 +214,22 @@
<property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
type="as" access="read" tp:type="DBus_Well_Known_Name[]">
<tp:docstring>
- 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>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>
@@ -222,7 +257,7 @@
<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.DRAFT">HandleChannels</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>
@@ -232,15 +267,16 @@
<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.</p>
+ 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 not a syntactically correct
- <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ 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>
@@ -278,13 +314,15 @@
<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 HandleChannels method called on it.</p>
- <!-- FIXME: tp:dbus-ref -->
+ <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
- CurrentlyHandledChannels property.</p>
- <!-- FIXME: tp:dbus-ref -->
+ <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
@@ -297,7 +335,14 @@
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.</p>
+ 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
@@ -331,6 +376,11 @@
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>
@@ -341,6 +391,24 @@
<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>
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index c77873d..d312a6d 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Dispatcher"
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: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
@@ -21,8 +21,8 @@
USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"
- tp:causes-havoc="experimental">
+ <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
@@ -67,12 +67,14 @@
specification:</p>
<dl>
- <dt>Observer</dt>
+ <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>Approver</dt>
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>p
<dd>
<p>Approvers notify the user that new channels have been created,
and also select which channel handler will be used for the channel,
@@ -80,7 +82,8 @@
channel handler.</p>
</dd>
- <dt>Handler</dt>
+ <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
@@ -99,7 +102,7 @@
<method name="CreateChannel" tp:name-for-bindings="Create_Channel">
<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.DRAFT</tp:dbus-ref>
+ <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>
@@ -119,10 +122,10 @@
<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.DRAFT.Proceed</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.DRAFT.Failed</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
is emitted with an appropriate error.</p>
<tp:rationale>
@@ -166,10 +169,10 @@
<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.DRAFT">UserActionTime</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.DRAFT">HandleChannels</tp:dbus-ref>.</p>
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
</tp:docstring>
</arg>
@@ -193,14 +196,15 @@
<p>This is partly so the channel dispatcher can call
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</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>
</tp:rationale>
- <p>If this is a well-known bus name, the channel dispatcher SHOULD
+ <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.Handler.DRAFT">AddRequest</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>
@@ -208,13 +212,18 @@
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>
</arg>
<arg direction="out" name="Request" type="o">
<tp:docstring>
A
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
object.
</tp:docstring>
</arg>
@@ -236,22 +245,22 @@
<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.DRAFT</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.DRAFT.Proceed</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.DRAFT.Failed</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.DRAFT'>CreateChannel</tp:dbus-ref>.</p>
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p>
</tp:rationale>
</tp:docstring>
@@ -284,12 +293,10 @@
tp:type="Unix_Timestamp64">
<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.DRAFT">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.DRAFT">HandleChannels</tp:dbus-ref>.</p>
+ 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>CreateChannel</tp:member-ref>.</p>
</tp:docstring>
</arg>
@@ -300,30 +307,10 @@
<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>
-
- <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.DRAFT">HandleChannels</tp:dbus-ref>
- on it, and partly so the channel dispatcher
- can recover state if it crashes and is restarted.</p>
- </tp:rationale>
-
- <p>If this is a well-known bus name, the channel dispatcher SHOULD
- call <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">AddRequest</tp:dbus-ref>
- on that Handler after this method has returned.</p>
-
- <tp:rationale>
- <p>This ordering allows a Handler which calls EnsureChannel with
- itself as the preferred handler to associate the call to
- AddRequest with that call.</p>
- </tp:rationale>
+ acceptable. The behaviour and rationale are the same as for the
+ corresponding parameter to
+ <tp:member-ref>CreateChannel</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
@@ -340,11 +327,11 @@
<tp:rationale>
<p>An address book application, for example, might call <tp:dbus-ref
- namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</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.DRAFT'>EnsureChannel</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
@@ -360,7 +347,7 @@
<arg direction="out" name="Request" type="o">
<tp:docstring>
A
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
object.
</tp:docstring>
</arg>
diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml
index b59ef72..d61123f 100644
--- a/spec/Channel_Dispatcher_Interface_Operation_List.xml
+++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Dispatcher_Interface_Operation_List"
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: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
@@ -21,10 +21,10 @@
USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList.DRAFT"
- tp:causes-havoc="experimental">
+ <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.DRAFT"/>
+ <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
@@ -71,11 +71,10 @@
<p>Each dictionary MUST contain at least the following keys:</p>
<ul>
- <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Interfaces</tp:dbus-ref></li>
- <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Connection</tp:dbus-ref></li>
- <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Account</tp:dbus-ref></li>
- <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Channels</tp:dbus-ref></li>
- <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.PossibleHandlers</tp:dbus-ref></li>
+ <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>
@@ -119,7 +118,7 @@
<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.DRAFT.Finished</tp:dbus-ref>).
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>).
<tp:rationale>
Strictly speaking this is redundant with
diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml
index 823d8a0..5bbca17 100644
--- a/spec/Channel_Future.xml
+++ b/spec/Channel_Future.xml
@@ -50,7 +50,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
pseudo-interface)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle</tp:dbus-ref>
+ <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>
diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml
index 3a8f6b1..edf975e 100644
--- a/spec/Channel_Handler.xml
+++ b/spec/Channel_Handler.xml
@@ -17,16 +17,15 @@ License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</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 client applications which are able to
- handle incoming channels. This
- interface is intended to be deprecated in favour of
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Client.Handler.DRAFT</tp:dbus-ref>
- when that interface comes out of DRAFT; client authors should consider
- implementing that interface instead.
- </p>
+ <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"/>
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
index 0df6e34..eec6a4b 100644
--- a/spec/Channel_Interface_Call_State.xml
+++ b/spec/Channel_Interface_Call_State.xml
@@ -20,12 +20,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Interface.CallState">
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
- <tp:docstring>
- An interface for streamed media channels that can indicate call
- progress or call states. The presence of this interface is no guarantee
- that call states will actually be signalled (for instance, SIP
- implementations are not guaranteed to generate status 180 Ringing,
- so a call can be accepted without the Ringing flag ever having been set).
+ <tp:docstring 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).</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"/>
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 490258f..a3319bf 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Group" 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: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
@@ -76,6 +76,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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"/>
@@ -241,6 +242,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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"
@@ -567,8 +581,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enum name="Channel_Group_Change_Reason" type="u">
<tp:enumvalue suffix="None" value="0">
- <tp:docstring>
- No reason was provided for this change.
+ <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">
@@ -950,16 +978,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
A string message, which can be blank if desired
</tp:docstring>
</arg>
- <tp:docstring>
- 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. 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_REJECT and
- CHANNEL_GROUP_FLAG_MESSAGE_RESCIND
- <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
- message should be provided.
+ <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"/>
diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml
index 835aff9..1e3a832 100644
--- a/spec/Channel_Interface_Hold.xml
+++ b/spec/Channel_Interface_Hold.xml
@@ -26,7 +26,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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.</p>
+ 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
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 8249331..5c29316 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Media_Signalling" 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: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
@@ -103,37 +103,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
within.
</tp:docstring>
</signal>
- <tp:property name="nat-traversal" type="s">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A string indicating the NAT traversal techniques employed by the
- streams within this channel. Can be protocol-specific values, but the
- following values should be used if appropriate:</p>
-
- <dl>
- <dt>none</dt>
- <dd>No attempt should be made at NAT traversal.</dd>
- <dt>stun</dt>
- <dd>If appropriate, a STUN request should be made to the given server
- to open a UDP port mapping and determine the external IP.</dd>
-
- <dt>gtalk-p2p</dt>
- <dd>Google Talk peer-to-peer connectivity establishment should be used,
- as implemented in libjingle 0.3.</dd>
- </dl>
+ <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.
+ 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.
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
index e1d2d25..bbb8b87 100644
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Media_Signalling_Future"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+ <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
@@ -22,7 +22,7 @@
<interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.MediaSignalling"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface contains functionality which we intend to incorporate
@@ -67,15 +67,37 @@
properties list of the channel class that advertises a contact's
ability to receive streamed media calls.</p>
- <p>Clients that are able to receive calls with particular NAT
- traversal mechanisms MAY include the following filters if
- calling <tp:dbus-ref
+ <p>Clients SHOULD NOT pass ICETransportAvailable and similar
+ properties to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
+ or similar functions. If they do, the connection manager MUST
+ accept and ignore any such property that is in the allowed properties
+ list.</p>
+
+ <tp:rationale>
+ <p>There is currently no way for clients to influence the choice
+ of transport: in general, a client making a call can't know the
+ capabilities of the streaming implementation, or even which
+ streaming implementation will be used (channels will often be
+ requested by an address book or similar application that will not
+ handle the channel itself).</p>
+
+ <p>If a mechanism for transport negotiation is added, it should be
+ something that happens after the request, but before calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Media.SessionHandler.Ready</tp:dbus-ref>,
+ so that it is the streaming implementation that chooses the
+ transport, rather than the requesting client.</p>
+ </tp:rationale>
+
+ <p>Clients that are able to receive calls with particular transports
+ MUST include the following filters if calling <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
(clients of a <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</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.DRAFT">HandlerChannelFilter</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
properties):</p>
<ul>
@@ -87,71 +109,13 @@
</ul>
<p>Connection managers MAY use this information to adjust the
- transports for which they advertise support to other contacts.
- If a client has indicated support for any particular transports,
- the connection manager SHOULD advertise support for
- each transport that is supported by any client, and also
- supported by the CM itself.</p>
+ transports for which they advertise support to other contacts.</p>
<tp:rationale>
- <p>This minimizes the possibility that a call will be started that
- cannot in fact succeed, because the intersection of the contacts'
- available transports is empty.</p>
+ <p>In particular, in XMPP, the connection manager will not be
+ callable unless a client has told it to advertise support for
+ at least one transport.</p>
</tp:rationale>
-
- <p>If no client has mentioned any of the transports known to the
- connection manager in a call to SetSelfCapabilities, the connection
- manager SHOULD advertise support for every transport that it can
- signal.</p>
-
- <tp:rationale>
- <p>This simplifies implementation on integrated platforms like Maemo,
- where it can be assumed that client libraries will support all the
- "standard" transports known to any connection manager, and
- lowers the "barrier to entry" for new Telepathy clients.</p>
- </tp:rationale>
-
- <p>Clients making outgoing calls for which the same client that made
- the request will handle the streaming MAY indicate their ability or
- inability to handle particular transports by including
- <code>ICETransportAvailable = true</code>,
- <code>RawUDPTransportAvailable = false</code>, etc.
- in the request properties parameter of their call to <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
- or similar functions. When they do so, the connection manager
- SHOULD attempt to use a transport that the client has indicated
- it is able to handle; if this is not possible, the connection
- manager SHOULD raise an error instead of creating a channel.</p>
-
- <tp:rationale>
- <p>This enables such clients to restrict the CM to the subset of
- transports supported by that particular client.</p>
- </tp:rationale>
-
- <p>Clients making outgoing calls for which they will not themselves
- handle the streaming (e.g. an address book starting a call which
- will be streamed by a separate call UI) SHOULD NOT include those
- properties in the request.</p>
-
- <tp:rationale>
- <p>In general, such a client can't know the capabilities of the
- streaming implementation, or even which streaming implementation
- will be used.</p>
- </tp:rationale>
-
- <p>In the absence of any indication of supported transports from the
- client, the connection manager SHOULD assume that the transports
- indicated by calling SetSelfCapabilities are available. If
- no transports were indicated as supported by calling
- SetSelfCapabilities either, it SHOULD assume that any transport
- that it can signal will be acceptable.</p>
-
- <p>If this property, or any of the similar transport availability
- properties, 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>
</tp:docstring>
</property>
@@ -165,8 +129,8 @@
</tp:docstring>
</property>
- <property name="GoogleP2PTransportAvailable"
- tp:name-for-bindings="Google_P2P_Transport_Available"
+ <property name="GTalkP2PTransportAvailable"
+ tp:name-for-bindings="GTalk_P2P_Transport_Available"
type="b" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
@@ -176,12 +140,23 @@
</tp:docstring>
</property>
- <property name="MSNTransportAvailable"
- tp:name-for-bindings="MSN_Transport_Available"
+ <property name="WLM85TransportAvailable"
+ tp:name-for-bindings="WLM_8_5_Transport_Available"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
+ but for the transport implemented by Windows Live Messenger 8.5 or
+ later (which resembles ICE draft 6).</p>
+ </tp:docstring>
+ </property>
+
+ <property name="WLM2009TransportAvailable"
+ tp:name-for-bindings="WLM_2009_Transport_Available"
type="b" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the variant of ICE used by MSN.</p>
+ but for the transport implemented by Windows Live Messenger 2009
+ or later (which resembles ICE draft 19).</p>
</tp:docstring>
</property>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 8cdee3c..c668067 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Messages"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+ <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
@@ -706,7 +706,8 @@ USA.</p>
</tp:member>
</tp:mapping>
- <tp:simple-type type="u" name="Message_Part_Index">
+ <tp:simple-type type="u" name="Message_Part_Index"
+ array-name="Message_Part_Index_List">
<tp:added version="0.17.17"/>
<tp:docstring>
The index of a message part within a message.
diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml
index 720849a..76720a6 100644
--- a/spec/Channel_Interface_Password.xml
+++ b/spec/Channel_Interface_Password.xml
@@ -1,9 +1,9 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
-Copyright (C) 2005, 2006 Collabora Limited
-Copyright (C) 2005, 2006 Nokia Corporation
-Copyright (C) 2006 INdT
+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
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index b2d0f31..4550673 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Tube" 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: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
@@ -17,8 +17,7 @@ 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.DRAFT"
- tp:causes-havoc="experimental">
+ <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
@@ -34,37 +33,76 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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 handles of type
- HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
- HANDLE_TYPE_ROOM (to communicate with others in the room
- simultaneously).</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.DRAFT">SetSelfCapabilities</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="readwrite" tp:name-for-bindings="Parameters">
+ 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. Connection managers
- must support the value being a string (D-Bus type 's'), array of bytes
- (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
- type 'i') and boolean (D-Bus type 'b').</p>
+ 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>Example of valid parameters for 'smb' Server Message Block over
- TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS
- SRV (RFC 2782) Service Types
- http://www.dns-sd.org/ServiceTypes.html</a>):
- <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
- <p>When requesting a channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
- this property MAY be included in the request. If it is not included in
- the request, the connection manager MUST consider the property to be
- empty. This property MAY be changed after the channel creation when
- the tube is in the state Not_Offered. If the tube is in another
- state, changing this property MUST fail without side effects.</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>
@@ -72,8 +110,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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 channel with
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
+
+ <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>
@@ -103,8 +143,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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 to offer the tube depend on
- the tube type.
+ state will be Remote_Pending. The method used to offer the tube
+ depends on the tube type.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
@@ -112,15 +152,106 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<signal name="TubeChannelStateChanged"
tp:name-for-bindings="Tube_Channel_State_Changed">
<tp:docstring>
- Emitted when the state of the tube channel changes.
+ 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">
+ <arg name="State" type="u" tp:type="Tube_Channel_State">
<tp:docstring>
- The new state of the tube; see the Tube_Channel_State enumeration.
+ 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>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index bf1bd38..4de78b4 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Request"
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: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
@@ -21,8 +21,8 @@
MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.ChannelRequest.DRAFT"
- tp:causes-havoc="experimental">
+ <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
@@ -34,9 +34,15 @@
<tp:rationale>
<p>See
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref>
+ <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"
@@ -62,6 +68,20 @@
</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">
@@ -79,6 +99,14 @@
</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>
@@ -105,7 +133,7 @@
</tp:docstring>
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+ <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.
@@ -144,7 +172,7 @@
<p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to
this method, the error SHOULD be
- <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+ <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
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 0b166bb..b0e905f 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Contact_Search" 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: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
@@ -18,135 +18,425 @@ Lesser General Public License for more details.</p>
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:causes-havoc='not well-tested'>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+ tp:causes-havoc='experimental'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:struct name="Search_Key_Info">
- <tp:docstring>A struct representing details on search strings.</tp:docstring>
- <tp:member type="b" name="Is_Mandatory">
- <tp:docstring>Booleans indicating if the search key is mandatory.
- </tp:docstring>
- </tp:member>
- <tp:member type="g" name="Type_Signature">
- <tp:docstring>The type signature of the value for this search key.
- </tp:docstring>
- </tp:member>
- </tp:struct>
+ <tp: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 in order to free unused handles.</p>
- <tp:mapping name="Search_Key_Info_Map">
- <tp:docstring>A dictionary mapping string search key names to its search details.
- </tp:docstring>
- <tp:member type="s" name="Term"/>
- <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
- </tp:mapping>
+ <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, so that any handles held
+ only by the channel can be released.</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>
- <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
- <arg direction="out" type="s">
- <tp:docstring>
- A string with any instructions from the server
- </tp:docstring>
- </arg>
- <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- A dictionary mapping string search key names to its search details.
- </tp:docstring>
- </arg>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Returns any instructions from the server along with a dictionary of
- search key names to their types, and a boolean indicating if the key is
- mandatory. The following well-known search key names should be used
- where appropriate:</p>
- <dl>
- <dt>s:first</dt><dd>The desired contact's given name</dd>
- <dt>s:last</dt><dd>The desired contact's family name</dd>
- <dt>s:nick</dt><dd>The desired contact's nickname</dd>
- <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
- </dl>
- </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:possible-errors>
- </method>
<tp:enum name="Channel_Contact_Search_State" type="u">
- <tp:enumvalue suffix="Before" value="0">
+ <tp:enumvalue suffix="Not_Started" value="0">
<tp:docstring>The search has not started</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="During" value="1">
+ <tp:enumvalue suffix="In_Progress" value="1">
<tp:docstring>The search is in progress</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="After" value="2">
+ <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>
- <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
- <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>The search state represented as one of the values of
- ChannelContactSearchState</tp:docstring>
+
+ <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: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 cannot change during the lifetime of the channel.
+ This property SHOULD be in the Allowed_Properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> 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:docstring>
- Returns the current state of this search channel object.
+ 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).
+ This property cannot change during the lifetime of a channel.
+
+ <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>
- </method>
- <method name="Search">
- <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
+ </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. A
- valid search request will cause the SearchStateChanged signal to be
- emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
+ 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.Disconnected"/>
+ <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:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
</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.Errors.Cancelled</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>
+
<signal name="SearchResultReceived"
tp:name-for-bindings="Search_Result_Received">
<arg name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>An integer handle for the contact</tp:docstring>
+ <tp:docstring>An integer handle for the contact, which will remain
+ valid at least until this Channel closes</tp:docstring>
</arg>
- <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
- <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
+ <arg 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.DRAFT</tp:dbus-ref>
+ interface. It is possible that a separate call to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+ would return more information than this signal provides.</p>
+
+ <p>This array SHOULD include the <code>x-telepathy-identifier</code>
+ field, whose values matches the result of calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ on the Contact handle.</p>
+
+ <tp:rationale>
+ <p>UIs will most likely want to show the identifier to the user;
+ while they could do this by inspecting the signalled handle,
+ including it in this signal is cheap and removes a roundtrip to
+ look it up.</p>
+ </tp:rationale>
+ </tp:docstring>
</arg>
<tp:docstring>
Emitted when a search result is received from the server.
</tp:docstring>
</signal>
- <signal name="SearchStateChanged"
- tp:name-for-bindings="Search_State_Changed">
- <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>An integer representing the new search state</tp:docstring>
- </arg>
+
+ <property name="Server" tp:name-for-bindings="Server"
+ type="s" access="read">
<tp:docstring>
- Emitted when the search state (as returned by the GetSearchState
- method) changes.
+ <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 cannot change during the lifetime of the channel.
+ This property SHOULD be in the Allowed_Properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> 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>
- </signal>
- <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 it should be
- closed when the search is completed or the required result has been found
- in order to free unused handles. The search can be cancelled at any time
- by calling the channel Close method, although depending upon the protocol
- the connection manager may not be able to prevent the server from sending
- further results.</p>
-
- <p>Before searching, the GetSearchKeys method should be used to discover any
- instructions sent by the server, and the valid search keys which can be
- provided to the Search method. A search request is then started by
- providing some of these terms to the Search method, and the search status
- will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
- returned by the server, the SearchResultReceived signal is emitted for each
- contact found, and when the search is complete, the search status will be
- set to CHANNEL_SEARCH_STATE_AFTER.</p>
- </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
index 2671a17..9615763 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_DBus_Tube" 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: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
@@ -17,10 +17,9 @@ 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.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+ <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>
@@ -54,14 +53,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
+ <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.
+ SHOULD NOT attempt to connect to the address until the tube is open.
</tp:docstring>
</arg>
<tp:possible-errors>
@@ -75,17 +87,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
+ <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 TubeStateChanged signal is
- emitted.
+ 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.
+ SHOULD NOT attempt to connect to the address until the tube is open.
</tp:docstring>
</arg>
</method>
@@ -96,12 +114,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
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">
+ <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[]">
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
Array of handles of former participants.
</tp:docstring>
@@ -113,11 +131,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<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
- com.example.ServiceName.</p>
+ <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>,
+ <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>
@@ -149,6 +168,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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>
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index c88834c..61e1bba 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
- Copyright (C) 2008 Collabora Limited
+ 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
@@ -76,6 +76,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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.DRAFT">SetSelfCapabilities</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"
@@ -146,6 +155,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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>
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 10ccac6..93ea777 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Room_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: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
@@ -87,7 +87,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dd>The current subject of conversation in the room</dd>
<dt>members (u)</dt>
- <dd>The number of members of the room</dd>
+ <dd>The number of members in the room</dd>
<dt>password (b)</dt>
<dd>True if the room requires a password to enter</dd>
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index b64f4a0..63e7b2f 100644
--- a/spec/Channel_Type_Stream_Tube.xml
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Stream_Tube" 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: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
@@ -17,19 +17,18 @@ 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.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
+ <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>OfferStreamTube</tp:member-ref> method. When a
+ <tp:member-ref>Offer</tp:member-ref> method. When a
recipient accepts a stream tube using the
- <tp:member-ref>AcceptStreamTube</tp:member-ref> method, 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
@@ -37,7 +36,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
- <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube">
+ <method name="Offer" tp:name-for-bindings="Offer">
<tp:docstring>
Offer a stream tube exporting the local socket specified.
</tp:docstring>
@@ -60,10 +59,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
when it connects.
</tp:docstring>
</arg>
- <arg direction="in" name="access_control_param" type="v">
+ <arg direction="in" name="parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
<tp:docstring>
- A parameter for the access control type, to be interpreted as
- specified in the documentation for the Socket_Access_Control enum.
+ 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>
@@ -83,12 +84,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:possible-errors>
</method>
- <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube">
+ <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 TubeStateChanged signal is
- emitted.
+ 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>
@@ -96,9 +98,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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 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">
@@ -129,17 +136,94 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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.
+ <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">
+ <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"
@@ -192,6 +276,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index b89065b..db0b657 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <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
@@ -22,7 +22,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
- <tp:enum name="Media_Stream_Type" type="u">
+ <tp: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>
@@ -86,7 +87,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
name="Pending_Send_Flags"/>
</tp:struct>
- <tp:simple-type name="Stream_ID" type="u"/>
+ <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[]"
@@ -118,9 +124,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member-ref>ListStreams</tp:member-ref>)
</tp:docstring>
</arg>
- <tp:docstring>
- Request that the given streams are removed.
+
+ <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">
A stream identifier is unknown
@@ -209,11 +230,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
MEDIA_STREAM_PENDING_REMOTE_SEND flag set, and the signal emitted again
with the flag cleared when the remote end has replied.</p>
- <p>If streams of the requested types have already been requested
- via this method or <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>/<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialVideo</tp:dbus-ref>,
- this method SHOULD return successfully.</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
@@ -231,10 +253,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- A stream type given is invalid
+ <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">
- That contact is not able to do this stream type
+ <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>
@@ -257,8 +304,54 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The stream type (a value from MediaStreamType)
</tp:docstring>
</arg>
- <tp:docstring>
- Emitted when a new stream has been added to this channel.
+ <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>
@@ -279,12 +372,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The new pending send flags (as defined in ListStreams)
</tp:docstring>
</arg>
- <tp:docstring>
- Emitted when the direction or pending flags of a stream are changed. 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.
+ <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>
@@ -367,6 +468,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
which point the contact should appear in the channel's <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemotePendingMembers</tp:dbus-ref>).</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>
+
<p>Incoming calls should be signalled as <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
= Contact, <tp:dbus-ref
@@ -377,10 +483,24 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref>
can be used to move the local user to the group's members.</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>
+ <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>
<p>In general this should be used in conjunction with the <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
@@ -422,6 +542,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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:flags>
</interface>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 2421ed6..07a181e 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Streamed_Media_Future"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+ <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
@@ -109,18 +109,18 @@
SHOULD include the following filters if calling <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
(clients of a <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</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.DRAFT">HandlerChannelFilter</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 audio-only or audio+video calls is supported</li>
+ if receiving calls with audio is supported</li>
<li>{ ChannelType = StreamedMedia, InitialVideo = true }
- if receiving video-only or audio+video calls is supported</li>
+ if receiving calls with video is supported</li>
</ul>
<tp:rationale>
@@ -128,21 +128,6 @@
like XMPP, need this information to advertise the appropriate
capabilities for their protocol.</p>
</tp:rationale>
-
- <p>If { ChannelType = StreamedMedia } is passed to
- SetSelfCapabilities, but no more specific channel class for
- audio or video has been passed to that method (in the presence
- of a ChannelDispatcher, this would mean that there is at least one
- client with that channel class in its HandlerChannelFilter, but
- no installed client has the more specific channel classes in its
- HandlerChannelFilter), then the connection manager SHOULD advertise
- support for every content type (audio or video) that it
- supports.</p>
-
- <tp:rationale>
- <p>This lowers the "barrier to entry" by allowing a simple client
- to say merely that it supports streamed media at all.</p>
- </tp:rationale>
</tp:docstring>
</property>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5c28dce..7d6e314 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Text" 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: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
@@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Type.Text">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:simple-type name="Message_ID" type="u">
+ <tp: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,
@@ -87,7 +87,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member-ref>AcknowledgePendingMessages</tp:member-ref> had also
been called.
</tp:docstring>
- <tp:deprecated since="0.17.3">
+ <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
@@ -290,7 +290,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</signal>
- <tp:enum name="Channel_Text_Message_Type" type="u">
+ <tp:enum name="Channel_Text_Message_Type" type="u"
+ array-name="Channel_Text_Message_Type_List">
<tp:docstring>
The type of message.
</tp:docstring>
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index f6829b5..c0a973f 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
- Copyright (C) 2007-2008 Collabora Limited
+ Copyright © 2007-2009 Collabora Limited
</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
@@ -19,6 +19,14 @@ 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
@@ -71,57 +79,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</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:enum name="Tube_Type" type="u">
+ <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
@@ -155,91 +113,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:enumvalue>
</tp:enum>
- <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">
- <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: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>The connecting process must send a single zero (NUL) 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>
-
<tp:mapping name="Supported_Socket_Map">
<tp:docstring>The supported socket address and access-control types
for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
diff --git a/spec/Client.xml b/spec/Client.xml
index d0bb8e5..19f6914 100644
--- a/spec/Client.xml
+++ b/spec/Client.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Client"
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: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
@@ -20,9 +20,8 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.12">(as a draft)</tp:added>
+ <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
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 8f59a19..8a920a1 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Client_Approver"
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: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
@@ -20,21 +20,29 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Approver.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.12">(as a draft)</tp:added>
+ <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.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Approvers notify the user that new channels have been created,
- and allow the user to accept or reject those channels.</p>
-
- <p>They can also select which channel handler will be used for the
+ <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.</p>
-
- <p>However, the Channel Dispatcher must be able to prioritize
+ 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>
@@ -49,12 +57,22 @@
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 with a
- particular channel handler. Approvers can also request that the
- channel is rejected. The first approver to reply gets its decision
- acted on; any other approvers that reply at the same time will
- get a D-Bus error, indicating that the channel has already been
- dealt with.</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
@@ -67,16 +85,16 @@
<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 the
- channels in a channel dispatch operation
- match this description.</p>
-
- <p>(FIXME: what happens if some but not all of the channels
- match this?)</p>
+ 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.DRAFT.ObserverChannelFilter</tp:dbus-ref>
- property. In the .client file, it is represented in 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>
@@ -92,18 +110,62 @@
operations already exist.</p>
<p>The channel dispatcher SHOULD call this method on all approvers
- at the same time. If no approvers return from this method
+ 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 shouldn't be making connections
- anyway - there should always be at least one approver running.
+ 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
@@ -115,19 +177,16 @@
<arg name="Properties" type="a{sv}"
tp:type="Qualified_Property_Value_Map" direction="in">
<tp:docstring>
- Properties of the channel dispatch operation. 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.DRAFT">Account</tp:dbus-ref>,
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Connection</tp:dbus-ref>,
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Channels</tp:dbus-ref>
- and
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">PossibleHandlers</tp:dbus-ref>
- properties.
+ <p>Properties of the channel dispatch operation. 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>
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index 59c253b..d366862 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Client_Handler"
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: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
@@ -20,16 +20,30 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Handler.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.12">(as a draft)</tp:added>
+ <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.DRAFT"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Client"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Channel handlers are the eventual handler for a channel or a
- channel bundle; a typical channel handler is a user interface
- process handling channels of a particular type.</p>
+ <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>
@@ -60,8 +74,11 @@
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.DRAFT.ObserverChannelFilter</tp:dbus-ref>
- property. In the .client file, it is represented in 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>
@@ -105,13 +122,14 @@
paths.</p>
</tp:rationale>
- <p>This method can raise any D-Bus error. If it does, or if the
- handler loses its bus name before all the channels have closed, the
+ <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.</p>
+ dispatcher MUST recover in an implementation-specific way; it MAY
+ attempt to dispatch the channels to another handler, or close the
+ channels.</p>
- <p>It is RECOMMENDED that the channel dispatcher attempts to
- close the channels using
+ <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
@@ -119,6 +137,17 @@
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">
@@ -140,7 +169,8 @@
</tp:docstring>
</arg>
- <arg name="Channels" type="a(oa{sv})" direction="in">
+ <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.
@@ -148,12 +178,17 @@
</arg>
<arg name="Requests_Satisfied" type="ao" direction="in">
- <tp:docstring>
- The requests satisfied by these channels.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requests satisfied by these channels.</p>
<tp:rationale>
- There can be more than one, if they were EnsureChannel
- requests.
+ <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>
@@ -167,95 +202,23 @@
</tp:docstring>
</arg>
- <!-- FIXME: invent a way to say "any error is possible" in spec markup -->
- </method>
-
- <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 be
- handled by this Handler.</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>
- </tp:rationale>
-
- <p>(FIXME: how do we know the returned channels will be handled by
- this handler? Do we just assume that they'll match the
- HandlerChannelFilter iff the request does?)</p>
- </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.DRAFT">CreateChannel</tp:dbus-ref>
- or <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT">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.DRAFT">Requests</tp:dbus-ref>
- and <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref>
- MUST be included.</p>
- </tp:docstring>
- </arg>
- </method>
-
- <method name="RemoveFailedRequest"
- tp:name-for-bindings="Remove_Failed_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>
- </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">
+ <arg name="Handler_Info" type="a{sv}" 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>Additional information about these channels. No keys are
+ currently defined.</p>
- <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>,
- this indicates that the request succeeded, but all the resulting
- channels were given to some other handler.</p>
+ <p>If keys are defined for this dictionary, all will be optional;
+ handlers MAY safely ignore any entry in this dictionary.</p>
</tp:docstring>
</arg>
- <arg name="Message" type="s" direction="in">
- <tp:docstring>
- Any message supplied with the D-Bus error.
- </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 Handler is currently handling.
- </p>
+ <p>A list of the channels that this process is currently handling.</p>
<p>There is no change notification.</p>
@@ -271,6 +234,17 @@
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>
diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml
new file mode 100644
index 0000000..f777a2a
--- /dev/null
+++ b/spec/Client_Interface_Requests.xml
@@ -0,0 +1,171 @@
+<?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>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
+ MUST be included.</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
index 40c71e7..a070175 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Client_Observer"
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: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
@@ -20,11 +20,10 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Observer.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.12">(as a draft)</tp:added>
+ <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.DRAFT"/>
+ <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
@@ -65,11 +64,11 @@
to the Observer.</p>
</tp:rationale>
- <p>Whenever new channels are signalled, the channel dispatcher
- will notify all running or activatable observers whose
+ <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 the channel.</p>
+ 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 -
@@ -78,6 +77,15 @@
<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"
@@ -87,11 +95,9 @@
<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 NewChannels signal match this description.</p>
-
- <p>(FIXME: open issue: do we want this, and the corresponding
- Approver and Handler properties, to be able to change at
- runtime?)</p>
+ 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>
@@ -116,10 +122,28 @@
</dl>
- <p>This property never changes while the observer process is
- running. 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>
+ <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
@@ -138,15 +162,15 @@
a local client:</p>
<pre>
-[org.freedesktop.Telepathy.Client.DRAFT]
-Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT;
+[org.freedesktop.Telepathy.Client]
+Interfaces=org.freedesktop.Telepathy.Client.Observer;
-[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0]
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 0]
org.freedesktop.Telepathy.Channel.Type 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.DRAFT.ObserverChannelFilter 1]
+[org.freedesktop.Telepathy.Client.Observer.ObserverChannelFilter 1]
org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
org.freedesktop.Telepathy.Channel.TargetHandleType u=2
org.freedesktop.Telepathy.Channel.Requested b=true
@@ -158,7 +182,18 @@ org.freedesktop.Telepathy.Channel.Requested b=true
<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 created.</p>
+ 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
@@ -167,12 +202,23 @@ org.freedesktop.Telepathy.Channel.Requested b=true
<tp:rationale>
<p>The channel dispatcher must wait for observers to start up,
to avoid the following race: text channel logger (observer) gets
- ObserveChannel, text channel handler gets
+ ObserveChannels, text channel handler gets
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</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">
@@ -206,19 +252,41 @@ org.freedesktop.Telepathy.Channel.Requested b=true
</tp:docstring>
</arg>
- <arg name="DispatchOperation" type="o" direction="in">
+ <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 path to the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
- for these channels, or the special value '/' if there is no
- ChannelDispatchOperation (because the channels were requested, not incoming).
+ The requests satisfied by these channels.
<tp:rationale>
- This allows an Observer to <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">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.DRAFT">AddDispatchOperation</tp:dbus-ref>.
+ 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>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 97a3c4c..2b03f96 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -22,8 +22,11 @@ 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">
@@ -45,17 +48,14 @@ USA.</p>
</tp:struct>
<method name="Connect" tp:name-for-bindings="Connect">
- <tp:docstring>
- 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.
- </tp:docstring>
+ <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>
- <tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
- The connection is already connecting or connected
- </tp:error>
- </tp:possible-errors>
+ <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">
@@ -272,6 +272,12 @@ USA.</p>
</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>
@@ -289,6 +295,12 @@ USA.</p>
</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
@@ -381,6 +393,15 @@ USA.</p>
</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
@@ -534,27 +555,31 @@ USA.</p>
</tp:enumvalue>
</tp:enum>
- <tp:simple-type name="Handle" type="u">
+ <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">
+ <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">
+ <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">
+ <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">
+ <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>
@@ -970,7 +995,8 @@ USA.</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.Presence for receiving and
+ 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
@@ -1007,6 +1033,11 @@ USA.</p>
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_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 7ef26af..e6f7ac5 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -21,7 +21,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Connection.Interface.Avatars">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:simple-type name="Avatar_Token" type="s">
+ <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
@@ -124,8 +125,131 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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)
@@ -179,6 +303,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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.
@@ -244,6 +370,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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.
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index e7b033b..d085454 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -31,28 +31,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:member>
<tp:member type="as" name="Parameters">
- <tp:docstring>
- A list of (lowercased) vCard type parameters applicable to this field.
- For example, a contact's preferred home address would have parameters
- 'home' and 'pref'.
+ <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>
- This is a list of strings rather than a bitwise OR of enum members
- because vCard type parameters are essentially arbitrary strings.
+ 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>
- For unstructured vCard fields (such as 'fn', a formatted name
- field), a single-element array containing the field's value; 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). A vCard field with multiple
- comma-separated values should be represented by several
- <tp:type>Contact_Info_Field</tp:type>s. Characters which are
- required to be escaped in vCard values, such as semi-colons, should
- not be escaped in this list.
+ <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
@@ -103,7 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
BEGIN:vCard
VERSION:3.0
FN:Wee Ninja
- N:Ninja;Wee;;;-san
+ N;LANGUAGE=ja:Ninja;Wee;;;-san
ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
;CB2 1SJ;UK
@@ -111,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
EMAIL;TYPE=INTERNET,PREF:wee.ninja at collabora.co.uk
EMAIL;TYPE=INTERNET:wee.ninja at 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>
@@ -118,15 +139,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<pre>
[
('fn', [], ['Wee Ninja']),
- ('n', [], ['Ninja', 'Wee', '', '', '-san']),
+ ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
- ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
- 'Cambridgeshire','CB2 1SJ','UK']),
- ('tel', ['voice','work'], ['+44 1223 362967']),
- ('tel', ['voice','work'], ['+44 7700 900753']),
- ('email', ['internet','pref'], ['wee.ninja at collabora.co.uk']),
- ('email', ['internet'], ['wee.ninja at example.com']),
+ ('adr', ['type=work','type=postal','type=parcel'],
+ ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+ ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+ ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+ ('email', ['type=internet','type=pref'], ['wee.ninja at collabora.co.uk']),
+ ('email', ['type=internet'], ['wee.ninja at example.com']),
('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+ ('nickname', [], ['HR Ninja']),
+ ('nickname', [], ['Enforcement Ninja'])
]</pre>
</tp:docstring>
</tp:struct>
@@ -267,11 +290,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:enumvalue>
</tp:enum>
+ <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_Flag" tp:name-for-bindings="Contact_Info_Flags">
<tp:docstring>
- An integer representing the bitwise-OR of flags on this channel. This
- property should be constant over the lifetime of a connection.
+ An integer representing the bitwise-OR of flags on this connection.
+ This property should be constant over the lifetime of a connection.
</tp:docstring>
</property>
@@ -280,11 +321,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this
Connection.</tp:docstring>
- <tp:member type="s" name="Name">
+ <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: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_Mandatory
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 6d9b24a..8a344d4 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -26,8 +26,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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"/>
- <!-- We hope to simplify these eventually -->
<tp:mapping name="Multiple_Status_Map">
<tp:docstring>Mapping used in
<tp:type>Last_Activity_And_Statuses</tp:type> and passed to
@@ -249,17 +249,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
map optional parameter names to their variant-boxed values
</tp:docstring>
</arg>
- <tp:docstring>
- 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. 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.
+ <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"/>
@@ -269,12 +281,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
+
+ <tp: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 will become deprecated in future versions. New
- client implementations MAY use <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
- instead; new connection managers SHOULD implement both Presence and
- SimplePresence.</p>
<p>This interface is for services which have a concept of presence which
can be published for yourself and monitored on your contacts.
@@ -287,28 +302,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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 following well-known values (in common with those in
- Galago) should be used where possible to allow clients to identify common
- choices:</p>
-
- <ul>
- <li>available (corresponding to Connection_Presence_Type_Available)</li>
- <li>away (corresponding to Connection_Presence_Type_Away)</li>
- <li>brb (Be Right Back) (corresponding to
- Connection_Presence_Type_Away, but more specific)</li>
- <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
- <li>dnd (Do Not Disturb) (corresponding to
- Connection_Presence_Type_Busy, but more specific)</li>
- <li>xa (Extended Away) (corresponding to
- Connection_Presence_Type_Extended_Away)</li>
- <li>hidden (aka Invisible) (corresponding to
- Connection_Presence_Type_Hidden)</li>
- <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
- <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
- <li>error (corresponding to Connection_Presence_Type_Error)</li>
- </ul>
+ 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
@@ -339,125 +341,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
intermittently to update any display of presence information.</p>
</tp:docstring>
- <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 result of <tp:member-ref>GetStatuses</tp:member-ref>,
- or in the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref>
- property of the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</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="Rich_Presence_Access_Control_Type" type="u">
- <tp:docstring>
- A type of access control for Rich_Presence_Access_Control.
- For most types, the exact access control is given by an associated
- variant.
-
- <tp:rationale>
- These are the access control types from XMPP publish/subscribe
- (XEP-0060).
- </tp:rationale>
- </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="Rich_Presence_Access_Control">
- <tp:docstring>
- An access control mode for extended presence items like geolocation.
- This type isn't actually used by the core Presence interface, but
- it's included here so it can be referenced by other specifications.
- </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
- Rich_Presence_Access_Control_Type.
- </tp:docstring>
- </tp:member>
- </tp:struct>
-
</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
index 3e47262..5c56db3 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -30,6 +30,12 @@
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">
@@ -217,6 +223,12 @@
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
@@ -356,6 +368,12 @@
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
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 16f3386..8446050 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -151,6 +151,16 @@
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">
@@ -232,9 +242,9 @@
<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 the user
- can set on themselves for this connection, and the values are the
- corresponding presence types.</p>
+ <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.
@@ -280,6 +290,128 @@
</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="Rich_Presence_Access_Control_Type" type="u"
+ array-name="Rich_Presence_Access_Control_Type_List">
+ <tp:docstring>
+ A type of access control for Rich_Presence_Access_Control.
+ For most types, the exact access control is given by an associated
+ variant.
+
+ <tp:rationale>
+ These are the access control types from XMPP publish/subscribe
+ (XEP-0060).
+ </tp:rationale>
+ </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="Rich_Presence_Access_Control">
+ <tp:docstring>
+ 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.DRAFT</tp:dbus-ref>.
+ </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: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>
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index 46b56ac..ad8f058 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -55,7 +55,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
characters were not specified</tp:changed>
</tp:simple-type>
- <tp:simple-type name="Protocol" type="s">
+ <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
diff --git a/spec/Debug.xml b/spec/Debug.xml
new file mode 100644
index 0000000..a21d9db
--- /dev/null
+++ b/spec/Debug.xml
@@ -0,0 +1,166 @@
+<?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.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.17.24"/>
+
+ <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
index a6cf519..70aa750 100644
--- a/spec/Media_Session_Handler.xml
+++ b/spec/Media_Session_Handler.xml
@@ -23,19 +23,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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>
- THIS METHOD IS DEPRECATED AND SHOULD NOT BE USED. Instead the Error
- function should be used on the relevant MediaStreamHandler objects.
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 StreamError signal on the
- channel for each stream within the session.
+ 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>
- An object path to a new MediaStreamHandler
+ 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">
@@ -45,14 +51,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<arg name="Media_Type" type="u" tp:type="Media_Stream_Type">
<tp:docstring>
- Enum for type of media that this stream should handle
- (a value from MediaStreamType)
+ Type of media that this stream should handle
</tp:docstring>
</arg>
<arg name="Direction" type="u" tp:type="Media_Stream_Direction">
<tp:docstring>
- Enum for direction of this stream (a value from
- MediaStreamDirection)
+ Direction of this stream
</tp:docstring>
</arg>
<tp:docstring>
@@ -64,7 +68,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>
Inform the connection manager that a client is ready to handle
this session handler (i.e. that it has connected to the
- NewStreamHandler signal and done any other necessary setup).
+ <tp:member-ref>NewStreamHandler</tp:member-ref> signal and done any
+ other necessary setup).
</tp:docstring>
</method>
<tp:docstring>
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index cb7c793..d335e38 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -70,6 +70,150 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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">
@@ -246,7 +390,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
String identifier for remote candidate to drop
</tp:docstring>
</arg>
- <tp:deprecated>
+ <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>).
diff --git a/spec/Properties_Interface.xml b/spec/Properties_Interface.xml
index 91423c1..bc9c8b2 100644
--- a/spec/Properties_Interface.xml
+++ b/spec/Properties_Interface.xml
@@ -39,7 +39,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:member type="u" name="New_Flags"/>
</tp:struct>
- <tp:simple-type name="Property_ID" type="u">
+ <tp: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>
@@ -158,7 +158,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
tp:type="Property_Value[]">
<!-- XXX: if we're ever breaking API compatibility, make this a{uv} -->
<tp:docstring>
- A dictionary mapping integer identifiers to boxed values
+ An array mapping integer property identifiers to boxed values
</tp:docstring>
</arg>
<tp:possible-errors>
diff --git a/spec/all.xml b/spec/all.xml
index 7745d54..dd228e2 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,11 +3,11 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.19</tp:version>
+<tp:version>0.17.26</tp:version>
-<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: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
@@ -25,69 +25,149 @@ 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>
-<xi:include href="Connection_Manager.xml"/>
-<xi:include href="Connection.xml"/>
-<xi:include href="Connection_Interface_Aliasing.xml"/>
-<xi:include href="Connection_Interface_Avatars.xml"/>
-<xi:include href="Connection_Interface_Capabilities.xml"/>
-<xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
-<xi:include href="Connection_Interface_Contact_Info.xml"/>
-<xi:include href="Connection_Interface_Contacts.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_Requests.xml"/>
-<xi:include href="Connection_Interface_Simple_Presence.xml"/>
-
-<xi:include href="Channel_Bundle.xml"/>
-
-<xi:include href="Channel.xml"/>
-<xi:include href="Channel_Future.xml"/>
-<xi:include href="Channel_Type_Contact_List.xml"/>
-<xi:include href="Channel_Type_Streamed_Media.xml"/>
-<xi:include href="Channel_Type_Streamed_Media_Future.xml"/>
-<xi:include href="Channel_Type_Room_List.xml"/>
-<xi:include href="Channel_Type_Text.xml"/>
-<xi:include href="Channel_Type_Tubes.xml"/>
-<xi:include href="Channel_Type_Stream_Tube.xml"/>
-<xi:include href="Channel_Type_DBus_Tube.xml"/>
-<xi:include href="Channel_Type_File_Transfer.xml"/>
-
-<xi:include href="Channel_Interface_Call_Merging.xml"/>
-<xi:include href="Channel_Interface_Call_State.xml"/>
-<xi:include href="Channel_Interface_Chat_State.xml"/>
-<xi:include href="Channel_Interface_Destroyable.xml"/>
-<xi:include href="Channel_Interface_DTMF.xml"/>
-<xi:include href="Channel_Interface_Group.xml"/>
-<xi:include href="Channel_Interface_Hold.xml"/>
-<xi:include href="Channel_Interface_HTML.xml"/>
-<xi:include href="Channel_Interface_Password.xml"/>
-<xi:include href="Channel_Interface_Media_Signalling.xml"/>
-<xi:include href="Channel_Interface_Media_Signalling_Future.xml"/>
-<xi:include href="Channel_Interface_Messages.xml"/>
-<xi:include href="Channel_Interface_Tube.xml"/>
-
-<xi:include href="Media_Session_Handler.xml"/>
-<xi:include href="Media_Stream_Handler.xml"/>
+<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"/>
+
+ <tp:section name="Connection Object">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Connections represent active protocol sessions.
+ </p>
+ </tp:docstring>
+ <xi:include href="Connection.xml"/>
+ <xi:include href="Connection_Interface_Aliasing.xml"/>
+ <xi:include href="Connection_Interface_Avatars.xml"/>
+ <xi:include href="Connection_Interface_Capabilities.xml"/>
+ <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
+ <xi:include href="Connection_Interface_Contact_Info.xml"/>
+ <xi:include href="Connection_Interface_Contacts.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_Requests.xml"/>
+ <xi:include href="Connection_Interface_Simple_Presence.xml"/>
+ </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_Contact_List.xml"/>
+ <xi:include href="Channel_Type_Streamed_Media.xml"/>
+ <xi:include href="Channel_Type_Streamed_Media_Future.xml"/>
+ <xi:include href="Channel_Type_Room_List.xml"/>
+ <xi:include href="Channel_Type_Text.xml"/>
+ <xi:include href="Channel_Type_Tubes.xml"/>
+ <xi:include href="Channel_Type_Stream_Tube.xml"/>
+ <xi:include href="Channel_Type_DBus_Tube.xml"/>
+ <xi:include href="Channel_Type_File_Transfer.xml"/>
+ <xi:include href="Channel_Type_Contact_Search.xml"/>
+ </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:
+ </p>
+ </tp:docstring>
+ <xi:include href="Channel_Interface_Call_Merging.xml"/>
+ <xi:include href="Channel_Interface_Call_State.xml"/>
+ <xi:include href="Channel_Interface_Chat_State.xml"/>
+ <xi:include href="Channel_Interface_Destroyable.xml"/>
+ <xi:include href="Channel_Interface_DTMF.xml"/>
+ <xi:include href="Channel_Interface_Group.xml"/>
+ <xi:include href="Channel_Interface_Hold.xml"/>
+ <xi:include href="Channel_Interface_HTML.xml"/>
+ <xi:include href="Channel_Interface_Password.xml"/>
+ <xi:include href="Channel_Interface_Media_Signalling.xml"/>
+ <xi:include href="Channel_Interface_Media_Signalling_Future.xml"/>
+ <xi:include href="Channel_Interface_Messages.xml"/>
+ <xi:include href="Channel_Interface_Tube.xml"/>
+ </tp:section>
+ </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="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_Avatar.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_Interface_Requests.xml"/>
+
+ <xi:include href="Channel_Handler.xml"/>
+</tp:section>
<xi:include href="Properties_Interface.xml"/>
-<xi:include href="Account_Manager.xml"/>
-<xi:include href="Account.xml"/>
-<xi:include href="Account_Interface_Avatar.xml"/>
-
-<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"/>
-
-<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="Channel_Handler.xml"/>
-
<xi:include href="errors.xml"/>
<xi:include href="generic-types.xml"/>
diff --git a/spec/errors.xml b/spec/errors.xml
index 0a2d7d2..7b1798d 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -1,8 +1,5 @@
<?xml version="1.0" ?>
<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">
- <!-- Don't re-order these errors until fd.o #17588 is fixed, or you will
- break telepathy-glib's ABI.
- -->
<tp:error name="Network Error">
<tp:docstring>
Raised when there is an error reading from or writing to the network.
@@ -296,8 +293,40 @@
</tp:docstring>
</tp:error>
- <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
+ <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:copyright>Copyright © 2005-2009 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
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index fba6a9f..d4dce15 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -17,23 +17,27 @@
interfaces.</tp:rationale>
</tp:simple-type>
- <tp:simple-type name="DBus_Bus_Name" type="s">
+ <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">
+ <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">
+ <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">
+ <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
@@ -60,7 +64,8 @@
characters. For example, "Ping".</tp:docstring>
</tp:simple-type>
- <tp:simple-type name="DBus_Qualified_Member" type="s">
+ <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,
@@ -90,11 +95,74 @@
<tp:member type="v" name="Value"/>
</tp:mapping>
- <tp:mapping name="String_String_Map">
+ <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:generic-types>
--
1.5.6.5
More information about the telepathy-commits
mailing list