diff options
| author | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2010-08-05 16:57:46 +0200 |
|---|---|---|
| committer | Guillaume Desmottes <guillaume.desmottes@collabora.co.uk> | 2010-08-05 17:04:10 +0200 |
| commit | 683172645a65c805fa8197826c714d71d02a4c1c (patch) | |
| tree | ce41b272be473bfe715bb750ddda719ab6b406d1 | |
| parent | a7418e92965713edae61d9e762b8c895a68a7251 (diff) | |
Update to spec 0.19.10
42 files changed, 4825 insertions, 608 deletions
diff --git a/spec/Account.xml b/spec/Account.xml index 4b112cb..5917c6f 100644 --- a/spec/Account.xml +++ b/spec/Account.xml @@ -261,6 +261,53 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="Service" tp:name-for-bindings="Service" type="s" + access="readwrite"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some protocols, like XMPP and SIP, are used by various different + user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by + Nokia</i>. On accounts for such services, this property SHOULD be + set to a string describing the service, which MUST consist only of + ASCII letters, numbers and hyphen/minus signs, and start with a + letter (matching the requirements for <tp:type>Protocol</tp:type>). + For the <tt>jabber</tt> protocol, one of the following service names + should be used if possible:</p> + + <ul> + <li><tt>google-talk</tt> (for <a + href="http://www.google.com/talk/">Google's IM service</a>)</li> + <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM + service)</li> + <li><tt>facebook</tt> (for <a + href="http://www.facebook.com/sitetour/chat.php">Facebook's IM + service</a>)</li> + <li><tt>lj-talk</tt> (for <a + href="http://www.livejournal.com/chat/">LiveJournal's IM + service</a>)</li> + + </ul> + + <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a + corresponding brand-specific icon name, if possible. In the future, + this property may be used as an index into additional + service-specific customizations. If this property is the empty string + (or missing), the service is determined by the protocol name (either + because this is a single-service protocol like <tt>msn</tt>, or + because this is just a generic <tt>jabber</tt> or <tt>sip</tt> + account without specific branding).</p> + + <p>This property MAY be set, if appropriate, when calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.AccountManager" + >CreateAccount</tp:dbus-ref>. Updating this property will fail on + externally-stored accounts whose <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Storage" + >StorageRestrictions</tp:dbus-ref> include + <code>Cannot_Set_Service</code>.</p> + </tp:docstring> + </property> + <property name="Parameters" tp:name-for-bindings="Parameters" type="a{sv}" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -273,10 +320,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </p> <p>This property cannot be altered using Set() - use <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p> - - <tp:rationale> - This avoids NMC being tied to gconf as a matter of API. - </tp:rationale> </tp:docstring> </property> @@ -287,7 +330,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. <p>If any of the changed parameters' <tp:type>Conn_Mgr_Param_Flags</tp:type> include - <code>DBus_Property</code>, the change will be applied to the + <code>DBus_Property</code>, the change will be applied immediately to + the corresponding D-Bus Property on the active <tp:member-ref>Connection</tp:member-ref>, if there is one. Changes to other parameters will not take effect until the next time the account @@ -329,14 +373,25 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </arg> <arg name="Reconnect_Required" type="as" direction="out"> - <tp:docstring> - A list of the names of parameters with changes that will not take - effect until the account is reconnected (this may be empty, e.g. if - all the parameters are D-Bus properties or parameters for which the - account manager has specific support). User interfaces that - require "instant apply" semantics MAY call - <tp:member-ref>Reconnect</tp:member-ref> in response to receiving - a non-empty list. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If all of the parameters had the <code>DBus_Property</code> flag, + the empty list, signifying that no reconnection is required for the + new parameters to take effect. For example, if the only parameter + updated is <tt>...Cellular.<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>, + the new value can be applied immediately to the connection.</p> + + <p>Otherwise, a list of the names of parameters with changes that + will not take effect until the account is reconnected. User + interfaces that require "instant apply" semantics MAY call + <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a + non-empty list. For example, if the caller updates both + <tt>...Anonymity.<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt> + and <tt>require-encryption</tt>, the former can be applied to the + current connection, but the latter needs a reconnect to take + effect, so this method should return + <code>["require-encryption"]</code>.</p> </tp:docstring> </arg> @@ -405,8 +460,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="ConnectionStatus" type="u" access="read" - tp:name-for-bindings="Connection_Status"> + <property name="ConnectionStatus" type="u" tp:type="Connection_Status" + access="read" tp:name-for-bindings="Connection_Status"> <tp:docstring> If the <tp:member-ref>Connection</tp:member-ref> property is non-empty, the status of that connection. @@ -426,7 +481,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="ConnectionStatusReason" type="u" access="read" + <property name="ConnectionStatusReason" type="u" + tp:type="Connection_Status_Reason" access="read" tp:name-for-bindings="Connection_Status_Reason"> <tp:docstring> The reason for the last change to @@ -442,6 +498,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> + <property name="ConnectionError" tp:name-for-bindings="Connection_Error" + access="read" type="s" tp:type="DBus_Error_Name"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the last connection to this account failed with an error, + the D-Bus error name of that error; otherwise, the empty string. + The account manager is expected to set this by observing the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.ConnectionError</tp:dbus-ref> and + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.StatusChanged</tp:dbus-ref> + signals.</p> + + <p>If ConnectionError is received before the connection disconnects, + its first argument should be used to set this property; + otherwise, the Reason argument of StatusChanged should be converted + to a suitable D-Bus error name.</p> + + <p>Whenever the Connection connects successfully, this property should + be reset to the empty string.</p> + + <tp:rationale> + <p>This combines the state-recoverability of + <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the + extensibility of Connection.ConnectionError.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="ConnectionErrorDetails" + tp:name-for-bindings="Connection_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the last connection to this account failed with an error, + a mapping representing any additional information about the last + disconnection; otherwise, the empty map. The keys and values are + the same as for the second argument of + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>Whenever the Connection connects successfully, this property should + be reset to the empty map.</p> + + <tp:rationale> + <p>This combines the state-recoverability of + <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the + extensibility of Connection.ConnectionError.</p> + </tp:rationale> + </tp:docstring> + </property> + <property name="CurrentPresence" type="(uss)" access="read" tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence"> <tp:docstring> @@ -480,6 +588,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/Account_Interface_Storage.xml b/spec/Account_Interface_Storage.xml new file mode 100644 index 0000000..4e3ba5d --- /dev/null +++ b/spec/Account_Interface_Storage.xml @@ -0,0 +1,169 @@ +<?xml version="1.0" ?> +<node name="/Account_Interface_Storage" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 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.Account.Interface.Storage"> + <tp:requires interface="org.freedesktop.Telepathy.Account"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + This interface extends the core Account interface to specify details + regarding the storage of this account. + </p> + + <tp:rationale> + <p> + Single-sign-on systems do not generally have directly user-editable + properties for Accounts, and require the user to visit a specific UI + to alter their account properties. User interfaces should know not to + expose these account properties as user-editable, and instead + redirect the user to the appropriate interface. + </p> + </tp:rationale> + + </tp:docstring> + <tp:added version="0.19.8"/> + + <property name="StorageProvider" tp:name-for-bindings="Storage_Provider" + type="s" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + The name of the account storage implementation, which SHOULD start + with a reversed domain name in the same way as D-Bus interface names. + When this is the empty string the account is internally stored. + </p> + <p> + This property cannot change once an Account has been created. + </p> + </tp:docstring> + </property> + + <property name="StorageIdentifier" + tp:name-for-bindings="Storage_Identifier" type="v" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Unique identification of the account within the storage backend. + The contents of the variant are defined by the + <tp:member-ref>StorageProvider</tp:member-ref>. + </p> + <p> + This property cannot change once an Account has been created. + </p> + <tp:rationale> + <p> + Different storage systems will have their own way of uniquely + identifying an account, typically an integer or a string. + Given that all users of this property should have direct knowledge + of the backend they should know what types to expect and how to + handle it. + </p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="StorageSpecificInformation" + tp:name-for-bindings="Storage_Specific_Information" type="a{sv}" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Map containing information specific to the storage backend. The keys + and the types of their values are defined by the + <tp:member-ref>StorageProvider</tp:member-ref>, and are not + interpreted by the AccountManager implementation. + </p> + <p> + As the values in this map may change at any time (due to an external + application manipulating the storage provider directly), this + property should not be cached; it should instead be retrieved each + time it is needed. + </p> + + <tp:rationale> + <p> + This can be used to provide additional hints to user interfaces + aware of a specific storage provider, without requiring those user + interfaces to use the + <tp:member-ref>StorageIdentifier</tp:member-ref> to query the + storage provider directly. + </p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="StorageRestrictions" + tp:name-for-bindings="Storage_Restrictions" type="u" + tp:type="Storage_Restriction_Flags" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + Bitfield which defines what restrictions this Storage method has. + </p> + <p> + This property cannot change once an Account has been created. + </p> + </tp:docstring> + </property> + + <tp:flags name="Storage_Restriction_Flags" + value-prefix="Storage_Restriction_Flag" type="u"> + <tp:docstring> + Flags indicating restrictions imposed on an Account by its storage + method. + </tp:docstring> + + <tp:flag suffix="Cannot_Set_Parameters" value="1"> + <tp:docstring> + The account's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >Parameters</tp:dbus-ref> property can't be changed by calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Enabled" value="2"> + <tp:docstring> + The account can't be enabled/disabled by setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >Enabled</tp:dbus-ref> property. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Presence" value="4"> + <tp:docstring> + The account's presence can't be changed by setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account" + >AutomaticPresence</tp:dbus-ref> properties. + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Cannot_Set_Service" value="8"> + <tp:docstring> + The account's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref> + property cannot be changed. + </tp:docstring> + </tp:flag> + </tp:flags> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml index 2b3eb65..8b9a17c 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 0000000..eea724f --- /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.xml b/spec/Channel.xml index 0fedf68..897b683 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -451,7 +451,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ be implemented by all channel objects, along with one single channel type, such as <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref> - which represents a list of people (such as a buddy list) or a <tp:dbus-ref + which represents a list of people (such as a buddy list) or <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which represents a channel over which textual messages are sent and received.</p> @@ -472,31 +472,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ information, by taking the first 7 components.</p> </tp:rationale> - <p>Each channel may have an immutable handle associated with it, which - may be any handle type, such as a contact, room or list handle, - indicating that the channel is for communicating with that handle.</p> - - <p>If a channel does not have a handle (an "anonymous channel" with - Target_Handle = 0 and Target_Handle_Type = Handle_Type_None), it - means that the channel is defined by some other terms, such as it - may be a transient group defined only by its members as visible - through the <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> - interface.</p> - - <p>Other optional interfaces can be implemented to indicate other available + <p>Each channel has a number of immutable properties (which cannot vary + after the channel has been announced with <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>), + provided to clients in the + <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and + <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref> + methods to permit immediate identification of the channel. This interface + contains immutable properties common to all channels. In brief:</p> + + <ul> + <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of + communication carried out on this channel;</li> + <li><tp:member-ref>TargetHandleType</tp:member-ref>, + <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetID</tp:member-ref> specify the entity with which + this channel communicates, such as the other party in a 1-1 call, or + the name of a multi-user chat room;</li> + <li><tp:member-ref>InitiatorHandle</tp:member-ref> and + <tp:member-ref>InitiatorID</tp:member-ref> specify who created this + channel;</li> + <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local + user requested this channel, or whether it is an incoming call, a text + conversation started by a remote contact, a chatroom invitation, + etc.</li> + </ul> + + <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be + implemented to indicate other available functionality, such as <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> if the channel contains a number of contacts, <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref> to indicate that a channel may have a password set to require entry, and <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Properties</tp:dbus-ref> for - extra data about channels which represent chat rooms or voice calls. The - interfaces implemented may not vary after the channel's creation has been - signalled to the bus (with the connection's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref> - signal).</p> + namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref> + for typing notifications. The interfaces implemented may not vary after + the channel has been created. These other interfaces (along with the + interface named by <tp:member-ref>ChannelType</tp:member-ref>) may + themselves specify immutable properties to be announced up-front along + with the properties on this interface.</p> + + <p>Some channels are “anonymous”, with + <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>, + which indicates that the channel is defined by some other properties. For + instance, transient ad-hoc chat rooms may be defined only by their members (as visible + through the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface), and <tp:dbus-ref + namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref> + channels represent a single search attempt for a particular <tp:dbus-ref + namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p> <p>Specific connection manager implementations may implement channel types and interfaces which are not contained within this specification in order to diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml index 26d9b57..6ec69a6 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 daee24c..474c809 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 0000000..ef3a3b8 --- /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"> + <tp:added version="0.19.7">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Interface for requesting the anonymity modes of a channel + (as defined in <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.Interface.Anonymity</tp:dbus-ref>).</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_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml index 89ad6da..27515d2 100644 --- a/spec/Channel_Interface_Chat_State.xml +++ b/spec/Channel_Interface_Chat_State.xml @@ -19,6 +19,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Channel.Interface.ChatState"> <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/> + <tp:mapping name="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring>A map from contacts to their chat states.</tp:docstring> + <tp:member name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring>A contact</tp:docstring> + </tp:member> + <tp:member name="State" type="u" tp:type="Channel_Chat_State"> + <tp:docstring>The contact's chat state</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="ChatStates" tp:name-for-bindings="Chat_States" + access="read" type="a{uu}" tp:type="Chat_State_Map"> + <tp:added version="0.19.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map containing the chat states of all contacts in this + channel whose chat state is not Inactive.</p> + + <p>Contacts in this channel, but who are not listed in this map, + may be assumed to be in the Inactive state.</p> + + <p>In implementations that do not have this property, its value may be + assumed to be empty until a + <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates + otherwise.</p> + + <tp:rationale> + <p>This property was not present in older versions of telepathy-spec, + because chat states in XMPP are not state-recoverable (if you + miss the change notification signal, there's no way to know the + state). However, this property still allows clients to recover + state changes that were seen by the CM before the client started + to deal with the channel.</p> + + <p>In CMs that follow older spec versions, assuming Inactive will + mean that initial chat states will always be assumed to be + Inactive, which is the best we can do. XEP 0085 specifies + Inactive as the "neutral" state to be assumed unless told + otherwise.</p> + </tp:rationale> + </tp:docstring> + </property> + <method name="SetChatState" tp:name-for-bindings="Set_Chat_State"> <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State"> <tp:docstring> diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml index 2441a7d..92d962d 100644 --- a/spec/Channel_Interface_Conference.xml +++ b/spec/Channel_Interface_Conference.xml @@ -270,7 +270,7 @@ invited into the new channel, as if they had been added with <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface" >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles, - <tp:member-ref>InvitationMessage</tp:member-ref> immediately after + <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after the channel was created.</p> <tp:rationale> diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml index 7545ff6..bd20f6e 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_Group.xml b/spec/Channel_Interface_Group.xml index a3319bf..92de9c5 100644 --- a/spec/Channel_Interface_Group.xml +++ b/spec/Channel_Interface_Group.xml @@ -580,6 +580,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <tp:enum name="Channel_Group_Change_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for a set of handles to move to one of + <tp:member-ref>Members</tp:member-ref>, + <tp:member-ref>LocalPendingMembers</tp:member-ref> or + <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed + from the group. A client may supply a reason when attempting to + remove members from a group with + <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons + are supplied by the CM when emitting + <tp:member-ref>MembersChanged</tp:member-ref> and + <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason + codes have different meanings depending on the <var>Actor</var> in a + MembersChanged signal.</p> + </tp:docstring> + <tp:enumvalue suffix="None" value="0"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>No reason was provided for this change.</p> @@ -712,7 +727,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>If a one-to-one <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> - call fails because the contact being called did not respond, the + call fails because the contact being called did not respond, or the + local user did not respond to an incoming call, the connection manager SHOULD indicate this by removing both the <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's handle from the Group interface with reason No_Answer.</p> @@ -836,6 +852,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ channel-specific handles are added, but that it is emitted <em>after</em> emitting a MembersChanged signal in which channel-specific handles are removed.</p> + + <p>See <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + for an overview of how group state changes are used to indicate the + progress of a call.</p> </tp:docstring> </signal> @@ -963,6 +984,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ channel-specific handles are added, but that it is emitted <em>after</em> emitting a MembersChangedDetailed signal in which channel-specific handles are removed.</p> + + <p>See <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + for an overview of how group state changes are used to indicate the + progress of a call.</p> </tp:docstring> <tp:added version="0.17.16"/> </signal> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 566e116..d4fde0d 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -1,8 +1,8 @@ <?xml version="1.0" ?> <node name="/Channel_Interface_Messages" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright © 2008–2010 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 @@ -25,40 +25,47 @@ USA.</p> <tp:added version="0.17.16">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface extends the Text interface to support more general - messages, including:</p> + <p>This interface extends the <tp:dbus-ref + namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref> + interface to support more general messages, including:</p> <ul> <li>messages with attachments (like MIME multipart/mixed)</li> <li>groups of alternatives (like MIME multipart/alternative)</li> - <li>delivery reports</li> + <li>delivery reports (which replace <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>), + addding support for protocols where the message content is not echoed + back to the sender on failure and for receiving positive + acknowledgements, as well as ensuring that incoming delivery reports + are not lost if no client is handling the channel yet;</li> <li>any extra types of message we need in future</li> </ul> - <p>Although this specification supports formatted (rich-text) - messages with unformatted alternatives, implementations SHOULD NOT - attempt to send formatted messages until the Telepathy specification - has also been extended to cover capability discovery for message - formatting.</p> + <p>Incoming messages, outgoing messages, and delivery reports are all + represented as lists of <tp:type>Message_Part</tp:type> structures, + with a format reminiscent of e-mail. Messages are sent by calling + <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are + announced to other clients which may be interested in the channel by + the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming + messages and delivery reports are signalled by + <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the + the <tp:member-ref>PendingMessages</tp:member-ref> property until + acknowledged by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>. + Only the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + for a channel should acknowledge messages; <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s + (such as loggers) and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s + for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p> <tp:rationale> - We intend to expose all rich-text messages as XHTML-IM, but on some - protocols, formatting is an extremely limited subset of that format - (e.g. there are protocols where foreground/background colours, font - and size can be set, but only for entire messages). - Until we can tell UIs what controls to offer to the user, it's - unfriendly to offer the user controls that may have no effect. + <p>If observers were allowed to acknowledge messages, then messages + might have been acknowledged before the handler even got to see the + channel, and hence could not be shown to the user.</p> </tp:rationale> - <p>This interface also replaces <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>, - adding support for - protocols where the message content is not echoed back to the sender on - failure, adding support for receiving positive acknowledgements, - and using the Messages queue for state-recovery - (ensuring that incoming delivery reports are not lost if there is not - currently a process handling them).</p> - <p>If this interface is present, clients that support it SHOULD listen for the <tp:member-ref>MessageSent</tp:member-ref> and <tp:member-ref>MessageReceived</tp:member-ref> signals, and @@ -70,6 +77,21 @@ USA.</p> namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> signals on the Text interface (which are guaranteed to duplicate signals from this interface).</p> + + <p>Although this specification supports formatted (rich-text) + messages with unformatted alternatives, implementations SHOULD NOT + attempt to send formatted messages until the Telepathy specification + has also been extended to cover capability discovery for message + formatting.</p> + + <tp:rationale> + We intend to expose all rich-text messages as XHTML-IM, but on some + protocols, formatting is an extremely limited subset of that format + (e.g. there are protocols where foreground/background colours, font + and size can be set, but only for entire messages). + Until we can tell UIs what controls to offer to the user, it's + unfriendly to offer the user controls that may have no effect. + </tp:rationale> </tp:docstring> <property name="SupportedContentTypes" type="as" access="read" @@ -182,11 +204,93 @@ USA.</p> array-depth="2"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Part of a message's content. In practice, this mapping never - appears in isolation - messages are represented by a list of - <tp:type>Message_Part</tp:type> mappings.</p> + appears in isolation: incoming messages are represented by a list of + <tp:type>Message_Part</tp:type> mappings in the + <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing + messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as + a list of these mappings.</p> + + <p>The first part of the message contains "headers", which refer + to the entire message. The second and subsequent parts contain the + message's content, including plain text, formatted text and/or + attached files. Well-known keys for the header and body parts are + defined by the <tp:type>Message_Header_Key</tp:type> and + <tp:type>Message_Body_Key</tp:type> types, respectively. It is an + error for a connection manager to put keys referring to the message + as a whole in the second or subsequent Message_Part, or keys intended + for body parts in the first Message_Part; clients MUST recover from + this error by ignoring these mis-placed keys.</p> + + <tp:rationale> + <p>Instead of representing messages as aa{sv} where the first + dictionary is special (a dictionary of headers), we could have + used a signature like (a{sv}aa{sv}) to separate out the headers + and the body parts.</p> + + <p>However, this would make access to the messages more awkward. + In Python, the syntax for access to a header field would remain + <code>message[0]['message-type']</code>, but access to a body + field in the second body part would change from + <code>message[2]['content'] to message[1][1]['content']</code>. In + GLib, the message would change from being a + <code>GPtrArray(GHashTable)</code> to being a + <code>GValueArray(GHashTable, GPtrArray(GHashTable))</code> which + is rather inconvenient to dereference.</p> + </tp:rationale> - <p>An example of how a rich-text message, with an embedded image, might - look, in a Python-like syntax:</p> + <p>In any group of parts with the same non-empty value for the + <tt>alternative</tt> key (which represent alternative versions of the + same content), more faithful versions of the intended message MUST + come before less faithful versions (note that this order is the + opposite of MIME <tt>multipart/alternative</tt> parts). Clients + SHOULD display the first alternative that they understand.</p> + + <tp:rationale> + <p>Specifying the preference order means that if the underlying + protocol doesn't support alternatives, the CM can safely delete + everything apart from the first supported alternative when + sending messages.</p> + + <p>The order is the reverse of MIME because MIME's rationale for + placing the "plainest" part first (legibility in pre-MIME UAs) + does not apply to us, and placing the most preferred part + first simplifies display (a client can iterate the message + in order, display the first alternative that it understands, + and skip displaying all subsequent parts with the same + "alternative" key).</p> + </tp:rationale> + + <p>Clients SHOULD present all parts that are not redundant + alternatives in the order they appear in this array, possibly + excluding parts that are referenced by another displayed part. + It is implementation-specific how the parts are presented to the + user.</p> + + <tp:rationale> + <p>This allows CMs to assume that all parts are actually shown to + the user, even if they are not explicitly referenced - we do + not yet recommend formatted text, and there is no way for + plain text to reference an attachment since it has no concept of + markup or references. This also forces clients to do something + sensible with messages that consist entirely of "attachments", + with no "body" at all.</p> + + <p>For instance, when displaying the above example, a client that + understands the HTML part should display the JPEG image once, + between the two lines "Here is a photo of my cat:" and + "Isn't it cute?"; it may additionally present the image in some + way for a second time, after "Isn't it cute?", or may choose + not to.</p> + + <p>A client that does not understand HTML, displaying the same + message, should display the plain-text part, followed by the JPEG + image.</p> + </tp:rationale> + + <h4>Example messages</h4> + + <p>A rich-text message, with an embedded image, might be represented + as:</p> <pre> [ @@ -215,9 +319,8 @@ USA.</p> }, ]</pre> - <p>An example of how a non-text message — in particular, a vCard sent - via SMS as implemented by telepathy-ring on Nokia's Maemo 5 — - looks:</p> + <p>telepathy-ring, Nokia's GSM connection manager, represents vCards + sent via SMS as:</p> <pre> [ @@ -234,34 +337,164 @@ USA.</p> }, ]</pre> + <h3>Delivery reports</h3> + <div> - <p>The first part of the message contains "headers" which refer - to the entire message.</p> + <p>Delivery reports are also represented as messages with the + <tt>message-type</tt> header mapping to + <tp:type>Channel_Text_Message_Type</tp:type> Delivery_Report. + Delivery reports SHOULD contain the <tt>message-sender</tt> header, + mapping to the intended recipient of the original message, if + possible; other headers specific to delivery reports are defined by + the <tp:type>Delivery_Report_Header_Key</tp:type> type. The second + and subsequent parts, if present, are a human-readable report from + the IM service.</p> + + <p>For backwards- and forwards-compatibility, whenever a delivery + error report is signalled—that is, with <tt>delivery-status</tt> + mapping to <tp:type>Delivery_Status</tp:type> Temporarily_Failed or + Permanently_Failed—<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> + SHOULD also be emitted; whenever <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref> + is emitted, a delivery report MUST also be signalled. + Delivery report messages on this interface MUST be represented in + emissions of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> + as messages with the Non_Text_Content + <tp:type>Channel_Text_Message_Flags</tp:type>; clients which + understand this interface SHOULD ignore the SendError signal in + favour of listening for delivery reports, as mentioned in the + introduction.</p> + + <p>The result of attempting to send delivery reports using + <tp:member-ref>SendMessage</tp:member-ref> is currently + undefined.</p> + + <h4>Example delivery reports</h4> - <p>It is an error for a connection manager to put keys referring - to the message as a whole in the second or subsequent - Message_Part, but clients MUST recover from this error by ignoring - these keys in the second and subsequent parts.</p> + <dl> + <dt>A minimal delivery report indicating permanent failure of the + sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown + reason</dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +]</pre></dd> - <tp:rationale> - <p>Instead of representing messages as aa{sv} where the first - dictionary is special (a dictionary of headers), we could have - used a signature like (a{sv}aa{sv}) to separate out the headers - and the body parts.</p> - - <p>However, this would make access to the messages more awkward. - In Python, the syntax for access to a header field would remain - <code>message[0]['message-type']</code>, but access to a body - field in the second body part would change from - message[2]['content'] to message[1][1]['content']. In GLib, - the message would change from being a - GPtrArray(GHashTable) to being a - GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather - inconvenient to dereference.</p> - </tp:rationale> + <dt>A delivery report where the failed message is echoed back to the + sender rather than being referenced by ID, and the failure reason + is that this protocol cannot send messages to offline contacts + such as the contact with handle 123</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Temporarily_Failed, +'delivery-error': Channel_Text_Send_Error_Offline, +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], - <p>Well-known keys for the message as a whole, and the corresponding - value types, include:</p> +# no body +]</pre></dd> + + <dt>A maximally complex delivery report: the server reports a + bilingual human-readable failure message because the user sent + a message "Hello, world!" with token + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact + with handle 123, but that handle represents a contact who does not + actually exist</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-error': Channel_Text_Send_Error_Invalid_Contact, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], +}, +{ # message from server (alternative in English) +'alternative': '404', +'content-type': 'text/plain', +'lang': 'en', +'content': 'I have no contact with that name', +}, +{ # message from server (alternative in German) +'alternative': '404'. +'content-type': 'text/plain', +'lang': 'de', +'content', 'Ich habe keinen Kontakt mit diesem Namen', +} +]</pre></dd> + + <dt>A minimal delivery report indicating successful delivery + of the sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Delivered, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +]</pre></dd> + + </dl> + + </div> + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring> + A key, which SHOULD be one of the well-known keys specified by + <tp:type>Message_Header_Key</tp:type>, + <tp:type>Message_Body_Key</tp:type> or + <tp:type>Delivery_Report_Header_Key</tp:type> if possible. + </tp:docstring> + </tp:member> + + <tp:member name="Value" type="v"> + <tp:docstring> + The value corresponding to the given key, which SHOULD be one of the + specified types for well-known keys. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:simple-type type="s" name="Message_Header_Key"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a + message, which contains metadata about the message as a whole, along + with the corresponding value types. Some keys make sense for both + incoming and outgoing messages, while others are only meaningful for + one or the other.</p> <dl> <dt>message-token (s)</dt> @@ -314,12 +547,28 @@ 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, Channel_Text_Message_Type_Normal MUST be assumed. MAY be omitted for normal chat messages.</dd> + <dt>supersedes (s – <tp:type>Protocol_Message_Token</tp:type>)</dt> + <dd>If present, this message supersedes a previous message, + identified by its <tt>protocol-token</tt> or + <tt>message-token</tt> header. The user interface MAY, for + example, choose to replace the superseded message with this + message, or grey out the superseded message. + + <tp:rationale>Skype, for example, allows the user to amend + messages they have already sent (to correct typos, + etc.).</tp:rationale> + </dd> + <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt> <dd>The incoming message ID. This MUST NOT be present on outgoing messages. Clients SHOULD NOT store this key - it is only valid @@ -350,72 +599,19 @@ USA.</p> does not make sense on outgoing messages, and SHOULD NOT appear there.</dd> </dl> - </div> - - <div> - <p>The second and subsequent parts contain the message's - content, including plain text, formatted text and/or attached - files.</p> - - <p>It is an error for a connection manager to put keys referring - to the message body in the first Message_Part; - clients MUST recover from this error by ignoring - these keys in first part.</p> - - <p>In any group of parts with the same non-empty value for the - "alternative" key (which represent alternative versions of the - same content), more faithful versions of the intended message MUST - come before less faithful versions (note that this order is the - opposite of MIME "multipart/alternative" parts). Clients SHOULD - display the first alternative that they understand.</p> - - <tp:rationale> - <p>Specifying the preference order means that if the underlying - protocol doesn't support alternatives, the CM can safely delete - everything apart from the first supported alternative when - sending messages.</p> - - <p>The order is the reverse of MIME because MIME's rationale for - placing the "plainest" part first (legibility in pre-MIME UAs) - does not apply to us, and placing the most preferred part - first simplifies display (a client can iterate the message - in order, display the first alternative that it understands, - and skip displaying all subsequent parts with the same - "alternative" key).</p> - </tp:rationale> - - <p>Clients SHOULD present all parts that are not redundant - alternatives in the order they appear in this array, possibly - excluding parts that are referenced by another displayed part. - It is implementation-specific how the parts are presented to the - user.</p> - - <tp:rationale> - <p>This allows CMs to assume that all parts are actually shown to - the user, even if they are not explicitly referenced - we do - not yet recommend formatted text, and there is no way for - plain text to reference an attachment since it has no concept of - markup or references. This also forces clients to do something - sensible with messages that consist entirely of "attachments", - with no "body" at all.</p> - - <p>For instance, when displaying the above example, a client that - understands the HTML part should display the JPEG image once, - between the two lines "Here is a photo of my cat:" and - "Isn't it cute?"; it may additionally present the image in some - way for a second time, after "Isn't it cute?", or may choose - not to.</p> - - <p>A client that does not understand HTML, displaying the same - message, should display the plain-text part, followed by the JPEG - image.</p> - </tp:rationale> + </tp:docstring> + </tp:simple-type> - <p>Well-known keys for the second and subsequent parts, and the - corresponding value types, include:</p> + <tp:simple-type type="s" name="Message_Body_Key"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the second and subsequent + <tp:type>Message_Part</tp:type>s of a message, which contain the + message content, along with the corresponding value types.</p> <dl> - <dt>identifier (s)</dt> + <dt>identifier (s — + <tp:type>Protocol_Content_Identifier</tp:type>)</dt> <dd>An opaque identifier for this part. Parts of a message MAY reference other parts by treating this identifier as if it were a MIME Content-ID and using @@ -442,8 +638,9 @@ USA.</p> <dt>content-type (s)</dt> <dd> <p>The MIME type of this part. See the documentation - for ReceivedMessage for notes on the special status of - "text/plain" parts.</p> + for <tp:member-ref>MessageReceived</tp:member-ref> and + <tp:member-ref>MessageSent</tp:member-ref> for notes on the + special status of "text/plain" parts.</p> <p>Connection managers MUST NOT signal parts without a 'content-type' key; if a protocol provides no way to determine @@ -498,8 +695,7 @@ USA.</p> 'content': [0xFF, 0xD8, ... 0xFF 0xD9], }, ... -] - </pre> +]</pre> </dd> <dt>needs-retrieval (b)</dt> @@ -543,38 +739,30 @@ USA.</p> can also appear on the first part, where it indicates that the entire message should be ignored if unsupported.)</dd> </dl> + </tp:docstring> + </tp:simple-type> - </div> - - - <div> - <p>Delivery reports are also represented as messages, of type - Channel_Text_Message_Type_Delivery_Report, with the - Non_Text_Content flag in the Text interface.</p> - - <p>Whenever a message of type - Channel_Text_Message_Type_Delivery_Report is signalled for a - delivery error report, Channel.Type.Text.SendError SHOULD also - be emitted; whenever Channel.Type.Text.SendError is emitted by a - channel which supports this interface, a message of type - Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p> - - <p>The corresponding message in the Messages interface MUST contain - "headers" for the delivery report, as specified below, in its - first Message_Part.</p> + <tp:simple-type type="s" name="Delivery_Report_Header_Key"> + <tp:added version="0.19.8"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Well-known keys for the first <tp:type>Message_Part</tp:type> of a + delivery report, along with the corresponding value types. Some of + these are special-cases of headers defined by + <tp:type>Message_Header_Key</tp:type>.</p> <dl> - <dt>message-sender (u - Contact_Handle as defined above)</dt> + <dt>message-sender (u - <tp:type>Contact_Handle</tp:type>, as + defined by <tp:type>Message_Header_Key</tp:type>)</dt> <dd>MUST be the intended recipient of the original message, if available (zero or omitted if the intended recipient is unavailable or is not a contact, e.g. a chatroom), even if the delivery report actually came from an intermediate server.</dd> - <dt>message-type (u - Channel_Text_Message_Type as defined - above)</dt> + <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>, + as defined by <tp:type>Message_Header_Key</tp:type>)</dt> <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd> - <dt>delivery-status (u - Delivery_Status)</dt> + <dt>delivery-status (u - <tp:type>Delivery_Status</tp:type>)</dt> <dd>The status of the message. All delivery reports MUST contain this key in the first Message_Part.</dd> @@ -599,14 +787,16 @@ USA.</p> </tp:rationale> </dd> - <dt>delivery-error (u - Channel_Text_Send_Error)</dt> + <dt>delivery-error (u - + <tp:type>Channel_Text_Send_Error</tp:type>)</dt> <dd> The reason for the failure. MUST be omitted if this was a successful delivery; SHOULD be omitted if it would be Channel_Text_Send_Error_Unknown. </dd> - <dt>delivery-dbus-error (s - DBus_Error_Name)</dt> + <dt>delivery-dbus-error (s - + <tp:type>DBus_Error_Name</tp:type>)</dt> <dd> The reason for the failure, specified as a (possibly implementation-specific) D-Bus error. MUST be omitted if this was @@ -621,7 +811,7 @@ USA.</p> omitted. </dd> - <dt>delivery-echo (aa{sv} - Message_Part[])</dt> + <dt>delivery-echo (aa{sv} - <tp:type>Message_Part[]</tp:type>)</dt> <dd> <p>The message content, as defined by the Messages interface. Omitted if no content is available. Content MAY have been @@ -651,134 +841,8 @@ USA.</p> </dd> </dl> - - <p>The second and subsequent Message_Part dictionaries, if present, - are a human-readable report from the IM service.</p> - - <p>Clients MUST NOT attempt to send delivery reports using the - SendMessage method in the Messages API, and connection managers - MUST NOT allow this to be done. If support for sending delivery - reports is later added, it will be part of this interface.</p> - - <p>Some example delivery reports in a Python-like syntax (in which - arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) - follow.</p> - - <dl> - <dt>A minimal delivery report indicating permanent failure of the - sent message whose token was - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown - reason</dt> - <dd><pre> -[{ -# header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Permanently_Failed, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -} -# no body -] -</pre></dd> - - <dt>A delivery report where the failed message is echoed back to the - sender rather than being referenced by ID, and the failure reason - is that this protocol cannot send messages to offline contacts - such as the contact with handle 123</dt> - <dd><pre> -[{ # header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Temporarily_Failed, -'delivery-error': Channel_Text_Send_Error_Offline, -'delivery-echo': - [{ # header of original message - 'message-sender': 1, - 'message-sent': 1210067943, - }, - { # body of original message - 'content-type': 'text/plain', - 'content': 'Hello, world!', - }] - ], - -# no body -] -</pre></dd> - - <dt>A maximally complex delivery report: the server reports a - bilingual human-readable failure message because the user sent - a message "Hello, world!" with token - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact - with handle 123, but that handle represents a contact who does not - actually exist</dt> - <dd><pre> -[{ # header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Permanently_Failed, -'delivery-error': Channel_Text_Send_Error_Invalid_Contact, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -'delivery-echo': - [{ # header of original message - 'message-sender': 1, - 'message-sent': 1210067943, - }, - { # body of original message - 'content-type': 'text/plain', - 'content': 'Hello, world!', - }] - ], -}, -{ # message from server (alternative in English) -'alternative': '404', -'content-type': 'text/plain', -'lang': 'en', -'content': 'I have no contact with that name', -}, -{ # message from server (alternative in German) -'alternative': '404'. -'content-type': 'text/plain', -'lang': 'de', -'content', 'Ich habe keinen Kontakt mit diesem Namen', -} -] -</pre></dd> - - <dt>A minimal delivery report indicating successful delivery - of the sent message whose token was - <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt> - <dd><pre> -[{ -# header -'message-sender': 123, -'message-type': Channel_Text_Message_Type_Delivery_Report, -'delivery-status': Delivery_Status_Delivered, -'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', -} -# no body -] -</pre></dd> - - </dl> - - </div> </tp:docstring> - - <tp:member name="Key" type="s"> - <tp:docstring> - A key, which SHOULD be one of the well-known keys specified, if - possible. - </tp:docstring> - </tp:member> - - <tp:member name="Value" type="v"> - <tp:docstring> - The value corresponding to the given key, which must be of one of - the types indicated. - </tp:docstring> - </tp:member> - </tp:mapping> + </tp:simple-type> <tp:simple-type type="u" name="Message_Part_Index" array-name="Message_Part_Index_List"> @@ -814,7 +878,8 @@ USA.</p> </tp:member> </tp:mapping> - <tp:simple-type type="s" name="Protocol_Message_Token"> + <tp:simple-type type="s" name="Protocol_Message_Token" + array-name="Protocol_Message_Token_List"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An opaque token used to identify messages in the underlying. protocol. As a special case, the empty string indicates that there @@ -838,6 +903,23 @@ USA.</p> </tp:docstring> </tp:simple-type> + <tp:simple-type name="Protocol_Content_Identifier" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A protocol-specific identifier for a blob of content, as used for + the <tt>identifier</tt> key in a <tp:type>Message_Part</tp:type>. The + same identifier MAY be re-used if the same content, byte-for-byte, + appears as a part of several messages.</p> + + <tp:rationale> + <p>On XMPP, these identifiers might be Content-IDs for custom + smileys implemented using <a + href="http://xmpp.org/extensions/xep-0231.html">XEP-0232 Bits of + Binary</a>; the same smiley might well appear in multiple + messages.</p> + </tp:rationale> + </tp:docstring> + </tp:simple-type> + <method name="SendMessage" tp:name-for-bindings="Send_Message"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Submit a message to the server for sending. @@ -873,7 +955,11 @@ USA.</p> <arg direction="in" name="Flags" type="u" tp:type="Message_Sending_Flags"> <tp:docstring> - Flags affecting how the message is sent. + Flags affecting how the message is sent. The channel MAY ignore some + or all flags, depending on + <tp:member-ref>DeliveryReportingSupport</tp:member-ref>; the flags + that were handled by the CM are provided in + <tp:member-ref>MessageSent</tp:member-ref>. </tp:docstring> </arg> @@ -902,7 +988,9 @@ USA.</p> type="u"> <tp:docstring> Flags altering the way a message is sent. The "most usual" action - should always be to have these flags unset. + should always be to have these flags unset. Some indication of which + flags are supported is provided by the + <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. </tp:docstring> <tp:flag suffix="Report_Delivery" value="1"> @@ -922,6 +1010,24 @@ USA.</p> messages.</p> </tp:docstring> </tp:flag> + + <tp:flag suffix="Report_Read" value="2"> + <tp:added version="0.19.9"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a delivery report when the message is read by the + recipient, even if this is not the default for this protocol. + Ignored if read reports are not possible on this protocol.</p> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Report_Deleted" value="4"> + <tp:added version="0.19.9"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a delivery report when the message is deleted by the + recipient, even if this is not the default for this protocol. + Ignored if such reports are not possible on this protocol.</p> + </tp:docstring> + </tp:flag> </tp:flags> <signal name="MessageSent" tp:name-for-bindings="Message_Sent"> @@ -929,28 +1035,29 @@ USA.</p> <p>Signals that a message has been submitted for sending. This MUST be emitted exactly once per emission of the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref> - signal on the Text interface. This SHOULD be emitted as soon as - the CM determines it's theoretically possible to send the message - (e.g. the parameters are supported and correct).</p> + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter if this interface is present, as mentioned + in the introduction.</p> + + <p>This SHOULD be emitted as soon as the CM determines it's + theoretically possible to send the message (e.g. the parameters are + supported and correct).</p> <tp:rationale> <p>This signal allows a process that is not the caller of - SendMessage to log sent messages. The double signal-emission - provides compatibility with older clients. Clients supporting - Messages should listen for Messages.MessageSent only (if the - channel has the Messages interface) or Text.Sent only - (otherwise).</p> + SendMessage to log sent messages.</p> </tp:rationale> </tp:docstring> <arg type="aa{sv}" tp:type="Message_Part[]" name="Content"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The message content (see <tp:type>Message_Part</tp:type> for full - details). If the message that was passed to SendMessage has a - formatted text part that the connection manager recognises, but no - text/plain alternative, the CM MUST use the formatted text part to - generate a text/plain alternative which is also included in this - signal argument.</p> + details). If the message that was passed to + <tp:member-ref>SendMessage</tp:member-ref> has a formatted text + part that the connection manager recognises, but no + <tt>text/plain</tt> alternative, the CM MUST use the formatted text + part to generate a <tt>text/plain</tt> alternative which is also + included in this signal argument.</p> <p>If the connection manager can predict that the message will be altered during transmission, this argument SHOULD reflect what @@ -1074,19 +1181,19 @@ USA.</p> messages queue. This MUST be emitted exactly once per emission of the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref> - signal on the Text interface. - - <tp:rationale> - The double signal-emission provides compatibility with older - clients. Clients supporting Messages should listen for - Messages.MessageReceived only (if the channel has the Messages - interface) or Text.Received only (otherwise). - </tp:rationale> + signal on the Text interface, for backwards-compatibility; clients + SHOULD ignore the latter in favour of this signal if this interface is + present, as mentioned in the introduction. </tp:docstring> <arg type="aa{sv}" tp:type="Message_Part[]" name="Message"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The message content, including any attachments or alternatives + <p>The message content, including any attachments or alternatives. If + the incoming message contains formatted text without a plain text + alternative, the connection manager MUST generate a + <tt>text/plain</tt> alternative from the formatted text, and + include it in this message (both here, and in the + <tp:member-ref>PendingMessages</tp:member-ref> property).</p> </tp:docstring> </arg> </signal> @@ -1101,7 +1208,8 @@ USA.</p> should still be signalled as either Temporarily_Failed or Permanently_Failed). If additional detail is required (e.g. distinguishing between the various types of permanent failure) this - will be done using additional keys in the Message_Part.</p> + will be done using additional + <tp:type>Delivery_Report_Header_Key</tp:type>s.</p> </tp:docstring> <tp:enumvalue suffix="Unknown" value="0"> @@ -1158,28 +1266,49 @@ USA.</p> </tp:rationale> </tp:docstring> </tp:enumvalue> + + <tp:enumvalue suffix="Read" value="5"> + <tp:added version="0.19.9"/> + <tp:docstring> + The message has been read by the intended recipient. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Deleted" value="6"> + <tp:added version="0.19.9"/> + <tp:docstring> + The message has been deleted by the intended recipient. This MAY be + signalled on its own if the message is deleted without being read, or + after <code>Read</code> if the message was read before being deleted. + </tp:docstring> + </tp:enumvalue> </tp:enum> <tp:flags name="Delivery_Reporting_Support_Flags" value-prefix="Delivery_Reporting_Support_Flag" type="u"> <tp:docstring> Flags indicating the level of support for delivery reporting on this - channel. Any future flags added to this set will conform to the + channel, as found on the + <tp:member-ref>DeliveryReportingSupport</tp:member-ref> property. Any + future flags added to this set will conform to the convention that the presence of an extra flag implies that - more operations will succeed. + more operations will succeed. Note that CMs may always provide more + reports than are requested in the + <tp:type>Message_Sending_Flags</tp:type> passed to + <tp:member-ref>SendMessage</tp:member-ref>. + + <tp:rationale> + If senders want delivery reports, they should ask for them. If they + don't want delivery reports, they can just ignore them, so there's no + need to have capability discovery for what will happen if a delivery + report isn't requested. + </tp:rationale> </tp:docstring> <tp:flag suffix="Receive_Failures" value="1"> <tp:docstring> Clients MAY expect to receive negative delivery reports if Message_Sending_Flag_Report_Delivery is specified when sending. - - <tp:rationale> - If senders want delivery reports, they should ask for them. - If they don't want delivery reports, they can just ignore them, - so there's no need to have capability discovery for what will - happen if a delivery report isn't requested. - </tp:rationale> </tp:docstring> </tp:flag> @@ -1187,13 +1316,26 @@ USA.</p> <tp:docstring> Clients MAY expect to receive positive delivery reports if Message_Sending_Flag_Report_Delivery is specified when sending. + </tp:docstring> + </tp:flag> - <tp:rationale> - Same rationale as Receive_Failures. - </tp:rationale> + <tp:flag suffix="Receive_Read" value="4"> + <tp:added version="0.19.9"/> + <tp:docstring> + Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> + <code>Read</code> reports if Message_Sending_Flag_Report_Read + is specified when sending. </tp:docstring> </tp:flag> + <tp:flag suffix="Receive_Deleted" value="8"> + <tp:added version="0.19.9"/> + <tp:docstring> + Clients MAY expect to receive <tp:type>Delivery_Status</tp:type> + <code>Deleted</code> reports if Message_Sending_Flag_Report_Deleted + is specified when sending. + </tp:docstring> + </tp:flag> </tp:flags> <property name="DeliveryReportingSupport" access="read" diff --git a/spec/Channel_Interface_Service_Point.xml b/spec/Channel_Interface_Service_Point.xml new file mode 100644 index 0000000..787397b --- /dev/null +++ b/spec/Channel_Interface_Service_Point.xml @@ -0,0 +1,86 @@ +<?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"> + <tp:added version="0.19.7">(as stable API)</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 a service point, the CM MUST set the + <tp:type>Service_Point_Type</tp:type> field to None; for instance, + this will be the case for ordinary calls. + </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="Service_Point" 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 4de78b4..1d59eb8 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 dacf906..f1d0f0e 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/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 5f5bd4b..de58bfc 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -18,16 +18,20 @@ Lesser General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT2" - tp:causes-havoc='experimental'> + <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:changed version="0.17.27">(draft 2)</tp:changed> + <tp:added version="0.19.10"> + as stable API. Changes from draft 2: + <tp:type>Contact_Search_Result_Map</tp:type> keys are now identifiers + rather than handles; consequently, the values need not include + <tt>x-telepathy-identifier</tt>. + </tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A channel type for searching server-stored user directories. A new channel should be requested by a client for each search attempt, and closed when the search is completed or the required result has been - found in order to free unused handles.</p> + found.</p> <p>Before searching, the <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be @@ -57,8 +61,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>The client should call the channel's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> - method when it is finished with the channel, so that any handles held - only by the channel can be released.</p> + method when it is finished with the channel.</p> <p>Each channel can only be used for a single search; a new channel should be requested for each subsequent search. Connection managers @@ -377,10 +380,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <tp:mapping name="Contact_Search_Result_Map"> - <tp:docstring>A map from contact handle to search result.</tp:docstring> - <tp:member name="Contact" type="u" tp:type="Contact_Handle"> - <tp:docstring> - An integer handle for the contact. + <tp:docstring>A map from contact identifier to search result, emitted in + the <tp:member-ref>SearchResultReceived</tp:member-ref> + signal.</tp:docstring> + + <tp:member name="Contact_Identifier" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The identifier of a contact matching the search terms. + + <tp:rationale> + This is an identifier rather than a handle in case we make handles + immortal; see <a + href="https://bugs.freedesktop.org/show_bug.cgi?id=23155">fd.o#23155</a> + and <a + href="https://bugs.freedesktop.org/show_bug.cgi?id=13347#c5">fd.o#13347 + comment 5</a>. + </tp:rationale> </tp:docstring> </tp:member> @@ -388,33 +403,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of fields representing information about this contact, in the same format used in the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo</tp:dbus-ref> interface. It is possible that a separate call to <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo">RequestContactInfo</tp:dbus-ref> would return more information than this signal provides.</p> - - <p>This array SHOULD include the <code>x-telepathy-identifier</code> - field, whose values matches the result of calling <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> - on the Contact handle.</p> - - <tp:rationale> - <p>UIs will most likely want to show the identifier to the user; - while they could do this by inspecting the signalled handle, - including it in this signal is cheap and removes a roundtrip to - look it up.</p> - </tp:rationale> </tp:docstring> </tp:member> </tp:mapping> <signal name="SearchResultReceived" tp:name-for-bindings="Search_Result_Received"> - <arg name="Result" type="a{ua(sasas)}" tp:type="Contact_Search_Result_Map"> - <tp:docstring>A mapping from contact handle to an array of fields - representing information about this contact. Handles in this mapping - MUST remain valid until the Channel closes.</tp:docstring> + <arg name="Result" type="a{sa(sasas)}" tp:type="Contact_Search_Result_Map"> + <tp:docstring>A mapping from contact identifier to an array of fields + representing information about this contact.</tp:docstring> </arg> + <tp:docstring> Emitted when a some search results are received from the server. This signal can be fired arbitrarily many times so clients MUST NOT diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml index 4484b7c..5445659 100644 --- a/spec/Channel_Type_Streamed_Media.xml +++ b/spec/Channel_Type_Streamed_Media.xml @@ -598,46 +598,126 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </property> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel that can send and receive streamed media such as audio or video. - Provides a number of methods for listing and requesting new streams, and - signals to indicate when streams have been added, removed and changed - status.</p> - - <p>To make a media call to a contact, clients should call <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref> - with <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref> - = <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>, - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = Contact, and one of <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - or <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref> - (which should yield a channel with the local user in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">Members</tp:dbus-ref>, - and the remote contact as <tp:dbus-ref + <p>A channel that can send and receive streamed media such as audio or + video. Provides a number of methods for listing and requesting new + streams, and signals to indicate when streams have been added, removed + and changed status. The state of the call (ringing remotely, ringing + locally, answered, missed, etc.) are represented using the properties + and signals of the Group interface.</p> + + <p>In general this should be used in conjunction with the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> + interface to exchange connection candidates and codec choices with + whichever component is responsible for the streams. However, in certain + applications where no candidate exchange is necessary (eg the streams + are handled by specialised hardware which is controlled directly by the + connection manager), the signalling interface can be omitted and this + channel type used simply to control the streams.</p> + + <h4>Outgoing calls</h4> + + <p>To make an audio-only call to a contact <tt>foo@example.com</tt>, + clients should call:</p> + + <blockquote> + <pre> +<tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({ + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: Contact, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'foo@example.com', + <tp:member-ref>InitialAudio</tp:member-ref>: True, +)</pre></blockquote> + + <p>As always, <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - but not in any group members list), then call - <tp:member-ref>RequestStreams</tp:member-ref> to initiate the call (at - which point the contact should appear in the channel's <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemotePendingMembers</tp:dbus-ref>).</p> + may be used in place of TargetID if the contact's handle is already + known. To make an audio-and-video call, the client should also specify + <tp:member-ref>InitialVideo</tp:member-ref>. The connection manager + SHOULD return a channel whose immutable properties contain the local + user as the <tp:dbus-ref namespace='ofdT.Channel'>InitiatorHandle</tp:dbus-ref>, + the remote contact as the <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>True</code> + (indicating that the call is outgoing); the <tp:dbus-ref + namespace='ofdT.Channel.Interface'>Group</tp:dbus-ref> interface should + initially have the local user in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>Members</tp:dbus-ref> and the remote + contact in <tp:dbus-ref + namespace='ofdT.Channel.Interface.Group'>RemotePendingMembers</tp:dbus-ref>, to + indicate that we are awaiting their response.</p> + + <p>The contact answering the call is represented by the CM signalling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + moving the remote contact to Members, with the remote contact as the + <var>Actor</var> and <var>Reason</var> <code>None</code>. The contact + rejecting the call is represented by both contacts being removed from + the group, with the remote contact as the <var>Actor</var> and + <var>Reason</var> set appropriately. The local user may hang up at any + time by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove themself, with an appropriate reason; the CM SHOULD relay the + reason to the remote contact, and emit MembersChanged removing both + contacts from the group with the self handle as the <var>Actor</var>.</p> - <p>In the past, several other patterns have been used to place outgoing + <p>(In the past, several other patterns have been used to place outgoing calls; see <a href="http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels">'Requesting StreamedMedia Channels' on the Telepathy wiki</a> - for the details.</p> + for the details.)</p> + + <h4>Incoming calls</h4> - <p>Incoming calls should be signalled as <tp:dbus-ref + <p>Incoming calls' immutable properties should contain <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> - = Contact, <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> - set to the remote contact, with the local user in <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref>; - to accept the call, <tp:dbus-ref + = Contact, both <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">InitiatorHandle</tp:dbus-ref> + set to the remote contact, <tp:dbus-ref + namespace='ofdT.Channel'>Requested</tp:dbus-ref> = <code>False</code> + (indicating that this is an incoming call), and appropriate values of + <tp:member-ref>InitialAudio</tp:member-ref> and + <tp:member-ref>InitialVideo</tp:member-ref>; the Group interface should + initially have the local user in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">LocalPendingMembers</tp:dbus-ref> + and the remote contact in <tp:dbus-ref + namespace="ofdT.Channel.Interface.Group">Members</tp:dbus-ref>, + indicating that the contact is awaiting our response.</p> + + <p>To accept the call, use <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Group">AddMembers</tp:dbus-ref> - can be used to move the local user to the group's members.</p> + to move the local user to the group's members. To reject the call, use + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref> + to remove the local member from the group, with an appropriate reason. + If the remote user ends the call before it is answered, this is + represented by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref> + removing both parties from the group with the remote contact as the + <var>Actor</var>, and <var>Reason</var> set appropriately.</p> + + <p>Note that the call may end with the self handle as the + <var>Actor</var> without the user having chosen to reject the call, as + indicated by the nature of the <var>Reason</var>. Specifically, some + local component may time out the call (indicating this with reason + <code>No_Answer</code>; for example, the CM may have forwarded the call + to another number, as configured using <tp:dbus-ref + namespace='ofdT.Connection.Interface'>Forwarding.DRAFT</tp:dbus-ref>), + or something may have gone wrong with the call + (indicated by reason <code>Error</code>). Such calls SHOULD be + considered missed, just as if the remote contact had hung up before the + local user answered the call.</p> + + <tp:rationale> + <p>This is a bit awkward, but these are the best ways we can represent + these situations. It's important to document which calls should be + considered missed, to ensure that the user can be notified.</p> + </tp:rationale> <p>When the local user accepts an incoming call, the connection manager SHOULD change the direction of any streams with pending local send @@ -658,14 +738,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ should be removed when this specification is revised.</p> </tp:rationale> - <p>In general this should be used in conjunction with the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">MediaSignalling</tp:dbus-ref> - interface to exchange connection candidates and codec choices with - whichever component is responsible for the streams. However, in certain - applications where no candidate exchange is necessary (eg the streams are - handled by specialised hardware which is controlled directly by the - connection manager), the signalling interface can be omitted and this - channel type used simply to control the streams.</p> + <h4>During a call</h4> + + <p>If <tp:member-ref>ImmutableStreams</tp:member-ref> is + <code>False</code>, new streams may be requested using + <tp:member-ref>RequestStreams</tp:member-ref> (to add video to an + audio-only call, for instance), and existing streams may be removed using + <tp:member-ref>RemoveStreams</tp:member-ref> (for example, to downgrade + an audio-video call to audio-only). The call may be ended by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembers</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">RemoveMembersWithReason</tp:dbus-ref>; the call ending is signalled by the CM emitting <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.Group">MembersChanged</tp:dbus-ref>, + removing both parties from the group.</p> <h4>Handler filters</h4> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 5315a55..e3cd6b9 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -325,9 +325,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:enumvalue suffix="Delivery_Report" value="4"> <tp:docstring> - This message type MUST NOT appear unless the channel supports the - DeliveryReporting interface. The message MUST be as defined by - the DeliveryReporting interface. + A delivery report. This message type MUST NOT appear unless the + channel supports the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Messages</tp:dbus-ref> + interface; see <tp:type>Message_Part</tp:type> for the format that + delivery reports must take. </tp:docstring> </tp:enumvalue> </tp:enum> diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index c6edf33..10a16bd 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 f777a2a..f4c1108 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 35e6d91..912edaf 100644 --- a/spec/Client_Observer.xml +++ b/spec/Client_Observer.xml @@ -180,6 +180,51 @@ org.freedesktop.Telepathy.Channel.Requested b=true </tp:docstring> </property> + <property name="Recover" tp:name-for-bindings="Recover" type="b" + access="read"> + <tp:added version="0.19.4"> + When using telepathy-mission-control, version 5.4.0 or later is + needed for this property to be useful. + </tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, upon the startup of this observer, <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Observer">ObserveChannels</tp:dbus-ref> + will be called for every already existing channel matching + its <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Observer">ObserverChannelFilter</tp:dbus-ref></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 + possibility that it will miss some events during this process + (particularly <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages), this window of event loss is kept to a minimum.</p> + + <p>Non-activatable observers can't take advantage of this + mechanism, but setting this property on a non-activatable + observer does allow it to "catch up" on channels that are + currently active at the time that it starts up.</p> + </tp:rationale> + + <p>When the ObserveChannels method is called due to observer recovery, + 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> + <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Called by the channel dispatcher when channels in which the @@ -294,10 +339,26 @@ org.freedesktop.Telepathy.Channel.Requested b=true <arg name="Observer_Info" type="a{sv}" direction="in"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Additional information about these channels. No keys are - currently defined.</p> - - <p>If keys are defined for this dictionary, all will be optional; + <p>Additional information about these channels. Currently defined + keys are:</p> + + <dl> + <dt><code>recovering</code> - b</dt> + <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 + to catch up on previous events (perhaps after a previous instance of + the same observer crashed). + </tp:rationale> + </dd> + </dl> + + <p>All defined keys for this dictionary are optional; observers MAY safely ignore any entry in this dictionary.</p> </tp:docstring> </arg> diff --git a/spec/Connection_Interface_Anonymity.xml b/spec/Connection_Interface_Anonymity.xml new file mode 100644 index 0000000..31f1554 --- /dev/null +++ b/spec/Connection_Interface_Anonymity.xml @@ -0,0 +1,195 @@ +<?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"> + <tp:added version="0.19.7">(as stable API)</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 Show_Client_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> + <p>In GSM, it's possible to have CLIR enabled by default, and + explicitly suppress CLIR for a single phone call.</p> + </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 + Show_Client_Info. 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="AnonymityMandatory" type="b" access="readwrite" + tp:name-for-bindings="Anonymity_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.WouldBreakAnonymity</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 SHOULD also be made available as a parameter of the + same (fully-qualified) name to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, + with the DBus_Property flag in its + <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed + by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, + this property SHOULD be set via the Account Manager as follows:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>({ + "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityMandatory": <var>new_value</var> + }, [])</code> + </blockquote> + </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 emission of + <tp:member-ref>AnonymityModesChanged</tp:member-ref> signal.</p> + + <p>This property SHOULD also be made available as a parameter of the + same (fully-qualified) name to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>, + with the DBus_Property flag in its + <tp:type>Conn_Mgr_Param_Flags</tp:type>. For connections managed + by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, + this property SHOULD be set via the Account Manager as follows:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>({ + "org.freedesktop.Telepathy.Connection.Interface.Anonymity.AnonymityModes": <var>new_value</var> + }, [])</code> + </blockquote> + </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_Balance.xml b/spec/Connection_Interface_Balance.xml index 1042bec..76f9040 100644 --- a/spec/Connection_Interface_Balance.xml +++ b/spec/Connection_Interface_Balance.xml @@ -35,41 +35,45 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An amount of money in a specified currency. For example, 3.21 British pounds would conventionally be represented by - (Amount = 321, Scale = 2, Currency = "GBP"), but could be - represented by (Amount = 3210, Scale = 3, Currency = "GBP") - in a service that records balance in units of 0.001 pounds.</p> + (<var>Amount</var> = <tt>321</tt>, <var>Scale</var> = <tt>2</tt>, + <var>Currency</var> = <tt>"GBP"</tt>), but could be represented by + (<var>Amount</var> = <tt>3210</tt>, <var>Scale</var> = <tt>3</tt>, + <var>Currency</var> = <tt>"GBP"</tt>) in a service that records + balance in units of 0.001 pounds.</p> - <p>As a special case, if Amount = 0, Scale = 2**32 - 1 (i.e. - the largest possible 32-bit unsigned integer) and Currency = "", - this indicates an unknown amount.</p> + <p>As a special case, if <var>Amount</var> = <tt>0</tt>, + <var>Scale</var> = <tt>2**32 - 1</tt> (i.e. the largest possible + 32-bit unsigned integer) and <var>Currency</var> = <tt>""</tt>, this + indicates an unknown amount.</p> </tp:docstring> <tp:member type="i" name="Amount"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The amount, expressed as a fixed-point number with decimal scale - defined by the Scale property; for instance, an Amount value of - 1234 with Scale of 2 represents 12.34 in the currency unit given - by the Currency.</p> + defined by the <var>Scale</var> field; for instance, an + <var>Amount</var> value of <tt>1234</tt> with <var>Scale</var> of + <tt>2</tt> represents 12.34 in the currency unit given by the + <var>Currency</var> field.</p> </tp:docstring> </tp:member> <tp:member type="u" name="Scale"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The decimal scale for the fixed point value of the Amount - property, defining the number of rightmost decimal digits from - the integer value which form the fractional part of the resulting - currency value.</p> + <p>The decimal scale for the fixed point value of the + <var>Amount</var> field, defining the number of rightmost decimal + digits from the integer value which form the fractional part of the + resulting currency value.</p> - <p>As well as defining the interpretation of Amount, user interfaces - may use this value to determine the precision with which to display - the amount.</p> + <p>As well as defining the interpretation of <var>Amount</var>, user + interfaces may use this value to determine the precision with which + to display the amount.</p> </tp:docstring> </tp:member> <tp:member type="s" name="Currency"> <tp:docstring> The currency code represented by this amount, which SHOULD be an - international currency code such as "EUR", "USD", or "JPY" if - possible. An empty string can be used to indicate that the currency - is not known. + international currency code such as <tt>"EUR"</tt>, <tt>"USD"</tt>, + or <tt>"JPY"</tt> if possible. An empty string can be used to + indicate that the currency is not known. </tp:docstring> </tp:member> </tp:struct> @@ -77,13 +81,15 @@ <property name="AccountBalance" tp:name-for-bindings="Account_Balance" access="read" type="(ius)" tp:type="Currency_Amount"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The user's balance on the account corresponding to this Connection. + <p>The user's balance on the account corresponding to this <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>. A negative amount may be possible on some services, and indicates that the user owes money to the service provider.</p> <p>On initial connection, this property may have an unknown - value, represented by Amount = 0, Scale = 2**32 - 1 (the largest - possible 32-bit unsigned integer) and Currency = "".</p> + value, represented by <var>Amount</var> = <tt>0</tt>, + <var>Scale</var> = <tt>2**32 - 1</tt> (the largest possible 32-bit + unsigned integer) and <var>Currency</var> = <tt>""</tt>.</p> </tp:docstring> </property> diff --git a/spec/Connection_Interface_Capabilities.xml b/spec/Connection_Interface_Capabilities.xml index 10d8102..8e5eb33 100644 --- a/spec/Connection_Interface_Capabilities.xml +++ b/spec/Connection_Interface_Capabilities.xml @@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An interface for connections where it is possible to know what channel @@ -56,6 +57,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ well-defined or consistent, and as far as we know it was never implemented correctly. This usage is now deprecated.</tp:changed> + <tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref> + instead.</tp:deprecated> + <tp:changed version="0.19.8">Connection managers implementing + Capabilities MUST implement ContactCapabilities too.</tp:changed> + <tp:flags name="Connection_Capability_Flags" value-prefix="Connection_Capability_Flag" type="u"> <tp:flag suffix="Create" value="1"> @@ -231,7 +238,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 0000000..bf0f1a9 --- /dev/null +++ b/spec/Connection_Interface_Cellular.xml @@ -0,0 +1,156 @@ +<?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"> + <tp:added version="0.19.8">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface is for various cellular things (GSM and/or CDMA) 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> + + <p>Connections with this interface SHOULD provide this property as a + parameter of the same (fully-qualified) name to <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >ConnectionManager.RequestConnection</tp:dbus-ref>, with the + <code>DBus_Property</code> flag. For connections managed by the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, + this property SHOULD be set via the Account Manager as follows:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageValidityPeriod": <var>new_validity_period</var> + }, [])</code> + </blockquote> + + <p>The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.</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"> + <p>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).</p> + + <p>Connections with this interface SHOULD provide this property as a + parameter of the same (fully-qualified) name to <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >ConnectionManager.RequestConnection</tp:dbus-ref>, with the + <code>DBus_Property</code> flag. For connections managed by the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, + this property SHOULD be set via the Account Manager as follows:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageServiceCentre": <var>new_smsc_address</var> + }, [])</code> + </blockquote> + + <p>The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.</p> + </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> + + <property name="MessageReducedCharacterSet" + tp:name-for-bindings="Message_Reduced_Character_Set" + type="b" access="readwrite"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Determines whether SMSes containing characters that do not fit into + a 7‐bit GSM character set should be sent as UCS‐2, or lossily + recoded. If <code>False</code> (which SHOULD be the default), + messages will be sent with no loss of fidelity (at the potential + financial cost of using twice as many SMSes); if <code>True</code>, + the message will be recoded in an implementation‐specific way to fit + into a country‐specific GSM reduced character set.</p> + + <p>Connections with this interface SHOULD provide this property as a + parameter of the same (fully-qualified) name to <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >ConnectionManager.RequestConnection</tp:dbus-ref>, with the + <code>DBus_Property</code> flag. For connections managed by the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>, + this property SHOULD be set via the Account Manager as follows:</p> + + <blockquote> + <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Account" + >UpdateParameters</tp:dbus-ref>({ + "org.freedesktop.Telepathy.Connection.Interface.Cellular.MessageReducedCharacterSet": <var>new_value</var> + }, [])</code> + </blockquote> + + <p>The AccountManager provides change-notification, as long as all + other clients cooperate by using it instead of setting this property + directly.</p> + </tp:docstring> + </property> + </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 0000000..87ab752 --- /dev/null +++ b/spec/Connection_Interface_Contact_Groups.xml @@ -0,0 +1,447 @@ +<?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.DRAFT2"/> + <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>; clients can also + get extra context for group membership changes by receiving + <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> and + <tp:member-ref>GroupsRemoved</tp:member-ref>; clients can also + distinguish between a create/remove pair and a renamed group by + receiving <tp:member-ref>GroupRenamed</tp:member-ref>.</p> + + <p>This property's value is not meaningful until the initial contact + list has been received, in protocols where this is applicable. + Clients MAY wait for this property to be meaningful by calling + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.ContactList.DRAFT2" + >RequestContactList</tp:dbus-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.</p> + + <p>Immediately after this signal is emitted, + <tp:member-ref>GroupsCreated</tp:member-ref> MUST signal the + creation of a group with the new name, and + <tp:member-ref>GroupsRemoved</tp:member-ref> MUST signal the + removal of a group with the old name.</p> + + <tp:rationale> + <p>Emitting these extra signals, in this order, means that clients + that are interested in the set of groups that exist (but treat a + rename and a create/remove pair identically) to ignore the + GroupRenamed signal entirely.</p> + </tp:rationale> + + <p>If the group was not empty, immediately after those signals are + 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, renaming a + group MAY be signalled as a set of + <tp:member-ref>GroupsCreated</tp:member-ref>, + <tp:member-ref>GroupsRemoved</tp:member-ref> and + <tp:member-ref>GroupsChanged</tp:member-ref> signals, instead of + emitting this signal.</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 xmlns="http://www.w3.org/1999/xhtml"> + <p>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.</p> + + <tp:rationale> + <p>Emitting the signals in this order allows for two modes of + operation. A client interested only in a contact's set of groups + can ignore <tp:member-ref>GroupsRemoved</tp:member-ref> and rely + on the <tp:member-ref>GroupsChanged</tp:member-ref> signal that + will follow; a more elaborate client wishing to distinguish between + all of a group's members being removed, and the group itself + being removed, can additionally watch for + <tp:member-ref>GroupsRemoved</tp:member-ref> and use it to + disambiguate.</p> + </tp:rationale> + </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 d085454..ce77a56 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -17,9 +17,8 @@ Lesser General Public License for more details.</p> License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> </tp:license> - <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.17.18">(as a draft)</tp:added> + <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactInfo"> + <tp:added version="0.19.4">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <tp:struct name="Contact_Info_Field" array-name="Contact_Info_Field_List"> @@ -110,6 +109,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ city), region (e.g., state or province), the postal code, and the country name.</dd> + <dt>label</dt> + <dd>A free-form street address for the contact, formatted as a + single value (with embedded newlines where necessary) suitable for + printing on an address label</dd> + <dt>tel</dt> <dd>A telephone number for the contact.</dd> @@ -124,9 +128,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ VERSION:3.0 FN:Wee Ninja N;LANGUAGE=ja:Ninja;Wee;;;-san - ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement + ORG:Collabora, Ltd.;Management Division;Human Resources\; Company Policy Enforcement ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire ;CB2 1SJ;UK + LABEL;TYPE=WORK,POSTAL,PARCEL:11 Kings Parade\nCambridge\nCambridgeshire\nUK\nCB2 1SJ TEL;TYPE=VOICE,WORK:+44 1223 362967, +44 7700 900753 EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk EMAIL;TYPE=INTERNET:wee.ninja@example.com @@ -140,9 +145,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ [ ('fn', [], ['Wee Ninja']), ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']), - ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']), + ('org', [], ['Collabora, Ltd.', 'Management Division', + 'Human Resources; Company Policy Enforcement']), ('adr', ['type=work','type=postal','type=parcel'], ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']), + ('label', ['type=work','type=postal','type=parcel'], + ['''11 Kings Parade + Cambridge + Cambridgeshire + UK + CB2 1SJ''']), ('tel', ['type=voice','type=work'], ['+44 1223 362967']), ('tel', ['type=voice','type=work'], ['+44 7700 900753']), ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']), @@ -162,7 +174,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ name="Contact_Info"/> </tp:mapping> - <signal name="ContactInfoChanged" tp:name-for-bindings="ContactInfoChanged"> + <signal name="ContactInfoChanged" tp:name-for-bindings="Contact_Info_Changed"> <arg name="Contact" type="u" tp:type="Contact_Handle"> <tp:docstring> An integer handle for the contact whose info has changed. @@ -197,10 +209,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Request information on several contacts at once. This SHOULD only return cached information, omitting handles for which no information is - cached from the returned map. For contacts without cached information, - the information SHOULD be requested from the network, with the result - signalled later by <tp:member-ref>ContactInfoChanged</tp:member-ref>. + cached from the returned map. + </tp:docstring> + </method> + + <method name="RefreshContactInfo" + tp:name-for-bindings="Refresh_Contact_Info"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + Integer handles for contacts. + </tp:docstring> + </arg> + <tp:docstring> + Retrieve information for the given contact, requesting it from the + network if an up-to-date version is not cached locally. This method + SHOULD return immediately, emitting + <tp:member-ref>ContactInfoChanged</tp:member-ref> when the contacts' + updated contact information is returned. + + <tp:rationale> + This method allows a client with cached contact information to + update its cache after a number of days. + </tp:rationale> </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> </method> <method name="RequestContactInfo" @@ -219,8 +254,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Retrieve information for a contact, requesting it from the network if it is not cached locally. + + <tp:rationale> + This method is appropriate for an explicit user request to show + a contact's information; it allows a UI to wait for the contact + info to be returned. + </tp:rationale> </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.InvalidHandle"/> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> The contact's information could not be retrieved. @@ -262,7 +306,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> - <tp:enum name="Contact_Info_Flag" value-prefix="Contact_Info_Flag" + <tp:flags name="Contact_Info_Flags" value-prefix="Contact_Info_Flag" type="u"> <tp:docstring> Flags defining the behaviour of contact information on this protocol. @@ -271,24 +315,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ and when it changes. </tp:docstring> - <tp:enumvalue suffix="Can_Set" value="1"> + <tp:flag suffix="Can_Set" value="1"> <tp:docstring> Indicates that <tp:member-ref>SetContactInfo</tp:member-ref> is supported on this connection. </tp:docstring> - </tp:enumvalue> + </tp:flag> - <tp:enumvalue suffix="Push" value="2"> + <tp:flag suffix="Push" value="2"> <tp:docstring> Indicates that the protocol pushes all contacts' information to the connection manager without prompting. If set, - <tp:member-ref>RequestContactInfo</tp:member-ref> will not cause a - network roundtrip and <tp:member-ref>ContactInfoChanged</tp:member-ref> will be emitted whenever contacts' information changes. </tp:docstring> - </tp:enumvalue> - </tp:enum> + </tp:flag> + </tp:flags> <tp:simple-type name="VCard_Field" type="s"> <tp:docstring> @@ -309,10 +351,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:simple-type> <property name="ContactInfoFlags" type="u" access="read" - tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags"> - <tp:docstring> - An integer representing the bitwise-OR of flags on this connection. - This property should be constant over the lifetime of a connection. + tp:type="Contact_Info_Flags" tp:name-for-bindings="Contact_Info_Flags"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An integer representing the bitwise-OR of flags on this + connection.</p> + + <p>This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.</p> + + <tp:rationale> + <p>Some XMPP servers, like Facebook Chat, do not allow the vCard to + be changed (and so would not have the Can_Set flag). Whether the + user's server is one of these cannot necessarily be detected until + quite late in the connection process.</p> + </tp:rationale> + </tp:docstring> </property> @@ -328,8 +382,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]"> <tp:docstring>The set of vCard type parameters which may be set on this field. If this list is empty and the - Contact_Info_Field_Flag_Parameters_Mandatory - flag is unset, any vCard type parameters may be used.</tp:docstring> + Contact_Info_Field_Flag_Parameters_Exact flag is not set, any vCard type + parameters may be used.</tp:docstring> </tp:member> <tp:member type="u" name="Flags" tp:type="Contact_Info_Field_Flags"> @@ -352,10 +406,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ list indicates that arbitrary vCard fields are permitted. This property SHOULD be the empty list, and be ignored by clients, if <tp:member-ref>ContactInfoFlags</tp:member-ref> does not contain the - Can_Set <tp:type>Contact_Info_Flag</tp:type>.</p> + Can_Set flag.</p> - <p>For example, an implementation of XEP-0054, which defines a mapping - of vCards to XML for use over XMPP, would set this property to the + <p>For example, a protocol in which arbitrary vCards were stored + as-is would set this property to the empty list. A protocol whose notion of contact information is one each of personal phone number, mobile phone number, location, email address and date of birth, with no attributes allowed on each piece @@ -364,22 +418,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <pre> [ - ('tel', ['home'], Parameters_Mandatory, 1), - ('tel', ['cell'], Parameters_Mandatory, 1), - ('adr', [], Parameters_Mandatory, 1), - ('bday', [], Parameters_Mandatory, 1), - ('email', ['internet'], Parameters_Mandatory, 1), + ('tel', ['type=home'], Parameters_Exact, 1), + ('tel', ['type=cell'], Parameters_Exact, 1), + ('adr', [], Parameters_Exact, 1), + ('bday', [], Parameters_Exact, 1), + ('email', ['type=internet'], Parameters_Exact, 1), ]</pre> <p>A protocol which allows users to specify up to four phone numbers, which may be labelled as personal and/or mobile, would set this - property to <code>[ ('tel', ['home', 'cell'], 0, 4), ]</code>.</p> + property to + <code>[ ('tel', ['type=home', 'type=cell'], 0, 4), ]</code>.</p> <tp:rationale> <p>Studying existing IM protocols shows that in practice protocols allow either a very restricted set of fields (such as MSN, which - seems to correspond roughly to the largest example above) or - something mapping 1-1 to vCard (such as XMPP).</p> + seems to correspond roughly to the largest example above), or + something mapping 1:1 to a large subset of vCard (such as XMPP's + XEP-0054).</p> + </tp:rationale> + + <p>This property MAY change, without change notification, at any time + before the connection moves to status Connection_Status_Connected. + It MUST NOT change after that point.</p> + + <tp:rationale> + <p>Some XMPP servers, like Google Talk, only allow a small subset of + the "vcard-temp" protocol. Whether the user's server is one of + these cannot be detected until quite late in the connection + process.</p> </tp:rationale> </tp:docstring> </property> @@ -389,7 +456,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Flags describing the behaviour of a vCard field. </tp:docstring> - <tp:flag suffix="Parameters_Mandatory" value="1"> + <tp:flag suffix="Parameters_Exact" value="1"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If present, exactly the parameters indicated must be set on this field; in the case of an empty list of parameters, this implies that @@ -411,7 +478,43 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:type>Contact_Info_Field</tp:type>s forming a structured representation of a vCard (as defined by RFC 2426), using field names and semantics defined therein.</p> + + <p>On some protocols, information about your contacts is pushed to you, + with change notification; on others, like XMPP, the client must + explicitly request the avatar, and has no way to tell whether it has + changed without retrieving it in its entirety. This distinction is + exposed by <tp:member-ref>ContactInfoFlags</tp:member-ref> containing + the Push flag.</p> + + <p>On protocols with the Push flag set, UIs can connect to + <tp:member-ref>ContactInfoChanged</tp:member-ref>, call + <tp:member-ref>GetContactInfo</tp:member-ref> once at login for the set + of contacts they are interested in, and then be sure they will receive + the latest contact info. On protocols like XMPP, clients can do the + same, but will receive (at most) opportunistic updates if the info is + retrieved for other reasons. Clients may call + <tp:member-ref>RequestContactInfo</tp:member-ref> or + <tp:member-ref>RefreshContactInfo</tp:member-ref> to force a contact's + info to be updated, but MUST NOT do so unless this is either in + response to direct user action, or to refresh their own cache after a + number of days.</p> + + <tp:rationale> + <p>We don't want clients to accidentally cause a ridiculous amount of + 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 0000000..9db86aa --- /dev/null +++ b/spec/Connection_Interface_Contact_List.xml @@ -0,0 +1,865 @@ +<?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.DRAFT2" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.19.8">(draft 2)</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>RequestContactList</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>RequestContactList</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="RequestContactList" + tp:name-for-bindings="Request_Contact_List"> + <tp:changed version="0.19.8">(in draft: renamed from + GetContactListAttributes)</tp:changed> + <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>, + except that if this list does not contain the ContactList + interface itself, it is treated as though that interface was also + requested.</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> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received, in protocols where this is applicable. + Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + </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> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received, in protocols where this is applicable. + Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</p> + </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> + + <p>This attribute SHOULD be omitted from the + <tp:type>Contact_Attributes_Map</tp:type> returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts" + >GetContactAttributes</tp:dbus-ref> until the initial contact + list has been received. Clients MAY wait for this by calling + <tp:member-ref>RequestContactList</tp:member-ref>.</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>RequestContactList</tp:member-ref>, + or when contacts 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>RequestContactList</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>RequestContactList</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 73051f4..e5457b1 100644 --- a/spec/Connection_Interface_Forwarding.xml +++ b/spec/Connection_Interface_Forwarding.xml @@ -1,78 +1,346 @@ <?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> + + <p>When an unanswered <tp:dbus-ref + namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> call is + forwarded, both the contact and the self handle should be removed from + the group with the self handle as the actor, and + <tp:type>Channel_Group_Change_Reason</tp:type> <code>No_Answer</code> or + <code>Busy</code>, as appropriate. For <tp:dbus-ref + namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref> channels, the + <tp:type>Call_State_Change_Reason</tp:type> <code>Forwarded</code> + should be used.</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 xmlns="http://www.w3.org/1999/xhtml"> + <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 xmlns="http://www.w3.org/1999/xhtml"> + <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> + </tp:member> + + <tp:member type="u" tp:type="Contact_Handle" name="Handle"> <tp:docstring> - An integer contact handle to whom incoming communication is forwarded + 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> - </arg> + </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 xmlns="http://www.w3.org/1999/xhtml"> + <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.</p> + + <tp:rationale> + <p>When forwarding is done by the provider, different providers + might support different chain sizes, or provider and local + implementation chain sizes might differ.</p> + </tp:rationale> + </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 xmlns="http://www.w3.org/1999/xhtml"> + <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> - An integer contact handle to forward incoming communications to + 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> + 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 xmlns="http://www.w3.org/1999/xhtml"> + <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 fdc622e..6c69a80 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 35678c2..cfe67a8 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 @@ -353,17 +361,30 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>If <tt>Thread_Based</tt> appears in the <tp:member-ref>MailNotificationFlags</tp:member-ref>, this property counts the number of threads, not the number of mails.</p> + + <p>Note that this count MAY be bigger than the number of items in + <tp:member-ref>UnreadMails</tp:member-ref>. See + <tp:member-ref>UnreadMails</tp:member-ref> for more details.</p> </tp:docstring> </property> <property name="UnreadMails" type="aa{sv}" tp:type="Mail[]" tp:name-for-bindings="Unread_Mails" access="read"> <tp:docstring> - A array of unread <tp:type>Mail</tp:type>s. Change notification is via - <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property is - only useful if <tt>Supports_Unread_Mails</tt> is set in - <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it MUST be - an empty list. + <p>An array of unread <tp:type>Mail</tp:type>s. Change notification is + via <tp:member-ref>UnreadMailsChanged</tp:member-ref>. This property + is only useful if <tt>Supports_Unread_Mails</tt> is set in + <tp:member-ref>MailNotificationFlags</tp:member-ref>; otherwise, it + MUST be an empty list.</p> + <p>The array size MAY be shorter than + <tp:member-ref>UnreadMailCount</tp:member-ref>.</p> + <tp:rationale> + <p>Some servers may limits the amount of detailed e-mails sent. This + can significantly reduce the network traffic for large inbox. For + this reason, it is normal that + <tp:member-ref>UnreadMailCount</tp:member-ref> be bigger or equal + to the size of this array.</p> + </tp:rationale> </tp:docstring> </property> diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml index d8239e5..2f233fa 100644 --- a/spec/Connection_Interface_Requests.xml +++ b/spec/Connection_Interface_Requests.xml @@ -550,6 +550,16 @@ available to old or minimal clients SHOULD have a channel class with the minimum number of Fixed_Properties, and MAY additionally have channel classes with extra Fixed_Properties.</p> + + <p>Interface designers SHOULD avoid introducing fixed properties + whose types are not serializable in a <code>.manager</code> + file.</p> + + <tp:rationale> + <p>Connection managers with a fixed property that is not + serializable cannot have a complete <code>.manager</code> + file.</p> + </tp:rationale> </tp:docstring> </tp:member> diff --git a/spec/Connection_Interface_Service_Point.xml b/spec/Connection_Interface_Service_Point.xml new file mode 100644 index 0000000..b135c04 --- /dev/null +++ b/spec/Connection_Interface_Service_Point.xml @@ -0,0 +1,136 @@ +<?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"> + <tp:added version="0.19.7">(as stable API)</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="Service_Point"> + <tp:docstring> + The service point. + </tp:docstring> + </tp:member> + <tp:member type="as" name="Service_IDs"> + <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 the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface.ServicePoint">InitialServicePoint</tp:dbus-ref> + property in a channel request. + </tp:docstring> + </tp:member> + <tp:docstring> + <p>Description of a service point and IDs which are mapped to it.</p> + + <p>An example Service Point info for GSM emergency calls (callable + through "911" and "112") could look like:</p> + +<pre> + ServicePointInfo = ( + Service_Point: ( + Service_Point_Type: 1 (Emergency), + Service_Point: "urn:service:sos" + ), + Service_IDs: [ "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="Service_Points" type="a((us)as)" tp:type="Service_Point_Info[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The new value of + <tp:member-ref>KnownServicePoints</tp:member-ref>.</p> + </tp:docstring> + </arg> + <tp:docstring> + Emitted when the list of known service points (or their IDs) has + changed. + </tp:docstring> + </signal> + + <tp:struct name="Service_Point"> + <tp:docstring>A service point.</tp:docstring> + <tp:member type="u" name="Service_Point_Type" + 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 a 'service' Uniform Resource Name as + specified by <a + href="http://www.rfc-editor.org/rfc/rfc5031.txt">RFC 5031</a>, + 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 a channel might connect to. + </tp:docstring> + + <tp:enumvalue value="0" suffix="None"> + <tp:docstring> + The channel is not communicating with a service point, or it is not + known whether it is communicating with a service point (e.g. an + ordinary call). + </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> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Connection_Manager.xml b/spec/Connection_Manager.xml index c4fecd6..709a9b9 100644 --- a/spec/Connection_Manager.xml +++ b/spec/Connection_Manager.xml @@ -80,8 +80,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <li>sip - Session Initiation Protocol (SIP), with or without SIMPLE support</li> <li>skype - Skype</li> - <li>tel - telephony (the PSTN, including GSM, CDMA and fixed-line - telephony)</li> + <li>tel - telephony (the + <abbr title="Public Switched Telephone Network">PSTN</abbr>, + including GSM, CDMA and fixed-line telephony)</li> <li>trepia - Trepia</li> <li>yahoo - YMSG (Yahoo! Messenger)</li> <li>yahoojp - Japanese version of YMSG</li> @@ -186,10 +187,50 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> + <tp:mapping name="Protocol_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from protocol identifiers supported by a connection + manager to the immutable properties of the corresponding + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Protocol</tp:dbus-ref> objects.</p> + </tp:docstring> + + <tp:member name="Protocol" type="s" tp:type="Protocol"> + <tp:docstring>A protocol name</tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring>The immutable properties of the corresponding + Protocol object</tp:docstring> + </tp:member> + </tp:mapping> + + <property name="Protocols" tp:name-for-bindings="Protocols" + access="read" type="a{sa{sv}}" tp:type="Protocol_Properties_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A map from protocol identifiers supported by this connection + manager to the immutable properties of the corresponding + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Protocol</tp:dbus-ref> objects.</p> + + <tp:rationale> + <p>Providing the immutable properties here means that + when the API of Protocol objects has been finalized, + most clients will only need one D-Bus round trip to interrogate + the ConnectionManager about all its protocols.</p> + </tp:rationale> + + <p>If this map is empty or missing, clients SHOULD fall back to + calling <tp:member-ref>ListProtocols</tp:member-ref> and + <tp:member-ref>GetParameters</tp:member-ref>.</p> + </tp:docstring> + </property> + <method name="ListProtocols" tp:name-for-bindings="List_Protocols"> <arg direction="out" type="as" tp:type="Protocol[]" name="Protocols"> <tp:docstring> - A array of string protocol identifiers supported by this manager + The keys of the <tp:member-ref>Protocols</tp:member-ref> map. </tp:docstring> </arg> <tp:docstring> @@ -369,17 +410,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <p>To be compatible with older connection managers, if retrieving this property fails, clients SHOULD assume that its value is an empty list.</p> + + <p>Connection managers with a non-empty list of Interfaces MUST + represent them in the <code>.manager</code> file, if they have one, + as an <code>Interfaces</code> key in the + group headed <code>[ConnectionManager]</code>, whose value is a list + of strings each followed by a semicolon.</p> </tp:docstring> <tp:added version="0.17.8"/> </property> - <!-- FIXME: One thing we could perhaps use Interfaces for would be a - ConnectionManager.Interface.Capabilities that can give hints regarding - the capabilities (in the sense of - Connection.Interface.Requests.AvailableChannelClasses and/or - Connection.GetInterfaces()) that a Connection from this CM is likely - to have --> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A D-Bus service which allows connections to be created. The manager processes are intended to be started by D-Bus service activation.</p> @@ -436,6 +476,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ a plugin architecture) should not install a <code>.manager</code> file.</p> + <p>The <code>.manager</code> file SHOULD have a group headed + <code>[ConnectionManager]</code>, containing a key + <code>Interfaces</code> representing + <tp:member-ref>Interfaces</tp:member-ref> as a sequence of strings + each followed by a semicolon (the "localestrings" type from the Desktop + Entry Specification).</p> + + <p>The <code>[ConnectionManager]</code> group SHOULD NOT contain keys + <code>ObjectPath</code> or <code>BusName</code>. If it does, they MUST + be ignored.</p> + + <tp:rationale> + <p>The object path and bus name are derivable from the connection + manager's name, which is part of the filename, so these keys are + redundant. They were required in very old versions of Telepathy.</p> + </tp:rationale> + <p>For each protocol name <em>proto</em> that would be returned by ListProtocols, the .manager file contains a group headed <code>[Protocol <em>proto</em>]</code>. For each parameter diff --git a/spec/Protocol.xml b/spec/Protocol.xml new file mode 100644 index 0000000..91c350f --- /dev/null +++ b/spec/Protocol.xml @@ -0,0 +1,369 @@ +<?xml version="1.0" ?> +<node name="/Protocol" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-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.Protocol"> + <tp:added version="0.19.10">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An object representing a protocol for which this <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref> + can create <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s.</p> + + <p>Each Protocol object has the same well-known bus name as its parent + ConnectionManager. Its object path is formed by taking the + ConnectionManager's object path and appending '/', followed by the + <tp:type>Protocol</tp:type> name with any hyphen/minus '-' converted + to underscores '_'.</p> + + <tp:rationale> + <p>This is the same as the representation of protocol names + in Account object paths, and in Connection object paths and bus + names. For instance, telepathy-gabble and telepathy-salut would + implement objects at + <code>/org/freedesktop/Telepathy/ConnectionManager/gabble/jabber</code> + and + <code>/org/freedesktop/Telepathy/ConnectionManager/salut/local_xmpp</code>, + respectively.</p> + </tp:rationale> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + access="read" type="as" tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of interfaces supported by this Protocol object.</p> + + <p>This property is immutable, and should not be confused with + <tp:member-ref>ConnectionInterfaces</tp:member-ref>, + which refers to the interfaces of <em>connections</em> to this + protocol.</p> + + <p>Connection managers with a <code>.manager</code> file + (as described as part of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface) MUST cache this + property in the protocol's section of the <code>.manager</code> + file, using the key <code>Interfaces</code>. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.</p> + </tp:docstring> + </property> + + <property name="Parameters" tp:name-for-bindings="Parameters" + access="read" type="a(susv)" tp:type="Param_Spec[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The parameters which must or may be provided to the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> method when connecting to the + given protocol. This property is immutable.</p> + + <p>Connection managers with a <code>.manager</code> file + (as described as part of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface) MUST cache this + property in the protocol's section of the <code>.manager</code> + file via keys of the form <code>param-<em>p</em></code> and + <code>default-<em>p</em></code>, as documented in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> interface.</p> + </tp:docstring> + </property> + + <property name="ConnectionInterfaces" + tp:name-for-bindings="Connection_Interfaces" + access="read" type="as" tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of interface names which might be in the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection" + >Interfaces</tp:dbus-ref> property of a + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref> to this protocol. Whether a Connection + will have all, some or none of these interfaces depends on server + capabilities.</p> + + <p>This property is immutable, and should not be confused with + <tp:member-ref>Interfaces</tp:member-ref>.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file, using the key + <code>ConnectionInterfaces</code>. The corresponding value + is a list of D-Bus interface names, each followed by a semicolon.</p> + </tp:docstring> + </property> + + <property name="RequestableChannelClasses" + tp:name-for-bindings="Requestable_Channel_Classes" + access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of channel classes which might be requestable from a + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref> to this protocol (i.e. they will, + or might, appear in the Connection's <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Requests" + >RequestableChannelClasses</tp:dbus-ref> property).</p> + + <p>Whether a Connection will have all, some or none of these + requestable channel classes depends on server capabilities; + similarly, individual contacts are not guaranteed to support + all of these channel classes.</p> + + <p>This property is immutable.</p> + + <p>Connection managers with a <code>.manager</code> file + MUST cache this property in the protocol's section of the + <code>.manager</code> file, using the key + <code>RequestableChannelClasses</code>. The corresponding value + is a list of opaque strings, each followed by a semicolon; each + of those strings is the name of a group in the <code>.manager</code> + file which represents a channel class.</p> + + <p>Each group representing a channel class has a key + <code>allowed</code> which is a list of D-Bus property names + representing allowed parameters. Any other keys that do not contain + a space MUST be ignored. Any key containing a space represents + a fixed property; the key has the form + "<code><em>propertyname</em> <em>type</em></code>", and the value + is encoded in the same way as for the <code>default-<em>p</em></code> + keys described in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >ConnectionManager</tp:dbus-ref> documentation.</p> + + <p>Connection managers that have channel classes whose fixed + properties are not representable in this form SHOULD NOT have + <code>.manager</code> files.</p> + + <p>For instance, this <code>.manager</code> file could represent + a simple Text-only connection manager:</p> + +<pre>[Protocol jabber] +param-account=s required +param-password=s required +RequestableChannelClasses=text + +[text] +org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy.Channel.TargetID; +</pre> + </tp:docstring> + </property> + + <property name="VCardField" tp:name-for-bindings="VCard_Field" + access="read" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the most common vCard field used for this protocol's + contact identifiers, normalized to lower case, or the empty string + if there is no such field.</p> + + <p>For example, this would be <code>x-jabber</code> for + Jabber/XMPP (including Google Talk), or <code>tel</code> for + the <abbr title="Public Switched Telephone Network">PSTN</abbr>.</p> + + <tp:rationale> + <p>This is taken from Mission Control profiles as used on Maemo 5. + One valid use of this field is to answer the question: given a + contact's vCard containing an X-JABBER field, how can you + communicate with the contact? By iterating through protocols + looking for an x-jabber VCardField, one can build up a list of + protocols that handle x-jabber, then offer the user a list of + accounts for those protocols and/or the option to create a new + account for one of those protocols.</p> + + <p>It is not necessarily valid to interpret contacts' identifiers + as values of this vCard field. For instance, telepathy-sofiasip + supports contacts whose identifiers are of the form + sip:jenny@example.com or tel:8675309, which would not normally + both be represented by any single vCard field. Representing + arbitrary handles/identifiers as vCard fields is a topic for + future work.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="EnglishName" tp:name-for-bindings="English_Name" + access="read" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the protocol in a form suitable for display to users, + such as "AIM" or "Yahoo!", or the empty string if none is + available.</p> + + <p>This is effectively in the C locale (international English); + user interfaces requiring a localized protocol name SHOULD look + one up in their own message catalog based on either the Telepathy + <tp:type>Protocol</tp:type> name or this property, but SHOULD use + this English version as a fallback if no translated version can be + found.</p> + + <tp:rationale> + <p>Many protocols are named after a company or product which isn't + translated in non-English locales. This also provides a fallback + display name, for UIs with no prior knowledge of a particular + protocol.</p> + </tp:rationale> + + <p>If this property's value is empty, clients MAY fall back to using + the Telepathy <tp:type>Protocol</tp:type> name, possibly with its + capitalization adjusted.</p> + </tp:docstring> + </property> + + <property name="Icon" tp:name-for-bindings="Icon" + access="read" type="s"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of an icon in the system's icon theme, such as "im-msn", or + the empty string.</p> + + <tp:rationale> + <p>This can be used as a default if the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref> + property is not set on an Account, or used by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref> + to choose a default icon if none is set during account + creation.</p> + </tp:rationale> + + <p>If this property's value is empty, clients MAY fall back to + generating a name based on the <tp:type>Protocol</tp:type> name.</p> + </tp:docstring> + </property> + + <method name="IdentifyAccount" + tp:name-for-bindings="Identify_Account"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Return a string which uniquely identifies the account to which the + given parameters would connect.</p> + + <tp:rationale> + <p>For many protocols, this would return the well-known 'account' + parameter. However, for IRC the returned string would be composed + from the 'account' (i.e. nickname) and 'server' parameters. + AccountManager implementations can use this to form the + account-specific part of an Account's object path.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Parameters" + type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + A set of parameters as would be provided to <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ConnectionManager" + >RequestConnection</tp:dbus-ref> + </tp:docstring> + </arg> + + <arg direction="out" name="Account_ID" type="s"> + <tp:docstring> + <p>An opaque string suitable for use as the account-specific part of + an <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Account</tp:dbus-ref>'s object path. This is not necessarily + globally unique, but should represent a "best-effort" + identification of the account.</p> + + <tp:rationale> + <p>For a pathological case, consider a user signing in as + 'me@example.com' with 'server' set to either jabber1.example.com + or jabber2.example.com. Both of these should result in + me@example.com being returned from this method, even if the user + can actually be signed in to those two servers + simultaneously.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The IdentifyAccount method is not supported by this connection + manager. The caller SHOULD fall back to deriving identification + from the parameters. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="NormalizeContact" + tp:name-for-bindings="Normalize_Contact"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Attempt to normalize the given contact ID. Where possible, this + SHOULD return the same thing that would be returned by + InspectHandles(RequestHandles(CONTACT, [Contact_ID])) on a connected + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection</tp:dbus-ref>.</p> + + <p>If full normalization requires network activity or is otherwise + impossible to do without a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, + this method SHOULD perform a best-effort normalization.</p> + + <tp:rationale> + <p>One common example of a best-effort offline normalization + differing from the ideal normalization is XMPP.</p> + + <p>On XMPP, contacts' JIDs should normally have the resource removed + during normalization, but for contacts in a MUC (chatroom), the + resource is an integral part of the JID - so the contact JID + alice@example.com/Empathy should normalize to alice@example.com, + but the in-MUC JID wonderland@conference.example.com/Alice should + normalize to itself.</p> + + <p>While online, the connection manager has enough context to know + which chatrooms the user is in, and can infer from that whether + to remove resources, but the best-effort normalization performed + while offline does not have this context, so the best that can be + done is to remove the resource from all JIDs.</p> + </tp:rationale> + + <p>This method MAY simply raise NotImplemented on some protocols.</p> + + <tp:rationale> + <p>In link-local XMPP, you can't talk to someone who isn't present + on your local network, so normalizing identifiers in advance is + meaningless.</p> + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact_ID" type="s"> + <tp:docstring> + The identifier of a contact in this protocol + </tp:docstring> + </arg> + + <arg direction="out" name="Normalized_Contact_ID" type="s"> + <tp:docstring> + The identifier of a contact in this protocol, normalized as much + as possible + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The NormalizeContact method is not supported by this connection + manager. The caller MAY recover by using the contact ID as-is. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Protocol_Interface_Avatars.xml b/spec/Protocol_Interface_Avatars.xml new file mode 100644 index 0000000..262741e --- /dev/null +++ b/spec/Protocol_Interface_Avatars.xml @@ -0,0 +1,158 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Avatars" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-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.Protocol.Interface.Avatars.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.8">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols where it might be possible to set the + user's avatar, and the expected size limits and supported MIME types + are known before connecting.</p> + + <tp:rationale> + <p>If the avatar requirements cannot be discovered while offline, + it's impossible to avoid setting the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Account</tp:dbus-ref>'s <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Account.Interface.Avatar" + >Avatar</tp:dbus-ref> property to an unsupported avatar.</p> + </tp:rationale> + + <p>Each property on this interface SHOULD be cached in the + <code>.manager</code> file, using a key of the same name as the + property in the <code>[Protocol <em>proto</em>]</code> + group. All properties are encoded in ASCII decimal in the obvious + way, except for + <tp:member-ref>SupportedAvatarMIMETypes</tp:member-ref> which is + encoded as a sequence of strings each followed by a semicolon + (as for the "localestrings" type in the Desktop Entry + Specification).</p> + + <p>For instance, an XMPP connection manager might have this + <code>.manager</code> file:</p> + +<pre>[Protocol jabber] +Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Avatars; +param-account=s required +param-password=s required +SupportedAvatarMIMETypes=image/png;image/jpeg;image/gif; +MinimumAvatarHeight=32 +RecommendedAvatarHeight=64 +MaximumAvatarHeight=96 +MinimumAvatarWidth=32 +RecommendedAvatarWidth=64 +MaximumAvatarWidth=96 +MaximumAvatarBytes=8192 +</pre> + </tp:docstring> + + <property name="SupportedAvatarMIMETypes" + tp:name-for-bindings="Supported_Avatar_MIME_Types" + type="as" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.SupportedAvatarMIMETypes</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MinimumAvatarHeight" + tp:name-for-bindings="Minimum_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MinimumAvatarHeight</tp:dbus-ref> + property on connections to this protocol. +</tp:docstring> + </property> + + <property name="MinimumAvatarWidth" + tp:name-for-bindings="Minimum_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MinimumAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="RecommendedAvatarHeight" + tp:name-for-bindings="Recommended_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.RecommendedAvatarHeight</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="RecommendedAvatarWidth" + tp:name-for-bindings="Recommended_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.RecommendedAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarHeight" + tp:name-for-bindings="Maximum_Avatar_Height" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarHeight</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarWidth" + tp:name-for-bindings="Maximum_Avatar_Width" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarWidth</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + + <property name="MaximumAvatarBytes" + tp:name-for-bindings="Maximum_Avatar_Bytes" + type="u" access="read"> + <tp:docstring> + The expected value of the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.Avatars.MaximumAvatarBytes</tp:dbus-ref> + property on connections to this protocol. + </tp:docstring> + </property> + </interface> +</node> diff --git a/spec/Protocol_Interface_Presence.xml b/spec/Protocol_Interface_Presence.xml new file mode 100644 index 0000000..47a37ea --- /dev/null +++ b/spec/Protocol_Interface_Presence.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" ?> +<node name="/Protocol_Interface_Presence" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright © 2009-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.Protocol.Interface.Presence.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.8">(draft 1)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface for protocols where it might be possible to set the + user's presence, and the supported presence types can be predicted + before connecting.</p> + + <tp:rationale> + <p>This allows UIs to show or hide presence types that aren't + always supported, such as "invisible", while not online.</p> + </tp:rationale> + + <p>The properties on this interface SHOULD be cached in the + <code>.manager</code> file, in the + <code>[Protocol <em>proto</em>]</code> + group. For each status <em>s</em> in + <tp:member-ref>Statuses</tp:member-ref>, that group should + contain a key of the form <code>status-<em>s</em></code> whose value + is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII + decimal integer, followed by a space-separated sequence of tokens + from the following set:</p> + + <dl> + <dt>settable</dt> + <dd>If present, the user can set this status on themselves using + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence" + >SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self + in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd> + + <dt>message</dt> + <dd>If present, the user can set a non-empty message for this status; + this corresponds to Can_Have_Message in the + <tp:type>Simple_Status_Spec</tp:type> struct.</dd> + </dl> + + <p>Unrecognised tokens MUST be ignored.</p> + + <p>For instance, an XMPP connection manager might have this + <code>.manager</code> file:</p> + +<pre>[Protocol jabber] +Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence; +param-account=s required +param-password=s required +status-offline=1 +status-unknown=7 +status-error=8 +status-hidden=5 settable message +status-xa=4 settable message +status-away=3 settable message +status-dnd=6 settable message +status-available=2 settable message +status-chat=2 settable message +</pre> + + <p>which corresponds to these property values (using a Python-like + syntax):</p> + +<pre>Statuses = { + 'offline': (OFFLINE, False, False), + 'unknown': (UNKNOWN, False, False), + 'error': (ERROR, False, False), + 'hidden': (HIDDEN, True, True), + 'xa': (EXTENDED_AWAY, True, True), + 'away': (AWAY, True, True), + 'dnd': (BUSY, True, True), + 'available': (AVAILABLE, True, True), + 'chat': (AVAILABLE, True, True), +} +</pre> + </tp:docstring> + + <property name="Statuses" + tp:name-for-bindings="Statuses" + type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read"> + <tp:docstring> + <p>The statuses that might appear in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy" + >Connection.Interface.SimplePresence.Statuses</tp:dbus-ref> + property on a connection to this protocol that supports + SimplePresence. This property is immutable.</p> + + <p>Depending on server capabilities, it is possible that not all + of these will actually appear on the Connection.</p> + </tp:docstring> + </property> + + </interface> +</node> diff --git a/spec/all.xml b/spec/all.xml index 0ec4708..9140a1f 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.3</tp:version> +<tp:version>0.19.10</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> @@ -32,6 +32,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> </tp:docstring> <xi:include href="Connection_Manager.xml"/> + <xi:include href="Protocol.xml"/> + <xi:include href="Protocol_Interface_Avatars.xml"/> + <xi:include href="Protocol_Interface_Presence.xml"/> <tp:section name="Connection Object"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> @@ -42,17 +45,23 @@ 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_Mail_Notification.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> <xi:include href="Connection_Interface_Renaming.xml"/> <xi:include href="Connection_Interface_Requests.xml"/> + <xi:include href="Connection_Interface_Service_Point.xml"/> <xi:include href="Connection_Interface_Simple_Presence.xml"/> </tp:section> @@ -80,16 +89,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Each Channel implements one of the following types: </p> </tp:docstring> + <xi:include href="Channel_Type_Call.xml"/> <xi:include href="Channel_Type_Contact_List.xml"/> - <xi:include href="Channel_Type_Streamed_Media.xml"/> + <xi:include href="Channel_Type_Contact_Search.xml"/> + <xi:include href="Channel_Type_DBus_Tube.xml"/> + <xi:include href="Channel_Type_File_Transfer.xml"/> <xi:include href="Channel_Type_Room_List.xml"/> + <xi:include href="Channel_Type_Stream_Tube.xml"/> + <xi:include href="Channel_Type_Streamed_Media.xml"/> <xi:include href="Channel_Type_Text.xml"/> <xi:include href="Channel_Type_Tubes.xml"/> - <xi:include href="Channel_Type_Stream_Tube.xml"/> - <xi:include href="Channel_Type_DBus_Tube.xml"/> - <xi:include href="Channel_Type_File_Transfer.xml"/> - <xi:include href="Channel_Type_Contact_Search.xml"/> - <xi:include href="Channel_Type_Call.xml"/> </tp:section> <tp:section name="Channel Interfaces"> @@ -99,18 +108,20 @@ 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"/> - <xi:include href="Channel_Interface_Destroyable.xml"/> <xi:include href="Channel_Interface_DTMF.xml"/> + <xi:include href="Channel_Interface_Destroyable.xml"/> <xi:include href="Channel_Interface_Group.xml"/> - <xi:include href="Channel_Interface_Hold.xml"/> <xi:include href="Channel_Interface_HTML.xml"/> - <xi:include href="Channel_Interface_Password.xml"/> + <xi:include href="Channel_Interface_Hold.xml"/> <xi:include href="Channel_Interface_Media_Signalling.xml"/> <xi:include href="Channel_Interface_Mergeable_Conference.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> + <xi:include href="Channel_Interface_Password.xml"/> + <xi:include href="Channel_Interface_Service_Point.xml"/> <xi:include href="Channel_Interface_Splittable.xml"/> <xi:include href="Channel_Interface_Tube.xml"/> </tp:section> @@ -124,6 +135,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"/> @@ -147,6 +159,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Account_Manager.xml"/> <xi:include href="Account.xml"/> <xi:include href="Account_Interface_Avatar.xml"/> + <xi:include href="Account_Interface_Storage.xml"/> </tp:section> <tp:section name="The Channel Dispatcher"> @@ -185,8 +198,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 22a629b..60a93c9 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. @@ -397,7 +420,20 @@ </tp:docstring> </tp:error> - <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> + <tp:error name="Would Break Anonymity"> + <tp:added version="0.19.7"/> + <tp:docstring> + Raised if a request cannot be satisfied without violating an earlier + request for anonymity, and the earlier request specified that raising + an error is preferable to disclosing the user's identity (for instance + via <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Connection.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy" + >Channel.Interface.Anonymity.AnonymityMandatory</tp:dbus-ref>). + </tp:docstring> + </tp:error> + + <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or diff --git a/spec/generic-types.xml b/spec/generic-types.xml index d4dce15..c017ba5 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> diff --git a/spec/template.xml b/spec/template.xml new file mode 100644 index 0000000..d752d72 --- /dev/null +++ b/spec/template.xml @@ -0,0 +1,33 @@ +<?xml version="1.0" ?> +<node name="/Foo" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <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.Foo.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.UNRELEASED">(draft 1)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Foo.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |