[telepathy-qt4/master] Update to spec 0.17.28
Andre Moreira Magalhaes (andrunko)
andre.magalhaes at collabora.co.uk
Fri Sep 18 09:03:33 PDT 2009
---
spec/Channel.xml | 11 +-
spec/Channel_Dispatcher.xml | 2 +-
spec/Channel_Interface_Call_State.xml | 14 +-
spec/Channel_Interface_Delivery_Reporting.xml | 444 --------------------
spec/Channel_Interface_Media_Signalling.xml | 78 ++++
spec/Channel_Interface_Media_Signalling_Future.xml | 164 -------
spec/Channel_Interface_Tube.xml | 2 +-
spec/Channel_Type_Contact_Search.xml | 32 +-
spec/Channel_Type_File_Transfer.xml | 2 +-
spec/Channel_Type_Room_List.xml | 2 +-
spec/Channel_Type_Streamed_Media.xml | 161 +++++++-
spec/Channel_Type_Streamed_Media_Future.xml | 151 -------
spec/Channel_Type_Text.xml | 4 +-
spec/Client_Approver.xml | 9 +-
spec/Client_Handler.xml | 65 +++
spec/Connection.xml | 72 +++-
spec/Connection_Interface_Aliasing.xml | 19 +-
spec/Connection_Interface_Avatars.xml | 15 +
spec/Connection_Interface_Capabilities.xml | 23 +-
spec/Connection_Interface_Contact_Capabilities.xml | 145 +++++--
spec/Connection_Interface_Contacts.xml | 64 ---
spec/Connection_Interface_Location.xml | 60 ++--
spec/Connection_Interface_Renaming.xml | 2 +-
spec/Connection_Interface_Requests.xml | 2 +
spec/Connection_Interface_Simple_Presence.xml | 12 +-
spec/Connection_Manager.xml | 7 +-
spec/Debug.xml | 5 +-
spec/Media_Stream_Handler.xml | 51 +++-
spec/all.xml | 4 +-
spec/errors.xml | 82 ++++-
30 files changed, 746 insertions(+), 958 deletions(-)
delete mode 100644 spec/Channel_Interface_Delivery_Reporting.xml
delete mode 100644 spec/Channel_Interface_Media_Signalling_Future.xml
delete mode 100644 spec/Channel_Type_Streamed_Media_Future.xml
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 2937680..223a612 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -362,10 +362,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
handle).</p>
<tp:rationale>
- <p>The careful wording about the self-handle is because the Renaming
- interface can cause the return from Connection.GetSelfHandle to
- change. It's something of a specification bug that we don't signal
- this in the Connection interface yet.</p>
+ <p>On some protocols, the SelfHandle may change (as signalled by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>),
+ but this property is immutable. Hence, locally-requested channels'
+ InitiatorHandle and InitiatorID may not match the current
+ SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
+ determine whether the channel was created locally.</p>
</tp:rationale>
<p>For channels requested by a remote user, this MUST be their handle.
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index d312a6d..06f0458 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -74,7 +74,7 @@
All observers are notified simultaneously.</p></dd>
<dt><tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>p
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>
<dd>
<p>Approvers notify the user that new channels have been created,
and also select which channel handler will be used for the channel,
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
index eec6a4b..b569a7f 100644
--- a/spec/Channel_Interface_Call_State.xml
+++ b/spec/Channel_Interface_Call_State.xml
@@ -25,7 +25,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
progress or call states. The presence of this interface is no guarantee
that call states will actually be signalled (for instance, SIP
implementations are not guaranteed to generate status 180 Ringing, so a
- call can be accepted without the Ringing flag ever having been set).</p>
+ call can be accepted without the Ringing flag ever having been set;
+ similarly, Jingle implementations are not guaranteed to send
+ <code><ringing/></code>).</p>
<p>To notify the other participant in the call that they are on hold,
see <tp:dbus-ref
@@ -114,6 +116,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
diverted.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ destination contact may not have been made aware of the call yet
+ (so the Ringing state is not appropriate). This corresponds to SIP's
+ status code 183 Session Progress, and could be used when the
+ outgoing call has reached a gateway, for instance.
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
</interface>
diff --git a/spec/Channel_Interface_Delivery_Reporting.xml b/spec/Channel_Interface_Delivery_Reporting.xml
deleted file mode 100644
index 494b44d..0000000
--- a/spec/Channel_Interface_Delivery_Reporting.xml
+++ /dev/null
@@ -1,444 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Interface_Delivery_Reporting"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
- <tp:license xmlns="http://www.w3.org/1999/xhtml">
- <p>This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.</p>
-
-<p>This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.</p>
-
-<p>You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
- </tp:license>
- <interface
- name="org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting.DRAFT"
- tp:causes-havoc="experimental">
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
- <tp:added version="0.17.5">(draft version, not API-stable)</tp:added>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface extends the Text and Messages interfaces with improved
- sent-message status reporting.</p>
-
- <p>This interface replaces Text.SendError, adding support for protocols
- where the message content is not echoed back to the sender on
- failure. It also adds support for receiving positive
- acknowledgements, and uses the Messages queue for state-recovery
- (ensuring that incoming delivery reports are not lost if there is not
- currently a process handling them).</p>
-
- <p>If this interface and the Messages interface are both present,
- clients that support it SHOULD listen for the MessageReceived signal
- to get delivery reports, and ignore the SendError signal on the Text
- interface.</p>
-
- <p>Delivery reports appear as messages of type
- Channel_Text_Message_Type_Delivery_Report in the Text and Messages
- interfaces. The message in the Text interface SHOULD have the
- Non_Text_Content flag.</p>
-
- <p>Whenever a message of type Channel_Text_Message_Type_Delivery_Report
- is signalled for a delivery error report, Channel.Type.Text.SendError
- SHOULD also be emitted; whenever Channel.Type.Text.SendError is
- emitted by a channel which supports this interface, a message of type
- Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>
-
- <p>The corresponding message in the Messages interface MUST contain
- "headers" for the delivery report, as specified below, in its
- first Message_Part.</p>
-
- <dl>
- <dt>interface (s - DBus_Interface, as defined in the Messages
- interface)</dt>
- <dd>MUST be the name of this interface.</dd>
-
- <dt>message-sender (u - Contact_Handle, as defined in the Messages
- interface)</dt>
- <dd>MUST be the intended recipient of the original message, if
- available (zero or omitted otherwise), even if the delivery report
- actually came from an intermediate server.</dd>
-
- <dt>message-type (u - Channel_Text_Message_Type, as defined in the
- Messages interface)</dt>
- <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
-
- <dt>delivery-status (u - Delivery_Status)</dt>
- <dd>The status of the message. All delivery reports MUST contain
- this key in the first Message_Part.</dd>
-
- <dt>delivery-token (s - Sent_Message_Token)</dt>
-
- <dd>
- <p>An identifier for the message to which this delivery report
- refers. MUST NOT be an empty string. Omitted if not
- available.</p>
-
- <p>Clients may match this against the token produced by the
- SendMessage method and MessageSent signal on the Messages
- interface. A status report with no token could match any sent
- message, and a sent message with an empty token could match
- any status report. If multiple sent messages match, clients
- SHOULD use some reasonable heuristic.</p>
-
- <tp:rationale>
- In an ideal world, we could unambiguously match reports
- against messages; however, deployed protocols are not ideal,
- and not all reports and messages can be matched.
- </tp:rationale>
- </dd>
-
- <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
- <dd>
- The reason for the failure. MUST be omitted if this was a
- successful delivery; SHOULD be omitted if it would be
- Channel_Text_Send_Error_Unknown.
- </dd>
-
- <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
- <dd>
- <p>The message content, as defined by the Messages interface.
- Omitted if no content is available. Content MAY have been
- truncated, message parts MAY have been removed, and message
- parts MAY have had their content removed (i.e. the message part
- metadata is present, but the 'content' key is not).</p>
-
- <tp:rationale>
- Some protocols, like XMPP, echo the failing message back to
- the sender. This is sometimes the only way to match it
- against the sent message, so we include it here.
- </tp:rationale>
-
- <p>Unlike in the Messages interface, content not visible
- in the value for this key cannot be retrieved by another
- means, so the connection manager SHOULD be more
- aggressive about including (possibly truncated) message
- content in the 'content' key.</p>
-
- <tp:rationale>
- The Messages interface needs to allow all content to be
- retrieved, but in this interface, the content we provide is
- merely a hint; so some is better than none, and it doesn't
- seem worth providing an API as complex as Messages'
- GetPendingMessageContent for the echoed message.
- </tp:rationale>
- </dd>
-
- </dl>
-
- <p>The second and subsequent Message_Part dictionaries, if present,
- are a human-readable report from the IM service.</p>
-
- <p>It is an error for this interface to appear on channels of type
- other than Text, or on Text channels without the Messages interface.
- Clients MUST recover from this error by ignoring the presence
- of the DeliveryReporting interface.</p>
-
- <p>Some example delivery reports in a Python-like syntax (in which
- arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
- follow.</p>
-
- <dl>
- <dt>A minimal delivery report indicating permanent failure of the
- sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
- reason</dt>
- <dd><pre>
-[{
-# header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- <dt>A delivery report where the failed message is echoed back to the
- sender rather than being referenced by ID, and the failure reason
- is that this protocol cannot send messages to offline contacts
- such as the contact with handle 123</dt>
- <dd><pre>
-[{ # header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Temporarily_Failed,
-'delivery-error': Channel_Text_Send_Error_Offline,
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-
-# no body
-]
-</pre></dd>
-
- <dt>A maximally complex delivery report: the server reports a bilingual
- human-readable failure message because the user sent a message
- "Hello, world!" with token
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
- with handle 123, but that handle represents a contact who does not
- actually exist</dt>
- <dd><pre>
-[{ # header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-},
-{ # message from server (alternative in English)
-'alternative': '404',
-'type': 'text/plain',
-'lang': 'en',
-'content': 'I have no contact with that name',
-},
-{ # message from server (alternative in German)
-'alternative': '404'.
-'type': 'text/plain',
-'lang': 'de',
-'content', 'Ich habe keinen Kontakt mit diesem Namen',
-}
-]
-</pre></dd>
-
- <dt>A minimal delivery report indicating successful delivery
- of the sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
- <dd><pre>
-[{
-# header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Delivered,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- </dl>
- </tp:docstring>
-
- <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" type="u">
- <tp:docstring>
- <p>The status of a message as indicated by a delivery report.</p>
-
- <p>If this enum is extended in future specifications, this should
- only be to add new, non-overlapping conditions (i.e. all failures
- should still be signalled as either Temporarily_Failed
- or Permanently_Failed). If additional detail is required (e.g.
- distinguishing between the various types of permanent failure) this
- will be done using additional keys in the Message_Part.</p>
- </tp:docstring>
-
- <tp:enumvalue suffix="Unknown" value="0">
- <tp:docstring>
- The message's disposition is unknown.
- Clients SHOULD consider all messages to have status
- Delivery_Status_Unknown unless otherwise specified; connection
- managers SHOULD NOT signal this delivery status explicitly.
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="Delivered" value="1">
- <tp:docstring>
- The message has been delivered to the intended recipient.
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="Temporarily_Failed" value="2">
- <tp:docstring>
- Delivery of the message has failed. Clients SHOULD notify the user,
- but MAY automatically try sending another copy of the message.
-
- <tp:rationale>
- Similar to errors with type="wait" in XMPP; analogous to
- 4xx errors in SMTP.
- </tp:rationale>
- </tp:docstring>
- </tp:enumvalue>
-
- <tp:enumvalue suffix="Permanently_Failed" value="3">
- <tp:docstring>
- Delivery of the message has failed. Clients SHOULD NOT try again
- unless by specific user action. If the user does not modify the
- message or alter configuration before re-sending, this error is
- likely to happen again.
-
- <tp:rationale>
- Similar to errors with type="cancel", type="modify"
- or type="auth" in XMPP; analogous to 5xx errors in SMTP.
- </tp:rationale>
- </tp:docstring>
- </tp:enumvalue>
- </tp:enum>
-
- <tp:flags name="Delivery_Reporting_Support_Flags"
- value-prefix="Delivery_Reporting_Support_Flag" type="u">
- <tp:docstring>
- Flags indicating the level of support for delivery reporting on this
- channel. Any future flags added to this set will conform to the
- convention that the presence of an extra flag implies that
- more operations will succeed.
- </tp:docstring>
-
- <tp:flag suffix="Receive_Failures" value="1">
- <tp:docstring>
- Clients MAY expect to receive negative delivery reports if
- Message_Sending_Flag_Report_Delivery is specified when sending.
-
- <tp:rationale>
- If senders want delivery reports, they should ask for them.
- If they don't want delivery reports, they can just ignore them,
- so there's no need to have capability discovery for what will
- happen if a delivery report isn't requested.
- </tp:rationale>
- </tp:docstring>
- </tp:flag>
-
- <tp:flag suffix="Receive_Successes" value="2">
- <tp:docstring>
- Clients MAY expect to receive positive delivery reports if
- Message_Sending_Flag_Report_Delivery is specified when sending.
-
- <tp:rationale>
- Same rationale as Receive_Failures.
- </tp:rationale>
- </tp:docstring>
- </tp:flag>
-
- <tp:flag suffix="Send_Failures" value="4">
- <tp:docstring>
- Clients MAY expect that sending a negative delivery report will
- succeed, and will actually get a message to the sender.
- </tp:docstring>
- </tp:flag>
-
- <tp:flag suffix="Send_Successes" value="8">
- <tp:docstring>
- Clients MAY expect that sending a positive delivery report will
- succeed, and will actually get a message to the sender.
- </tp:docstring>
- </tp:flag>
-
- </tp:flags>
-
- <property name="DeliveryReportingSupport" access="read"
- tp:type="Delivery_Reporting_Support_Flags" type="u"
- tp:name-for-bindings="Delivery_Reporting_Support">
- <tp:docstring>
- A bitfield indicating features supported by this channel.
- </tp:docstring>
- </property>
-
- <method name="SendDeliveryReport"
- tp:name-for-bindings="Send_Delivery_Report">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Request that a delivery report is sent for the specified pending
- incoming message. Delivery reports cannot currently be sent for
- messages that have already been acknowledged.</p>
-
- <tp:rationale>
- <p>The only use-case I can see for delivery reports on non-pending
- messages is a "read receipt" like in email's RFC 3798. Delivery
- reports on non-pending messages will also need a more complex
- API.</p>
-
- <p>If they turn out to be needed, we can add a method like
- SendDeliveryReportByContent(aa{sv}: message) and add a flag to
- Delivery_Reporting_Support_Flags indicating that this method is
- implemented.</p>
- </tp:rationale>
-
- <p>Clients SHOULD NOT attempt to send delivery reports that are
- not indicated to be supported using the DeliveryReportingSupport
- property.</p>
-
- <p>Clients MUST NOT attempt to send delivery reports using the
- SendMessage method in the Messages API, and connection managers
- MUST NOT allow this to be done.</p>
- </tp:docstring>
-
- <arg name="Messages" type="au" tp:type="Message_ID[]" direction="in">
- <tp:docstring>
- The IDs of one or more unacknowledged messages.
- </tp:docstring>
- </arg>
-
- <arg name="Status" direction="in" type="u" tp:type="Delivery_Status">
- <tp:docstring>
- The status to be reported.
- </tp:docstring>
- </arg>
-
- <arg name="Reason" direction="in" type="u"
- tp:type="Channel_Text_Send_Error">
- <tp:docstring>
- If the status to be reported is a failure, the reason for that
- failure. If the status to be reported is not an error, this MUST be
- Channel_Text_Send_Error_Unknown.
- </tp:docstring>
- </arg>
-
- <tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.NetworkError">
- </tp:error>
-
- <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
- <tp:docstring>
- One of the specified message IDs was invalid. No delivery reports
- were sent.
- </tp:docstring>
- </tp:error>
-
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
- <tp:docstring>
- The requested message status could not be reported to the sender
- (for instance, this will be raised if a positive delivery report
- is requested on a protocol that only supports negative delivery
- reports). Clients MUST treat this error as non-fatal.
- </tp:docstring>
- </tp:error>
-
- <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
- <tp:docstring>
- This channel cannot report message status back to the sender
- at all. Do not call this method on this channel again.
- </tp:docstring>
- </tp:error>
- </tp:possible-errors>
- </method>
-
- </interface>
-</node>
-<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 5c29316..004df5b 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -152,6 +152,84 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:property>
+ <tp:handler-capability-token name="gtalk-p2p">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>gtalk-p2p</code>.</p>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="ice-udp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>ice-udp</code>.</p>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="wlm-8.5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-8.5</code>.</p>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="wlm-2009">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-2009</code>.</p>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
+ <tp:handler-capability-token name="video/h264" is-family="yes">
+ <tp:docstring>
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on StreamedMedia channels.</p>
+ </tp:rationale>
+
+ <p>For example, a client could advertise support for
+ Speex, Theora and H264 by having three
+ handler capability tokens,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>,
+ in its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.</p>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:handler-capability-token>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
deleted file mode 100644
index bbb8b87..0000000
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ /dev/null
@@ -1,164 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Interface_Media_Signalling_Future"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright © 2009 Nokia Corporation </tp:copyright>
- <tp:license xmlns="http://www.w3.org/1999/xhtml">
- <p>This library is free software; you can redistribute it and/or
- modify it under the terms of the GNU Lesser General Public
- License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.</p>
-
- <p>This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.</p>
-
- <p>You should have received a copy of the GNU Lesser General Public
- License along with this library; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
- USA.</p>
- </tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE">
- <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface contains functionality which we intend to incorporate
- into the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.Interface.MediaSignalling</tp:dbus-ref>
- interface in future. It should be considered to be conceptually part
- of the core MediaSignalling interface, but without API or ABI
- guarantees.</p>
-
- <tp:rationale>
- <p>The rationale is the same as for <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.FUTURE</tp:dbus-ref>.</p>
- </tp:rationale>
- </tp:docstring>
-
- <property name="ICETransportAvailable"
- tp:name-for-bindings="ICE_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>True if this channel supports the use of the ICE-UDP transport
- (<a href="http://xmpp.org/extensions/xep-0176.html">XEP-0176</a>,
- <a href="http://tools.ietf.org/html/draft-ietf-mmusic-ice">ICE RFC
- draft)</a>. Various other transports have boolean properties
- that work in the same way as this one, so this description covers
- all such transports.</p>
-
- <p>This property is immutable (cannot change), and therefore SHOULD
- appear wherever immutable properties are reported, e.g. <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
- signals.</p>
-
- <p>Connection managers capable of signalling streamed media calls to
- contacts SHOULD include the properties representing all supported
- transports in the allowed properties list of the channel class
- in <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
- that advertises support for streamed media channels.</p>
-
- <p>Similarly, connection managers that support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref>
- interface SHOULD include all supported transports in the allowed
- properties list of the channel class that advertises a contact's
- ability to receive streamed media calls.</p>
-
- <p>Clients SHOULD NOT pass ICETransportAvailable and similar
- properties to <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
- or similar functions. If they do, the connection manager MUST
- accept and ignore any such property that is in the allowed properties
- list.</p>
-
- <tp:rationale>
- <p>There is currently no way for clients to influence the choice
- of transport: in general, a client making a call can't know the
- capabilities of the streaming implementation, or even which
- streaming implementation will be used (channels will often be
- requested by an address book or similar application that will not
- handle the channel itself).</p>
-
- <p>If a mechanism for transport negotiation is added, it should be
- something that happens after the request, but before calling
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Media.SessionHandler.Ready</tp:dbus-ref>,
- so that it is the streaming implementation that chooses the
- transport, rather than the requesting client.</p>
- </tp:rationale>
-
- <p>Clients that are able to receive calls with particular transports
- MUST include the following filters if calling <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
- (clients of a <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
- SHOULD instead arrange for the ChannelDispatcher to do this,
- by including the filters in their <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
- properties):</p>
-
- <ul>
- <li>{ ChannelType = StreamedMedia, ICETransportAvailable = true }
- if the ICE transport is supported</li>
- <li>{ ChannelType = StreamedMedia, RawUDPTransportAvailable = true }
- if the raw UDP transport is supported</li>
- <li>... and so on, one filter per available transport.</li>
- </ul>
-
- <p>Connection managers MAY use this information to adjust the
- transports for which they advertise support to other contacts.</p>
-
- <tp:rationale>
- <p>In particular, in XMPP, the connection manager will not be
- callable unless a client has told it to advertise support for
- at least one transport.</p>
- </tp:rationale>
- </tp:docstring>
- </property>
-
- <property name="RawUDPTransportAvailable"
- tp:name-for-bindings="Raw_UDP_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for raw UDP streaming as described by <a
- href="http://xmpp.org/extensions/xep-0177.html">XEP-0177</a>.</p>
- </tp:docstring>
- </property>
-
- <property name="GTalkP2PTransportAvailable"
- tp:name-for-bindings="GTalk_P2P_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the variant of ICE used by the Google Talk peer-to-peer
- connectivity establishment mechanism (as implemented in libjingle
- 0.3).</p>
- </tp:docstring>
- </property>
-
- <property name="WLM85TransportAvailable"
- tp:name-for-bindings="WLM_8_5_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the transport implemented by Windows Live Messenger 8.5 or
- later (which resembles ICE draft 6).</p>
- </tp:docstring>
- </property>
-
- <property name="WLM2009TransportAvailable"
- tp:name-for-bindings="WLM_2009_Transport_Available"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>ICETransportAvailable</tp:member-ref>,
- but for the transport implemented by Windows Live Messenger 2009
- or later (which resembles ICE draft 19).</p>
- </tp:docstring>
- </property>
-
- </interface>
-</node>
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index 4550673..858a15d 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -44,7 +44,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
even if no client has indicated via
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
that such a tube is supported. They SHOULD also allow clients to offer tubes with any
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index b0e905f..5f5bd4b 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -18,9 +18,10 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT2"
tp:causes-havoc='experimental'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:changed version="0.17.27">(draft 2)</tp:changed>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel type for searching server-stored user directories. A new
@@ -375,13 +376,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
- <signal name="SearchResultReceived"
- tp:name-for-bindings="Search_Result_Received">
- <arg name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>An integer handle for the contact, which will remain
- valid at least until this Channel closes</tp:docstring>
- </arg>
- <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:mapping name="Contact_Search_Result_Map">
+ <tp:docstring>A map from contact handle to search result.</tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of fields representing information about this
contact, in the same format used in the <tp:dbus-ref
@@ -402,9 +405,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
look it up.</p>
</tp:rationale>
</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="SearchResultReceived"
+ tp:name-for-bindings="Search_Result_Received">
+ <arg name="Result" type="a{ua(sasas)}" tp:type="Contact_Search_Result_Map">
+ <tp:docstring>A mapping from contact handle to an array of fields
+ representing information about this contact. Handles in this mapping
+ MUST remain valid until the Channel closes.</tp:docstring>
</arg>
<tp:docstring>
- Emitted when a search result is received from the server.
+ Emitted when a some search results are received from the server.
+ This signal can be fired arbitrarily many times so clients MUST NOT
+ assume they'll get only one signal.
</tp:docstring>
</signal>
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index 61e1bba..19dda06 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -80,7 +80,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>Connection managers SHOULD NOT advertise support for file transfer to
other contacts unless it has been indicated by a call to
<tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>.
</p>
<tp:rationale>
<p>People would send us files, and it would always fail. That would be silly.</p>
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 93ea777..6d6ce31 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -74,7 +74,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dl>
<dt>handle-name (s)</dt>
- <dd>The string name of the room handle (as would be returned by
+ <dd>The identifier of the room (as would be returned by
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>)</dd>
<dt>name (s)</dt>
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index db0b657..4c651cd 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -441,6 +441,156 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</signal>
+ <property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If set to true in a channel request that will create a new channel,
+ the connection manager should immediately attempt to establish an
+ audio stream to the remote contact, making it unnecessary for the
+ client to call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p>
+
+ <p>If this property, or InitialVideo, is passed to EnsureChannel
+ (as opposed to CreateChannel), the connection manager SHOULD ignore
+ these properties when checking whether it can return an existing
+ channel as suitable; these properties only become significant when
+ the connection manager has decided to create a new channel.</p>
+
+ <p>If true on a requested channel, this indicates that the audio
+ stream has already been requested and the client does not need to
+ call RequestStreams, although it MAY still do so.</p>
+
+ <p>If true on an unrequested (incoming) channel, this indicates that
+ the remote contact initially requested an audio stream; this does
+ not imply that that audio stream is still active (as indicated by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p>
+
+ <p>This property is immutable (cannot change), and therefore SHOULD
+ appear wherever immutable properties are reported, e.g. <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signals.</p>
+
+ <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale>
+
+ <p>Connection managers capable of signalling audio calls to contacts
+ SHOULD include a channel class in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
+ = <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ = Contact in the fixed properties dictionary, and InitialAudio
+ (and also InitialVideo, if applicable) in the allowed properties
+ list. Clients wishing to discover whether a connection manager
+ can signal audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all protocols support signalling video calls, and it would be
+ possible (although unlikely) to have a protocol where only video,
+ and not audio, could be signalled.</p>
+ </tp:rationale>
+
+ <p>Connection managers that support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
+ interface SHOULD represent the capabilities of receiving audio
+ and/or video calls by including a channel class in
+ a contact's capabilities with ChannelType = StreamedMedia
+ in the fixed properties dictionary, and InitialAudio and/or
+ InitialVideo in the allowed properties list. Clients wishing to
+ discover whether a particular contact is likely to be able to
+ receive audio and/or video calls SHOULD use this information.</p>
+
+ <tp:rationale>
+ <p>Not all clients support video calls, and it would also be
+ possible (although unlikely) to have a client which could only
+ stream video, not audio.</p>
+ </tp:rationale>
+
+ <p>Clients that are willing to receive audio and/or video calls
+ SHOULD include the following among their channel classes if
+ calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">UpdateCapabilities</tp:dbus-ref>
+ (clients of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ SHOULD instead arrange for the ChannelDispatcher to do this,
+ by including the filters in their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ properties):</p>
+
+ <ul>
+ <li>{ ChannelType = StreamedMedia }</li>
+ <li>{ ChannelType = StreamedMedia, InitialAudio = true }
+ if receiving calls with audio is supported</li>
+ <li>{ ChannelType = StreamedMedia, InitialVideo = true }
+ if receiving calls with video is supported</li>
+ </ul>
+
+ <tp:rationale>
+ <p>Connection managers for protocols with capability discovery,
+ like XMPP, need this information to advertise the appropriate
+ capabilities for their protocol.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
+ a video stream. This property is immutable (cannot change).</p>
+
+ <p>In particular, note that if this property is false, this does not
+ imply that an active video stream has not been added, only that no
+ video stream was active at the time the channel appeared.</p>
+
+ <p>This property is the correct way to discover whether connection
+ managers, contacts etc. support video calls; it appears in
+ capabilities structures in the same way as InitialAudio.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="ImmutableStreams" tp:name-for-bindings="Immutable_Streams"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If <tt>True</tt>, once streams have been requested for this channel
+ (either by setting <tp:member-ref>InitialAudio</tp:member-ref> or
+ <tp:member-ref>InitialVideo</tp:member-ref> when the channel is
+ requested, or by calling
+ <tp:member-ref>RequestStreams</tp:member-ref> on a channel with no
+ streams), a stream of a different content type cannot be added;
+ subsequent calls to <tp:member-ref>RequestStreams</tp:member-ref>
+ that attempt to do so will fail.</p>
+
+ <p>If this property is missing, clients SHOULD assume that it is false,
+ and thus that the channel's streams can be changed once the call has
+ started.</p>
+
+ <p>If this property is present in the "allowed" set in all of the
+ StreamedMedia entries in a contact's capabilities, then user
+ interfaces MAY choose to show a separate "call" option for each
+ class of call.</p>
+
+ <tp:rationale>
+ <p>For example, once an audio-only Google Talk call has started,
+ it is not possible to add a video stream; both audio and video
+ must be requested at the start of the call if video is desired.
+ User interfaces may use this pseudo-capability as a hint to
+ display separate "Audio call" and "Video call" buttons, rather
+ than a single "Call" button with the option to add and remove
+ video once the call has started for contacts without this flag.
+ </p>
+ </tp:rationale>
+
+ <p>This property is immutable, and therefore SHOULD be announced
+ in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>,
+ etc.</p>
+ </tp:docstring>
+ </property>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A channel that can send and receive streamed media such as audio or video.
Provides a number of methods for listing and requesting new streams, and
@@ -517,8 +667,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The channel-type-specific capability flags used for
Channel.Type.StreamedMedia in the <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Connection.Interface.Capabilities</tp:dbus-ref>
- interface. See the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">FUTURE.InitialAudio</tp:dbus-ref>
+ interface. See the <tp:member-ref>InitialAudio</tp:member-ref>
property for details of the mechanisms that will replace this.
</tp:docstring>
<tp:flag suffix="Audio" value="1">
@@ -549,6 +698,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
NATs.
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="Immutable_Streams" value="32">
+ <tp:docstring>
+ Channels whose target handle is this contact will have
+ <tp:member-ref>ImmutableStreams</tp:member-ref> = <tt>True</tt>.
+ </tp:docstring>
+ </tp:flag>
+
</tp:flags>
</interface>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
deleted file mode 100644
index 07a181e..0000000
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ /dev/null
@@ -1,151 +0,0 @@
-<?xml version="1.0" ?>
-<node name="/Channel_Type_Streamed_Media_Future"
- xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright © 2009 Nokia Corporation </tp:copyright>
- <tp:license xmlns="http://www.w3.org/1999/xhtml">
- <p>This library is free software; you can redistribute it and/or
- modify it under the terms of the GNU Lesser General Public
- License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.</p>
-
- <p>This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.</p>
-
- <p>You should have received a copy of the GNU Lesser General Public
- License along with this library; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
- USA.</p>
- </tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Type.StreamedMedia.FUTURE">
- <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface contains functionality which we intend to incorporate
- into the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.Type.StreamedMedia</tp:dbus-ref>
- interface in future. It should be considered to be conceptually part
- of the core StreamedMedia interface, but without API or ABI
- guarantees.</p>
-
- <tp:rationale>
- <p>The rationale is the same as for <tp:dbus-ref
- namespace="org.freedesktop.Telepathy">Channel.FUTURE</tp:dbus-ref>.</p>
- </tp:rationale>
- </tp:docstring>
-
- <property name="InitialAudio" tp:name-for-bindings="Initial_Audio"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>If set to true in a channel request that will create a new channel,
- the connection manager should immediately attempt to establish an
- audio stream to the remote contact, making it unnecessary for the
- client to call <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">RequestStreams</tp:dbus-ref>.</p>
-
- <p>If this property, or InitialVideo, is passed to EnsureChannel
- (as opposed to CreateChannel), the connection manager SHOULD ignore
- these properties when checking whether it can return an existing
- channel as suitable; these properties only become significant when
- the connection manager has decided to create a new channel.</p>
-
- <p>If true on a requested channel, this indicates that the audio
- stream has already been requested and the client does not need to
- call RequestStreams, although it MAY still do so.</p>
-
- <p>If true on an unrequested (incoming) channel, this indicates that
- the remote contact initially requested an audio stream; this does
- not imply that that audio stream is still active (as indicated by
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type.StreamedMedia">ListStreams</tp:dbus-ref>).</p>
-
- <p>This property is immutable (cannot change), and therefore SHOULD
- appear wherever immutable properties are reported, e.g. <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
- signals.</p>
-
- <tp:rationale><p>This reduces D-Bus round trips.</p></tp:rationale>
-
- <p>Connection managers capable of signalling audio calls to contacts
- SHOULD include a channel class in <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
- with <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>
- = <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
- and <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
- = Contact in the fixed properties dictionary, and InitialAudio
- (and also InitialVideo, if applicable) in the allowed properties
- list. Clients wishing to discover whether a connection manager
- can signal audio and/or video calls SHOULD use this information.</p>
-
- <tp:rationale>
- <p>Not all protocols support signalling video calls, and it would be
- possible (although unlikely) to have a protocol where only video,
- and not audio, could be signalled.</p>
- </tp:rationale>
-
- <p>Connection managers that support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities.DRAFT</tp:dbus-ref>
- interface SHOULD represent the capabilities of receiving audio
- and/or video calls by including a channel class in
- a contact's capabilities with ChannelType = StreamedMedia
- in the fixed properties dictionary, and InitialAudio and/or
- InitialVideo in the allowed properties list. Clients wishing to
- discover whether a particular contact is likely to be able to
- receive audio and/or video calls SHOULD use this information.</p>
-
- <tp:rationale>
- <p>Not all clients support video calls, and it would also be
- possible (although unlikely) to have a client which could only
- stream video, not audio.</p>
- </tp:rationale>
-
- <p>Clients that are willing to receive audio and/or video calls
- SHOULD include the following 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</tp:dbus-ref>
- SHOULD instead arrange for the ChannelDispatcher to do this,
- by including the filters in their <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
- properties):</p>
-
- <ul>
- <li>{ ChannelType = StreamedMedia }</li>
- <li>{ ChannelType = StreamedMedia, InitialAudio = true }
- if receiving calls with audio is supported</li>
- <li>{ ChannelType = StreamedMedia, InitialVideo = true }
- if receiving calls with video is supported</li>
- </ul>
-
- <tp:rationale>
- <p>Connection managers for protocols with capability discovery,
- like XMPP, need this information to advertise the appropriate
- capabilities for their protocol.</p>
- </tp:rationale>
- </tp:docstring>
- </property>
-
- <property name="InitialVideo" tp:name-for-bindings="Initial_Video"
- type="b" access="read">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>The same as <tp:member-ref>InitialAudio</tp:member-ref>, but for
- a video stream. This property is immutable (cannot change).</p>
-
- <p>In particular, note that if this property is false, this does not
- imply that an active video stream has not been added, only that no
- video stream was active at the time the channel appeared.</p>
-
- <p>This property is the correct way to discover whether connection
- managers, contacts etc. support video calls; it appears in
- capabilities structures in the same way as InitialAudio.</p>
- </tp:docstring>
- </property>
-
- </interface>
-</node>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 7d6e314..5315a55 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -419,8 +419,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:property>
<tp:property name="name" type="s">
<tp:docstring>
- A human-visible name for the channel, if it differs from the string
- version of the channel's handle.
+ A human-visible name for the channel, if it differs from the channel's
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>.
</tp:docstring>
</tp:property>
<tp:property name="description" type="s">
diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 8a920a1..dd26303 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -177,10 +177,11 @@
<arg name="Properties" type="a{sv}"
tp:type="Qualified_Property_Value_Map" direction="in">
<tp:docstring>
- <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
+ <p>Properties of the channel dispatch operation. The keys MUST be
+ fully qualified D-Bus property names. This MUST NOT include
+ properties that could change, SHOULD include as many properties as
+ possible given that constraint, and MUST include at least the
+ <tp:dbus-ref
namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Account</tp:dbus-ref>,
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.ChannelDispatchOperation">Connection</tp:dbus-ref>
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index d366862..c6edf33 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -109,6 +109,71 @@
</tp:docstring>
</property>
+ <tp:simple-type name="Handler_Capability_Token" type="s"
+ array-name="Handler_Capability_Token_List">
+ <tp:docstring>
+ A <tp:type>DBus_Interface</tp:type>, followed by a slash '/' character
+ and an identifier for a capability defined by that interface. The
+ capability identifier SHOULD be in lower case. If an interface
+ references an external specification which is case-insensitive (such
+ as MIME), then names from that specification MUST be normalized to
+ lower-case before providing them to this Telepathy API, so that
+ implementations can safely rely on simple byte-by-byte comparison.
+
+ <tp:rationale>
+ These aren't D-Bus core Properties, and we want them to look visibly
+ different.
+ </tp:rationale>
+
+ <p>So far, all client capabilities are defined by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref>
+ interface.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="Capabilities" tp:name-for-bindings="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The set of additional capabilities supported by this handler.
+ This describes things like support for streamed media codecs and
+ NAT traversal mechanisms: see the Contact Capabilities
+ interface for more details.</p>
+
+ <p>For handlers that have a <code>.client</code> file, the
+ channel dispatcher may discover this property from the
+ <code>org.freedesktop.Telepathy.Client.Handler.Capabilities</code>
+ group; for each capability, that group contains a key
+ whose name is the capability, with value <code>true</code>.
+ Keys with other values SHOULD NOT appear in this group.</p>
+
+ <p>For instance, the <code>.client</code> file for a streamed media
+ handler that supports ICE-UDP NAT traversal, Speex audio,
+ and Theora and H264 video might contain this group:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler.Capabilities]
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora=true
+org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
+</pre>
+
+ <p>Like the <tp:member-ref>HandlerChannelFilter</tp:member-ref>
+ property, this property cannot change while the Handler owns its
+ Client bus name. However, the <code>.client</code> file, if any,
+ can change (due to upgrades or installation of pluggable codecs),
+ and the capabilities really supported by the handler might not
+ exactly match what is cached in the <code>.client</code> file.</p>
+
+ <tp:rationale>
+ <p>The client file is installed statically and is intended to list
+ codecs etc. that the handler guarantees it can support (e.g. by
+ having a hard dependency on them), whereas the running handler
+ process might be able to find additional codecs.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
<method name="HandleChannels" tp:name-for-bindings="Handle_Channels">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Called by the channel dispatcher when this client should handle these
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 2b03f96..72e1bb8 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -251,7 +251,7 @@ USA.</p>
<arg direction="out" type="as" name="Identifiers">
<tp:docstring>
- An array of handle names in the same order as the given numbers
+ An array of identifiers corresponding to the given handles, in the same order.
</tp:docstring>
</arg>
@@ -591,16 +591,16 @@ USA.</p>
</tp:docstring>
</arg>
- <arg direction="in" name="Names" type="as">
+ <arg direction="in" name="Identifiers" type="as">
<tp:docstring>
- An array of names of entities to request handles for
+ An array of identifiers of entities to request handles for
</tp:docstring>
</arg>
<arg direction="out" type="au" tp:type="Handle[]"
name="Handles">
<tp:docstring>
- An array of integer handle numbers in the same order as the given strings
+ An array of integer handle numbers in the same order as the given identifiers.
</tp:docstring>
</arg>
@@ -611,16 +611,18 @@ USA.</p>
client who invokes this method, and must not deallocate the handles
until the client disconnects from the bus or calls the
<tp:member-ref>ReleaseHandles</tp:member-ref>
- method. Where the name refers to an entity that already has a handle
- in this connection manager, this handle should be returned instead.
- The handle number 0 must not be returned by the connection manager.
+ method. Where the identifier refers to an entity that already has a
+ handle in this connection manager, this handle should be returned
+ instead. The handle number 0 must not be returned by the connection
+ manager.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
- The given name does not identify a valid entity of the given type.
+ The given identifier does not identify a valid entity of the given
+ type.
<tp:rationale>
For instance, an XMPP connection would raise this error for
@@ -698,8 +700,18 @@ USA.</p>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error sending or receiving on the network socket.</p>
- <p>When disconnected for this reason, the equivalent D-Bus error is
- <code>org.freedesktop.Telepathy.Error.NetworkError</code>.</p>
+ <p>When the status changes from Connecting to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
+ or some more specific error.</p>
+
+ <p>When the status changes from Connected to Disconnected for this
+ reason, the equivalent D-Bus error is either
+ <code>org.freedesktop.Telepathy.Error.NetworkError</code>,
+ <code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
+ or some more specific error.</p>
</tp:docstring>
</tp:enumvalue>
@@ -737,12 +749,17 @@ USA.</p>
<li>If the status change is from Connecting to Disconnected
and the 'register' parameter to RequestConnection was present
and true, the requested account could not be created on the
- server because it already exists.</li>
+ server because it already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
+ </li>
<li>If the status change is from Connecting to Disconnected
but the 'register' parameter is absent or false, the connection
manager could not connect to the specified account because
a connection to that account already exists.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
<tp:rationale>
In some protocols, like XMPP (when connecting with the same
@@ -755,6 +772,8 @@ USA.</p>
the existing connection was automatically disconnected because
a new connection to the same account (perhaps from a different
client or location) was established.
+ The equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
<tp:rationale>
In some protocols, like MSNP (when connecting twice with the
@@ -763,15 +782,6 @@ USA.</p>
</tp:rationale>
</li>
</ul>
-
- <p>When disconnected for this reason, the equivalent D-Bus error is
- <code>org.freedesktop.Telepathy.Error.NotYours</code>.
- </p>
-
- <tp:rationale>
- These three errors are distinct but very similar, and can be
- distinguished by other factors.
- </tp:rationale>
</tp:docstring>
</tp:enumvalue>
@@ -897,8 +907,12 @@ USA.</p>
<tp:docstring>
The name of a D-Bus error describing the error that occurred,
which may correspond to a
- <tp:type>Connection_Status_Reason</tp:type> or be a
- protocol-specific or connection-manager-specific error in a
+ <tp:type>Connection_Status_Reason</tp:type>, or may be a more
+ specific Telepathy error
+ (such as
+ <code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code>
+ for Connection_Status_Reason_Network_Error)
+ or a protocol-specific or connection-manager-specific error in a
suitable namespace.
<tp:rationale>
@@ -954,6 +968,16 @@ USA.</p>
</tp:docstring>
</signal>
+ <tp:contact-attribute name="contact-id" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
+ this is always present in the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
+ whether it was explicitly requested or not.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
@@ -1018,9 +1042,9 @@ USA.</p>
ambiguous. Connection manager implementations should reference count these
handles to determine if they are in use either by any active clients or any
open channels, and may deallocate them when this ceases to be true. Clients
- may request handles of a given type and name with the
+ may request handles of a given type and identifier with the
<tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
- name of handles with the <tp:member-ref>InspectHandles</tp:member-ref>
+ identifier with the <tp:member-ref>InspectHandles</tp:member-ref>
method, keep handles from being released with
<tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
longer storing handles with
diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
index a599436..9675771 100644
--- a/spec/Connection_Interface_Aliasing.xml
+++ b/spec/Connection_Interface_Aliasing.xml
@@ -119,9 +119,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<tp:docstring>
Request the value of several contacts' aliases at once. This SHOULD
- only return cached aliases, falling back on the handle name if none is
- present. Also if there was no cached alias, a request SHOULD be started
- of which the result is later signalled by
+ only return cached aliases, falling back on the contact identifier
+ (i.e. the string corresponding to the handle) if none is present. Also
+ if there was no cached alias, a request SHOULD be started of which the
+ result is later signalled by
<tp:member-ref>AliasesChanged</tp:member-ref>.
</tp:docstring>
<tp:possible-errors>
@@ -152,6 +153,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
+
+ <tp:contact-attribute name="alias" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetAliases</tp:member-ref>
+ (always present with some value, possibly the
+ same as Connection/contact-id, if information from the
+ Aliasing interface was requested)
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface on connections to support protocols where contacts have an
alias which they can change at will. Provides a method for the user to set
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index e6f7ac5..3b9290e 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -450,6 +450,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
+ <tp:contact-attribute name="token" type="s" tp:type="Avatar_Token">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same string that would be returned by
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+ (omitted from the result if the contact's avatar token is not known,
+ present as an empty string if the contact is known not to have
+ an avatar). Unlike in the
+ <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+ method, the avatar tokens for the self handle aren't required to be
+ present. This attribute should not be used to determine whether or
+ not the Avatar needs to be set.
+ </p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for requesting avatars for contacts on a given connection,
receiving notification when avatars are changed, and publishing your own
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index 4e58d02..10d8102 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -56,12 +56,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
well-defined or consistent, and as far as we know it was never
implemented correctly. This usage is now deprecated.</tp:changed>
- <!-- FIXME: are the type-specific flags sufficient, in a world that has
- the Requests interface? It'd be nice if we could advertise capabilities
- that are not defined in terms of a channel type but rather in terms of
- a property or something, e.g. Channel.Interface.TLS.Secure for
- individually TLS'd channels. -->
-
<tp:flags name="Connection_Capability_Flags"
value-prefix="Connection_Capability_Flag" type="u">
<tp:flag suffix="Create" value="1">
@@ -160,6 +154,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
that the set is kept accurate - for example, a client may remove
capabilities or type specific capability flags when it exits
which are still provided by another client.</p>
+
+ <p>On connections managed by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>,
+ this method SHOULD NOT be used by clients other than the
+ ChannelDispatcher itself.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
@@ -231,6 +230,18 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:possible-errors>
</method>
+ <tp:contact-attribute name="caps"
+ type="a(usuu)" tp:type="Contact_Capability">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetCapabilities</tp:member-ref>
+ (all of them will redundantly have the contact's handle as the
+ first member). Omitted from the result if the contact's capabilities
+ are not known; present in the result as an empty array if the
+ contact is known to have no capabilities at all.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Capabilities.xml b/spec/Connection_Interface_Contact_Capabilities.xml
index 042b24b..6596ecb 100644
--- a/spec/Connection_Interface_Contact_Capabilities.xml
+++ b/spec/Connection_Interface_Contact_Capabilities.xml
@@ -18,10 +18,9 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT"
- tp:causes-havoc="experimental">
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <tp:added version="0.17.16">(as a draft)</tp:added>
+ <tp:added version="0.17.28">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Contact capabilities describe the channel classes which may be
@@ -38,38 +37,77 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>This interface also enables user interfaces to notify the connection
manager what capabilities to advertise for the user to other contacts.
This is done by using the
- <tp:member-ref>SetSelfCapabilities</tp:member-ref> method, and deals
- with channel property values pertaining to them which are implemented
- by available client processes.</p>
+ <tp:member-ref>UpdateCapabilities</tp:member-ref> method.</p>
+ <tp:rationale>
+ <p>XMPP is a major user of this interface: XMPP contacts will not,
+ in general, be callable using VoIP unless they advertise suitable
+ Jingle capabilities.</p>
+
+ <p>Many other protocols also have some concept of capability flags,
+ which this interface exposes in a protocol-independent way.</p>
+ </tp:rationale>
</tp:docstring>
- <method name="SetSelfCapabilities"
- tp:name-for-bindings="Set_Self_Capabilities">
- <arg direction="in" name="caps" type="aa{sv}"
+ <tp:struct name="Handler_Capabilities"
+ array-name="Handler_Capabilities_List">
+ <tp:docstring>
+ A structure representing the capabilities of a single client.
+ </tp:docstring>
+
+ <tp:member name="Well_Known_Name" type="s" tp:type="DBus_Well_Known_Name">
+ <tp:docstring>
+ For implementations of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client</tp:dbus-ref>
+ interface, the well-known bus name name of the client; for any other
+ process, any other reversed domain name that uniquely identifies it.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Channel_Classes" type="aa{sv}"
tp:type="String_Variant_Map[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- An array of channel classes to replace to the list of what the
- connection can handle. If you include optional properties, they
- may not get advertised. The given properties are matched to the
- mandatory properties.
+ An array of channel classes that can be handled by this client.
+ This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ property.
</tp:docstring>
- </arg>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Used by user interfaces to indicate which channel classes they are
- able to handle on this connection. It replaces the previous advertised
- channel classes by the set given as parameter.</p>
+ </tp:member>
- <p>If a channel class is unknown by the connection manager, it is just
- ignored. No error are returned in this case, and other known channel
- class are added.</p>
+ <tp:member name="Capabilities"
+ type="as" tp:type="Handler_Capability_Token[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An array of client capabilities supported by this client, to be
+ used by the connection manager to determine what capabilities to
+ advertise. This will usually be a copy of the client's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
- <p>Upon a successful invocation of this method, the
- <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
- will only be emitted for the user's own
- handle (as returned by GetSelfHandle) by the connection manager if, in
- the given protocol, the given capabilities are distinct from the
- previous state.</p>
+ <method name="UpdateCapabilities" tp:name-for-bindings="Update_Capabilities">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Alter the connection's advertised capabilities to include
+ the intersection of the given clients' capabilities with what the
+ connection manager is able to implement.</p>
+
+ <p>On connections managed by the ChannelDispatcher, processes other
+ than the ChannelDispatcher SHOULD NOT call this method, and the
+ ChannelDispatcher SHOULD use this method to advertise the
+ capabilities of all the registered <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>
+ implementations.On connections not managed by the ChannelDispatcher,
+ clients MAY use this method directly, to indicate the channels they
+ will handle and the extra capabilities they have.</p>
+
+ <p>Upon a successful invocation of this method, the connection manager
+ will only emit the
+ <tp:member-ref>ContactCapabilitiesChanged</tp:member-ref> signal
+ for the user's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">SelfHandle</tp:dbus-ref>
+ if, in the underlying protocol, the new capabilities are distinct
+ from the previous state.</p>
<tp:rationale>
<p>The connection manager will essentially intersect the provided
@@ -79,10 +117,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
channel) will almost certainly not be advertised.</p>
</tp:rationale>
+ <p>This method MAY be called on a newly-created connection while it
+ is still in the DISCONNECTED state, to request that when the
+ connection connects, it will do so with the appropriate
+ capabilities. Doing so MUST NOT fail.</p>
</tp:docstring>
+
+ <arg direction="in" name="Handler_Capabilities" type="a(saa{sv}as)"
+ tp:type="Handler_Capabilities[]">
+ <tp:docstring>
+ <p>The capabilities of one or more clients.</p>
+
+ <p>For each client in the given list, any capabilities previously
+ advertised for the same client name are discarded, then replaced by
+ the capabilities indicated.</p>
+
+ <p>As a result, if a client becomes unavailable, this method SHOULD
+ be called with a <tp:type>Handler_Capabilities</tp:type> structure
+ containing its name, an empty list of channel classes, and an
+ empty list of capabilities. When this is done, the connection
+ manager SHOULD free all memory associated with that client name.</p>
+
+ <tp:rationale>
+ <p>This method takes a list of clients so that
+ when the channel dispatcher first calls it (with a list of all
+ the Handlers that are initially available), the changes can be
+ made atomically, with only one transmission of updated
+ capabilities to the network. Afterwards, the channel dispatcher
+ will call this method with a single-element list every time
+ a Handler becomes available or unavailable.</p>
+ </tp:rationale>
+
+ <p>The connection manager MUST ignore any channel classes and client
+ capabilities for which there is no representation in the protocol
+ or no support in the connection manager.</p>
+ </tp:docstring>
+ </arg>
+
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
@@ -95,11 +168,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>The handle zero MUST NOT be included in the request.</p>
</tp:docstring>
</arg>
- <!-- There was a bug in dbus-glib that prevent to use the right type:
- Instead of a{ua(a{sv}as)}, we used a(ua{sv}as) as a workaround.
- See http://bugs.freedesktop.org/show_bug.cgi?id=17329
- Now there is a fix, so we don't use the workaround anymore.
- -->
<arg direction="out" type="a{ua(a{sv}as)}"
tp:type="Contact_Capabilities_Map" name="Contact_Capabilities">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -161,6 +229,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
</tp:mapping>
+ <tp:contact-attribute name="capabilities"
+ type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same structs that would be returned by
+ <tp:member-ref>GetContactCapabilities</tp:member-ref>.
+ Omitted from the result if the contact's capabilities
+ are not known; present in the result as an empty array if the
+ contact is known to have no capabilities at all.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml
index 1033e04..92c80c8 100644
--- a/spec/Connection_Interface_Contacts.xml
+++ b/spec/Connection_Interface_Contacts.xml
@@ -29,70 +29,6 @@
<p>Each contact attribute has an string identifier
(<tp:type>Contact_Attribute</tp:type>), which is namespaced
by the D-Bus interface which defines it.</p>
-
- <p>An initial set of contact attributes is defined here:</p>
-
- <dl>
- <dt>org.freedesktop.Telepathy.Connection/contact-id
- (type s)</dt>
- <dd>The same string that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
- (always present in the result)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias
- (type s)</dt>
- <dd>The same string that would be returned by <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">GetAliases</tp:dbus-ref>
- (always present with some value, possibly the
- same as Connection/contact-id, if information from the
- Aliasing interface was requested)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Avatars/token
- (type s, <tp:type>Avatar_Token</tp:type>)</dt>
- <dd>The same string that would be returned by <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
- (omitted from the result if the contact's avatar token is not known,
- present as an empty string if the contact is known not to have
- an avatar). Unlike in the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref>
- method, the avatar tokens for the self handle aren't required to be
- present. This attribute should not be used to determine whether or
- not the Avatar needs to be set.
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence
- (type (uss), <tp:type>Simple_Presence</tp:type>)</dt>
- <dd> The same struct that would be returned by
- <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
- (always present with some value if information from the
- SimplePresence interface was requested)
- </dd>
- <dt>org.freedesktop.Telepathy.Connection.Interface.Capabilities/caps
- (type a(usuu), <tp:type>Contact_Capability</tp:type>)</dt>
- <dd>The same structs that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Capabilities">GetCapabilities</tp:dbus-ref>
- (all of them will redundantly have the contact's handle as the
- first member). Omitted from the result if the contact's capabilities
- are not known; present in the result as an empty array if the
- contact is known to have no capabilities at all.</dd>
-
- <dt>org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT/caps
- (type a{ua(a{sv}as)},
- <tp:type>Contact_Capabilities_Map</tp:type>)</dt>
- <dd>The same structs that would be returned by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">GetContactCapabilities</tp:dbus-ref>
- Omitted from the result if the contact's capabilities
- are not known; present in the result as an empty array if the
- contact is known to have no capabilities at all.</dd>
-
- <dt>org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT/location
- (type a{sv}, <tp:type>Location</tp:type>)</dt>
- <dd>The same struct used by
- <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT">GetLocations</tp:dbus-ref>
- Omitted from the result if the contact's location
- is not known.</dd>
-
- </dl>
</tp:docstring>
<tp:simple-type name="Contact_Attribute" type="s">
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index 8821ec0..fdc622e 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -18,9 +18,8 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT"
- tp:causes-havoc='experimental'>
- <tp:added version="0.17.18">(as a draft)</tp:added>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Location">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -50,6 +49,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
possible.</p>
</tp:docstring>
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<tp:enum name="Location_Accuracy_Level" type="i">
<tp:docstring>
A location accuracy level. This should be kept in sync with
@@ -89,11 +90,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:enumvalue>
<tp:enumvalue suffix="Detailed" value="6">
<tp:docstring>
- The location's accuracy is given by the error, horizontal-error-m
- and/or vertical-error-m keys.
+ The location's accuracy is given by the accuracy key.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+ -->
<tp:mapping name="Location">
<tp:docstring>
@@ -137,6 +138,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
information about it</li>
</ul>
+ <p>Since the previous strings have data intended to be read by users,
+ the language used should be stated using:</p>
+
+ <ul>
+ <li>language - s: a specific language or locale of location
+ information in a format compatible to RFC 4646. Note that UTF-8
+ is the only allowed encoding, e.g. "en" or "fr-CA".</li>
+ </ul>
+
<p>Positions are represented by the following well-known keys:</p>
<ul>
@@ -164,6 +174,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
This is from XEP-0080
</tp:rationale>
</li>
+
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>):
an indication of accuracy, which SHOULD be omitted if it would be
Location_Accuracy_Level_None or
@@ -174,24 +187,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
with any future XEP-0080 terminology.
</tp:rationale>
</li>
- <li>error - d: horizontal position error in arc-minutes (1/60
- degree) if known
- <tp:rationale>
- This is from XEP-0080
- </tp:rationale>
- </li>
- <li>vertical-error-m - d: vertical position error in metres if
- known
- <tp:rationale>
- This exists as a struct field in GeoClue; the name is new
- in this specification.
- </tp:rationale>
- </li>
- <li>horizontal-error-m - d: horizontal position error in metres if
+ -->
+
+ <li>accuracy - d: horizontal position error in metres if
known
<tp:rationale>
- This exists as a struct field in GeoClue; the name is new
- in this specification.
+ This is from XEP-0080
</tp:rationale>
</li>
</ul>
@@ -211,12 +212,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
called "direction" in GeoClue
</tp:rationale>
</li>
- <li>climb - d: rate of change of 'alt' in metres per second
- <tp:rationale>
- This is a struct field in GeoClue; the name is new to this
- specification, but seems uncontroversial
- </tp:rationale>
- </li>
</ul>
<p>Other well-known keys:</p>
@@ -389,6 +384,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
set it to be as restrictive as possible (an empty whitelist, if
supported).</tp:docstring>
</property>
+
+ <tp:contact-attribute name="location"
+ type="a{sv}" tp:type="Location">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same mapping that would be returned by
+ <tp:member-ref>GetLocations</tp:member-ref> for this contact.
+ Omitted from the result if the contact's location
+ is not known.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Renaming.xml b/spec/Connection_Interface_Renaming.xml
index c81d7ed..d08b748 100644
--- a/spec/Connection_Interface_Renaming.xml
+++ b/spec/Connection_Interface_Renaming.xml
@@ -65,7 +65,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</signal>
<method name="RequestRename" tp:name-for-bindings="Request_Rename">
- <arg direction="in" name="Name" type="s">
+ <arg direction="in" name="Identifier" type="s">
<tp:docstring>
The desired identifier
</tp:docstring>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 5c56db3..d8239e5 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -252,6 +252,7 @@
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
@@ -383,6 +384,7 @@
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
<tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 8446050..5c7ae97 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -395,7 +395,7 @@
This type isn't actually used by the SimplePresence interface, but
it's included here so it can be referenced by rich presence interfaces
such as <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">Location.DRAFT</tp:dbus-ref>.
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>.
</tp:docstring>
<tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
@@ -412,6 +412,16 @@
</tp:member>
</tp:struct>
+ <tp:contact-attribute name="presence"
+ type="(uss)" tp:type="Simple_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same struct that would be returned by
+ <tp:member-ref>GetPresences</tp:member-ref>
+ (always present with some value if information from the
+ SimplePresence interface was requested)</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface is for services which have a concept of presence which
can be published for yourself and monitored on your contacts.</p>
diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml
index ad8f058..ad0f895 100644
--- a/spec/Connection_Manager.xml
+++ b/spec/Connection_Manager.xml
@@ -303,6 +303,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dt>stun-port (q)</dt>
<dd>The UDP port number on the stun-server to use for STUN. Only
significant if the stun-server is also supplied.</dd>
+
+ <dt>keepalive-interval (u)</dt>
+ <dd>The time in seconds between pings sent to the server to ensure
+ that the connection is still alive, or <tt>0</tt> to disable such
+ pings.</dd>
</dl>
<p>Every successful RequestConnection call will cause the emission of a
@@ -444,7 +449,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dt>b (boolean)</dt>
<dd>"true" (case-insensitively) or "1" means True, "false"
(case-insensitively) or "0" means False</dd>
- <dt>q, u, t (16-, 32-, 64-bit unsigned integer)</dt>
+ <dt>y, q, u, t (8-, 16-, 32-, 64-bit unsigned integer)</dt>
<dd>ASCII decimal integer</dd>
<dt>n, i, x (16-, 32-, 64-bit signed integer)</dt>
<dd>ASCII decimal integer, optionally prefixed with "-"</dd>
diff --git a/spec/Debug.xml b/spec/Debug.xml
index a21d9db..70a82e9 100644
--- a/spec/Debug.xml
+++ b/spec/Debug.xml
@@ -17,9 +17,8 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Debug.DRAFT"
- tp:causes-havoc="experimental">
- <tp:added version="0.17.24"/>
+ <interface name="org.freedesktop.Telepathy.Debug">
+ <tp:added version="0.17.27">(as stable API)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for providing debug messages.</p>
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index d335e38..c9ae78f 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -265,12 +265,59 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:enum name="Media_Stream_Error" type="u">
<tp:enumvalue suffix="Unknown" value="0">
<tp:docstring>
- An unknown error occured.
+ An unknown error occured.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="EOS" value="1">
<tp:docstring>
- The end of the stream was reached.
+ The end of the stream was reached.
+ </tp:docstring>
+ <tp:deprecated version="0.17.27">
+ This error has no use anywhere. In Farsight 1 times, it was used to
+ indicate a GStreamer EOS (when the end of a file is reached). But
+ since this is for live calls, it makes no sense.
+ </tp:deprecated>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Codec_Negotiation_Failed" value="2">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no common codecs between the local side
+ and the other particpants in the call. The possible codecs are not
+ signalled here: the streaming implementation is assumed to report
+ them in an implementation-dependent way, e.g. Farsight should use
+ GstMissingElement.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Connection_Failed" value="3">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ A network connection for the Media could not be established or was
+ lost.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Network_Error" value="4">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the networking stack
+ (other than the connection failure).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="No_Codecs" value="5">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There are no installed codecs for this media type.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_CM_Behavior" value="6">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ The CM is doing something wrong.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Media_Error" value="7">
+ <tp:added version="0.17.27"/>
+ <tp:docstring>
+ There was an error in the media processing stack.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
diff --git a/spec/all.xml b/spec/all.xml
index dd228e2..076bb83 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.26</tp:version>
+<tp:version>0.17.28</tp:version>
<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
@@ -79,7 +79,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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"/>
@@ -106,7 +105,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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>
diff --git a/spec/errors.xml b/spec/errors.xml
index 7b1798d..22a629b 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -48,7 +48,7 @@
<tp:error name="Invalid Handle">
<tp:docstring>
- The contact name specified is unknown on this channel or connection.
+ The handle specified is unknown on this channel or connection.
</tp:docstring>
</tp:error>
@@ -71,9 +71,13 @@
</tp:error>
<tp:error name="Not Yours">
- <tp:docstring>
- The requested channel or other resource already exists, and another
- client is responsible for it
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested channel or other resource already exists, and another
+ user interface in this session is responsible for it.</p>
+
+ <p>User interfaces SHOULD handle this error unobtrusively, since it
+ indicates that some other user interface is already processing the
+ channel.</p>
</tp:docstring>
</tp:error>
@@ -260,7 +264,9 @@
<tp:error name="Busy">
<tp:docstring>
Used to represent a user being removed from a channel because of a
- "busy" indication.
+ "busy" indication. This error SHOULD NOT be used to represent a server
+ or other infrastructure being too busy to process a request - for that,
+ see ServerBusy.
<tp:rationale>
This corresponds to Busy in the
@@ -325,6 +331,72 @@
</tp:docstring>
</tp:error>
+ <tp:error name="Already Connected">
+ <tp:docstring>
+ Raised when the user attempts to connect to an account but they are
+ already connected (perhaps from another client or computer), and the
+ protocol or account settings do not allow this.
+
+ <tp:rationale>
+ XMPP can have this behaviour if the user chooses the same resource
+ in both clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Connection Replaced">
+ <tp:docstring>
+ Raised by an existing connection to an account if it is replaced by
+ a new connection (perhaps from another client or computer).
+
+ <tp:rationale>
+ In MSNP, when connecting twice with the same Passport, the new
+ connection "wins" and the old one is automatically disconnected.
+ XMPP can also have this behaviour if the user chooses the same
+ resource in two clients (it is server-dependent whether the result is
+ AlreadyConnected on the new connection, ConnectionReplaced on the
+ old connection, or two successful connections).
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Registration Exists">
+ <tp:docstring>
+ Raised during in-band registration if the server indicates that the
+ requested account already exists.
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Service Busy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Raised if a server or some other piece of infrastructure cannot process
+ the request, e.g. due to resource limitations. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ This is not the same error as Busy, which indicates that a
+ <em>user</em> is busy.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
+ <tp:error name="Resource Unavailable">
+ <tp:docstring>
+ Raised if a request cannot be satisfied because a process local to the
+ user has insufficient resources. Clients MAY try again
+ later.
+
+ <tp:rationale>
+ For instance, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>
+ might raise this error for some or all channel requests if it has
+ detected that there is not enough free memory.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:error>
+
<tp: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">
--
1.5.6.5
More information about the telepathy-commits
mailing list