summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSimon McVittie <simon.mcvittie@collabora.co.uk>2010-05-25 15:45:24 +0100
committerSimon McVittie <simon.mcvittie@collabora.co.uk>2010-05-25 16:01:09 +0100
commit2948ab95e843a969840d9e2696103e9b63282c92 (patch)
tree0d7461643c8a39671c3b2062b5e6f5dd856b80ef
parentfc4cf185b4528a582c5f2eb2efeb0cc60509371a (diff)
Update to spec 0.19.6
-rw-r--r--docs/reference/telepathy-glib-sections.txt24
-rw-r--r--spec/Account.xml38
-rw-r--r--spec/Call_Content_Interface_Media.xml2
-rw-r--r--spec/Call_Content_Interface_Mute.xml83
-rw-r--r--spec/Channel_Dispatch_Operation.xml66
-rw-r--r--spec/Channel_Dispatcher.xml4
-rw-r--r--spec/Channel_Interface_Anonymity.xml68
-rw-r--r--spec/Channel_Interface_DTMF.xml179
-rw-r--r--spec/Channel_Interface_Messages.xml4
-rw-r--r--spec/Channel_Interface_Service_Point.xml85
-rw-r--r--spec/Channel_Request.xml5
-rw-r--r--spec/Channel_Type_Call.xml21
-rw-r--r--spec/Client_Handler.xml10
-rw-r--r--spec/Client_Interface_Requests.xml6
-rw-r--r--spec/Client_Observer.xml25
-rw-r--r--spec/Connection_Interface_Anonymity.xml170
-rw-r--r--spec/Connection_Interface_Capabilities.xml2
-rw-r--r--spec/Connection_Interface_Cellular.xml82
-rw-r--r--spec/Connection_Interface_Contact_Groups.xml412
-rw-r--r--spec/Connection_Interface_Contact_Info.xml11
-rw-r--r--spec/Connection_Interface_Contact_List.xml837
-rw-r--r--spec/Connection_Interface_Forwarding.xml365
-rw-r--r--spec/Connection_Interface_Location.xml36
-rw-r--r--spec/Connection_Interface_Mail_Notification.xml14
-rw-r--r--spec/Connection_Interface_Service_Point.xml135
-rw-r--r--spec/Makefile.am8
-rw-r--r--spec/all.xml13
-rw-r--r--spec/errors.xml23
-rw-r--r--spec/generic-types.xml30
29 files changed, 2652 insertions, 106 deletions
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 151ea042..21b2d248 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -678,12 +678,17 @@ tp_svc_channel_interface_call_state_get_type
<SUBSECTION>
TpSvcChannelInterfaceDTMF
TpSvcChannelInterfaceDTMFClass
+tp_svc_channel_interface_dtmf_implement_multiple_tones
tp_svc_channel_interface_dtmf_implement_start_tone
tp_svc_channel_interface_dtmf_implement_stop_tone
+tp_svc_channel_interface_dtmf_return_from_multiple_tones
tp_svc_channel_interface_dtmf_return_from_start_tone
tp_svc_channel_interface_dtmf_return_from_stop_tone
+tp_svc_channel_interface_dtmf_multiple_tones_impl
tp_svc_channel_interface_dtmf_start_tone_impl
tp_svc_channel_interface_dtmf_stop_tone_impl
+tp_svc_channel_interface_dtmf_emit_sending_tones
+tp_svc_channel_interface_dtmf_emit_stopped_tones
<SUBSECTION Standard>
TP_SVC_CHANNEL_INTERFACE_DTMF
TP_IS_SVC_CHANNEL_INTERFACE_DTMF
@@ -2027,6 +2032,7 @@ TpDebugLevel
NUM_TP_DEBUG_LEVELS
TpContactInfoFlags
TpContactInfoFieldFlags
+TpLocationFeatures
</SECTION>
<SECTION>
@@ -2138,6 +2144,7 @@ TP_IFACE_QUARK_CLIENT_OBSERVER
TP_IFACE_CLIENT_INTERFACE_REQUESTS
TP_IFACE_QUARK_CLIENT_INTERFACE_REQUESTS
TP_PROP_ACCOUNT_AUTOMATIC_PRESENCE
+TP_PROP_ACCOUNT_CHANGING_PRESENCE
TP_PROP_ACCOUNT_CONNECTION
TP_PROP_ACCOUNT_CONNECTION_STATUS
TP_PROP_ACCOUNT_CONNECTION_STATUS_REASON
@@ -2169,6 +2176,8 @@ TP_PROP_CHANNEL_DISPATCH_OPERATION_POSSIBLE_HANDLERS
TP_PROP_CHANNEL_INITIATOR_HANDLE
TP_PROP_CHANNEL_INITIATOR_ID
TP_PROP_CHANNEL_INTERFACES
+TP_PROP_CHANNEL_INTERFACE_DTMF_CURRENTLY_SENDING_TONES
+TP_PROP_CHANNEL_INTERFACE_DTMF_INITIAL_TONES
TP_PROP_CHANNEL_INTERFACE_GROUP_GROUP_FLAGS
TP_PROP_CHANNEL_INTERFACE_GROUP_HANDLE_OWNERS
TP_PROP_CHANNEL_INTERFACE_GROUP_LOCAL_PENDING_MEMBERS
@@ -2232,6 +2241,7 @@ TP_PROP_CONNECTION_INTERFACE_CONTACT_INFO_CONTACT_INFO_FLAGS
TP_PROP_CONNECTION_INTERFACE_CONTACT_INFO_SUPPORTED_FIELDS
TP_PROP_CONNECTION_INTERFACE_LOCATION_LOCATION_ACCESS_CONTROL
TP_PROP_CONNECTION_INTERFACE_LOCATION_LOCATION_ACCESS_CONTROL_TYPES
+TP_PROP_CONNECTION_INTERFACE_LOCATION_SUPPORTED_LOCATION_FEATURES
TP_PROP_CONNECTION_INTERFACE_REQUESTS_CHANNELS
TP_PROP_CONNECTION_INTERFACE_REQUESTS_REQUESTABLE_CHANNEL_CLASSES
TP_PROP_CONNECTION_INTERFACE_SIMPLE_PRESENCE_STATUSES
@@ -2249,6 +2259,7 @@ TP_TOKEN_CONNECTION_INTERFACE_ALIASING_ALIAS
TP_TOKEN_CONNECTION_INTERFACE_AVATARS_TOKEN
TP_TOKEN_CONNECTION_INTERFACE_CAPABILITIES_CAPS
TP_TOKEN_CONNECTION_INTERFACE_CONTACT_CAPABILITIES_CAPABILITIES
+TP_TOKEN_CONNECTION_INTERFACE_CONTACT_INFO_INFO
TP_TOKEN_CONNECTION_INTERFACE_SIMPLE_PRESENCE_PRESENCE
TP_TOKEN_CONNECTION_INTERFACE_LOCATION_LOCATION
TP_TOKEN_CHANNEL_INTERFACE_MEDIA_SIGNALLING_GTALK_P2P
@@ -2643,6 +2654,12 @@ tp_cli_channel_interface_dtmf_call_start_tone
tp_cli_channel_interface_dtmf_call_stop_tone
tp_cli_channel_interface_dtmf_callback_for_start_tone
tp_cli_channel_interface_dtmf_callback_for_stop_tone
+tp_cli_channel_interface_dtmf_call_multiple_tones
+tp_cli_channel_interface_dtmf_callback_for_multiple_tones
+tp_cli_channel_interface_dtmf_connect_to_sending_tones
+tp_cli_channel_interface_dtmf_signal_callback_sending_tones
+tp_cli_channel_interface_dtmf_connect_to_stopped_tones
+tp_cli_channel_interface_dtmf_signal_callback_stopped_tones
<SUBSECTION>
tp_cli_channel_interface_hold_callback_for_get_hold_state
tp_cli_channel_interface_hold_call_get_hold_state
@@ -2658,6 +2675,8 @@ tp_cli_channel_interface_media_signalling_call_get_session_handlers
tp_cli_channel_interface_media_signalling_callback_for_get_session_handlers
tp_cli_channel_interface_media_signalling_connect_to_new_session_handler
tp_cli_channel_interface_media_signalling_signal_callback_new_session_handler
+<SUBSECTION Private>
+tp_cli_channel_interface_dtmf_run_multiple_tones
</SECTION>
<SECTION>
@@ -3530,6 +3549,8 @@ tp_cli_channel_dispatch_operation_callback_for_claim
tp_cli_channel_dispatch_operation_call_claim
tp_cli_channel_dispatch_operation_callback_for_handle_with
tp_cli_channel_dispatch_operation_call_handle_with
+tp_cli_channel_dispatch_operation_callback_for_handle_with_time
+tp_cli_channel_dispatch_operation_call_handle_with_time
tp_cli_channel_dispatch_operation_signal_callback_channel_lost
tp_cli_channel_dispatch_operation_connect_to_channel_lost
tp_cli_channel_dispatch_operation_signal_callback_finished
@@ -3597,6 +3618,9 @@ tp_svc_channel_dispatch_operation_implement_claim
tp_svc_channel_dispatch_operation_return_from_handle_with
tp_svc_channel_dispatch_operation_handle_with_impl
tp_svc_channel_dispatch_operation_implement_handle_with
+tp_svc_channel_dispatch_operation_handle_with_time_impl
+tp_svc_channel_dispatch_operation_implement_handle_with_time
+tp_svc_channel_dispatch_operation_return_from_handle_with_time
tp_svc_channel_dispatch_operation_emit_channel_lost
tp_svc_channel_dispatch_operation_emit_finished
<SUBSECTION Standard>
diff --git a/spec/Account.xml b/spec/Account.xml
index 4b112cb4..f315c15d 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -480,6 +480,44 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</property>
+ <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, a change to the presence of this account is
+ in progress.</p>
+
+ <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on
+ an account that could go online, or whenever an account with a
+ non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes
+ able to go online (for instance because
+ <tp:member-ref>Enabled</tp:member-ref> or
+ <tp:member-ref>Valid</tp:member-ref> changes to True),
+ ChangingPresence MUST change to True, and the two property changes MUST
+ be emitted in the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the
+ Set method returns.</p>
+
+ <p>When the account manager succeeds or fails in changing the presence,
+ or the connection disconnects due to an error, ChangingPresence MUST
+ change to False as part of the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ <p>This allows UIs to indicate that a presence change is in progress
+ or has finished, even if the change was initiated by a different
+ UI.</p>
+
+ <p>For instance, Maemo 5 and Empathy indicate a presence change by
+ having the presence indicator alternate between the
+ <tp:member-ref>RequestedPresence</tp:member-ref>
+ and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should
+ start blinking when ChangingPresence becomes true, and stop when it
+ becomes false.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </property>
+
<method name="Reconnect" tp:name-for-bindings="Reconnect">
<tp:added version="0.17.24"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
index 2b3eb65d..8b9a17c8 100644
--- a/spec/Call_Content_Interface_Media.xml
+++ b/spec/Call_Content_Interface_Media.xml
@@ -61,7 +61,7 @@
</tp:docstring>
</tp:member>
- <tp:member name="Parameters" type="a{ss}">
+ <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
Extra parameters for this codec
</tp:docstring>
diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml
new file mode 100644
index 00000000..eea724f5
--- /dev/null
+++ b/spec/Call_Content_Interface_Mute.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for calls which may be muted. This only makes sense
+ for channels where audio or video is streaming between members.</p>
+
+ <p>Muting a call content indicates that the user does not wish to send
+ outgoing audio or video.</p>
+
+ <p>Although it's client's responsibility to actually mute the microphone
+ or turn off the camera, using this interface the client can also
+ inform the CM and other clients of that fact.</p>
+ <tp:rationale>
+ <p>For some protocols, the fact that the content is muted needs to be
+ transmitted to the peer; for others, the notification to the peer is
+ only informational (eg. XMPP), and some protocols may have no notion
+ of muting at all.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed">
+ <tp:docstring>
+ Emitted to indicate that the mute state has changed for this call content.
+ This may occur as a consequence of the client calling
+ <tp:member-ref>Muted</tp:member-ref>, or as an indication that another
+ client has (un)muted the content.
+ </tp:docstring>
+
+ <arg name="MuteState" type="b">
+ <tp:docstring>
+ True if the content is now muted.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="MuteState" type="b"
+ access="read" tp:name-for-bindings="Mute_State">
+ <tp:docstring>
+ True if the content is muted.
+ </tp:docstring>
+ </property>
+
+ <method name="Muted" tp:name-for-bindings="Muted">
+ <arg direction="in" name="Muted" type="b">
+ <tp:docstring>
+ True if the client has muted the content.
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ <p>Inform the CM that the call content has been muted or unmuted by
+ che client.</p>
+
+ <p>It is the client's responsibility to actually mute or unmute the
+ microphone or camera used for the content. However, the client
+ MUST call this whenever it mutes or unmutes the content.</p>
+ </tp:docstring>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 26d9b579..6ec69a67 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -370,6 +370,72 @@
</tp:possible-errors>
</method>
+ <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time">
+ <tp:added version="0.19.6">
+ At the time of writing, no released implementation of the
+ Channel Dispatcher implements this method; clients should fall
+ back to calling <tp:member-ref>HandleWith</tp:member-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the
+ approver to pass an user action time. This timestamp will be passed
+ to the Handler when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ is called.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel, or the empty string
+ if the client has no preferred channel handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is non-empty, but is not a syntactically
+ correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
<signal name="Finished" tp:name-for-bindings="Finished">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when this dispatch operation finishes. The dispatch
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index daee24c9..474c809f 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -164,7 +164,7 @@
</arg>
<arg direction="in" name="User_Action_Time" type="x"
- tp:type="Unix_Timestamp64">
+ tp:type="User_Action_Timestamp">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.
@@ -305,7 +305,7 @@
</arg>
<arg direction="in" name="User_Action_Time" type="x"
- tp:type="Unix_Timestamp64">
+ tp:type="User_Action_Timestamp">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.</p>
diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml
new file mode 100644
index 00000000..7477f963
--- /dev/null
+++ b/spec/Channel_Interface_Anonymity.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Anonymity"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for requesting the anonymity modes of a channel
+ (as defined in Connection.Interface.Anonymity.DRAFT).</p>
+ </tp:docstring>
+
+ <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+ access="read" tp:name-for-bindings="Anonymity_Modes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The list of initially requested anonymity modes on the channel. This
+ MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityMandatory" type="b" access="read"
+ tp:name-for-bindings="Anonymity_Mandatory">
+ <tp:docstring>
+ Whether or not the anonymity settings are required for this channel.
+ This MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymousID" type="s" access="read"
+ tp:name-for-bindings="Anonymous_ID">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This is the ID that the remote user of the channel MAY see
+ (assuming there's a single ID). For example, for SIP connections
+ where the From address has been scrambled by the CM, the scrambled
+ address would be available here for the client to see. This is
+ completely optional, and MAY be an empty string ("") in
+ cases where anonymity modes are not set, or the CM doesn't know
+ what the remote contact will see, or any other case where this
+ doesn't make sense.</p>
+
+ <p>This MAY change over the lifetime of the channel, and SHOULD NOT
+ be used with the Request interface.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml
index 7545ff6f..bd20f6ed 100644
--- a/spec/Channel_Interface_DTMF.xml
+++ b/spec/Channel_Interface_DTMF.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" ?>
<node name="/Channel_Interface_DTMF" 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-2010 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
@@ -21,31 +21,57 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF">
<tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An interface that gives a Channel the ability to send DTMF events over
+ audio streams which have been established using the StreamedMedia channel
+ type. The event codes used are in common with those defined in <a
+ href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
+ listed in the <tp:type>DTMF_Event</tp:type> enumeration.
+ </tp:docstring>
+
<method name="StartTone" tp:name-for-bindings="Start_Tone">
<arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
- <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the tone SHOULD be sent to all
+ eligible streams in the channel.</tp:docstring>
</arg>
<arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
<tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
</arg>
+
<tp:docstring>
- Start sending a DTMF tone on this stream. Where possible, the tone
- will continue until <tp:member-ref>StopTone</tp:member-ref> is called.
- On certain protocols, it may
- only be possible to send events with a predetermined length. In this
- case, the implementation may emit a fixed-length tone, and the StopTone
- method call should return NotAvailable.
+ <p>Start sending a DTMF tone to all eligible streams in the channel.
+ Where possible, the tone will continue until
+ <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols,
+ it may only be possible to send events with a predetermined length. In
+ this case, the implementation MAY emit a fixed-length tone, and the
+ StopTone method call SHOULD return NotAvailable.</p>
+ <tp:rationale>
+ The client may wish to control the exact duration and timing of the
+ tones sent as a result of user's interaction with the dialpad, thus
+ starting and stopping the tone sending explicitly.
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
- The given stream ID was invalid.
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
- The requested event is not available on this stream.
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
</tp:docstring>
</tp:error>
</tp:possible-errors>
@@ -53,28 +79,136 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<method name="StopTone" tp:name-for-bindings="Stop_Tone">
<arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
- <tp:docstring>A stream ID as defined in the StreamedMedia channel type.</tp:docstring>
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the sending SHOULD be stoped in
+ all eligible streams in the channel.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Stop sending any DTMF tones which have been started using the
+ <tp:member-ref>StartTone</tp:member-ref> or
+ <tp:member-ref>MultipleTones</tp:member-ref> methods.
+ If there is no current tone, this method will do nothing.
+ If MultipleTones was used, the client should not assume the
+ sending has stopped immediately; instead, the client should wait
+ for the StoppedTones signal.
+ <tp:rationale>
+ On some protocols it might be impossible to cancel queued tones
+ immediately.
+ </tp:rationale>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Continuous tones are not supported by this stream. Deprecated,
+ since stream IDs are ignored.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones">
+ <tp:added version="0.19.6" />
+ <arg direction="in" name="Tones" type="s">
+ <tp:docstring>A string representation of one or more DTMF
+ events.</tp:docstring>
</arg>
<tp:docstring>
- Stop sending any DTMF tone which has been started using the
- <tp:member-ref>StartTone</tp:member-ref>
- method. If there is no current tone, this method will do nothing.
+ <p>Send multiple DTMF events to all eligible streams in the channel.
+ Each character in the Tones string must be a valid DTMF event
+ (as defined by
+ <a href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>).
+ Each tone will be played for a pre-defined number of milliseconds,
+ followed by a pause before the next tone is played. The
+ duration/pause is defined by the protocol or connection manager.</p>
+ <tp:rationale>
+ In cases where the client knows in advance the tone sequence it wants
+ to send, it's easier to use this method than manually start and stop
+ each tone in the sequence.
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
- The given stream ID was invalid.
+ The supplied Tones string was invalid.
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
- Continuous tones are not supported by this stream.
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
+ <property name="CurrentlySendingTones"
+ tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ Indicates whether there are DTMF tones currently being sent in the
+ channel. If so, the client should wait for
+ <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to
+ send more tones.
+ </tp:docstring>
+ </property>
+
+ <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
+ type="s" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ <p>If non-empty in a channel request that will create a new channel,
+ the connection manager should send the tones immediately after
+ at least one eligible audio stream has been created in the
+ channel.</p>
+
+ <p>This property is immutable (cannot change).</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="SendingTones" tp:name-for-bindings="Sending_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Tones" type="s">
+ <tp:docstring>DTMF string (one or more events) that is to be played.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tone(s)are being sent to all eligible streams in the channel.
+ The signal is provided to indicating the fact that the streams are
+ currently being used to send one or more DTMF tones, so any other
+ media input is not getting through to the audio stream. It also
+ serves as a cue for the
+ <tp:member-ref>StopTone</tp:member-ref> method.</p>
+ </tp:docstring>
+ </signal>
+
+ <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Cancelled" type="b">
+ <tp:docstring>True if the DTMF tones were actively cancelled via
+ <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tones have finished playing on streams in this channel.</p>
+ </tp:docstring>
+ </signal>
+
<tp:enum name="DTMF_Event" type="y">
<tp:enumvalue suffix="Digit_0" value="0">
<tp:docstring>0</tp:docstring>
@@ -125,15 +259,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:docstring>D</tp:docstring>
</tp:enumvalue>
</tp:enum>
-
- <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- An interface that gives a Channel the ability to send DTMF events over
- audio streams which have been established using the StreamedMedia channel
- type. The event codes used are in common with those defined in <a
- href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
- listed in the <tp:type>DTMF_Event</tp:type> enumeration.
- </tp:docstring>
-
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 566e1166..b3363354 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -314,6 +314,10 @@ USA.</p>
<dd>The contact who sent the message. If 0 or omitted, the contact
who sent the message could not be determined.</dd>
+ <dt>sender-nickname (s)</dt>
+ <dd>The nickname chosen by the sender of the message, which can be
+ different for each message in a conversation.</dd>
+
<dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>)
</dt>
<dd>The type of message; if omitted,
diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml
new file mode 100644
index 00000000..5a0d540e
--- /dev/null
+++ b/spec/Channel_Interface_Service_Point.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels
+ that can indicate when/if they are connected to some form
+ of service point. For example, when
+ dialing 9-1-1 in the US, a GSM modem/network will recognize that as
+ an emergency call, and inform higher levels of the stack that the
+ call is being handled by an emergency service. In this example,
+ the call is handled by a Public Safety Answering Point (PSAP) which is labeled
+ as "urn:service:sos". Other networks and protocols may handle this
+ differently while still using this interface.</p>
+
+ <p>Note that while the majority of examples given in this
+ documentation are for GSM calls, they could just as easily be
+ SIP calls, GSM SMS's, etc.</p>
+ </tp:docstring>
+
+ <property name="InitialServicePoint" tp:name-for-bindings="Initial_Service_Point"
+ type="(us)" tp:type="Service_Point" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This property is used to indicate that the channel target is a
+ well-known service point. Please note that the CM (or lower layers
+ of the stack or network) may forward the connection to other other
+ service points, which the CM SHOULD indicate via
+ <tp:member-ref>ServicePointChanged</tp:member-ref>
+ signal.</p>
+
+ <p>This property SHOULD be set for channel requests that are
+ specifically targeting service points.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CurrentServicePoint" tp:name-for-bindings="Current_Service_Point"
+ type="(us)" tp:type="Service_Point" access="read">
+ <tp:docstring>
+ The service point that the channel is connected to. If the channel is
+ not connected to any service points, the CM MUST set the
+ <tp:type>Service_Point_Type</tp:type> field to None.
+ </tp:docstring>
+ </property>
+
+ <signal name="ServicePointChanged" tp:name-for-bindings="Service_Point_Changed">
+ <tp:docstring>
+ <p>Emitted when a channel changes the service point that it's connected to. This
+ might be a new call being connected to a service, a call connected to
+ a service being routed to a different service
+ (ie, an emergency call being routed from a generic emergency PSAP to
+ a poison control PSAP), or any number of other things.</p>
+
+ <p>Note that this should be emitted as soon as the CM has been notified
+ of the switch, and has updated its internal state. The CM MAY still
+ be in the process of connecting to the new service point.</p>
+ </tp:docstring>
+
+ <arg name="ServicePoint" type="(us)" tp:type="Service_Point">
+ <tp:docstring>
+ The new service point that is being used.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 4de78b40..1d59eb87 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -55,14 +55,11 @@
</property>
<property name="UserActionTime" tp:name-for-bindings="User_Action_Time"
- type="x" tp:type="Unix_Timestamp64" access="read">
+ type="x" tp:type="User_Action_Timestamp" access="read">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The time at which user action occurred, or 0 if this channel
request is for some reason not involving user action.</p>
- <p>This corresponds to the _NET_WM_USER_TIME property in
- <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
-
<p>This property is set when the channel request is created,
and can never change.</p>
</tp:docstring>
diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml
index dacf906b..f1d0f0e0 100644
--- a/spec/Channel_Type_Call.xml
+++ b/spec/Channel_Type_Call.xml
@@ -381,6 +381,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:rationale>
</tp:docstring>
</tp:flag>
+
+ <tp:flag suffix="Muted" value="64">
+ <tp:docstring>
+ The call has been muted by the local user, e.g. using the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Call.Content.Interface"
+ >Mute.DRAFT</tp:dbus-ref> interface. This flag SHOULD only be set if
+ there is at least one Content, and all Contents are locally muted;
+ it makes sense on calls in state Call_State_Pending_Receiver or
+ Call_State_Accepted.
+ </tp:docstring>
+ </tp:flag>
</tp:flags>
<property name="CallStateDetails"
@@ -477,6 +488,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
rejected as busy, kicked from a conference by a moderator, etc.).</p>
</tp:docstring>
</tp:enumvalue>
+
+ <tp:enumvalue suffix="Forwarded" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The call was forwarded. If known, the handle of the contact
+ the call was forwarded to will be indicated by the Actor member
+ of a <tp:type>Call_State_Reason</tp:type> struct.</p>
+ </tp:docstring>
+ </tp:enumvalue>
</tp:enum>
<tp:struct name="Call_State_Reason">
@@ -557,7 +576,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</tp:docstring>
</arg>
- <arg name="Call_State_Reason" type="(uus)">
+ <arg name="Call_State_Reason" type="(uus)" tp:type="Call_State_Reason">
<tp:docstring>
The new value of the <tp:member-ref>CallStateReason</tp:member-ref>
property.
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index c6edf337..10a16bd6 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -106,6 +106,14 @@
matches closely related Text channels by their Bundle property.
(This is use-case dis5)</p>
</tp:rationale>
+
+ <p>For service-activatable handlers, this property should be specified
+ in the handler's <tt>.client</tt> file as follows:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Handler]
+BypassApproval=true
+</pre>
</tp:docstring>
</property>
@@ -264,6 +272,8 @@ org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264=true
is to be handled for some reason not involving user action.
Handlers SHOULD use this for focus-stealing prevention,
if applicable.
+ This property has the same semantic as <tp:type>User_Action_Timestamp</tp:type>
+ but is unsigned for historical reasons.
</tp:docstring>
</arg>
diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml
index f777a2a9..f4c11087 100644
--- a/spec/Client_Interface_Requests.xml
+++ b/spec/Client_Interface_Requests.xml
@@ -119,9 +119,11 @@
properties as possible, given that constraint.</p>
<p>In particular, the properties <tp:dbus-ref
- namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>
- and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">Requests</tp:dbus-ref>,
+ <tp:dbus-ref
namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref>
MUST be included.</p>
</tp:docstring>
</arg>
diff --git a/spec/Client_Observer.xml b/spec/Client_Observer.xml
index a2256a75..912edaf4 100644
--- a/spec/Client_Observer.xml
+++ b/spec/Client_Observer.xml
@@ -194,9 +194,17 @@ org.freedesktop.Telepathy.Channel.Requested b=true
its <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></p>
- <p>When activatable client having this property disappears from the bus
- and there are channels matching its ObserverChannelFilter,
- ObserveChannels will be called immediately to reactivate it again.</p>
+ <p>When an activatable client having this property disappears from the
+ bus and there are channels matching its ObserverChannelFilter,
+ ObserveChannels will be called immediately to reactivate it
+ again. Such clients should specify this property in their
+ <tt>.client</tt> file as follows:</p>
+
+<pre>
+[org.freedesktop.Telepathy.Client.Observer]
+Recover=true
+</pre>
+
<tp:rationale>
<p>This means that if an activatable Observer crashes, it will
be restarted as soon as possible; while there is an unavoidable
@@ -212,8 +220,8 @@ org.freedesktop.Telepathy.Channel.Requested b=true
</tp:rationale>
<p>When the ObserveChannels method is called due to observer recovery,
- the "Observer_Info" dictionary will contain one extra item with key
- "recovering" and boolean value of True.</p>
+ the <var>Observer_Info</var> dictionary will contain one extra item
+ mapping the key <code>"recovering"</code> to <code>True</code>.</p>
</tp:docstring>
</property>
@@ -336,8 +344,11 @@ org.freedesktop.Telepathy.Channel.Requested b=true
<dl>
<dt><code>recovering</code> - b</dt>
- <dd>True if ObserveChannels was called on existing channel due to
- observer recovery, otherwise False.
+ <dd><code>True</code> if ObserveChannels was called for an existing
+ channel (due to the <tp:member-ref>Recover</tp:member-ref>
+ property being <code>True</code>); <code>False</code> or omitted
+ otherwise.
+
<tp:rationale>
This allows observers to distinguish between new channels (the normal
case), and existing channels that were given to the observer in order
diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml
new file mode 100644
index 00000000..5426b5d5
--- /dev/null
+++ b/spec/Connection_Interface_Anonymity.xml
@@ -0,0 +1,170 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Anonymity"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Anonymity.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface to support anonymity settings on a per-connection basis.
+ This defines what personal identifying information a remote contact
+ may or may not see. For example, GSM might use this for CLIR, while
+ SIP might use this for privacy service requests.</p>
+ </tp:docstring>
+
+ <tp:flags name="Anonymity_Mode_Flags" value-prefix="Anonymity_Mode" type="u">
+ <tp:docstring>
+ <p>Flags for the various types of anonymity modes. These modes are solely to
+ inform the CM of the desired anonymous settings. It is up to the
+ CM to determine whether the anonymity modes should be handled within
+ the CM itself, or whether the network that a CM might be talking to
+ should be enforcing anonymity.</p>
+
+ <p>CMs MAY support only a subset of these modes, and specific
+ connections MAY support none at all.</p>
+ </tp:docstring>
+
+ <tp:flag value="1" suffix="Client_Info">
+ <tp:docstring>
+ <p>Obscure any information that provides user identification,
+ user-agent identification or personal details. Examples of this
+ information might be GSM CallerID, SIP from address, various
+ informational email headers, etc.</p>
+
+ <p>The CM should scrub/replace any of this information before
+ passing messages or data onto the network. Note that a CM which
+ has the option of obscuring the information at the CM or privacy
+ service level would choose both (anonymity services are opaque
+ to clients of this interface).</p>
+
+ <p>Clients SHOULD NOT set both Client_Info and ShowClient_Info modes.
+ If they are set, the CM MUST respect Client_Info and ignore
+ Show_Client_Info.</p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag value="2" suffix="Show_Client_Info">
+ <tp:docstring>
+ <p>Explicitly request showing of client information. In connection
+ context, this can be used to override service default. In channel
+ context, this overrides connection anonymity modes.</p>
+ <tp:rationale>
+ In GSM, it's possible to have CLIR enabled by default, and
+ explicitly suppress CLIR for a single phone call.
+ </tp:rationale>
+
+ <p>Clients SHOULD NOT set both Client_Info and Show_Client_Info modes.
+ If they are set, the CM MUST respect Client_Info and ignore
+ ShowClientInfo. The CM MAY set both Client_Info and Show_Client_Info
+ in <tp:member-ref>SupportedAnonymityModes</tp:member-ref> to indicate
+ its support for explicitly hiding and publicising client information.
+ </p>
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag value="4" suffix="Network_Info">
+ <tp:docstring>
+ <p>Obscure any originating IP address information, contact URIs,
+ and anonymize all traffic involved with sending/receiving any
+ media streams or call content.
+ Examples of this include the "headers" portions of
+ <a href="http://www.rfc-editor.org/rfc/rfc3323.txt">RFC 3323</a> as
+ well as the History-Info (described in
+ <a href="http://www.rfc-editor.org/rfc/rfc4244.txt">RFC 4244</a>)
+ for a SIP CM.</p>
+
+ <p>This SHOULD have the effect of hiding address information from
+ the remote contact (ie, the contact cannot know what IP address
+ the session is originated from). Obviously the network still needs
+ to be able to route information between contacts, so this provides
+ no guarantees of what can be seen by intermediaries.</p>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="SupportedAnonymityModes" type="u" access="read"
+ tp:type="Anonymity_Mode_Flags" tp:name-for-bindings="Supported_Anonymity_Modes">
+ <tp:docstring>
+ The anonymity modes supported by the CM for this connection. Once
+ Connection.Status has moved to Connected, this property MUST NOT change.
+ </tp:docstring>
+ </property>
+
+ <property name="Mandatory" type="b" access="readwrite"
+ tp:name-for-bindings="Mandatory">
+ <tp:docstring>
+ <p>This specifies whether or not the anonymity settings MUST be respected
+ by the CM and any intermediaries between the local and remote contacts.
+ If this is set to true but anonymity settings cannot be followed, then
+ the session MUST be denied with a
+ <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> error.
+ Any client that sets <tp:member-ref>AnonymityModes</tp:member-ref>
+ SHOULD also set this property first (rather than accepting the CM's
+ default value).</p>
+
+ <p>This property can also be set using a connection parameter in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
+ see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+ access="readwrite" tp:name-for-bindings="Anonymity_Modes">
+ <tp:docstring>
+ <p>The currently enabled anonymity modes for the connection. Setting
+ has the effect of requesting new modes for the connection, and may
+ raise an error if the unsupported modes are set. Successfully changing
+ the modes will result in emmision of
+ <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p>
+
+ <p>This property can also be set using a connection parameter in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>,
+ see <tp:type>Conn_Mgr_Param_Flags</tp:type> for more information.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ An unsupported mode was supplied. Supported modes are specified
+ in the SupportedAnonymityModes property, and this should be
+ checked prior to setting AnonymityModes.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </property>
+
+ <signal name="AnonymityModesChanged"
+ tp:name-for-bindings="Anonymity_Modes_Changed">
+ <tp:docstring>
+ Emitted when the anonymity mode has changed.
+ </tp:docstring>
+
+ <arg name="Modes" type="u" tp:type="Anonymity_Mode_Flags">
+ <tp:docstring>
+ The new anonymity modes for this connection.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml
index 10d8102f..56f92317 100644
--- a/spec/Connection_Interface_Capabilities.xml
+++ b/spec/Connection_Interface_Capabilities.xml
@@ -231,7 +231,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</method>
<tp:contact-attribute name="caps"
- type="a(usuu)" tp:type="Contact_Capability">
+ 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>
diff --git a/spec/Connection_Interface_Cellular.xml b/spec/Connection_Interface_Cellular.xml
new file mode 100644
index 00000000..c2a25503
--- /dev/null
+++ b/spec/Connection_Interface_Cellular.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Cellular"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Cellular.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface is for various cellular things (GSM and/or CDMA) things that
+ aren't really applicable to other protocols.</p>
+ </tp:docstring>
+
+ <property name="MessageValidityPeriod" tp:name-for-bindings="Message_Validity_Period"
+ type="u" access="readwrite">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Define how long should the service centre try message delivery before
+ giving up, failing delivery and deleting the message. A value of 0 means
+ to use the service centre's default period.</p>
+ <p>The value specified is in seconds. Note that various protocols or
+ implementations may round the value up (eg. to a minute or hour
+ precision). The maximum validity period may vary depending on
+ protocol or provider.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="MessageServiceCentre" tp:name-for-bindings="Message_Service_Centre"
+ type="s" access="readwrite">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Address for the messaging service centre. Typically (as is the case
+ for GSM's SMSC), it's the ISDN / telephony address (ie. a phone number).
+ </tp:docstring>
+ </property>
+
+ <property name="IMSI" tp:name-for-bindings="IMSI" type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The International Mobile Subscriber Identifier, if it exists. This
+ would originate from a SIM card. If the IMSI is unknown, this will
+ contain an empty string ("").</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="IMSIChanged" tp:name-for-bindings="IMSI_Changed">
+ <tp:docstring>
+ Emitted when the IMSI for the connection changes. This sort of thing
+ is rare, but could happen on cellular phones that allow hot-swapping
+ of SIM cards. In the case of SIM swapping, this signal would be
+ emitted twice; the first time while the SIM is being ejected (with an
+ empty string), and the second time after a new SIM has been inserted
+ (assuming that the IMSI can be determined from the new SIM).
+ </tp:docstring>
+
+ <arg name="IMSI" type="s">
+ <tp:docstring>
+ The new IMSI value. This may be an empty string in the case where
+ the IMSI is being reset or removed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Groups.xml b/spec/Connection_Interface_Contact_Groups.xml
new file mode 100644
index 00000000..35465a76
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Groups.xml
@@ -0,0 +1,412 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Groups" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactGroups.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"/>
+ <tp:added version="0.19.6">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections in which contacts can be placed in
+ user-defined groups.</p>
+ </tp:docstring>
+
+ <property name="DisjointGroups" tp:name-for-bindings="Disjoint_Groups"
+ access="read" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if each contact can be in at most one group; false if each
+ contact can be in many groups.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="GroupStorage" tp:name-for-bindings="Group_Storage"
+ type="u" tp:type="Contact_Metadata_Storage_Type" access="read">
+ <tp:docstring>
+ <p>Indicates the extent to which contacts' groups can be set and
+ stored.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:contact-attribute name="groups" type="as">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The names of groups of which a contact is a member.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>GroupsChanged</tp:member-ref>,
+ <tp:member-ref>GroupRenamed</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <property name="Groups" type="as" access="read"
+ tp:name-for-bindings="Groups">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The names of all groups that currently exist. This may be a
+ larger set than the union of all contacts' <code>groups</code>
+ contact attributes, if the connection allows groups to be
+ empty.</p>
+
+ <p>Change notification is via
+ <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupRenamed</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="GroupsCreated" tp:name-for-bindings="Groups_Created">
+ <tp:docstring>
+ Emitted when new, empty groups are created. This will often be
+ followed by <tp:member-ref>GroupsChanged</tp:member-ref> signals that
+ add some members.
+ </tp:docstring>
+
+ <arg name="Names" type="as">
+ <tp:docstring>The names of the new groups.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="GroupRenamed" tp:name-for-bindings="Group_Renamed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a group is renamed. If the group was not empty,
+ immediately after this signal is emitted,
+ <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ that the members of that group were removed from the old name
+ and added to the new name.</p>
+
+ <p>On connection managers where groups behave like tags, this signal
+ will probably only be emitted when
+ <tp:member-ref>RenameGroup</tp:member-ref> is called, and renaming a
+ group from another client MAY be signalled as a
+ <tp:member-ref>GroupsChanged</tp:member-ref> signal instead.</p>
+
+ <tp:rationale>
+ <p>On protocols like XMPP, another resource "renaming a group" is
+ indistinguishable from changing contacts' groups individually.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Old_Name" type="s">
+ <tp:docstring>The old name of the group.</tp:docstring>
+ </arg>
+
+ <arg name="New_Name" type="s">
+ <tp:docstring>The new name of the group.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="GroupsRemoved" tp:name-for-bindings="Groups_Removed">
+ <tp:docstring>
+ Emitted when one or more groups are removed. If they had members at
+ the time that they were removed, then immediately after this signal is
+ emitted, <tp:member-ref>GroupsChanged</tp:member-ref> MUST signal
+ that their members were removed.
+ </tp:docstring>
+
+ <arg name="Names" type="as">
+ <tp:docstring>The names of the groups.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="GroupsChanged" tp:name-for-bindings="Groups_Changed">
+ <tp:docstring>
+ Emitted when contacts' groups change.
+ </tp:docstring>
+
+ <arg name="Contact" type="au" tp:type="Contact_Handle">
+ <tp:docstring>The relevant contacts.</tp:docstring>
+ </arg>
+
+ <arg name="Added" type="as">
+ <tp:docstring>The names of groups to which the contacts were
+ added.</tp:docstring>
+ </arg>
+
+ <arg name="Removed" type="as">
+ <tp:docstring>The names of groups from which the contacts were
+ removed.</tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetContactGroups" tp:name-for-bindings="Set_Contact_Groups">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given contact to the given groups (creating new groups
+ if necessary), and remove them from all other groups.</p>
+
+ <tp:rationale>
+ <p>This is the easiest and most correct way to implement user
+ interfaces that display a single contact with a list of groups,
+ resulting in a user expectation that when they apply the changes,
+ the contact's set of groups will become exactly what was
+ displayed.</p>
+ </tp:rationale>
+
+ <p>If the user is removed from a group of which they were the only
+ member, the group MAY be removed automatically.</p>
+
+ <tp:rationale>
+ <p>In protocols like XMPP where groups behave like tags, a group
+ with no members has no protocol representation.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
+ <tp:docstring>The contact to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Groups" type="as" direction="in">
+ <tp:docstring>The set of groups which the contact should be
+ in.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>Raised if <tp:member-ref>DisjointGroups</tp:member-ref>
+ is true and the list of groups has more than one
+ member.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="SetGroupMembers" tp:name-for-bindings="Set_Group_Members">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given members to the given group (creating it if necessary),
+ and remove all other members.</p>
+
+ <tp:rationale>
+ <p>This is the easiest and most correct way to implement user
+ interfaces that display a single group with a list of contacts,
+ resulting in a user expectation that when they apply the changes,
+ the groups's set of members will become exactly what was
+ displayed.</p>
+ </tp:rationale>
+
+ <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
+ this will also remove each member from their previous group.</p>
+
+ <p>If the user is removed from a group of which they were the only
+ member, the group MAY be removed automatically.</p>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members for the group. If this set is
+ empty, this method MAY remove the group.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="AddToGroup" tp:name-for-bindings="Add_To_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Add the given members to the given group, creating it if
+ necessary.</p>
+
+ <p>If <tp:member-ref>DisjointGroups</tp:member-ref> is true,
+ this will also remove each member from their previous group.</p>
+
+ <tp:rationale>
+ <p>This is good for user interfaces in which you can edit groups
+ via drag-and-drop.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsCreated</tp:member-ref>,
+ <tp:member-ref>GroupsChanged</tp:member-ref> and
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members to include in the group.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveFromGroup" tp:name-for-bindings="Remove_From_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove the given members from the given group.</p>
+
+ <tp:rationale>
+ <p>This is good for user interfaces in which you can edit groups
+ via drag-and-drop.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to alter. If it does not exist, then it has
+ no members by definition, so this method SHOULD return
+ successfully.</tp:docstring>
+ </arg>
+
+ <arg name="Members" type="au" tp:type="Contact_Handle[]" direction="in">
+ <tp:docstring>The set of members to remove from the group. It is not
+ an error to remove members who are already not in the group.
+ If there are no members left in the group afterwards, the group MAY
+ itself be removed.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveGroup" tp:name-for-bindings="Remove_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove all members from the given group, then remove the group
+ itself. If the group already does not exist, this method SHOULD
+ return successfully.</p>
+
+ <p>Any <tp:member-ref>GroupsChanged</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Group" type="s" direction="in">
+ <tp:docstring>The group to remove.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RenameGroup" tp:name-for-bindings="Rename_Group">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Rename the given group.</p>
+
+ <p>On protocols where groups behave like tags, this is an API
+ short-cut for adding all of the group's members to a group with
+ the new name, then removing the old group.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients can't perform this operation atomically, even
+ if the connection could.</p>
+ </tp:rationale>
+
+ <p>Any <tp:member-ref>GroupRenamed</tp:member-ref> or
+ <tp:member-ref>GroupsRemoved</tp:member-ref> signals that result from
+ this method call MUST be emitted before the method returns.</p>
+ </tp:docstring>
+
+ <arg name="Old_Name" type="s" direction="in">
+ <tp:docstring>The group to rename.</tp:docstring>
+ </arg>
+
+ <arg name="New_Name" type="s" direction="in">
+ <tp:docstring>The new name for the group.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised if <tp:member-ref>GroupStorage</tp:member-ref>
+ is Contact_Metadata_Storage_Type_None, i.e. groups cannot be edited.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.DoesNotExist">
+ <tp:docstring>Raised if there is no group with that
+ name.</tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>Raised if there is already a group with the new
+ name.</tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index 91a948e6..ce77a56a 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -504,6 +504,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
network traffic.</p>
</tp:rationale>
</tp:docstring>
+
+ <tp:contact-attribute name="info"
+ type="a(sasas)" tp:type="Contact_Info_Field[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The same value that would be returned by
+ <tp:member-ref>GetContactInfo</tp:member-ref> for this contact.
+ Omitted from the result if the contact's info
+ is not known.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml
new file mode 100644
index 00000000..3ded8708
--- /dev/null
+++ b/spec/Connection_Interface_Contact_List.xml
@@ -0,0 +1,837 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+ <tp:added version="0.19.6">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections that have any concept of a list of
+ known contacts (roster, buddy list, friends list etc.)</p>
+
+ <tp:rationale>
+ <p>On many protocols, there's a server-side roster (as in XMPP),
+ or a set of server-side lists that can be combined to form a
+ roster (as in MSN).</p>
+
+ <p>In some protocols (like link-local XMPP), while there might not be
+ any server or roster, it's possible to list "nearby" contacts.</p>
+
+ <p>In Telepathy 0.18 and older, we represented contact lists as a
+ collection of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type"
+ >ContactList</tp:dbus-ref> channels. This is remarkably difficult to
+ work with in practice - every client that cares about contact lists
+ has to take the union of some hard-to-define set of these
+ channels - and conflicts with the idea that channels that cannot
+ be dispatched to a handler should be closed.</p>
+ </tp:rationale>
+
+ <p>The list of contacts is not exposed as a D-Bus property; it can be
+ fetched using <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ </p>
+
+ <tp:rationale>
+ <p>In some protocols, such as XMPP, the contact list may not be
+ available immediately. The
+ <tp:member-ref>GetContactListAttributes</tp:member-ref> method
+ will wait until the contact list is available before returning.
+ Using a method also allows extra attributes to be retrieved at
+ the same time.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <method name="GetContactListAttributes"
+ tp:name-for-bindings="Get_Contact_List_Attributes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Return some contact attributes for a list of contacts somehow
+ associated with the user.</p>
+
+ <p>This definition is deliberately vague: in practice, most user
+ interfaces should display some subset of this list, by filtering it
+ by some contact attributes (for instance, displaying all contacts
+ whose "subscribe" attribute is Yes is expected to be a common case).
+ This list MAY contain any contacts whatsoever, but MUST contain
+ at least the following:</p>
+
+ <ul>
+ <li>all contacts whose "subscribe" attribute is Ask or Yes</li>
+ <li>all contacts whose "publish" attribute is Ask or Yes</li>
+ <li>all contacts with a persistently-stored stored alias, if
+ supported</li>
+ <li>all contacts in user-defined contact groups, if supported</li>
+ </ul>
+
+ <p>This list does not need to contain every visible contact: for
+ instance, contacts seen in XMPP or IRC chatrooms SHOULD NOT appear
+ here. Blocked contacts SHOULD NOT appear here either, unless they
+ are still stored in a persistent roster/contact list as well as
+ being blocked.</p>
+
+ <tp:rationale>
+ <p>This is basically the union of the historical <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type"
+ >ContactList</tp:dbus-ref> subscribe, publish and stored
+ channels.</p>
+
+ <p>For example, XMPP, it's the roster; on link-local XMPP, it's the
+ set of visible users on the local network; on MSN, it's the union
+ of the forward and reverse buddy lists.</p>
+
+ <p>An easy way for an application to display a contact list is to
+ call this method with at least this interface in the Interfaces
+ argument, then check which subset of contacts should be displayed
+ (perhaps based on their subscribe attribute, for instance) and display
+ them. Any additional information required to display the contact
+ list, like aliases or presence, can be retrieved at the same
+ time.</p>
+
+ <p>In practice, most user interfaces for the contact list will
+ usually display a large proportion of this list
+ (for instance, most contacts on the contact list will usually
+ have subscribe=Yes in practice, so contact lists that display
+ subscribe=Yes contacts need to display almost the entire list),
+ so the overhead of returning information about too many contacts
+ is small.</p>
+ </tp:rationale>
+
+ <p>This method SHOULD NOT return before the contact list has been
+ retrieved, on protocols where this is possible. As a result,
+ clients SHOULD use a longer-than-default timeout for this method
+ call, since retrieving the contact list can take a significant
+ time on some servers.</p>
+
+ <tp:rationale>
+ <p>This makes it possible for clients to wait for the contact list.
+ For instance, on XMPP this method shouldn't return until the
+ roster has been retrieved, which is an asynchronous process.
+ However, on link-local XMPP you can't know when you have the
+ complete list, so this method would have to return immediately.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Interfaces" type="as"
+ tp:type="DBus_Interface[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of strings indicating which D-Bus interfaces the calling
+ process is interested in. Equivalent to the corresponding argument
+ to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Hold" type="b">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Whether to hold the handles on behalf of the calling process.
+ Equivalent to the corresponding argument to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref>.</p>
+
+ <p><em>FIXME: if we do distributed refcounting, we should probably
+ rename this to 'Reference' and implement handle-refcounting
+ semantics first? On the other hand, if we make handles persist
+ for the lifetime of the connection, we can just remove this
+ parameter.</em></p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" type="a{ua{sv}}" name="Attributes"
+ tp:type="Contact_Attributes_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary mapping the contact handles to contact attributes,
+ equivalent to the result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts"
+ >GetContactAttributes</tp:dbus-ref>.</p>
+
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:enum name="Presence_State" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A tristate indicating whether presence subscription is denied,
+ denied but pending permission, or allowed. The exact semantics
+ vary according to where this type is used.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="No" value="0">
+ <tp:docstring>Presence information cannot be seen.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Ask" value="1">
+ <tp:docstring>Presence information cannot be seen, but permission
+ to see presence information has been requested.</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Yes" value="2">
+ <tp:docstring>Presence information can be seen.</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:contact-attribute name="subscribe"
+ type="u" tp:type="Presence_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If this attribute on a contact is Yes, this connection can
+ expect to receive their presence, along with any other information
+ that has the same access control.</p>
+
+ <tp:rationale>
+ <p>This is subscription="from" or subscription="both" in XMPP,
+ the "forward list" on MSN, or the contact being "added to
+ the local user's buddy list" in ICQ, for example.</p>
+ </tp:rationale>
+
+ <p>If this attribute is No or Ask, the local user cannot generally
+ expect to receive presence from this contact. Their presence status
+ as returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">GetPresences</tp:dbus-ref>
+ is likely to be (Unknown, "unknown", ""), unless the local user
+ can temporarily see their presence for some other reason (for
+ instance, on XMPP, contacts seen in chatrooms will temporarily
+ have available presence).</p>
+
+ <p>If this attribute is Ask, this indicates that the local user has
+ asked to receive the contact's presence at some time. It is
+ implementation-dependent whether contacts' subscribe attributes
+ can remain set to Ask, or are reset to No, when the connection
+ disconnects.</p>
+
+ <tp:rationale>
+ <p>Some protocols store the fact that we wishes to see a contact's
+ presence; on these protocols, this attribute can remain Ask
+ indefinitely. On other protocols, only contacts who have been
+ asked during the current session will ever have Ask status.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="publish"
+ type="u" tp:type="Presence_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If this attribute on a contact is Yes, the local user's presence
+ is published to that contact, along with any other information that
+ shares an access-control mechanism with presence (depending on
+ protocol, server configuration and/or user configuration, this may
+ include avatars, "rich presence" such as location, etc.).</p>
+
+ <tp:rationale>
+ <p>This is subscription="to" or subscription="both" in XMPP,
+ the "reverse list" on MSN, or the state of "being added to
+ the contact's buddy list" in ICQ, for example.</p>
+ </tp:rationale>
+
+ <p>If this attribute is No or Ask, the
+ local user's presence is not published to that contact; however,
+ if it is Ask, the contact has requested that the local user's
+ presence is made available to them.</p>
+
+ <p>It is implementation-dependent whether contacts' publish
+ attributes can remain set to Ask, or are reset to No, when the
+ connection disconnects.</p>
+
+ <tp:rationale>
+ <p>Some protocols store the fact that a contact wishes to see our
+ presence; on these protocols, this attribute can remain Ask
+ indefinitely. On other protocols, only contacts who have asked
+ during the current session will ever have Ask status.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <tp:contact-attribute name="publish-request" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the "publish" attribute is Ask, an optional message that was
+ sent by the contact asking to receive the local user's presence;
+ omitted if none was given.</p>
+
+ <tp:rationale>
+ <p>If the contact asking to receive our presence is also using
+ Telepathy, this is the message they supplied as the Message
+ argument to <tp:member-ref>RequestSubscription</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>Otherwise, this SHOULD be omitted.</p>
+ </tp:docstring>
+ </tp:contact-attribute>
+
+ <property name="SubscriptionsPersist"
+ tp:name-for-bindings="Subscriptions_Persist" type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, presence subscriptions (in both directions) on this
+ connection are stored by the server or other infrastructure.</p>
+
+ <tp:rationale>
+ <p>XMPP, MSN, ICQ, etc. all behave like this.</p>
+ </tp:rationale>
+
+ <p>If false, presence subscriptions on this connection are not
+ stored.</p>
+
+ <tp:rationale>
+ <p>In SIMPLE (SIP), <em>clients</em> are expected to keep a record
+ of subscriptions, as described below. In link-local XMPP,
+ subscriptions are implicit (everyone on the local network receives
+ presence from everyone else) so nothing is ever stored.</p>
+ </tp:rationale>
+
+ <p>If <tp:member-ref>CanChangeSubscriptions</tp:member-ref>
+ is true, Telepathy clients (e.g. user interfaces or address books)
+ MAY keep a record of permission to publish and requests to subscribe
+ locally, and attempt to restore it for each Connection. If
+ SubscriptionsPersist is false, clients MAY do this for all contacts;
+ if SubscriptionsPersist is true, clients SHOULD NOT change the state
+ of contacts that were not changed locally.</p>
+
+ <tp:rationale>
+ <p>In SIMPLE (SIP), SubscriptionsPersist is false, but
+ CanChangeSubscriptions is true. Presence will not be received
+ unless clients renew any subscriptions they have for each
+ connection, in the way described. There is no server-side storage,
+ so clients have no alternative but to maintain independent contact
+ lists.</p>
+
+ <p>In protocols like XMPP and MSN, it may be useful for clients to
+ queue up subscription requests or removals made while offline and
+ process them next time the connection is online. However, clients
+ should only replay the changes, rather than resetting the contact
+ list to match a stored copy, to avoid overwriting changes that
+ were made on the server.</p>
+ </tp:rationale>
+
+ <p>Clients that replay requests like this SHOULD do so by calling
+ AuthorizePublication to pre-approve publication of presence to the
+ appropriate contacts, followed by RequestSubscription to request the
+ appropriate contacts' presences.</p>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Contact_Metadata_Storage_Type" type="u">
+ <tp:docstring>
+ Values of this enumeration indicate the extent to which metadata
+ such as aliases and group memberships can be stored for the contacts
+ on a particular connection.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This connection cannot store this type of metadata at all, and
+ attempting to do so will fail with NotImplemented.</p>
+
+ <tp:rationale>
+ <p>Link-local XMPP can't store aliases or group memberships at
+ all, and subscription and presence states are implicit (all
+ contacts on the local network have subscribe = publish = Yes
+ and no other contacts exist).</p>
+
+ <p>As of April 2010, the XMPP server for Facebook Chat provides a
+ read-only view of the user's Facebook contacts, so it could also
+ usefully have this storage type.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Subscribed_Or_Pending" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This type of metadata can only be stored permanently for contacts
+ whose subscribe attribute is Ask or Yes.</p>
+
+ <tp:rationale>
+ <p>Contact aliases and groups on MSN have this behaviour.</p>
+ </tp:rationale>
+
+ <p>If this type of metadata is set on a contact with subscribe=No,
+ the Connection MUST cache it until disconnected, and return it
+ if requested. If subscription to the contact's presence is
+ subsequently requested, making it possible to store this metadata,
+ the Connection MUST store the cached value at that time.</p>
+
+ <tp:rationale>
+ <p>This supports the recommended calling pattern for adding a
+ new contact, in which alias and groups are set (without
+ necessarily waiting for a reply) before requesting the
+ contact's presence. Until the subscription request is
+ processed by the server, the alias and groups will be cached
+ in memory; when the subscription request has been processed,
+ the connection manager will store the metadata on the server.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Subscribed" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This type of metadata can only be stored permanently for contacts
+ whose subscribe attribute is Yes.</p>
+
+ <tp:rationale>
+ <p>No service with this behaviour is currently known, but it's a
+ stricter form of Subscribed_Or_Pending.</p>
+ </tp:rationale>
+
+ <p>If this type of metadata is set on a contact with subscribe != Yes,
+ the Connection MUST cache it until disconnected, and return it
+ if requested. If subscription to the contact's presence is
+ subsequently allowed, making it possible to store this metadata,
+ the Connection MUST store the cached value at that time.</p>
+
+ <tp:rationale>
+ <p>The same rationale applies as for Subscribed_Or_Pending,
+ except that metadata must be stored until the subscription
+ request is not only processed by the server, but also allowed
+ by the remote user.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Anyone" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The user can set this metadata for any valid contact identifier,
+ whether or not they have any presence subscription relationship
+ to it, and it will be stored on their contact list.</p>
+
+ <tp:rationale>
+ <p>Contact aliases and groups on XMPP have this behaviour; it
+ is possible to put a contact in a group, or assign an alias
+ to them, without requesting that presence be shared.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Contact_Subscriptions" array-name="">
+ <tp:docstring>
+ A single contact's subscribe, publish and publish-request attributes.
+ </tp:docstring>
+
+ <tp:member name="Subscribe" type="u" tp:type="Presence_State">
+ <tp:docstring>
+ The new value of the contact's "subscribe" attribute.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Publish" type="u" tp:type="Presence_State">
+ <tp:docstring>
+ The new value of the contact's "publish" attribute.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Publish_Request" type="s">
+ <tp:docstring>
+ The new value of the contact's "publish-request" attribute,
+ or the empty string if that attribute would be omitted.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Contact_Subscription_Map" array-name="">
+ <tp:docstring>
+ A map from contacts to their subscribe, publish and publish-request
+ attributes.
+ </tp:docstring>
+
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact's handle.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="States" type="(uus)" tp:type="Contact_Subscriptions">
+ <tp:docstring>
+ The contact's subscribe, publish and publish-request attributes.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="ContactsChanged"
+ tp:name-for-bindings="Contacts_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the contact list becomes available, when contacts'
+ basic stored properties change, when new contacts are added to the
+ list that would be returned by
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>,
+ or when contact are removed from that list.</p>
+
+ <tp:rationale>
+ <p>This provides change notification for that list, and for
+ contacts' "subscribe", "publish" and
+ "publish-request" attributes.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg type="a{u(uus)}" name="Changes" tp:type="Contact_Subscription_Map">
+ <tp:docstring>
+ The new subscribe, publish and publish-request attributes of all the
+ contacts that have been added, and all the contacts for which those
+ attributes have changed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Removals" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The contacts that have been removed from the list that would be
+ returned by
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.
+ This also implies that they have subscribe = No and publish = No;
+ contacts MUST NOT be listed both here and in Changes.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CanChangeSubscriptions" type="b" access="read"
+ tp:name-for-bindings="Can_Change_Subscriptions">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, presence subscription and publication can be changed
+ using the
+ <tp:member-ref>RequestSubscription</tp:member-ref>,
+ <tp:member-ref>AuthorizePublication</tp:member-ref> and
+ <tp:member-ref>RemoveContacts</tp:member-ref> methods.</p>
+
+ <p>If false, all of those methods will always fail; they SHOULD raise
+ the error org.freedesktop.Telepathy.Error.NotImplemented.</p>
+
+ <tp:rationale>
+ <p>In XEP-0174 "Serverless Messaging" (link-local XMPP), presence is
+ implicitly published to everyone in the local subnet, so the user
+ cannot control their presence publication.</p>
+ </tp:rationale>
+
+ <p>This property cannot change after the connection has moved to the
+ Connected state. Until then, its value is undefined, and it may
+ change at any time, without notification.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="RequestSubscription" tp:name-for-bindings="Request_Subscription">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given contacts allow the local user to
+ subscribe to their presence, i.e. that their subscribe attribute
+ becomes Yes.</p>
+
+ <p>Before calling this method on a connection where <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
+ >GetAliasFlags</tp:dbus-ref> returns the <code>User_Set</code> flag,
+ user interfaces SHOULD obtain, from the user, an alias to
+ identify the contact in future, and store it using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing"
+ >SetAliases</tp:dbus-ref>.
+
+ The user MAY be
+ prompted using the contact's current self-assigned nickname, or
+ something derived from the contact's (presumably self-assigned)
+ identifier, as a default, but these names chosen by the contact
+ SHOULD NOT be used without user approval.</p>
+
+ <tp:rationale>
+ <p>This is a generalization of
+ <a href="http://xmpp.org/extensions/xep-0165.html"
+ >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>)
+ to protocols other than XMPP. A reasonable user interface for
+ this, as used in many XMPP clients, is to have a text entry
+ for the alias adjacent to the text entry for the identifier
+ to add.</p>
+ </tp:rationale>
+
+ <p>For contacts with subscribe=Yes, this method has no effect.
+ It MUST return successfully if all contacts are in this state.</p>
+
+ <p>For contacts with subscribe=Ask, this method SHOULD send a new
+ request, with the given message, if allowed by the underlying
+ protocol.</p>
+
+ <p>For contacts with subscribe=No, this method SHOULD request that
+ the contact allows the local user to subscribe to their presence;
+ in general, this will change their publish attribute from No
+ to Ask (although it could change directly from No to Yes in some
+ situations).</p>
+
+ <p>Any state changes that immediately result from this request MUST
+ be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
+ before this method returns.</p>
+
+ <tp:rationale>
+ <p>This makes it easy for user interfaces to see what practical
+ effect this method had.</p>
+ </tp:rationale>
+
+ <p>If the remote contact accepts the request, their subscribe
+ attribute will later change from Ask to Yes; if they explicitly
+ reject the request (in protocols that allow this), their subscribe
+ attribute will later change from Ask to No.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to whom requests are to be sent.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An optional plain-text message from the user, to send to those
+ contacts with the subscription request. The
+ <tp:member-ref>RequestUsesMessage</tp:member-ref> property
+ indicates whether this message will be used or ignored.</p>
+
+ <p>Clients SHOULD NOT send a non-empty message without first giving
+ the user an opportunity to edit it.</p>
+
+ <tp:rationale>
+ <p>These messages are typically presented to the remote contact
+ as if the user had typed them, so as a minimum, the user should be
+ allowed to see what the UI will be saying on their behalf.</p>
+ </tp:rationale>
+
+ <p>Connections where this message is not useful MUST still allow it to
+ be non-empty.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action, because
+ <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="RequestUsesMessage" type="b" access="read"
+ tp:name-for-bindings="Request_Uses_Message">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, the Message parameter to
+ <tp:member-ref>RequestSubscription</tp:member-ref> is likely to be
+ significant, and user interfaces SHOULD prompt the user for a
+ message to send with the request; a message such as "I would like
+ to add you to my contact list", translated into the local user's
+ language, might make a suitable default.</p>
+
+ <tp:rationale>
+ <p>This matches user expectations in XMPP and ICQ, for instance.</p>
+ </tp:rationale>
+
+ <p>If false, the parameter is ignored; user interfaces SHOULD avoid
+ prompting the user, and SHOULD pass an empty string to
+ RequestSubscription.</p>
+
+ <tp:rationale>
+ <p><em>FIXME: is there any such protocol?</em></p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="AuthorizePublication"
+ tp:name-for-bindings="Authorize_Publication">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>For each of the given contacts, request that the local user's
+ presence is sent to that contact, i.e. that their publish attribute
+ becomes Yes.</p>
+
+ <p>For contacts with publish=Yes, this method has no effect; it
+ MUST return successfully if all contacts given have this state.</p>
+
+ <p>For contacts with publish=Ask, this method accepts the
+ contact's request to see the local user's presence, changing
+ their publish attribute from Ask to Yes.</p>
+
+ <p>For contacts with publish=No, if the protocol allows it, this
+ method allows the contacts to see the local user's presence even
+ though they have not requested it, changing their publish attribute
+ from No to Yes. Otherwise, it merely records the fact that
+ presence publication to those contacts is allowed; if any of
+ those contacts ask to receive the local user's presence
+ later in the lifetime of the connection, the connection SHOULD
+ immediately allow them to do so, changing their publish
+ attribute directly from No to Yes.</p>
+
+ <tp:rationale>
+ <p>This makes it easy to implement the common UI policy that if
+ the user attempts to subscribe to a contact's presence, requests
+ for reciprocal subscription are automatically approved.</p>
+ </tp:rationale>
+
+ <p>Any state changes that immediately result from this request MUST
+ be signalled via <tp:member-ref>ContactsChanged</tp:member-ref>
+ before this method returns.</p>
+
+ <tp:rationale>
+ <p>This makes it easy for user interfaces to see what practical
+ effect this method had.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to authorize.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action, because
+ <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveContacts" tp:name-for-bindings="Remove_Contacts">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Remove the given contacts from the contact list entirely. It is
+ protocol-dependent whether this works, and under which
+ circumstances.</p>
+
+ <p>If possible, this method SHOULD set the contacts' subscribe and
+ publish attributes to No, remove any stored aliases for those
+ contacts, and remove the contacts from the result of
+ <tp:member-ref>GetContactListAttributes</tp:member-ref>.</p>
+
+ <p>This method SHOULD succeed even if it was not possible to carry out
+ the request entirely or for all contacts (for instance, if there is an
+ outstanding request to subscribe to the contact's presence, and it's
+ not possible to cancel such requests). However, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns, so that clients can interpret the result.</p>
+
+ <tp:rationale>
+ <p>User interfaces removing a contact from the contact list are
+ unlikely to want spurious failure notifications resulting from
+ limitations of a particular protocol. However, emitting the
+ signals first means that if a client does want to check exactly
+ what happened, it can wait for the method to return (while
+ applying change-notification signals to its local cache of the
+ contact list's state), then consult its local cache of the
+ contact list's state to see whether the contact is still there.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Unsubscribe" tp:name-for-bindings="Unsubscribe">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to set the given contacts' subscribe attribute to No,
+ i.e. stop receiving their presence.</p>
+
+ <p>For contacts with subscribe=Ask, this attempts to cancel
+ an earlier request to subscribe to the contact's presence; for
+ contacts with subscribe=Yes, this attempts to
+ unsubscribe from the contact's presence.</p>
+
+ <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
+ SHOULD succeed even if it was not possible to carry out the request
+ entirely or for all contacts; however, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Unpublish" tp:name-for-bindings="Unpublish">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Attempt to set the given contacts' publish attribute to No,
+ i.e. stop sending presence to them.</p>
+
+ <p>For contacts with publish=Ask, this method explicitly rejects the
+ contact's request to subscribe to the user's presence; for
+ contacts with publish=Yes, this method attempts to prevent the
+ user's presence from being received by the contact.</p>
+
+ <p>As with <tp:member-ref>RemoveContacts</tp:member-ref>, this method
+ SHOULD succeed even if it was not possible to carry out the request
+ entirely or for all contacts; however, all signals that
+ immediately result from this method call MUST be emitted before it
+ returns.</p>
+ </tp:docstring>
+
+ <arg name="Contacts" direction="in"
+ type="au" tp:type="Contact_Handle[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more contacts to remove.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It was not possible to perform the requested action because
+ <tp:member-ref>CanChangeSubscriptions</tp:member-ref> is false.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Forwarding.xml b/spec/Connection_Interface_Forwarding.xml
index 73051f4b..4c1c1193 100644
--- a/spec/Connection_Interface_Forwarding.xml
+++ b/spec/Connection_Interface_Forwarding.xml
@@ -1,78 +1,335 @@
<?xml version="1.0" ?>
-<node name="/Connection_Interface_Forwarding" 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>
+<node name="/Connection_Interface_Forwarding"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT </tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.</p>
-
-<p>This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-Lesser General Public License for more details.</p>
-
-<p>You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
</tp:license>
- <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding"
- tp:causes-havoc='not well-tested'>
- <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
- <signal name="ForwardingChanged" tp:name-for-bindings="Forwarding_Changed">
- <arg name="Forward_To" type="u" tp:type="Contact_Handle">
+
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This connection interface is for protocols that are capable of
+ signaling to remote contacts that incoming communication channels
+ should be instead sent to a separate contact. This might apply to
+ things such as call forwarding, for example.</p>
+
+ <p>In some cases, a CM may register forwarding rules with an external
+ service; in those cases, it will never see the incoming channel, and
+ the forwarding will happen automatically.</p>
+
+ <p>In other cases, the CM will handle the forwarding itself. When an
+ incoming channel is detected, the status of the local user will
+ determine whether or not a forwarding rule is matched. For some
+ rules, this MAY happen immediately (ie, if the user is Busy); for
+ others, there MAY be a timeout (in seconds) that must expire
+ before the forwarding rule is matched (the timeout is specified
+ by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p>
+
+ <p>Once a forwarding rule is matched and any necessary timeouts have
+ expired, the CM can forward the incoming channel to the specified
+ handle. If for whatever reason the remote handle does not accept
+ the channel AND the CM supports multiple forwarding entries AND
+ any necessary timeouts have expired (specified by the next entry
+ in the list), the CM can forward the incoming channel to the next
+ handle in the entry list. This continues until the list is
+ exhausted, or the incoming channel is accepted.</p>
+
+ <p>Note that the rule matches are only for the first entry in the
+ in the forwarding rule list. Once the incoming channel has been
+ forwarded, the next entry in the list (assuming one exists and
+ the contact that the channel has been forwarded to does not respond
+ after any necessary timeouts) is used regardless of the status of
+ the forwarded channel. The initial match rule might have been
+ Busy, whereas the contact that the channel has been forwarded to
+ might be offline. Even in this case, the Busy list is still
+ traversed until the channel is handled (or there are no more
+ forwarding entries in the list).</p>
+
+ <p>For example, assuming the following dict for Forwarding_Rules:</p>
+ <pre>
+ ForwardingRules = {
+ Busy: ( initial-timeout: 30, [
+ (handle: 3, timeout: 15),
+ (handle: 5, timeout: 20)
+ ]),
+ NoReply: ( initial-timeout: 15, [
+ (handle: 5, timeout: 30),
+ (handle: 3, timeout: 20)
+ ])
+ }</pre>
+
+ <p>We can imagine a scenario where an incoming channel is detected,
+ the media stream is available (ie, not Busy),
+ and the local user is online. While the CM is waiting for the local user to
+ accept the channel, it looks at NoReply's first timeout value. After 15s if
+ the local user hasn't accepted, the CM forwards the channel to Handle #5. The
+ CM then waits 30s for Handle #5 to accept the channel. If after 30s it does
+ not, the CM forwards the incoming channel to Handle #3, which will have
+ 20s to accept the channel.</p>
+ </tp:docstring>
+
+ <tp:enum name="Forwarding_Condition" type="u">
+ <tp:docstring>
+ The various forwarding conditions that are supported by this interface.
+ In general, the conditions should not overlap; it should be very clear
+ which rule would be chosen given a CM's behavior with an incoming
+ channel. The exception to this is Unconditional,
+ which will override all other rules.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="Unconditional">
<tp:docstring>
- An integer contact handle to forward communication to
+ Incoming channels should always be forwarded. Note that setting this
+ will override any other rules. If not set, other rules will
+ be checked when an incoming communication channel is detected.
</tp:docstring>
- </arg>
- <tp:docstring>
- Emitted when the forwarding contact handle for this connection has been
- changed. An zero handle indicates forwarding is disabled.
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Busy">
+ <tp:docstring>
+ <p>The incoming channel should be forwarded if a busy signal is
+ detected. What defines "Busy" is CM-specific (perhaps a single
+ resource is already in use, or a user's status is set to Busy
+ <tp:type>Connection_Presence_Type</tp:type>).</p>
+ <p>If initial timeout is specified for Busy condition and call
+ waiting is not supported by the service, the timeout will be
+ ignored.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="No_Reply">
+ <tp:docstring>
+ The incoming channel should be forwarded if the local user doesn't
+ accept it within the specified amount of time.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="3" suffix="Not_Reachable">
+ <tp:docstring>
+ The incoming channel should be forwarded if the user is offline.
+ This could be a manual setting (the user has chosen to set their
+ presence to offline or invisible) or something specified by the
+ underlying network (the user is not within range of a cell tower).
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:struct name="Forwarding_Rule_Entry"
+ array-name="Forwarding_Rule_Entry_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A forwarding rule entry. These MAY be chained together
+ for CMs that support chaining of forwards (in other words,
+ a forwarding rule may have multiple entries; if the contact
+ in the first entry doesn't respond, the incoming channel
+ might be forwarded to the contact in the second entry).</p>
+
+ <p>For CMs and protocols that don't support chaining of
+ entries, only the first entry would be used.</p>
</tp:docstring>
- </signal>
- <method name="GetForwardingHandle"
- tp:name-for-bindings="Get_Forwarding_Handle">
- <arg direction="out" type="u" tp:type="Contact_Handle">
+
+ <tp:member type="u" name="Timeout">
<tp:docstring>
- An integer contact handle to whom incoming communication is forwarded
+ <p>The length of time (in seconds) to wait the contact to respond
+ to the forwarded channel. This MAY be ignored by the CM if it
+ isn't supported by the underlying network/protocol for the
+ specific status of the remote contact (for example, a GSM call
+ that is forwarded may return Not_Reachable immediately without
+ waiting for the timeout value to expire).</p>
+ <p>A value of 0 means the condition can match immediately. A
+ value of MAX_UINT32 means that the CM's default should be
+ used.</p>
</tp:docstring>
- </arg>
+ </tp:member>
+
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle">
+ <tp:docstring>
+ The contact to forward an incoming channel to. If the handle
+ doesn't point to anything (e.g. points to a phone number that
+ doesn't exist), the entry SHOULD be skipped.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:struct name="Forwarding_Rule_Chain">
<tp:docstring>
- Returns the current forwarding contact handle, or zero if none is set.
+ A chain of forwarding rules and an initial timeout after which
+ the rules are applied.
</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>
- <method name="SetForwardingHandle"
- tp:name-for-bindings="Set_Forwarding_Handle">
- <arg direction="in" name="Forward_To" type="u" tp:type="Contact_Handle">
+
+ <tp:member type="u" name="InitialTimeout">
+ <tp:docstring>Initial timeout for the rule.</tp:docstring>
+ </tp:member>
+
+ <tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>The forwarding targets (an array of type
+ <tp:type>Forwarding_Rule_Entry</tp:type>).
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Forwarding_Rule_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are forwarding conditions and
+ whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs.
+ </tp:docstring>
+
+ <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
+ <tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain"
+ name="Rule_Chain" />
+ </tp:mapping>
+
+ <tp:mapping name="Supported_Forwarding_Conditions_Map" array-name="">
+ <tp:docstring>A dictionary whose keys are forwarding conditions and
+ whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
+ for the condition.
+ </tp:docstring>
+ <tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
+ <tp:member type="u" name="Chain_Length" />
+ </tp:mapping>
+
+ <property name="SupportedForwardingConditions" type="a{uu}" access="read"
+ tp:type="Supported_Forwarding_Conditions_Map"
+ tp:name-for-bindings="Supported_Forwarding_Conditions">
+ <tp:docstring>
+ <p>
+ A map of forwarding conditions supported on this connection to
+ maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
+ supported for the specific condition.
+ <tp:rationale>
+ When forwarding is done by the provider, different providers
+ might support different chain sizes, or provider and local
+ implementation chain sizes might differ.
+ </tp:rationale>
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="ForwardingRules" type="a{u(ua(uu))}" access="read"
+ tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules">
+ <tp:docstring>
+ <p>The current forwarding rules that are enabled for this connection.
+ Forwarding rules each contain an array of type
+ <tp:type>Forwarding_Rule_Entry</tp:type>.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ForwardingRuleChanged"
+ tp:name-for-bindings="Forwarding_Rule_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p>
+
+ <p>By the time this is emitted, the property MUST have been updated
+ with the new rules being active. If any protocol/network
+ requests must be made, they should be completed before the signal
+ is emitted.</p>
+ </tp:docstring>
+
+ <arg name="Condition" type="u" tp:type="Forwarding_Condition">
+ <tp:docstring>
+ The condition of the forwarding rule that's been changed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Timeout" type="u">
+ <tp:docstring>
+ The new initial timeout for the rule.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
<tp:docstring>
- An integer contact handle to forward incoming communications to
+ The new (and as of the emission of the signal, currently active)
+ forwards. The order is relevant; those at the lowest array index
+ are used first.
</tp:docstring>
</arg>
+ </signal>
+
+ <method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule">
<tp:docstring>
- Set a contact handle to forward incoming communications to. A zero
- handle disables forwarding.
+ Update the forwarding rules.
</tp:docstring>
+
+ <arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition">
+ <tp:docstring>
+ <p>The forwarding rule to override. Note that this SHOULD not affect
+ other rules; setting a rule that overrides others (such as
+ Forwarding_Rule_Unconditional) will not modify other rules. This
+ means that when a client sets Forwarding_Rule_Busy and then
+ temporarily sets Forwarding_Rule_Unconditional, the
+ Forwarding_Rule_Busy rule will retain settings after
+ Forwarding_Rule_Unconditional, has been unset.</p>
+
+ <p>If the CM has no choice but to adjust multiple rules after a call
+ to this function (ie, due to the network or protocol forcing such
+ behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref>
+ signals for each changed rule. The order of the signals is
+ implementation-dependent, with the only requirement that the
+ last signal is for the rule that was originally requested to have
+ been changed (e.g. if Unconditional automatically modifies
+ Busy and NoReply, three
+ separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the
+ last signal being for Forwarding_Rule_Unconditional).</p>
+
+ <p>Each forwarding condition will occur no more than once in
+ the rule array. Setting a rule will overwrite the old rule
+ with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>
+ The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to
+ activate for the rule. An empty array will effectively disable the
+ rule.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
+ <tp:docstring>
+ The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>).
+ This is the list of entries that is being replaced with the call to
+ <tp:member-ref>SetForwardingRule</tp:member-ref>.
+ </tp:docstring>
+ </arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
- <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
- <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The specified Condition is not supported by this connection,
+ or the number of chained
+ <tp:member-ref>SupportedForwardingConditions</tp:member-ref> should
+ be checked prior to calling
+ <tp:member-ref>SetForwardingRule</tp:member-ref>.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
+ <tp:docstring>
+ A Handle that has been supplied is invalid.
+ </tp:docstring>
+ </tp:error>
</tp:possible-errors>
</method>
- <tp:docstring>
- A connection interface for services which can signal to contacts
- that they should instead contact a different user ID, effectively
- forwarding all incoming communication channels to another contact on
- the service.
- </tp:docstring>
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Location.xml b/spec/Connection_Interface_Location.xml
index fdc622ea..6c69a80c 100644
--- a/spec/Connection_Interface_Location.xml
+++ b/spec/Connection_Interface_Location.xml
@@ -365,7 +365,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
- <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The user's server does not support publishing their own location.
+ If it is possible to determine this ahead of time, the
+ <code>Can_Set</code> flag will not be set in
+ <tp:member-ref>SupportedLocationFeatures</tp:member-ref>.
+ </tp:docstring>
+ </tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
@@ -385,6 +392,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
supported).</tp:docstring>
</property>
+ <property name="SupportedLocationFeatures"
+ tp:name-for-bindings="Supported_Location_Features"
+ type="u" tp:type="Location_Features" access="read">
+ <tp:added version="0.19.6"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Indicates the Location features supported by this connection. This
+ property MAY be undefined before <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref>
+ becomes <code>Connected</code>, but MUST remain constant thereafter.
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature">
+ <tp:flag suffix="Can_Set" value="1">
+ <tp:docstring>
+ Indicates that setting your own location with
+ <tp:member-ref>SetLocation</tp:member-ref> is supported on this
+ connection.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Flags describing the Location features which may be supported on any
+ given connection.
+ </tp:docstring>
+ </tp:flags>
+
<tp:contact-attribute name="location"
type="a{sv}" tp:type="Location">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml
index c74dd59f..cfe67a8f 100644
--- a/spec/Connection_Interface_Mail_Notification.xml
+++ b/spec/Connection_Interface_Mail_Notification.xml
@@ -159,9 +159,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:struct>
<tp:struct name="Mail_Address" array-name="Mail_Address_List">
- <tp:docstring>
- A pair (name, address) representing an e-mail address,
- such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk").
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A pair (name, address) representing an e-mail address,
+ such as ("Nicolas Dufresne", "nicolas.dufresne@collabora.co.uk"). At
+ least one of name and address MUST be provided. A missing element will
+ be represented by the empty string.</p>
+ <tp:rationale>
+ <p>The CM should provide as much information as possible, but not all
+ protocols provide both the displayed name and the address. (If a
+ protocol doesn't provide either, it should omit the appropriate
+ field from the <tp:type>Mail</tp:type> entirely.)</p>
+ </tp:rationale>
</tp:docstring>
<tp:member type="s" name="Name">
<tp:docstring>The displayed name corresponding to the e-mail
diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml
new file mode 100644
index 00000000..b0b34b67
--- /dev/null
+++ b/spec/Connection_Interface_Service_Point.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Service_Point" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Connection.Interface.ServicePoint.DRAFT" tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for connections whose channels may be able to indicate
+ specific they are connected to some form
+ of service station. For example, when
+ dialing 9-1-1 in the US, a GSM modem/network will recognize that as
+ an emergency call, and inform higher levels of the stack that the
+ call is being handled by an emergency service. In this example,
+ the call is handled by a Public Safety Answering Point (PSAP) which is labeled
+ as "urn:service:sos". Other networks and protocols may handle this
+ differently while still using this interface.</p>
+ </tp:docstring>
+
+ <tp:struct name="Service_Point_Info" array-name="Service_Point_Info_List">
+ <tp:member type="(us)" tp:type="Service_Point" name="ServicePoint">
+ <tp:docstring>
+ The service point.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="as" name="ServiceIDs">
+ <tp:docstring>
+ A list of IDs that are mapped to this service. This is provided as
+ a convenience for the UIs, but the preferred method for
+ requesting channel to a service is by setting <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint.DRAFT">InitialServicePoint</tp:dbus-ref>
+ property in channel request.
+ </tp:docstring>
+ </tp:member>
+ <tp:docstring>
+ <p>Description of a service point and IDs which are mapped to id.</p>
+
+ <p>An example Service Point info for GSM emergency calls (callable through
+ "911" and "112") could look like:</p>
+
+<pre>
+ ServicePointInfo = (
+ ServicePoint: (
+ ServicePointType: 1 (Emergency),
+ ServicePoint: "urn:service:sos"
+ ),
+ ServiceIDs: [ "911", "112" ]
+ )
+</pre>
+ </tp:docstring>
+ </tp:struct>
+
+ <property name="KnownServicePoints" tp:name-for-bindings="Known_Service_Points"
+ type="a((us)as)" tp:type="Service_Point_Info[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The list of all (known) service points.
+ </tp:docstring>
+ </property>
+
+ <signal name="ServicePointsChanged" tp:name-for-bindings="Service_Points_Changed">
+ <arg name="ServicePoints" type="a((us)as)" tp:type="Service_Point_Info[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The new list of service points.</p>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Indicate that the list of known service points (or their IDs) have
+ changed, presenting the new list.
+ </tp:docstring>
+ </signal>
+
+ <tp:struct name="Service_Point">
+ <tp:docstring>A service point.</tp:docstring>
+ <tp:member type="u" name="ServicePointType" tp:type="Service_Point_Type">
+ <tp:docstring>
+ The service type.
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Service">
+ <tp:docstring>
+ String representation of the service point. The representation is
+ service specific; it may be <tp:type>Uniform_Resource_Name</tp:type>
+ or may be in some other form. Empty, unused or unknown value is
+ represented by "".
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:enum name="Service_Point_Type" type="u">
+ <tp:docstring>
+ The various types of service points the channel might connect to.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="None">
+ <tp:docstring>
+ The service point is not used/available.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Emergency">
+ <tp:docstring>
+ The service point is a generic emergency point.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Counseling">
+ <tp:docstring>
+ The service point is some kind of counseling service (ie, mental health
+ or child-services counseling).
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:simple-type name="Uniform_Resource_Name" type="s">
+ <tp:docstring>Uniform Resource Name as specified by
+ <a href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>.</tp:docstring>
+ </tp:simple-type>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Makefile.am b/spec/Makefile.am
index 91f378c3..a1d08d29 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -5,6 +5,7 @@ EXTRA_DIST = \
all.xml \
Call_Content.xml \
Call_Content_Interface_Media.xml \
+ Call_Content_Interface_Mute.xml \
Call_Content_Codec_Offer.xml \
Call_Stream.xml \
Call_Stream_Interface_Media.xml \
@@ -14,6 +15,7 @@ EXTRA_DIST = \
Channel_Dispatcher_Interface_Operation_List.xml \
Channel_Future.xml \
Channel_Handler.xml \
+ Channel_Interface_Anonymity.xml \
Channel_Interface_Call_State.xml \
Channel_Interface_Chat_State.xml \
Channel_Interface_Conference.xml \
@@ -26,6 +28,7 @@ EXTRA_DIST = \
Channel_Interface_Mergeable_Conference.xml \
Channel_Interface_Messages.xml \
Channel_Interface_Password.xml \
+ Channel_Interface_Service_Point.xml \
Channel_Interface_Splittable.xml \
Channel_Interface_Transfer.xml \
Channel_Interface_Tube.xml \
@@ -49,11 +52,15 @@ EXTRA_DIST = \
Client_Observer.xml \
Connection_Future.xml \
Connection_Interface_Aliasing.xml \
+ Connection_Interface_Anonymity.xml \
Connection_Interface_Avatars.xml \
Connection_Interface_Balance.xml \
Connection_Interface_Capabilities.xml \
+ Connection_Interface_Cellular.xml \
Connection_Interface_Contact_Capabilities.xml \
+ Connection_Interface_Contact_Groups.xml \
Connection_Interface_Contact_Info.xml \
+ Connection_Interface_Contact_List.xml \
Connection_Interface_Contacts.xml \
Connection_Interface_Forwarding.xml \
Connection_Interface_Location.xml \
@@ -62,6 +69,7 @@ EXTRA_DIST = \
Connection_Interface_Privacy.xml \
Connection_Interface_Renaming.xml \
Connection_Interface_Requests.xml \
+ Connection_Interface_Service_Point.xml \
Connection_Interface_Simple_Presence.xml \
Connection_Manager.xml \
Connection.xml \
diff --git a/spec/all.xml b/spec/all.xml
index a5ea1c4d..591efb52 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.19.5</tp:version>
+<tp:version>0.19.6</tp:version>
<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
@@ -42,13 +42,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Connection.xml"/>
<xi:include href="Connection_Future.xml"/>
<xi:include href="Connection_Interface_Aliasing.xml"/>
+ <xi:include href="Connection_Interface_Anonymity.xml"/>
<xi:include href="Connection_Interface_Avatars.xml"/>
<xi:include href="Connection_Interface_Balance.xml"/>
<xi:include href="Connection_Interface_Capabilities.xml"/>
+ <xi:include href="Connection_Interface_Cellular.xml"/>
<xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
+ <xi:include href="Connection_Interface_Contact_Groups.xml"/>
<xi:include href="Connection_Interface_Contact_Info.xml"/>
+ <xi:include href="Connection_Interface_Contact_List.xml"/>
<xi:include href="Connection_Interface_Contacts.xml"/>
+ <xi:include href="Connection_Interface_Forwarding.xml"/>
<xi:include href="Connection_Interface_Location.xml"/>
+ <xi:include href="Connection_Interface_Service_Point.xml"/>
<xi:include href="Connection_Interface_Mail_Notification.xml"/>
<xi:include href="Connection_Interface_Presence.xml"/>
<xi:include href="Connection_Interface_Renaming.xml"/>
@@ -99,6 +105,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
depending on its type:
</p>
</tp:docstring>
+ <xi:include href="Channel_Interface_Anonymity.xml"/>
<xi:include href="Channel_Interface_Call_State.xml"/>
<xi:include href="Channel_Interface_Chat_State.xml"/>
<xi:include href="Channel_Interface_Conference.xml"/>
@@ -107,6 +114,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Interface_Group.xml"/>
<xi:include href="Channel_Interface_Hold.xml"/>
<xi:include href="Channel_Interface_HTML.xml"/>
+ <xi:include href="Channel_Interface_Service_Point.xml"/>
<xi:include href="Channel_Interface_Password.xml"/>
<xi:include href="Channel_Interface_Media_Signalling.xml"/>
<xi:include href="Channel_Interface_Mergeable_Conference.xml"/>
@@ -124,6 +132,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<tp:section name="Calls">
<xi:include href="Call_Content.xml"/>
<xi:include href="Call_Content_Interface_Media.xml"/>
+ <xi:include href="Call_Content_Interface_Mute.xml"/>
<xi:include href="Call_Content_Codec_Offer.xml"/>
<xi:include href="Call_Stream.xml"/>
<xi:include href="Call_Stream_Interface_Media.xml"/>
@@ -185,8 +194,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="errors.xml"/>
<xi:include href="generic-types.xml"/>
-<!-- Never implemented, insufficient (needs conditions)
-<xi:include href="Connection_Interface_Forwarding.xml"/> -->
<!-- Never implemented, vague
<xi:include href="Connection_Interface_Privacy.xml"/> -->
<!-- Causes havoc, never implemented, unclear requirements
diff --git a/spec/errors.xml b/spec/errors.xml
index 22a629ba..0137e776 100644
--- a/spec/errors.xml
+++ b/spec/errors.xml
@@ -1,5 +1,28 @@
<?xml version="1.0" ?>
<tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The D-Bus errors used in Telepathy all start with
+ <code>org.freedesktop.Telepathy.Error.</code>. They are used in
+ D-Bus messages of type ERROR, and also as plain strings annotated with
+ the <tp:type>DBus_Error_Name</tp:type> type.</p>
+
+ <p>In principle, any method can raise any error (this is a general fact
+ of IPC). For instance, generic D-Bus errors starting with
+ <code>org.freedesktop.DBus.Error.</code> will occur in some
+ situations.</p>
+
+ <p>Telepathy methods can also raise implementation-specific errors to
+ indicate specialized failure conditions. For better interoperability,
+ if a suitable Telepathy error exists, it should be preferred.</p>
+
+ <p>The namespace <code>org.freedesktop.Telepathy.Qt4.Error.</code>
+ is reserved for use by the D-Bus client implementation in telepathy-qt4,
+ which uses it to represent certain error situations that did not involve
+ a D-Bus ERROR message. These errors are defined and documented as part of
+ telepathy-qt4's C++ API, and should not be used on D-Bus.</p>
+ </tp:docstring>
+
<tp:error name="Network Error">
<tp:docstring>
Raised when there is an error reading from or writing to the network.
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index d4dce155..c017ba59 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -165,4 +165,34 @@
</tp:member>
</tp:struct>
+ <tp:simple-type name="User_Action_Timestamp" type="x">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which an user action occurred. This type has the 2
+ following special values:</p>
+
+ <p>0: the action doesn't involve any user action. Clients
+ SHOULD avoid stealing focus when presenting the channel.</p>
+
+ <p>MAX_INT64: clients SHOULD behave as though the user action happened
+ at the current time, e.g. a client MAY request that its window gains
+ focus.
+ </p>
+
+ <tp:rationale>
+ <p>This can be used by clients that can't know the X server time like
+ command line applications for example.</p>
+ </tp:rationale>
+
+ <p>For all the other values it corresponds to the time of the user
+ action. Clients SHOULD use this for focus-stealing prevention,
+ if applicable.
+ Note that the time is dependant on the local
+ environment and so is not necessarily a wall-clock time.
+ For example in an X environment it's expected to be the X timestamp
+ of events.
+ This corresponds to the _NET_WM_USER_TIME property in
+ <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
</tp:generic-types>