[Telepathy-commits] [telepathy-glib/master] Update telepathy-spec to 0.17.21
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Mar 17 12:53:52 PDT 2009
---
NEWS | 6 +-
spec/Account.xml | 6 +-
spec/Account_Manager.xml | 4 +-
spec/Channel.xml | 6 +-
spec/Channel_Dispatch_Operation.xml | 2 +-
spec/Channel_Dispatcher.xml | 4 +-
spec/Channel_Interface_Group.xml | 68 +++-
spec/Channel_Interface_Media_Signalling.xml | 12 +-
spec/Channel_Interface_Media_Signalling_Future.xml | 6 +-
spec/Channel_Interface_Messages.xml | 4 +-
spec/Channel_Interface_Password.xml | 6 +-
spec/Channel_Interface_Tube.xml | 37 ++-
spec/Channel_Request.xml | 8 +-
spec/Channel_Type_Contact_Search.xml | 451 +++++++++++++++-----
spec/Channel_Type_DBus_Tube.xml | 12 +-
spec/Channel_Type_File_Transfer.xml | 11 +-
spec/Channel_Type_Room_List.xml | 6 +-
spec/Channel_Type_Stream_Tube.xml | 12 +-
spec/Channel_Type_Streamed_Media.xml | 13 +-
spec/Channel_Type_Streamed_Media_Future.xml | 4 +-
spec/Channel_Type_Text.xml | 6 +-
spec/Channel_Type_Tubes.xml | 2 +-
spec/Client_Handler.xml | 2 +-
spec/Connection.xml | 3 +-
spec/Connection_Interface_Avatars.xml | 4 +
spec/Connection_Interface_Contact_Info.xml | 96 +++--
spec/Connection_Interface_Presence.xml | 193 ++-------
spec/Connection_Interface_Simple_Presence.xml | 137 ++++++-
spec/all.xml | 9 +-
29 files changed, 776 insertions(+), 354 deletions(-)
diff --git a/NEWS b/NEWS
index 81617c2..7ec38c4 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,10 @@ Enhancements:
* Add an example connection manager that has dummy ContactList channels
vaguely resembling the XMPP roster
+* Update to telepathy-spec 0.17.21 (adding
+ TP_CHANNEL_GROUP_FLAG_MESSAGE_DEPART and
+ TP_CHANNEL_MEDIA_CAPABILITY_NAT_TRAVERSAL_ICE_UDP)
+
Fixes:
* fd.o #20646: in TpChannel, when adding contacts to one of the Group sets,
@@ -32,7 +36,7 @@ Fixes:
* Fix some memory leaks when making TpContact objects, when holding handles in
TpContactsMixin, when filling contact attributes in TpPresenceMixin,
when setting simple presence, and in the regression tests
-
+
* Update the valgrind suppressions file to cope with new telepathy-glib code,
GTest, and glibc 2.9
diff --git a/spec/Account.xml b/spec/Account.xml
index 991dcbd..9dc34ad 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -427,7 +427,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
The actual presence. If the connection is not online, this should be
(Connection_Presence_Type_Offline, "", "").
If the connection is online but does not support the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
interface, this should be (Connection_Presence_Type_Unset, "", "").
The account manager is expected to set this by observing signals
from the Connection.
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
index 98fe00d..6fb9b08 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Account_Manager"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 7b4a7ad..2937680 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
- <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 7f61f6f..6f728c3 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -161,7 +161,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The name of a D-Bus error indicating why the channel closed. If
no better reason can be found,
- <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY
+ <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
be used as a fallback; this means that this error SHOULD NOT be
given any more specific meaning.</p>
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index c77873d..af671bd 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Dispatcher"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 490258f..9c7e254 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright>
- <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -241,6 +241,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:rationale>
</tp:docstring>
</tp:flag>
+ <tp:flag suffix="Message_Depart" value="8192">
+ <tp:added version="0.17.UNRELEASED"/>
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ the <tp:member-ref>SelfHandle</tp:member-ref>.
+
+ <tp:rationale>
+ This would be set for XMPP Multi-User Chat or IRC channels,
+ but not for a typical implementation of streamed media calls.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
<property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
@@ -950,16 +963,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
A string message, which can be blank if desired
</tp:docstring>
</arg>
- <tp:docstring>
- Requests the removal of contacts from a channel, reject their request
- for channel membership on the pending local list, or rescind their
- invitation on the pending remote list. A message may be provided along
- with the request, which will be sent to the server if supported. See
- the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE,
- CHANNEL_GROUP_FLAG_MESSAGE_REJECT and
- CHANNEL_GROUP_FLAG_MESSAGE_RESCIND
- <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
- message should be provided.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Requests the removal of contacts from a channel, reject their
+ request for channel membership on the pending local list, or
+ rescind their invitation on the pending remote list.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group,
+ it can be removed via this method, in order to leave the group
+ gracefully. This is the recommended way to leave a chatroom, close
+ or reject a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call, and so on.</p>
+
+ <p>Accordingly, connection managers SHOULD support
+ doing this, regardless of the value of
+ <tp:member-ref>GroupFlags</tp:member-ref>.
+ If doing so fails with PermissionDenied, this is considered to a bug
+ in the connection manager, but clients MUST recover by falling back
+ to closing the channel with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method.</p>
+
+ <p>Removing any contact from the local pending list is always
+ allowed. Removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members
+ is allowed if and only if Channel_Group_Flag_Can_Remove is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>,
+ while removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list
+ is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>.</p>
+
+ <p>A message may be provided along with the request, which will be
+ sent to the server if supported. See the
+ Channel_Group_Flag_Message_Remove,
+ Channel_Group_Flag_Message_Depart,
+ Channel_Group_Flag_Message_Reject and
+ Channel_Group_Flag_Message_Rescind
+ <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+ message should be provided.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 8249331..b69e5b3 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -120,6 +120,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<dt>gtalk-p2p</dt>
<dd>Google Talk peer-to-peer connectivity establishment should be used,
as implemented in libjingle 0.3.</dd>
+
+ <dt>ice-udp</dt>
+ <dd>
+ Interactive Connectivity Establishment should be used, as defined by
+ the IETF MMUSIC working group.
+ </dd>
</dl>
</tp:docstring>
</tp:property>
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
index e1d2d25..d908450 100644
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Media_Signalling_Future"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2009 Nokia Corporation </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -22,7 +22,7 @@
<interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
- <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.MediaSignalling"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface contains functionality which we intend to incorporate
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 8cdee3c..c012f2f 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Messages"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml
index 720849a..76720a6 100644
--- a/spec/Channel_Interface_Password.xml
+++ b/spec/Channel_Interface_Password.xml
@@ -1,9 +1,9 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
-Copyright (C) 2005, 2006 Collabora Limited
-Copyright (C) 2005, 2006 Nokia Corporation
-Copyright (C) 2006 INdT
+Copyright © 2005-2009 Collabora Limited
+Copyright © 2005-2009 Nokia Corporation
+Copyright © 2006 INdT
</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index b2d0f31..8e6eb65 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -38,10 +38,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
HANDLE_TYPE_ROOM (to communicate with others in the room
simultaneously).</p>
+
+ <p>As an exception to the usual handling of capabilities, connection managers
+ for protocols with capability discovery, such as XMPP, SHOULD advertise the
+ capability representing each Tube type that they support
+ (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
+ even if no client has indicated via
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
+ that such a tube is supported.</p>
+
+ <tp:rationale>
+ <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
+ if the contact announced to support tubes.</p>
+ </tp:rationale>
</tp:docstring>
<property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
- access="readwrite" tp:name-for-bindings="Parameters">
+ access="read" tp:name-for-bindings="Parameters">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Each tube has a dictionary of arbitrary parameters. Parameters are
commonly used to bootstrap legacy protocols where you can't
@@ -60,11 +79,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
<p>When requesting a channel with
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
- this property MAY be included in the request. If it is not included in
- the request, the connection manager MUST consider the property to be
- empty. This property MAY be changed after the channel creation when
- the tube is in the state Not_Offered. If the tube is in another
- state, changing this property MUST fail without side effects.</p>
+ this property MUST NOT be included in the request. This property is undefined until the tube is offered
+ (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref>
+ or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>).
+ Once it has been offered, this property MUST NOT change.</p>
+ <p>When receiving an incoming tube, this property is immutable and so advertised in the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ signal.</p>
</tp:docstring>
</property>
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index bf1bd38..3706bdb 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -2,8 +2,8 @@
<node name="/Channel_Request"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -105,7 +105,7 @@
</tp:docstring>
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
This method has already been called, so it is no longer
available. Stop calling it.
@@ -144,7 +144,7 @@
<p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to
this method, the error SHOULD be
- <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
<p>If the channel has already been dispatched to a handler, then
it's too late to call this method, and the channel request will
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 0b166bb..204ecf1 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -18,135 +18,394 @@ Lesser General Public License for more details.</p>
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"
- tp:causes-havoc='not well-tested'>
+ <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+ tp:causes-havoc='experimental'>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
- <tp:struct name="Search_Key_Info">
- <tp:docstring>A struct representing details on search strings.</tp:docstring>
- <tp:member type="b" name="Is_Mandatory">
- <tp:docstring>Booleans indicating if the search key is mandatory.
- </tp:docstring>
- </tp:member>
- <tp:member type="g" name="Type_Signature">
- <tp:docstring>The type signature of the value for this search key.
- </tp:docstring>
- </tp:member>
- </tp:struct>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel type for searching server-stored user directories. A new
+ channel should be requested by a client for each search attempt, and
+ closed when the search is completed or the required result has been
+ found in order to free unused handles.</p>
- <tp:mapping name="Search_Key_Info_Map">
- <tp:docstring>A dictionary mapping string search key names to its search details.
- </tp:docstring>
- <tp:member type="s" name="Term"/>
- <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
- </tp:mapping>
+ <p>Before searching, the
+ <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
+ inspected to determine the valid search keys which can be provided to
+ the <tp:member-ref>Search</tp:member-ref> method. A search request is
+ then started by providing some of these terms to the Search method, and
+ the <tp:member-ref>SearchState</tp:member-ref> will change from
+ <code>Not_Started</code> to <code>In_Progress</code>. As results are
+ returned by the server, the
+ <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
+ for each contact found; when the search is complete, the search state
+ will be set to <code>Completed</code>. If the search fails after Search
+ has been called, the state will change to <code>Failed</code>. A
+ running search can be cancelled by calling
+ <tp:member-ref>Stop</tp:member-ref>.</p>
+
+ <p>The client should call the channel's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method when it is finished with the channel, so that any handles held
+ only by the channel can be released.</p>
+
+ <p>Each channel can only be used for a single search; a new channel
+ should be requested for each subsequent search. Connection managers
+ MUST support multiple ContactSearch channels being open at once (even
+ to the same server, if applicable).</p>
+
+ <p>It does not make sense to request this channel type using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
+ clients SHOULD request channels of this type using
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+ instead.</p>
+
+ <tp:rationale>
+ <p>A contact search channel that is already in use for a different
+ search isn't useful.</p>
+ </tp:rationale>
+ </tp:docstring>
- <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
- <arg direction="out" type="s">
- <tp:docstring>
- A string with any instructions from the server
- </tp:docstring>
- </arg>
- <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- A dictionary mapping string search key names to its search details.
- </tp:docstring>
- </arg>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>Returns any instructions from the server along with a dictionary of
- search key names to their types, and a boolean indicating if the key is
- mandatory. The following well-known search key names should be used
- where appropriate:</p>
- <dl>
- <dt>s:first</dt><dd>The desired contact's given name</dd>
- <dt>s:last</dt><dd>The desired contact's family name</dd>
- <dt>s:nick</dt><dd>The desired contact's nickname</dd>
- <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
- </dl>
- </tp:docstring>
- <tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
- </tp:possible-errors>
- </method>
<tp:enum name="Channel_Contact_Search_State" type="u">
- <tp:enumvalue suffix="Before" value="0">
+ <tp:enumvalue suffix="Not_Started" value="0">
<tp:docstring>The search has not started</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="During" value="1">
+ <tp:enumvalue suffix="In_Progress" value="1">
<tp:docstring>The search is in progress</tp:docstring>
</tp:enumvalue>
- <tp:enumvalue suffix="After" value="2">
+ <tp:enumvalue suffix="Completed" value="2">
<tp:docstring>The search has been completed</tp:docstring>
</tp:enumvalue>
+ <tp:enumvalue suffix="Failed" value="3">
+ <tp:docstring>The search has failed</tp:docstring>
+ </tp:enumvalue>
</tp:enum>
- <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
- <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>The search state represented as one of the values of
- ChannelContactSearchState</tp:docstring>
+
+ <property name="SearchState" tp:name-for-bindings="Search_State"
+ access="read" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>
+ The current state of this search channel object. Change notification
+ is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="SearchStateChanged"
+ tp:name-for-bindings="Search_State_Changed">
+ <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
+ <tp:docstring>The new search state</tp:docstring>
+ </arg>
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ If the new state is <code>Failed</code>, the name of a D-Bus error
+ describing what went wrong. Otherwise, the empty string.
+ </tp:docstring>
+ </arg>
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about the state transition, which may
+ include the following well-known keys:</p>
+
+ <dl>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ </dl>
+
+ <tp:rationale>
+ <p>This argument allows for future extensions. For instance,
+ if moving to state <code>Failed</code> because the server
+ rejected one of our search terms, we could define a key
+ that indicates which terms were invalid.</p>
+ </tp:rationale>
+ </tp:docstring>
</arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+ changes. The implementation MUST NOT make transitions other than the
+ following:</p>
+
+ <ul>
+ <li><code>Not_Started</code> → <code>In_Progress</code></li>
+ <li><code>In_Progress</code> → <code>Completed</code></li>
+ <li><code>In_Progress</code> → <code>Failed</code></li>
+ </ul>
+ </tp:docstring>
+ </signal>
+
+ <tp:simple-type name="Contact_Search_Key" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Any of the following search keys, with the indicated result for
+ the search:</p>
+
+ <dl>
+ <dt>The empty string</dt>
+ <dd>Search for the search term in some implementation-dependent
+ set of fields, using an implementation-dependent algorithm
+ (e.g. searching for each word mentioned)
+ <tp:rationale>
+ The "one big search box" approach to searching, as is familiar
+ from Google. The Sametime plugin to Pidgin appears to search in
+ this way.
+ </tp:rationale>
+ </dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type></dt>
+ <dd>Search for the search term in fields matching that name (for
+ instance, <code>nickname</code> would search nicknames, and
+ <code>tel</code> would search any available phone number,
+ regardless of its work/home/mobile/... status).</dd>
+
+ <dt>A <tp:type>VCard_Field</tp:type> followed by
+ "<code>;</code>" and a
+ <tp:type>VCard_Type_Parameter</tp:type> of the form
+ "<code>type=...</code>"</dt>
+ <dd>Search for the search term in fields of that name and type
+ only (for instance, <code>tel;type=mobile</code>).</dd>
+
+ <dt><code>x-telepathy-identifier</code></dt>
+ <dd>Search for contacts whose identifier in the IM protocol
+ matches the search term (e.g. contains it as a substring)
+ <tp:rationale>
+ Otherwise, starting a search by identifier would require the UI
+ to know the vCard field name corresponding to identifiers in
+ this protocol, which might be non-standard (like
+ <code>x-jabber</code>) or not exist at all.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-gender</code></dt>
+ <dd>For the search term "male" or "female", search only for contacts
+ listed as male or female, respectively. The results for other
+ search terms are undefined; it is likely that contacts with
+ unspecified gender will only be matched if this search key
+ is omitted from the request.
+ <tp:rationale>
+ Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
+ also supports limiting search results by gender.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-family</code></dt>
+ <dd>Search for the search term in contacts' family names
+ (the first component of the vCard field <code>n</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC seem to support this mode of searching.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-n-given</code></dt>
+ <dd>Search for the search term in contacts' given names
+ (the second component of the vCard field <code>n</code>).
+ <tp:rationale>
+ As for <code>x-n-family</code>.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-online</code></dt>
+ <dd>For the search term "yes", search only for contacts who are
+ currently online. The results for other search terms are undefined.
+ <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
+ </dd>
+
+ <dt><code>x-adr-locality</code></dt>
+ <dd>Search for the search term as a locality or city (the fourth
+ component of the vCard field <code>adr</code>).
+ <tp:rationale>
+ Gadu-Gadu and TOC appear to support this.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>x-search-offset</code></dt>
+ <dd>
+ <p>For protocols that support paging results, the offset from the
+ start of the results that should be returned, i.e. the number of
+ contacts from the beginning that should be omitted.</p>
+
+ <p>For example, if the search terms match 50 contacts, this key
+ is set to <code>"20"</code> and <code>x-search-limit</code>
+ is set to <code>"10"</code>, then the ten contacts from the 21st
+ to the 30th should be returned.</p>
+
+ <p>Connection managers for protocols which do not natively support
+ restricting the number of results returned MUST NOT support
+ either this term or <code>x-search-limit</code>: all results
+ should be signalled, and the client can provide its own paging as
+ desired.</p>
+ </dd>
+
+ <dt><code>x-search-limit</code></dt>
+ <dd>For protocols that support limiting results, the maximum number
+ of results that should be returned. For example, if the search
+ terms match <i>Antonius</i>, <i>Bridget</i> and <i>Charles</i> and
+ this key is set to <code>"2"</code>, the search service SHOULD only
+ return <i>Antonius</i> and <i>Bridget</i>.</dd>
+ </dl>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <property name="AvailableSearchKeys" type="as" access="read"
+ tp:name-for-bindings="Available_Search_Keys">
<tp:docstring>
- Returns the current state of this search channel object.
+ The set of search keys supported by this channel. Example values
+ include [""] (for protocols where several address fields are
+ implicitly searched) or ["x-n-given", "x-n-family", "nickname",
+ "email"] (for XMPP XEP-0055, without extensibility via Data Forms).
+ This property cannot change during the lifetime of a channel.
+
+ <tp:rationale>
+ It can be in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+ signal for round-trip reduction.
+ </tp:rationale>
</tp:docstring>
- </method>
- <method name="Search">
- <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
+ </property>
+
+ <tp:mapping name="Contact_Search_Map">
+ <tp:docstring>A map from search keys to search terms.</tp:docstring>
+ <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
+ <tp:docstring>
+ The search key to match against
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Term" type="s">
+ <tp:docstring>
+ The term or terms to be searched for in the search key; depending on
+ the protocol and the server implementation, this may be matched by
+ exact or approximate equality, substring matching, word matching
+ or any other matching algorithm
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <method name="Search" tp:name-for-bindings="Search">
+ <arg direction="in" name="Terms"
+ type="a{ss}" tp:type="Contact_Search_Map">
<tp:docstring>
A dictionary mapping search key names to the desired values
</tp:docstring>
</arg>
<tp:docstring>
- Send a request to start a search for contacts on this connection. A
- valid search request will cause the SearchStateChanged signal to be
- emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
+ Send a request to start a search for contacts on this connection. This
+ may only be called while the <tp:member-ref>SearchState</tp:member-ref>
+ is Not_Started; a valid search request will cause the
+ <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
+ with the state In_Progress.
</tp:docstring>
<tp:possible-errors>
- <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is no longer
+ Not_Started, so this method is no longer available.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The search terms included something this connection manager cannot
+ search for.
+ </tp:docstring>
+ </tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
</tp:possible-errors>
</method>
+
+ <method name="Stop" tp:name-for-bindings="Stop">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Stop the current search. This may not be called while the
+ <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called
+ while the SearchState is In_Progress,
+ <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted,
+ with the state Failed and the error
+ <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+
+ <p>Calling this method on a search in state Completed or Failed
+ succeeds, but has no effect.</p>
+
+ <tp:rationale>
+ <p>Specifying Stop to succeed when the search has finished means that
+ clients who call Stop just before receiving
+ <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to
+ handle a useless error.</p>
+ </tp:rationale>
+
+ <p>Depending on the protocol, the connection manager may not be
+ able to prevent the server from sending further results after this
+ method returns; if this is the case, it MUST ignore any further
+ results.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so
+ this method is not yet available.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
<signal name="SearchResultReceived"
tp:name-for-bindings="Search_Result_Received">
<arg name="Contact" type="u" tp:type="Contact_Handle">
- <tp:docstring>An integer handle for the contact</tp:docstring>
+ <tp:docstring>An integer handle for the contact, which will remain
+ valid at least until this Channel closes</tp:docstring>
</arg>
- <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
- <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
+ <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An array of fields representing information about this
+ contact, in the same format used in the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
+ interface. It is possible that a separate call to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+ would return more information than this signal provides.</p>
+
+ <p>This array SHOULD include the <code>x-telepathy-identifier</code>
+ field, whose values matches the result of calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ on the Contact handle.</p>
+
+ <tp:rationale>
+ <p>UIs will most likely want to show the identifier to the user;
+ while they could do this by inspecting the signalled handle,
+ including it in this signal is cheap and removes a roundtrip to
+ look it up.</p>
+ </tp:rationale>
+ </tp:docstring>
</arg>
<tp:docstring>
Emitted when a search result is received from the server.
</tp:docstring>
</signal>
- <signal name="SearchStateChanged"
- tp:name-for-bindings="Search_State_Changed">
- <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
- <tp:docstring>An integer representing the new search state</tp:docstring>
- </arg>
+
+ <property name="Server" tp:name-for-bindings="Server"
+ type="s" access="read">
<tp:docstring>
- Emitted when the search state (as returned by the GetSearchState
- method) changes.
+ <p>For protocols which support searching for contacts on multiple
+ servers with different DNS names (like XMPP), the DNS name of the
+ server being searched by this channel, e.g.
+ "characters.shakespeare.lit". Otherwise, the empty string.</p>
+
+ <tp:rationale>
+ <p>XEP 0055 defines a mechanism for XMPP clients to search services
+ of their choice for contacts, such as users.jabber.org (the "Jabber
+ User Directory").</p>
+ </tp:rationale>
+
+ <p>This property cannot change during the lifetime of the channel.
+ This property SHOULD be in the Allowed_Properties of a
+ <tp:type>Requestable_Channel_Class</tp:type> if and only if the
+ protocol supports querying multiple different servers;
+ implementations SHOULD use a sensible default if possible if this
+ property is not specified in a channel request.</p>
+
+ <tp:rationale>
+ <p>This allows a client to perform searches on a protocol it knows
+ nothing about without requiring the user to guess a valid server's
+ hostname.</p>
+ </tp:rationale>
</tp:docstring>
- </signal>
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A channel type for searching server-stored user directories. A new channel
- should be requested by a client for each search attempt, and it should be
- closed when the search is completed or the required result has been found
- in order to free unused handles. The search can be cancelled at any time
- by calling the channel Close method, although depending upon the protocol
- the connection manager may not be able to prevent the server from sending
- further results.</p>
-
- <p>Before searching, the GetSearchKeys method should be used to discover any
- instructions sent by the server, and the valid search keys which can be
- provided to the Search method. A search request is then started by
- providing some of these terms to the Search method, and the search status
- will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
- returned by the server, the SearchResultReceived signal is emitted for each
- contact found, and when the search is complete, the search status will be
- set to CHANNEL_SEARCH_STATE_AFTER.</p>
- </tp:docstring>
+ </property>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
index 2671a17..513d77c 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -58,6 +58,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
<tp:docstring>
Offers a D-Bus tube providing the service specified.
</tp:docstring>
+ <arg direction="in" name="parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ The dictionary of arbitrary
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+ to send with the tube offer.
+ </tp:docstring>
+ </arg>
<arg direction="out" name="address" type="s">
<tp:docstring>
The string describing the address of the private bus. The client
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index c88834c..7795f9d 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
- Copyright (C) 2008 Collabora Limited
+ Copyright © 2008-2009 Collabora Limited
</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
@@ -76,6 +76,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<p>The File channel type may be requested for handles of type
HANDLE_TYPE_CONTACT. If the channel is requested for any other
handle type then the behaviour is undefined.</p>
+
+ <p>Connection managers SHOULD NOT advertise support for file transfer to
+ other contacts unless it has been indicated by a call to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>.
+ </p>
+ <tp:rationale>
+ <p>People would send us files, and it would always fail. That would be silly.</p>
+ </tp:rationale>
</tp:docstring>
<property name="State" type="u" tp:type="File_Transfer_State"
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 10ccac6..4170fce 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index b64f4a0..060cd0b 100644
--- a/spec/Channel_Type_Stream_Tube.xml
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
- <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -66,6 +66,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
specified in the documentation for the Socket_Access_Control enum.
</tp:docstring>
</arg>
+ <arg direction="in" name="parameters" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring>
+ The dictionary of arbitrary
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+ to send with the tube offer.
+ </tp:docstring>
+ </arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index b89065b..701c8a5 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -422,6 +422,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
connections (as implemented in libjingle 0.3) to traverse NATs.
</tp:docstring>
</tp:flag>
+ <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16">
+ <tp:docstring>
+ The handle is capable of establishing ICE UDP peer-to-peer
+ connections (as defined by the IETF MMUSIC working group) to traverse
+ NATs.
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
</interface>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 2421ed6..fa8a015 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Streamed_Media_Future"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2009 Nokia Corporation </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5c28dce..f5828a4 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
- <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
- <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
- <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index f6829b5..925ae1b 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" ?>
<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
- Copyright (C) 2007-2008 Collabora Limited
+ Copyright © 2007-2009 Collabora Limited
</tp:copyright>
<tp:license>
This library is free software; you can redistribute it and/or
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index 59c253b..b29ffac 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -238,7 +238,7 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The name of the D-Bus error with which the request failed.</p>
- <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>,
+ <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>,
this indicates that the request succeeded, but all the resulting
channels were given to some other handler.</p>
</tp:docstring>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 97a3c4c..ec0cc2e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -970,7 +970,8 @@ USA.</p>
<p>As well as the methods and signatures below, arbitrary interfaces may be
provided by the Connection object to represent extra connection-wide
- functionality, such as the Connection.Interface.Presence for receiving and
+ functionality, such as the Connection.Interface.SimplePresence for
+ receiving and
reporting presence information, and Connection.Interface.Aliasing for
connections where contacts may set and change an alias for themselves.
These interfaces can be discovered using the
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 7ef26af..acc44de 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -179,6 +179,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
same order as the given array of contact handles
</tp:docstring>
</arg>
+ <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens
+ instead.</tp:deprecated>
<tp:docstring>
Get the unique tokens for all of the given contacts' avatars.
@@ -244,6 +246,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
unknown
</tp:docstring>
</arg>
+ <tp:deprecated version="0.15.5">Use RequestAvatars
+ instead.</tp:deprecated>
<tp:docstring>
Request the avatar for a given contact. Using this method in new
Telepathy clients is deprecated; use RequestAvatars instead.
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index e7b033b..a9d086a 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -31,28 +31,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:docstring>
</tp:member>
<tp:member type="as" name="Parameters">
- <tp:docstring>
- A list of (lowercased) vCard type parameters applicable to this field.
- For example, a contact's preferred home address would have parameters
- 'home' and 'pref'.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of vCard type parameters applicable to this field, with their
+ values. The type parameter names, and any values that are
+ case-insensitive in vCard, MUST be in lower case. For example, a
+ contact's preferred home address would have parameters
+ 'type=home' and 'type=pref'.</p>
<tp:rationale>
- This is a list of strings rather than a bitwise OR of enum members
- because vCard type parameters are essentially arbitrary strings.
+ The type parameter 'type' is likely to be the most common, but
+ there can be others, such as 'language=en'.
+ </tp:rationale>
+
+ <p>Characters which are required to be escaped in vCard type
+ parameters should not be escaped in this list. For instance,
+ a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become
+ ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p>
+
+ <tp:rationale>
+ This avoids Telepathy UIs having to understand the escaping and
+ unescaping rules for vCards. The type parameter name is not
+ allowed (by RFC 2425) to contain an '=' character, so no ambiguity
+ is introduced.
</tp:rationale>
</tp:docstring>
</tp:member>
<tp:member type="as" name="Field_Value">
- <tp:docstring>
- For unstructured vCard fields (such as 'fn', a formatted name
- field), a single-element array containing the field's value; for
- structured fields (such as 'adr', an address field), an array
- corresponding to the semicolon-separated elements of the field (with
- empty strings for empty elements). A vCard field with multiple
- comma-separated values should be represented by several
- <tp:type>Contact_Info_Field</tp:type>s. Characters which are
- required to be escaped in vCard values, such as semi-colons, should
- not be escaped in this list.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For unstructured vCard fields (such as 'fn', a formatted name
+ field), a single-element array containing the field's value.</p>
+
+ <p>For structured fields (such as 'adr', an address field), an array
+ corresponding to the semicolon-separated elements of the field (with
+ empty strings for empty elements).</p>
+
+ <p>A vCard field with multiple comma-separated values, such as
+ 'nickname', should be represented by several
+ <tp:type>Contact_Info_Field</tp:type>s.</p>
+
+ <p>Characters which are required to be escaped in vCard values, such as
+ semi-colons and newlines, should not be escaped in this list (e.g. if
+ a value contains a newline, the data passed over D-Bus should
+ contain a literal newline character).</p>
<tp:rationale>
An earlier draft of this interface split structured vCard fields
@@ -103,7 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
BEGIN:vCard
VERSION:3.0
FN:Wee Ninja
- N:Ninja;Wee;;;-san
+ N;LANGUAGE=ja:Ninja;Wee;;;-san
ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
;CB2 1SJ;UK
@@ -111,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
EMAIL;TYPE=INTERNET,PREF:wee.ninja at collabora.co.uk
EMAIL;TYPE=INTERNET:wee.ninja at example.com
URL:http://www.thinkgeek.com/geektoys/plush/8823/
+ NICKNAME:HR Ninja,Enforcement Ninja
END:vCard</pre>
<p>would be represented by (in Python-like syntax):</p>
@@ -118,15 +139,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<pre>
[
('fn', [], ['Wee Ninja']),
- ('n', [], ['Ninja', 'Wee', '', '', '-san']),
+ ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
- ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
- 'Cambridgeshire','CB2 1SJ','UK']),
- ('tel', ['voice','work'], ['+44 1223 362967']),
- ('tel', ['voice','work'], ['+44 7700 900753']),
- ('email', ['internet','pref'], ['wee.ninja at collabora.co.uk']),
- ('email', ['internet'], ['wee.ninja at example.com']),
+ ('adr', ['type=work','type=postal','type=parcel'],
+ ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+ ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+ ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+ ('email', ['type=internet','type=pref'], ['wee.ninja at collabora.co.uk']),
+ ('email', ['type=internet'], ['wee.ninja at example.com']),
('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+ ('nickname', [], ['HR Ninja']),
+ ('nickname', [], ['Enforcement Ninja'])
]</pre>
</tp:docstring>
</tp:struct>
@@ -267,11 +290,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:enumvalue>
</tp:enum>
+ <tp:simple-type name="VCard_Field" type="s">
+ <tp:docstring>
+ A string naming a field in a vCard, such as "fn" or "adr". Although
+ these are case-insensitive in RFC 2425, in Telepathy they MUST be
+ normalized to lower case. In the terminology of RFC 2425 this is
+ called a "type name", and corresponds to the "name" production given
+ in the ABNF.
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:simple-type name="VCard_Type_Parameter" type="s">
+ <tp:docstring>
+ A type parameter as defined by RFC 2426, such as "type=cell" or
+ "language=en".
+ </tp:docstring>
+ </tp:simple-type>
+
<property name="ContactInfoFlags" type="u" access="read"
tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags">
<tp:docstring>
- An integer representing the bitwise-OR of flags on this channel. This
- property should be constant over the lifetime of a connection.
+ An integer representing the bitwise-OR of flags on this connection.
+ This property should be constant over the lifetime of a connection.
</tp:docstring>
</property>
@@ -280,11 +320,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this
Connection.</tp:docstring>
- <tp:member type="s" name="Name">
+ <tp:member type="s" name="Name" tp:type="VCard_Field">
<tp:docstring>A vCard field name, such as 'tel'.</tp:docstring>
</tp:member>
- <tp:member type="as" name="Parameters">
+ <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]">
<tp:docstring>The set of vCard type parameters which may be set on this
field. If this list is empty and the
Contact_Info_Field_Flag_Parameters_Mandatory
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 6d9b24a..ecf96f8 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -27,7 +27,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Connection.Interface.Presence">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <!-- We hope to simplify these eventually -->
<tp:mapping name="Multiple_Status_Map">
<tp:docstring>Mapping used in
<tp:type>Last_Activity_And_Statuses</tp:type> and passed to
@@ -249,17 +248,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
map optional parameter names to their variant-boxed values
</tp:docstring>
</arg>
- <tp:docstring>
- Request that the user's presence be changed to the given statuses and
- desired parameters. Changes will be reflected by
- <tp:member-ref>PresenceUpdate</tp:member-ref>
- signals being emitted. On certain protocols, this method may be
- called on a newly-created connection which is still in the
- DISCONNECTED state, and will sign on with the requested status.
- If the requested status is not available after signing on,
- NotAvailable will be returned and the connection will remain
- offline, or if the protocol does not support signing on with
- a certain status, Disconnected will be returned.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the user's presence be changed to the given statuses
+ and desired parameters. Changes will be reflected by
+ <tp:member-ref>PresenceUpdate</tp:member-ref>
+ signals being emitted.</p>
+
+ <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+ is Offline, Error or Unknown MUST NOT be passed to this
+ function. Connection managers SHOULD reject these statuses.</p>
+
+ <tp:rationale>
+ <p>The same rationale as for <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
+ applies.</p>
+ </tp:rationale>
+
+ <p>On certain protocols, this method may be
+ called on a newly-created connection which is still in the
+ DISCONNECTED state, and will sign on with the requested status.
+ If the requested status is not available after signing on,
+ NotAvailable will be returned and the connection will remain
+ offline, or if the protocol does not support signing on with
+ a certain status, Disconnected will be returned.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -269,12 +280,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
+
+ <tp:deprecated version="0.17.UNRELEASED">New client implementations
+ SHOULD use <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ instead. New connection managers SHOULD implement both Presence
+ and SimplePresence.</tp:deprecated>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>This interface will become deprecated in future versions. New
- client implementations MAY use <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
- instead; new connection managers SHOULD implement both Presence and
- SimplePresence.</p>
<p>This interface is for services which have a concept of presence which
can be published for yourself and monitored on your contacts.
@@ -287,28 +300,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
per connection, and a list of them can be obtained with the
<tp:member-ref>GetStatuses</tp:member-ref> method.</p>
+ <p>(The SimplePresence interface which replaces this one restricts
+ presences to one status per contact, with an optional message, which is
+ in practice all that was implemented on this interface.)</p>
+
<p>Each status has an arbitrary string identifier which should have an agreed
meaning between the connection manager and any client which is expected to
- make use of it. The following well-known values (in common with those in
- Galago) should be used where possible to allow clients to identify common
- choices:</p>
-
- <ul>
- <li>available (corresponding to Connection_Presence_Type_Available)</li>
- <li>away (corresponding to Connection_Presence_Type_Away)</li>
- <li>brb (Be Right Back) (corresponding to
- Connection_Presence_Type_Away, but more specific)</li>
- <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
- <li>dnd (Do Not Disturb) (corresponding to
- Connection_Presence_Type_Busy, but more specific)</li>
- <li>xa (Extended Away) (corresponding to
- Connection_Presence_Type_Extended_Away)</li>
- <li>hidden (aka Invisible) (corresponding to
- Connection_Presence_Type_Hidden)</li>
- <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
- <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
- <li>error (corresponding to Connection_Presence_Type_Error)</li>
- </ul>
+ make use of it. The well-known values defined by the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface SHOULD be used where possible</p>
<p>As well as these well-known status identifiers, every status also has a
numerical type value chosen from
@@ -339,125 +339,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
intermittently to update any display of presence information.</p>
</tp:docstring>
- <tp:enum name="Connection_Presence_Type" type="u">
- <tp:enumvalue suffix="Unset" value="0">
- <tp:docstring>
- An invalid presence type used as a null value. This value MUST NOT
- appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>,
- or in the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref>
- property of the <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
- interface.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Offline" value="1">
- <tp:docstring>
- Offline
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Available" value="2">
- <tp:docstring>
- Available
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Away" value="3">
- <tp:docstring>
- Away
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Extended_Away" value="4">
- <tp:docstring>
- Away for an extended time
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Hidden" value="5">
- <tp:docstring>
- Hidden (invisible)
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Busy" value="6">
- <tp:added version="0.17.0"/>
- <tp:docstring>
- Busy, Do Not Disturb.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Unknown" value="7">
- <tp:added version="0.17.8"/>
- <tp:docstring>
- Unknown, unable to determine presence for this contact, for example
- if the protocol only allows presence of subscribed contacts.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Error" value="8">
- <tp:added version="0.17.8"/>
- <tp:docstring>
- Error, an error occurred while trying to determine presence. The
- message, if set, is an error from the server.
- </tp:docstring>
- </tp:enumvalue>
- </tp:enum>
-
- <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
- <tp:docstring>
- A type of access control for Rich_Presence_Access_Control.
- For most types, the exact access control is given by an associated
- variant.
-
- <tp:rationale>
- These are the access control types from XMPP publish/subscribe
- (XEP-0060).
- </tp:rationale>
- </tp:docstring>
-
- <tp:enumvalue suffix="Whitelist" value="0">
- <tp:docstring>
- The associated variant is a list of contacts (signature 'au',
- Contact_Handle[]) who can see the extended presence information.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Publish_List" value="1">
- <tp:docstring>
- All contacts in the user's 'publish' contact list can see the
- extended presence information. The associated variant is ignored.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Group" value="2">
- <tp:docstring>
- The associated variant is a handle of type Group (signature 'u',
- Group_Handle) representing a group of contacts who can see the
- extended presence information.
- </tp:docstring>
- </tp:enumvalue>
- <tp:enumvalue suffix="Open" value="3">
- <tp:docstring>
- Anyone with access to the service can see the extended presence
- information.
- </tp:docstring>
- </tp:enumvalue>
- </tp:enum>
-
- <tp:struct name="Rich_Presence_Access_Control">
- <tp:docstring>
- An access control mode for extended presence items like geolocation.
- This type isn't actually used by the core Presence interface, but
- it's included here so it can be referenced by other specifications.
- </tp:docstring>
-
- <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
- <tp:docstring>
- The type of access control to apply.
- </tp:docstring>
- </tp:member>
- <tp:member name="Detail" type="v">
- <tp:docstring>
- Any additional information required by the Type. The required
- type and semantics are defined for each
- Rich_Presence_Access_Control_Type.
- </tp:docstring>
- </tp:member>
- </tp:struct>
-
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 16f3386..7acea32 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -151,6 +151,16 @@
the choices would be appropriate, and incorrect information
about the user would be conveyed.</p>
</tp:rationale>
+
+ <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+ is Offline, Error or Unknown MUST NOT be passed to this
+ function. Connection managers SHOULD reject these statuses.</p>
+
+ <tp:rationale>
+ <p>To go offline, call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref>
+ instead. The "error" and "unknown" statuses make no sense.</p>
+ </tp:rationale>
</tp:docstring>
</arg>
<arg direction="in" name="Status_Message" type="s">
@@ -232,9 +242,9 @@
<property name="Statuses" tp:name-for-bindings="Statuses" access="read"
type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- <p>A dictionary where the keys are the presence statuses that the user
- can set on themselves for this connection, and the values are the
- corresponding presence types.</p>
+ <p>A dictionary where the keys are the presence statuses that are
+ available on this connection, and the values are the corresponding
+ presence types.</p>
<p>While the connection is in the DISCONNECTED state, it contains
the set of presence statuses allowed to be set before connecting.
@@ -280,6 +290,127 @@
</tp:docstring>
</signal>
+ <tp:enum name="Connection_Presence_Type" type="u">
+ <tp:enumvalue suffix="Unset" value="0">
+ <tp:docstring>
+ An invalid presence type used as a null value. This value MUST NOT
+ appear in the <tp:member-ref>Statuses</tp:member-ref> property,
+ or in the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Presence">GetStatuses</tp:dbus-ref>
+ on the deprecated <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+ interface.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring>
+ Offline
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Available" value="2">
+ <tp:docstring>
+ Available
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Away" value="3">
+ <tp:docstring>
+ Away
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Extended_Away" value="4">
+ <tp:docstring>
+ Away for an extended time
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Hidden" value="5">
+ <tp:docstring>
+ Hidden (invisible)
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Busy" value="6">
+ <tp:added version="0.17.0"/>
+ <tp:docstring>
+ Busy, Do Not Disturb.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Unknown" value="7">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Unknown, unable to determine presence for this contact, for example
+ if the protocol only allows presence of subscribed contacts.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="8">
+ <tp:added version="0.17.8"/>
+ <tp:docstring>
+ Error, an error occurred while trying to determine presence. The
+ message, if set, is an error from the server.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
+ <tp:docstring>
+ A type of access control for Rich_Presence_Access_Control.
+ For most types, the exact access control is given by an associated
+ variant.
+
+ <tp:rationale>
+ These are the access control types from XMPP publish/subscribe
+ (XEP-0060).
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Whitelist" value="0">
+ <tp:docstring>
+ The associated variant is a list of contacts (signature 'au',
+ Contact_Handle[]) who can see the extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Publish_List" value="1">
+ <tp:docstring>
+ All contacts in the user's 'publish' contact list can see the
+ extended presence information. The associated variant is ignored.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Group" value="2">
+ <tp:docstring>
+ The associated variant is a handle of type Group (signature 'u',
+ Group_Handle) representing a group of contacts who can see the
+ extended presence information.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Open" value="3">
+ <tp:docstring>
+ Anyone with access to the service can see the extended presence
+ information.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Rich_Presence_Access_Control">
+ <tp:docstring>
+ An access control mode for extended presence items like geolocation.
+ This type isn't actually used by the SimplePresence interface, but
+ it's included here so it can be referenced by rich presence interfaces
+ such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Location.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+
+ <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
+ <tp:docstring>
+ The type of access control to apply.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Detail" type="v">
+ <tp:docstring>
+ Any additional information required by the Type. The required
+ type and semantics are defined for each
+ <tp:type>Rich_Presence_Access_Control_Type</tp:type>.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This interface is for services which have a concept of presence which
can be published for yourself and monitored on your contacts.</p>
diff --git a/spec/all.xml b/spec/all.xml
index 7745d54..1c377df 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,11 +3,11 @@
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.19</tp:version>
+<tp:version>0.17.21</tp:version>
-<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
-<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
-<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+<tp:copyright>Copyright © 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
@@ -52,6 +52,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Type_Stream_Tube.xml"/>
<xi:include href="Channel_Type_DBus_Tube.xml"/>
<xi:include href="Channel_Type_File_Transfer.xml"/>
+<xi:include href="Channel_Type_Contact_Search.xml"/>
<xi:include href="Channel_Interface_Call_Merging.xml"/>
<xi:include href="Channel_Interface_Call_State.xml"/>
--
1.5.6.5
More information about the telepathy-commits
mailing list