[telepathy-glib/master] Update to telepathy-spec 0.17.23 (add Terminated error)
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Apr 22 04:34:28 PDT 2009
---
spec/Account.xml | 16 ++
spec/Channel_Dispatch_Operation.xml | 152 +++++++++++----
spec/Channel_Dispatcher.xml | 89 ++++-----
...Channel_Dispatcher_Interface_Operation_List.xml | 19 +-
spec/Channel_Handler.xml | 15 +-
spec/Channel_Interface_Group.xml | 19 ++-
spec/Channel_Interface_Media_Signalling_Future.xml | 4 +-
spec/Channel_Request.xml | 34 +++-
spec/Channel_Type_File_Transfer.xml | 9 +
spec/Channel_Type_Streamed_Media.xml | 29 +++-
spec/Channel_Type_Streamed_Media_Future.xml | 4 +-
spec/Client.xml | 10 +-
spec/Client_Approver.xml | 142 ++++++++++----
spec/Client_Handler.xml | 168 +++++++----------
spec/Client_Interface_Requests.xml | 173 +++++++++++++++++
spec/Client_Observer.xml | 135 ++++++++++----
spec/Connection.xml | 46 ++++-
spec/Connection_Interface_Presence.xml | 8 +-
spec/Connection_Interface_Requests.xml | 12 ++
spec/Makefile.am | 1 +
spec/Media_Session_Handler.xml | 25 ++-
spec/all.xml | 199 ++++++++++++++------
spec/errors.xml | 21 ++-
telepathy-glib/errors.c | 6 +
telepathy-glib/errors.h | 1 +
25 files changed, 949 insertions(+), 388 deletions(-)
create mode 100644 spec/Client_Interface_Requests.xml
diff --git a/spec/Account.xml b/spec/Account.xml
index 9dc34ad..b6a2670 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -494,6 +494,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/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index fdee944..a44712c 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -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:causes-havoc="not yet final">
<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">
@@ -164,17 +201,6 @@
<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.DRAFT</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 af671bd..8680f6d 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -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:causes-havoc="not yet final">
<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 7a1c0e1..e3270ce 100644
--- a/spec/Channel_Dispatcher_Interface_Operation_List.xml
+++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml
@@ -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:causes-havoc="not yet final">
- <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
@@ -51,7 +51,7 @@
<tp:docstring>
The object path of the
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>.
</tp:docstring>
</tp:member>
@@ -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_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_Group.xml b/spec/Channel_Interface_Group.xml
index db17a0b..a3319bf 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -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"/>
@@ -580,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">
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
index 102f206..bbb8b87 100644
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -94,10 +94,10 @@
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>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 3706bdb..c69266a 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -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:causes-havoc="not yet final">
<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>
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index 7795f9d..61e1bba 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -155,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_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index c4ddea7..db0b657 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -253,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>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 5b75c5f..07a181e 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -109,10 +109,10 @@
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>
diff --git a/spec/Client.xml b/spec/Client.xml
index 5307efa..ba29900 100644
--- a/spec/Client.xml
+++ b/spec/Client.xml
@@ -20,8 +20,8 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Client"
+ tp:causes-havoc="not yet final">
<tp:added version="0.17.12">(as a draft)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -105,9 +105,9 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of the extra interfaces provided by this client.
This SHOULD include at least one of
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT</tp:dbus-ref>,
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver.DRAFT</tp:dbus-ref> or
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler.DRAFT</tp:dbus-ref>.</p>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p>
<p>In the <code>.client</code> file, this is represented by key
"<code>Interfaces</code>" in the group named after this interface.
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 8725c81..62f6694 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -20,21 +20,30 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Approver.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Client.Approver"
+ tp:causes-havoc="not yet final">
<tp:added version="0.17.12">(as a draft)</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 +58,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 +86,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,22 +111,66 @@
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
- <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>
to be processed.</p>
</tp:docstring>
</arg>
@@ -115,19 +178,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 3d75f0b..da48701 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -20,21 +20,36 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Handler.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Client.Handler"
+ tp:causes-havoc="not yet final">
<tp:added version="0.17.12">(as a draft)</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>
= FALSE) is offered to
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref>s
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
by the channel dispatcher, it also offers the Approvers a list of all
the running or activatable handlers whose
<tp:member-ref>HandlerChannelFilter</tp:member-ref> property
@@ -60,8 +75,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 +123,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 +138,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">
@@ -149,12 +179,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>
@@ -168,95 +203,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.DRAFT</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.Error.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>
@@ -272,6 +235,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..1b0de98
--- /dev/null
+++ b/spec/Client_Interface_Requests.xml
@@ -0,0 +1,173 @@
+<?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:causes-havoc="not yet final">
+ <tp:added version="0.17.23">(as a draft; functionality
+ moved from Handler)</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 c06f83d..58b67b3 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -20,11 +20,11 @@
02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Client.Observer.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Client.Observer"
+ tp:causes-havoc="not yet final">
<tp:added version="0.17.12">(as a draft)</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
@@ -56,7 +56,7 @@
channels, doing the actual data transfer for file transfers,
setting up the out-of-band connection for Tubes). The
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client">Handler.DRAFT</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
is responsible for such tasks.</p>
<p>Handlers MAY, of course, delegate responsibility for these
@@ -65,11 +65,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 +78,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 +96,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 +123,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 +163,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 +183,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 +203,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 +253,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 39fb738..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
@@ -1012,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_Presence.xml b/spec/Connection_Interface_Presence.xml
index 100ec36..8a344d4 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -26,6 +26,7 @@ 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"/>
<tp:mapping name="Multiple_Status_Map">
<tp:docstring>Mapping used in
@@ -281,11 +282,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
- <tp:deprecated version="0.17.21">New client implementations
+ <tp:deprecated version="0.17.21">Client implementations
SHOULD use <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
- instead. New connection managers SHOULD implement both Presence
- and SimplePresence.</tp:deprecated>
+ 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">
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 3e47262..b63aa5b 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -217,6 +217,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 +362,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/Makefile.am b/spec/Makefile.am
index 3e12b10..a8abd87 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -37,6 +37,7 @@ EXTRA_DIST = \
Client.xml \
Client_Approver.xml \
Client_Handler.xml \
+ Client_Interface_Requests.xml \
Client_Observer.xml \
Connection_Interface_Aliasing.xml \
Connection_Interface_Avatars.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/all.xml b/spec/all.xml
index 952ff6b..93ce925 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,7 +3,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.22</tp:version>
+<tp:version>0.17.23</tp:version>
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
@@ -25,70 +25,145 @@ 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_Type_Contact_Search.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>
+
+<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..f82c532 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,22 @@
</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: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/telepathy-glib/errors.c b/telepathy-glib/errors.c
index 92f33ca..e4d1e03 100644
--- a/telepathy-glib/errors.c
+++ b/telepathy-glib/errors.c
@@ -133,6 +133,11 @@
* not respond, e.g. to a StreamedMedia call.
* @TP_ERROR_DOES_NOT_EXIST: org.freedesktop.Telepathy.Error.DoesNotExist:
* Raised when the requested user does not, in fact, exist.
+ * @TP_ERROR_TERMINATED: org.freedesktop.Telepathy.Error.Terminated:
+ * 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.
*
* Enumerated type representing the Telepathy D-Bus errors.
*/
@@ -229,6 +234,7 @@ tp_error_get_type (void)
{ TP_ERROR_BUSY, "TP_ERROR_BUSY", "Busy" },
{ TP_ERROR_NO_ANSWER, "TP_ERROR_NO_ANSWER", "NoAnswer" },
{ TP_ERROR_DOES_NOT_EXIST, "TP_ERROR_DOES_NOT_EXIST", "DoesNotExist" },
+ { TP_ERROR_TERMINATED, "TP_ERROR_TERMINATED", "Terminated" },
{ 0 }
};
diff --git a/telepathy-glib/errors.h b/telepathy-glib/errors.h
index 78046e6..81e6b1c 100644
--- a/telepathy-glib/errors.h
+++ b/telepathy-glib/errors.h
@@ -68,6 +68,7 @@ typedef enum {
TP_ERROR_BUSY,
TP_ERROR_NO_ANSWER,
TP_ERROR_DOES_NOT_EXIST,
+ TP_ERROR_TERMINATED,
} TpError;
G_END_DECLS
--
1.5.6.5
More information about the telepathy-commits
mailing list