diff options
| author | Jonny Lamb <jonny.lamb@collabora.co.uk> | 2010-12-16 11:14:51 +0000 |
|---|---|---|
| committer | Jonny Lamb <jonny.lamb@collabora.co.uk> | 2010-12-16 11:14:51 +0000 |
| commit | 2e6318650c968f2372b1337535910c59437e4375 (patch) | |
| tree | a7851e743d549562a27f03997e366d231ca3ee7d | |
| parent | 83fa2c4dea286b4cbc96814361c9dacca78a2f21 (diff) | |
spec: update to version 0.21.7
Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>
28 files changed, 2118 insertions, 264 deletions
diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml new file mode 100644 index 0000000..4b2846b --- /dev/null +++ b/spec/Account_Interface_Addressing.xml @@ -0,0 +1,76 @@ +<?xml version="1.0" ?> +<node name="/Account_Interface_Addressing" 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.Account.Interface.Addressing"> + <tp:requires interface="org.freedesktop.Telepathy.Account"/> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Some accounts can be used for multiple protocols; for instance, SIP + and Skype accounts can often be used to contact the PSTN, MSN and + Yahoo accounts can contact each other, and XMPP accounts can + potentially contact many protocols via a transport.</p> + <p>However, if the user does not intend to make use of this functionality, + user interfaces can improve clarity by not displaying it: for instance, + if a user prefers to call phone numbers via a particular SIP account, + when an address book displays a contact with a phone number, it is + desirable to display a "call with SIP" button for that account, but + avoid displaying similar buttons for any other configured SIP or + Skype accounts.</p> + <p>The purpose of this interface is to allow this "for use with" information + to be recorded and retrieved.</p> + </tp:docstring> + + <property name="URISchemes" type="as" access="read" + tp:name-for-bindings="URI_Schemes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of fields indicating the type of URI addressing scheme + the the account should be used for (eg 'tel') indicating the + account is intended for use by applications offering a telephony + UI, or 'sip' or 'xmpp' for those protocols</p> + <p>Note that these fields signify intent, not ability: It is + entirely possible that an account which can be used for a + given URI scheme is not wanted for it by the user, and + therefore not flagged as such in this field.</p> + </tp:docstring> + </property> + + <method name="SetURISchemeAssociation" + tp:name-for-bindings="Set_URI_Scheme_Association"> + <tp:docstring> + <p>Associate (or disassociate) an account with a particular + URI addressing scheme, (such as 'tel' for telephony)</p> + </tp:docstring> + + <arg name="URI_Scheme" direction="in" type="s"> + <tp:docstring> + <p>URI scheme to associate/disassociate the account with/from</p> + </tp:docstring> + </arg> + + <arg name="Association" direction="in" type="b"> + <tp:docstring> + <p>True to associate this account with a given addressing scheme</p> + <p>False if the account should not be associated with said scheme</p> + </tp:docstring> + </arg> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml index e0a791f..f88143f 100644 --- a/spec/Call_Content_Codec_Offer.xml +++ b/spec/Call_Content_Codec_Offer.xml @@ -65,16 +65,23 @@ </tp:docstring> </property> - <property name="RemoteContactCodecMap" - tp:name-for-bindings="Remote_Contact_Codec_Map" - type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read" + <property name="RemoteContactCodecs" + tp:name-for-bindings="Remote_Contact_Codecs" + type="a(usuua{ss})" tp:type="Codec[]" access="read" tp:immutable="yes"> <tp:docstring> - A map from remote contact to the list of codecs he or she - supports. + A list of codecs the remote contact supports. </tp:docstring> </property> + <property name="RemoteContact" tp:name-for-bindings="Remote_Contact" + type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes"> + <tp:docstring> + The contact handle that this codec offer applies to. + </tp:docstring> + </property> + + </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 24811fd..274d8b2 100644 --- a/spec/Call_Content_Interface_Media.xml +++ b/spec/Call_Content_Interface_Media.xml @@ -36,25 +36,82 @@ in a device specific hardware way and the CM does not need to concern itself with codecs.</p> - <p>On new <tp:dbus-ref - namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channels, - handlers should wait for <tp:dbus-ref + <h4>Codec negotiation</h4> + + <p>When a new <tp:dbus-ref + namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel + appears, whether it was requested or not, a <tp:dbus-ref namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> - objects to appear (one will either already be present, or will - appear at some point in the channel's lifetime).</p> + will either be waiting in the + <tp:member-ref>CodecOffer</tp:member-ref> property, or will + appear at some point via the + <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p> + + <p>The <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + property on the codec offer lists the codecs which are + supported by the remote contact, and so will determine the + codecs that should be proposed by the local user's streaming + implementation. An empty list means all codecs can be proposed.</p> + + <p>For incoming calls on protocols where codecs are proposed when + starting the call (for example, <a + href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>), + the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + will contain information on the codecs that have already been + proposed by the remote contact, otherwise the codec map will + be the empty list.</p> - <p>If the Call is incoming, then the codec offer's <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> - will already be filled with the codec information of the - remote contacts. Depending on the protocol, an outgoing call's + <p>The streaming implementation should look at the remote codec + map and the codecs known by the local user and call <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> - will either be filled with remote contact codec information, or - it will be empty. If empty, then this SHOULD be interpreted to - mean that all codecs are supported. Once a compatible list of - codecs has been decided, <tp:dbus-ref namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref> - should be called with the details of these codecs.</p> + on the intersection of these two codec lists.</p> + + <p>This means that in practice, outgoing calls will have a codec + offer pop up with no information in the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + so the local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the list of all codecs supported. If this codec offer is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will fire with the details of the codecs passed into + <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If + the call is incoming, then the <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> + will contain details of the remote contact's codecs and the + local user will call <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref> + with the codecs that both sides understand. After the codec + set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref> + will fire to signal this change.</p> + + <h4>Protocols without codec negotiation</h4> + + <p>For protocols where the codecs are not negotiable, instead of + popping up the initial content's <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object with an empty <tp:dbus-ref + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>, + the CM should set the supported codec values to known codec + values in the said object's codec map.</p> + + <h4>Changing codecs mid-call</h4> + + <p>To update the codec list used mid-call, the + <tp:member-ref>UpdateCodecs</tp:member-ref> method should be + called with details of the new codec list. If this is + accepted, then <tp:member-ref>CodecsChanged</tp:member-ref> + will be emitted with the new codec set.</p> + + <p>If the other side decides to update his or her codec list + during a call, a new <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object will appear through + <tp:member-ref>NewCodecOffer</tp:member-ref> which should be + acted on as documented above.</p> </tp:docstring> @@ -116,11 +173,16 @@ >CodecOffer.DRAFT</tp:dbus-ref> </tp:docstring> </tp:member> - <tp:member name="Remote_Contact_Codec_Map" type="a{ua(usuua{ss})}" - tp:type="Contact_Codec_Map"> + <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The contact handle that this codec offer applies to. + </tp:docstring> + </tp:member> + <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})" + tp:type="Codec[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property of the codec offer. </tp:docstring> </tp:member> @@ -167,7 +229,14 @@ <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> <tp:docstring> - Raised when not used during an existing call to update the codec mapping. + Raised when a <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object exists and is referred to in the + <tp:member-ref>CodecOffer</tp:member-ref> property which + should be used instead of calling this method, or before + the content's initial <tp:dbus-ref + namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref> + object has appeared. </tp:docstring> </tp:error> </tp:possible-errors> @@ -196,23 +265,28 @@ <p>Emission of this signal indicates that the <tp:member-ref>CodecOffer</tp:member-ref> property has changed to - <code>(Offer, Codecs)</code>.</p> + <code>(Contact, Offer, Codecs)</code>.</p> </tp:docstring> + <arg name="Contact" type="u"> + <tp:docstring> + The contact the codec offer belongs to. + </tp:docstring> + </arg> <arg name="Offer" type="o"> <tp:docstring> The object path of the new codec offer. This replaces any previous codec offer. </tp:docstring> </arg> - <arg name="Codecs" type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map"> + <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property of the codec offer.</p> <tp:rationale> Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> + namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref> property here saves a D-Bus round-trip - it shouldn't be necessary to get the property from the CodecOffer object, in practice. @@ -222,21 +296,26 @@ </signal> <property name="CodecOffer" tp:name-for-bindings="Codec_Offer" - type="(oa{ua(usuua{ss})})" tp:type="Codec_Offering" access="read"> + type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The object path to the current <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT</tp:dbus-ref> object, and its + >CodecOffer.DRAFT</tp:dbus-ref> object, its + <tp:dbus-ref namespace="ofdT.Call.Content" + >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and <tp:dbus-ref namespace="ofdT.Call.Content" - >CodecOffer.DRAFT.RemoteContactCodecMap</tp:dbus-ref> property. + >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties. If the object path is "/" then there isn't an outstanding codec offer, and the mapping MUST be empty.</p> <tp:rationale> Having the <tp:dbus-ref - namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecMap</tp:dbus-ref> - property here saves a D-Bus round-trip - it shouldn't be - necessary to get the property from the CodecOffer object, in + namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContact</tp:dbus-ref> and + <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT" + >RemoteContactCodecs</tp:dbus-ref> + properties here saves a D-Bus round-trip - it shouldn't be + necessary to get these properties from the CodecOffer object, in practice. </tp:rationale> diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml index 3d4fb13..9e62c87 100644 --- a/spec/Call_Stream_Interface_Media.xml +++ b/spec/Call_Stream_Interface_Media.xml @@ -27,6 +27,26 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> [FIXME] + + <h4>ICE restarts</h4> + + <p>If the <tp:dbus-ref + namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref> + signal is fired during a call once it has been called before + whilst setting up the call for initial use, and the + credentials have changed, then there has been an ICE + restart. In such a case, the CM SHOULD also empty the remote + candidate list in the <tp:dbus-ref + namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p> + + <p>If the CM does an ICE restart, then the + <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is + emitted and the streaming implementation should then call + <tp:member-ref>SetCredentials</tp:member-ref> again.</p> + + <p>For more information on ICE restarts see + <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245 + section 9.1.1.1</a></p> </tp:docstring> <method name="SetCredentials" tp:name-for-bindings="Set_Credentials"> @@ -133,7 +153,13 @@ <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> A transport that can be used for streaming. </tp:docstring> - <tp:enumvalue suffix="Raw_UDP" value="0"> + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The stream transport type is unknown or not applicable + (for streams that do not have a configurable transport). + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Raw_UDP" value="1"> <tp:docstring> Raw UDP, with or without STUN. All streaming clients are assumed to support this transport, so there is no handler capability token for @@ -143,7 +169,7 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="ICE" value="1"> + <tp:enumvalue suffix="ICE" value="2"> <tp:docstring> Interactive Connectivity Establishment, as defined by RFC 5245. Note that this value covers ICE-UDP only. @@ -151,7 +177,7 @@ Media.StreamHandler interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="GTalk_P2P" value="2"> + <tp:enumvalue suffix="GTalk_P2P" value="3"> <tp:docstring> Google Talk peer-to-peer connectivity establishment, as implemented by libjingle 0.3. @@ -159,7 +185,7 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="WLM_2009" value="3"> + <tp:enumvalue suffix="WLM_2009" value="4"> <tp:docstring> The transport used by Windows Live Messenger 2009 or later, which resembles ICE draft 19. @@ -167,13 +193,19 @@ interface.] </tp:docstring> </tp:enumvalue> - <tp:enumvalue suffix="SHM" value="4"> + <tp:enumvalue suffix="SHM" value="5"> <tp:added version="0.21.2"/> <tp:docstring> Shared memory transport, as implemented by the GStreamer shmsrc and shmsink plugins. </tp:docstring> </tp:enumvalue> + <tp:enumvalue suffix="Multicast" value="6"> + <tp:added version="0.21.5"/> + <tp:docstring> + Multicast transport. + </tp:docstring> + </tp:enumvalue> </tp:enum> <property name="Transport" tp:name-for-bindings="Transport" @@ -401,6 +433,15 @@ <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p> </tp:docstring> </property> + + <signal name="PleaseRestartICE" + tp:name-for-bindings="Please_Restart_ICE"> + <tp:docstring> + Emitted when the CM does an ICE restart to notify the + streaming implementation that it should call + <tp:member-ref>SetCredentials</tp:member-ref> again. + </tp:docstring> + </signal> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel.xml b/spec/Channel.xml index b1772d7..11d3e50 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -87,10 +87,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ property.</p> <p>This is fixed for the lifetime of the channel, so channels which - could potentially be used to communicate with multiple contacts - (such as streamed media calls defined by their members, or ad-hoc - chatrooms like MSN switchboards) must have TargetHandleType set - to Handle_Type_None and TargetHandle set to 0.</p> + could potentially be used to communicate with multiple contacts, + and do not have an identity of their own (such as a Handle_Type_Room + handle), must have TargetHandleType set to Handle_Type_None and + TargetHandle set to 0.</p> <p>Unlike in the telepathy-spec 0.16 API, there is no particular uniqueness guarantee - there can be many channels with the same diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml index 474c809..2dd000b 100644 --- a/spec/Channel_Dispatcher.xml +++ b/spec/Channel_Dispatcher.xml @@ -101,6 +101,165 @@ <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Equivalent to calling + <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty + <var>Hints</var> parameter.</p> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + 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> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + <tp:changed version="0.19.0"> + Previously, the spec didn't say that this should disregard the + handler's filter. This has been implemented since + telepathy-mission-control 5.3.2. + </tp:changed> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Equivalent to calling + <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty + <var>Hints</var> parameter.</p> + </tp:docstring> + + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + for which the new channel is to be created. + </tp:docstring> + </arg> + + <arg direction="in" name="Requested_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties.</p> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="x" + 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> + + <p>This parameter is used in the same way as the corresponding + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="Preferred_Handler" type="s" + tp:type="DBus_Well_Known_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Either the well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) + of the preferred handler for this + channel, or an empty string to indicate that any handler would be + acceptable. The behaviour and rationale are the same as for the + corresponding parameter to + <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring> + The Preferred_Handler is syntactically invalid or does + not start with <code>org.freedesktop.Telepathy.Client.</code>, + the Account does not exist, or one of the Requested_Properties + is invalid + </tp:docstring> + </tp:error> + </tp:possible-errors> + + </method> + + <method name="CreateChannelWithHints" + tp:name-for-bindings="Create_Channel_With_Hints"> + <tp:added version="0.21.5"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to create a channel. This initially just creates a <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> object, which can be used to continue the request and track its @@ -235,6 +394,19 @@ </tp:changed> </arg> + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + <p>Additional information about the channel request, which will be + used as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + property.</p> + + <tp:rationale> + <p>See the Hints property's documentation for rationale.</p> + </tp:rationale> + </tp:docstring> + </arg> + <arg direction="out" name="Request" type="o"> <tp:docstring> A @@ -256,7 +428,15 @@ </method> - <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> + <method name="EnsureChannelWithHints" + tp:name-for-bindings="Ensure_Channel_With_Hints"> + <tp:added version="0.21.5"> + Support for this method is indicated by the + <tp:member-ref>SupportsRequestHints</tp:member-ref> property. + Clients MUST recover from this method being unsupported by falling back + to <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>. + </tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Start a request to ensure that a channel exists, creating it if necessary. This initially just creates a <tp:dbus-ref @@ -275,7 +455,7 @@ <tp:rationale> <p>The rationale is as for <tp:dbus-ref - namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannel</tp:dbus-ref>.</p> + namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p> </tp:rationale> </tp:docstring> @@ -311,7 +491,8 @@ request is for some reason not involving user action.</p> <p>This parameter is used in the same way as the corresponding - parameter to <tp:member-ref>CreateChannel</tp:member-ref>.</p> + parameter to + <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p> </tp:docstring> </arg> @@ -324,8 +505,8 @@ channel, or an empty string to indicate that any handler would be acceptable. The behaviour and rationale are the same as for the corresponding parameter to - <tp:member-ref>CreateChannel</tp:member-ref>, except as noted - here.</p> + <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except + as noted here.</p> <p>If any new channels are created in response to this request, the channel dispatcher SHOULD dispatch as many as @@ -359,6 +540,14 @@ </tp:docstring> </arg> + <arg direction="in" name="Hints" type="a{sv}"> + <tp:docstring> + Additional information about the channel request, which will be used + as the value for the resulting request's <tp:dbus-ref + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + property.</tp:docstring> + </arg> + <arg direction="out" name="Request" type="o"> <tp:docstring> A @@ -380,6 +569,27 @@ </method> + <property name="SupportsRequestHints" + tp:name-for-bindings="Supports_Request_Hints" + type="b" access="read"> + <tp:added version="0.21.5"/> + <tp:docstring> + If <code>True</code>, the channel dispatcher is new enough to support + <tp:member-ref>CreateChannelWithHints</tp:member-ref> and + <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition + to the older <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref> + and <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref> + methods, and also new enough to emit <tp:dbus-ref + namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref> + before the older <tp:dbus-ref + namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal. + If <code>False</code> or missing, only the metadata-less + variants are supported. + </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml index 0eeee39..62e8384 100644 --- a/spec/Channel_Interface_Messages.xml +++ b/spec/Channel_Interface_Messages.xml @@ -104,6 +104,8 @@ USA.</p> This list MUST NOT be empty, since all Messages implementations MUST accept messages containing a single "text/plain" part.</p> + <p>Items in this list MUST be normalized to lower-case.</p> + <p>Some examples of how this property interacts with the <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p> @@ -142,6 +144,20 @@ USA.</p> </tp:docstring> </property> + <property name="MessageTypes" type="au" + tp:type="Channel_Text_Message_Type[]" access="read" + tp:name-for-bindings="Message_Types" + tp:immutable="yes"> + <tp:added version="0.21.5"> + This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text" + >GetMessageTypes</tp:dbus-ref>; fall back to that method for + compatibility with older connection managers. + </tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of message types which may be sent on this channel.</p> + </tp:docstring> + </property> + <property name="MessagePartSupportFlags" type="u" tp:type="Message_Part_Support_Flags" access="read" tp:name-for-bindings="Message_Part_Support_Flags" @@ -289,6 +305,17 @@ USA.</p> image.</p> </tp:rationale> + <p>Connection managers, clients and extensions to this specification + SHOULD NOT include <tp:type>Handle</tp:type>s as values in a + Message_Part, except for <code>message-sender</code> in the + header.</p> + + <tp:rationale> + <p>Reference-counting handles in clients becomes problematic if + the channel proxy cannot know whether particular map values + are handles or not.</p> + </tp:rationale> + <h4>Example messages</h4> <p>A rich-text message, with an embedded image, might be represented @@ -491,6 +518,12 @@ USA.</p> <tp:simple-type type="s" name="Message_Header_Key"> <tp:added version="0.19.8"/> + <tp:changed version="0.21.5"> + Removed <tt>protocol-token</tt>—which had never been implemented—and + respecified <tt>message-token</tt> not to have unimplementable + uniqueness guarantees. + </tp:changed> + <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 @@ -499,39 +532,37 @@ USA.</p> one or the other.</p> <dl> - <dt>message-token (s)</dt> - <dd> - <p>An opaque, globally-unique identifier for the entire message. - This MAY be treated as if it were a MIME Message-ID, e.g. for - the mid: and cid: URI schemes. If omitted, there is no suitable - token; the protocol-token key SHOULD be provided if the protocol - identifies messages in some less unique way.</p> - </dd> - - <dt>protocol-token (s - <tp:type>Protocol_Message_Token</tp:type>)</dt> + <dt>message-token (s - + <tp:type>Protocol_Message_Token</tp:type>) + </dt> <dd> - <p>An opaque token for the entire message, with whatever uniqueness - guarantee is provided by the underlying protocol. As described - for the Protocol_Message_Token type, this token is <em>not</em> - guaranteed to be unique between contacts, or even within the - scope of a Channel.</p> + <p>An opaque identifier for the message, as used by the + underlying protocol. For outgoing messages, this SHOULD be + globally unique; for incoming messages, this is <em>not</em> + guaranteed to uniquely identify a message, <em>even within the + scope of a single channel or contact</em>; the only guarantee + made is that two messages with different <tt>message-token</tt> + headers are different messages.</p> + + <p>Clients wishing to determine whether a new message with the + <tt>scrollback</tt> header matches a previously-logged message + with the same <tt>message-token</tt> SHOULD compare the + message's sender, contents, <tt>message-sent</tt> or + <tt>message-received</tt> timestamp, etc. Note that, in XMPP, + the server only supplies a timestamp for scrollback messages, + not for messages received while you are in a room; thus, + non-scrollback messages will lack a <tt>message-sent</tt> + timestamp.</p> <tp:rationale> - <p>In practice, in most protocols there is no token with the - uniqueness guarantees demanded for message-token; the - definition of message-token was inappropriate, but must now - be preserved for the benefit of clients that rely on it, at - least until Telepathy breaks backwards compatibility.</p> - </tp:rationale> - - <p>The message-token and protocol-token SHOULD NOT both be present; - clients requiring an identifier with the semantics of the - protocol-token SHOULD look for the message-token first, falling - back to the protocol-token.</p> - - <tp:rationale> - <p>This is for compatibility with CMs older than the - protocol-token key.</p> + <p>In practice, most protocols do not provide globally-unique + identifiers for messages. Connection managers, being + stateless, do not have the necessary information — namely, IM + logs — to generate reliable unique tokens for messages.</p> + + <p>For instance, some XMPP clients (including Gabble) stamp + messages they send with unique identifiers, but others number + outgoing messages in a conversation from 1 upwards.</p> </tp:rationale> </dd> @@ -549,6 +580,13 @@ 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>message-sender-id (s)</dt> + <dd>The identifier of the contact who sent the message, + i.e. the result of calling <tp:dbus-ref + namespace="ofdT.Connection">InspectHandles</tp:dbus-ref> + on <code>message-sender</code>. If omitted, clients MUST + fall back to looking at <code>message-sender</code>.</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> @@ -601,7 +639,8 @@ USA.</p> does not make sense on outgoing messages, and SHOULD NOT appear there.</dd> </dl> - </tp:docstring> + + </tp:docstring> </tp:simple-type> <tp:simple-type type="s" name="Message_Body_Key"> @@ -652,6 +691,12 @@ USA.</p> <p>Clients MUST ignore parts without a 'content-type' key, which are reserved for future expansion.</p> + + <p>When sending messages, clients SHOULD normalize the + content-type to lower case, but connection managers SHOULD NOT + rely on this. When signalling sent or received messages, + connection managers MUST normalize the content-type to lower + case.</p> </dd> <dt>lang (s)</dt> @@ -703,16 +748,19 @@ USA.</p> <dt>needs-retrieval (b)</dt> <dd>If false or omitted, the connection manager already holds this part in memory. If present and true, - this part will be retrieved on demand (like MIME's - message/external-body), so clients should expect retrieval to - take time; if this specification is later extended to provide a - streaming version of GetPendingMessageContent, clients should - use it for parts with this flag.</dd> + this part must be retrieved on demand (like MIME's + <tt>message/external-body</tt>) by a mechanism to be defined later. + + <tp:rationale>The mechanism was meant to be + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, but + that didn't work out. It's worth leaving the header in in + preparation for a future mechanism. + </tp:rationale> + </dd> <dt>truncated (b)</dt> - <dd>The content available via the 'content' key or - GetPendingMessageContent has been truncated by the server - or connection manager (equivalent to + <dd>The content available via the 'content' key has been truncated + by the server or connection manager (equivalent to Channel_Text_Message_Flag_Truncated in the Text interface). </dd> @@ -826,20 +874,6 @@ USA.</p> the sender. This is sometimes the only way to match it against the sent message, so we include it here. </tp:rationale> - - <p>Unlike in the Messages interface, content not visible - in the value for this key cannot be retrieved by another - means, so the connection manager SHOULD be more - aggressive about including (possibly truncated) message - content in the 'content' key.</p> - - <tp:rationale> - The Messages interface needs to allow all content to be - retrieved, but in this interface, the content we provide is - merely a hint; so some is better than none, and it doesn't - seem worth providing an API as complex as Messages' - GetPendingMessageContent for the echoed message. - </tp:rationale> </dd> </dl> @@ -848,6 +882,11 @@ USA.</p> <tp:simple-type type="u" name="Message_Part_Index" array-name="Message_Part_Index_List"> + <tp:deprecated version="0.21.5"> + This type is only used by + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is + unimplemented and deprecated. + </tp:deprecated> <tp:added version="0.17.17"/> <tp:docstring> The index of a message part within a message. @@ -856,6 +895,11 @@ USA.</p> <tp:mapping name="Message_Part_Content_Map"> <tp:added version="0.17.17"/> + <tp:deprecated version="0.21.5"> + This structure is only used by + <tp:member-ref>GetPendingMessageContent</tp:member-ref>, which is + unimplemented and deprecated. + </tp:deprecated> <tp:docstring> A mapping from message part indexes to their content, as returned by <tp:member-ref>GetPendingMessageContent</tp:member-ref>. @@ -888,7 +932,7 @@ USA.</p> is no particular identification for a message.</p> <p>CM implementations SHOULD use an identifier expected to be unique, - such as a UUID, if possible.</p> + such as a UUID, for outgoing messages (if possible).</p> <p>Some protocols can only track a limited number of messages in a small message-ID space (SMS messages are identified by a single @@ -946,12 +990,27 @@ USA.</p> <p>If this method fails, message submission to the server has failed and no signal on this interface (or the Text interface) is emitted.</p> + + <p>If this method succeeds, message submission to the server has + succeeded, but the message has not necessarily reached its intended + recipient. If a delivery failure is detected later, this is + signalled by receiving a message whose <code>message-type</code> + header maps to + <tp:type>Channel_Text_Message_Type</tp:type>_Delivery_Report. + Similarly, if delivery is detected to have been successful + (which is not possible in all protocols), a successful delivery + report will be signalled.</p> </tp:docstring> <arg direction="in" type="aa{sv}" tp:type="Message_Part[]" name="Message"> <tp:docstring> - The message content, including any attachments or alternatives + The message content, including any attachments or alternatives. + This MUST NOT include the following headers, or any others that + do not make sense for a client to specify: + <code>message-sender</code>, <code>message-sender-id</code>, + <code>message-sent</code>, <code>message-received</code>, + <code>pending-message-id</code>. </tp:docstring> </arg> <arg direction="in" name="Flags" type="u" @@ -1061,6 +1120,14 @@ USA.</p> part to generate a <tt>text/plain</tt> alternative which is also included in this signal argument.</p> + <p>The connection manager SHOULD include the + <code>message-sender</code>, <code>message-sender-id</code> and + <code>message-sent</code> headers in the representation of the + message that is signalled here. If the channel has + channel-specific handles, the <code>message-sender</code> and + <code>message-sender-id</code> SHOULD reflect the sender that + other contacts will see.</p> + <p>If the connection manager can predict that the message will be altered during transmission, this argument SHOULD reflect what other contacts will receive, rather than being a copy of the @@ -1128,6 +1195,14 @@ USA.</p> <method name="GetPendingMessageContent" tp:name-for-bindings="Get_Pending_Message_Content"> + <tp:deprecated version='0.21.5' + xmlns="http://www.w3.org/1999/xhtml"> + This method has never been implemented, and in any case would have been + impossible to use correctly when multiple clients (such as a logger and + the handler) are interested in a text channel. See <a + href='https://bugs.freedesktop.org/show_bug.cgi?id=26417'>freedesktop.org + bug #26417</a> for more details. + </tp:deprecated> <tp:docstring> Retrieve the content of one or more parts of a pending message. Note that this function may take a considerable amount of time diff --git a/spec/Channel_Interface_SASL_Authentication.xml b/spec/Channel_Interface_SASL_Authentication.xml new file mode 100644 index 0000000..38568b1 --- /dev/null +++ b/spec/Channel_Interface_SASL_Authentication.xml @@ -0,0 +1,704 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_SASL_Authentication" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +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.SASLAuthentication"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel interface for SASL authentication, + as defined by + <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>. + When this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, it represents authentication with the server. In future, + it could also be used to authenticate with secondary services, + or even to authenticate end-to-end connections with contacts. As a result, + this interface does not REQUIRE <tp:dbus-ref namespace="ofdT.Channel.Type" + >ServerAuthentication</tp:dbus-ref> to allow for a potential future + Channel.Type.PeerAuthentication interface.</p> + + <p>In any protocol that requires a password, the connection manager can + use this channel to let a user interface carry out a simple SASL-like + handshake with it, as a way to get the user's credentials + interactively. This can be used to connect to protocols that may + require a password, without requiring that the password is saved in + the <tp:dbus-ref + namespace="ofdT">Account.Parameters</tp:dbus-ref>.</p> + + <p>In some protocols, such as XMPP, authentication with the server + is also carried out using SASL. In these protocols, a channel with this + interface can provide a simple 1:1 mapping of the SASL negotiations + taking place in the protocol, allowing more advanced clients to + perform authentication via SASL mechanisms not known to the + connection manager.</p> + + <tp:rationale> + <p>By providing SASL directly when the protocol supports it, we can + use mechanisms like Kerberos or Google's <code>X-GOOGLE-TOKEN</code> + without specific support in the connection manager.</p> + </tp:rationale> + + <p>For channels managed by a + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>, + only the channel's <tp:dbus-ref + namespace="ofdT.Client">Handler</tp:dbus-ref> may call the + methods on this interface. Other clients MAY observe the + authentication process by watching its signals and properties.</p> + + <tp:rationale> + <p>There can only be one Handler, which is a good fit for SASL's + 1-1 conversation between a client and a server.</p> + </tp:rationale> + </tp:docstring> + + <tp:simple-type name="SASL_Mechanism" type="s" + array-name="SASL_Mechanism_List"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A SASL mechanism, as defined by + <a href="http://tools.ietf.org/html/rfc4422">RFC 4422</a> + and registered in + <a href="http://www.iana.org/assignments/sasl-mechanisms">the + IANA registry of SASL mechanisms</a>, or an unregistered + SASL mechanism such as <code>X-GOOGLE-TOKEN</code> used in the + same contexts.</p> + + <p>As a special case, pseudo-mechanisms starting with + <code>X-TELEPATHY-</code> are defined by this specification. + Use of these pseudo-mechanisms indicates that the user's credentials + are to be passed to the connection manager, which will then use + them for authentication with the service, either by implementing + the client side of some SASL mechanisms itself or by using a + non-SASL protocol. The only such pseudo-mechanism currently + defined is <code>X-TELEPATHY-PASSWORD</code>.</p> + + <p>The <code>X-TELEPATHY-PASSWORD</code> mechanism is extremely + simple:</p> + + <ul> + <li>The client MUST call + <tp:member-ref>StartMechanismWithData</tp:member-ref>, with + Initial_Data set to the password encoded in UTF-8. + For simplicity, calling <tp:member-ref>StartMechanism</tp:member-ref> + followed by calling <tp:member-ref>Respond</tp:member-ref> is not + allowed in this mechanism.</li> + + <li>The connection manager uses the password, together with + authentication details from the Connection parameters, to + authenticate itself to the server.</li> + + <li>When the connection manager finishes its attempt to authenticate + to the server, the channel's state changes to + either SASL_Status_Server_Succeeded or + SASL_Status_Server_Failed as appropriate.</li> + </ul> + </tp:docstring> + </tp:simple-type> + + <property name="AvailableMechanisms" + tp:name-for-bindings="Available_Mechanisms" + type="as" tp:type="SASL_Mechanism[]" + access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The SASL mechanisms as offered by the server, plus any + pseudo-SASL mechanisms supported by the connection manager for + credentials transfer. For instance, in a protocol that + natively uses SASL (like XMPP), this might be + <code>[ "X-TELEPATHY-PASSWORD", "PLAIN", "DIGEST-MD5", + "SCRAM-SHA-1" ]</code>.</p> + + <p>To make it possible to implement a very simple password-querying + user interface without knowledge of any particular SASL mechanism, + implementations of this interface MUST implement the + pseudo-mechanism <code>X-TELEPATHY-PASSWORD</code>, unless none + of the available mechanisms use a password at all.</p> + </tp:docstring> + </property> + + <property name="HasInitialData" tp:name-for-bindings="Has_Initial_Data" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>StartMechanismWithData</tp:member-ref> + can be expected to work for SASL mechanisms not starting with + <code>X-TELEPATHY-</code> (this is the case in most, but not all, + protocols). If false, <tp:member-ref>StartMechanism</tp:member-ref> + must be used instead.</p> + + <p>This property does not affect the <code>X-TELEPATHY-</code> + pseudo-mechanisms such as <code>X-TELEPATHY-PASSWORD</code>, + which can use + <tp:member-ref>StartMechanismWithData</tp:member-ref> regardless + of the value of this property.</p> + </tp:docstring> + </property> + + <property name="CanTryAgain" tp:name-for-bindings="Can_Try_Again" + type="b" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, <tp:member-ref>StartMechanism</tp:member-ref> and (if + supported) <tp:member-ref>StartMechanismWithData</tp:member-ref> + can be expected to work when in one of the Failed states. If + false, the only thing you can do after failure is to close the + channel.</p> + + <tp:rationale> + <p>Retrying isn't required to work, although some protocols and + implementations allow it.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property type="u" tp:type="SASL_Status" access="read" + name="SASLStatus" tp:name-for-bindings="SASL_Status"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The current status of this channel. + Change notification is via the + <tp:member-ref>SASLStatusChanged</tp:member-ref> signal. + </tp:docstring> + </property> + + <property type="s" tp:type="DBus_Error_Name" access="read" + name="SASLError" tp:name-for-bindings="SASL_Error"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The reason for the <tp:member-ref>SASLStatus</tp:member-ref>, or + an empty string if the state is neither + Server_Failed nor Client_Failed.</p> + + <p>In particular, an ordinary authentication failure (as would + be produced for an incorrect password) SHOULD be represented by + <tp:error-ref>AuthenticationFailed</tp:error-ref>, + cancellation by the user's request SHOULD be represented + by <tp:error-ref>Cancelled</tp:error-ref>, and + cancellation by a local process due to inconsistent or invalid + challenges from the server SHOULD be represented by + <tp:error-ref>ServiceConfused</tp:error-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, this error code SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="SASLErrorDetails" + tp:name-for-bindings="SASL_Error_Details" + access="read" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If <tp:member-ref>SASLError</tp:member-ref> is non-empty, + 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="ofdT">Connection.ConnectionError</tp:dbus-ref>.</p> + + <p>If this interface appears on a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel, and connection to the server fails with an authentication + failure, these details SHOULD be copied into the + <tp:dbus-ref + namespace="ofdT">Connection.ConnectionError</tp:dbus-ref> + signal.</p> + </tp:docstring> + </property> + + <property name="AuthorizationIdentity" + tp:name-for-bindings="Authorization_Identity" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The identity for which authorization is being attempted, + typically the 'account' from the <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref> + parameters, normalized and formatted according to the + conventions used for SASL in this protocol.</p> + + <tp:rationale> + <p>The normalization used for SASL might not be the same + normalization used elsewhere: for instance, in a protocol + with email-like identifiers such as XMPP or SIP, the user + "juliet@example.com" might have to authenticate to the + example.com server via SASL PLAIN as "juliet".</p> + </tp:rationale> + + <p>This is usually achieved by using the authorization identity for + authentication, but an advanced Handler could offer the option + to authenticate under a different identity.</p> + + <p>The terminology used here is that the authorization identity + is who you want to act as, and the authentication identity is + used to prove that you may do so. For instance, if Juliet is + authorized to access a role account, "sysadmin@example.com", + and act on its behalf, it might be possible to authenticate + as "juliet@example.com" with her own password, but request to + be authorized as "sysadmin@example.com" instead of her own + account. See + <a href="http://tools.ietf.org/html/rfc4422#section-3.4.1">RFC + 4422 §3.4.1</a> for more details.</p> + + <tp:rationale> + <p>In SASL the authorization identity is normally guessed from + the authentication identity, but the information available + to the connection manager is the identity for which + authorization is required, such as the desired JID in XMPP, + so that's what we signal to UIs; it's up to the UI to + choose whether to authenticate as the authorization identity + or some other identity.</p> + + <p>As a concrete example, the "sysadmin" XMPP account mentioned + above would have <code>{ 'account': 'sysadmin@example.com' }</code> + in its Parameters, and this property would also be + 'sysadmin@example.com'. A simple Handler would + merely prompt for sysadmin@example.com's password, + and use that JID as both the authorization and authentication + identity, which might result in SASL PLAIN authentication with the + initial response + '\000sysadmin@example.com\000root'.</p> + + <p>A more advanced Handler might also ask for an authentication + identity, defaulting to 'sysadmin@example.com'; if Juliet + provided authentication identity 'juliet@example.com' and + password 'romeo', the Handler might perform SASL PLAIN + authentication using the initial response + 'sysadmin@example.com\000juliet@example.com\000romeo'.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="DefaultUsername" + tp:name-for-bindings="Default_Username" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default username for use with SASL mechanisms that deal + with a "simple username" (as defined in <a + href="http://tools.ietf.org/html/rfc4422">RFC 4422</a>). If + such a SASL mechanism is in use, clients SHOULD default to + using the DefaultUsername; also, if the client uses + the DefaultUsername, it SHOULD assume that the authorization + identity <tp:member-ref>AuthorizationIdentity</tp:member-ref> + will be derived from it by the server.</p> + + <tp:rationale> + <p>In XMPP, <a href="http://trac.tools.ietf.org/wg/xmpp/trac/ticket/49"> + servers typically expect</a> "user@example.com" to + authenticate with username "user"; this was a SHOULD in <a + href="http://tools.ietf.org/html/rfc3920">RFC 3920</a>.</p> + + <p><a + href="http://tools.ietf.org/html/draft-ietf-xmpp-3920bis-19">3920bis</a> + weakens that SHOULD to "in the absence of local information + provided by the server, an XMPP client SHOULD assume that + the authentication identity for such a SASL mechanism is the + combination of a user name and password, where the simple + user name is the localpart of the user's JID".</p> + </tp:rationale> + + <p>For example, in the simple case, if the user connects with + <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>user@example.com</tt>" }) and use PLAIN with + password "password", he or she should authenticate like so: + "<tt>\0user\0password</tt>" and the channel will look like + this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "user", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "user@example.com } +</pre></blockquote> + + <p>In the complex case, if the same user is using his or her + sysadmin powers to log in as the "announcements" role address, + he or she would connect with <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>({ + account: "<tt>announcements@example.com</tt>" }) and the SASL + channel would look like this:</p> + +<blockquote><pre>{ "...<tp:member-ref>DefaultUsername</tp:member-ref>": "announcements", + "...<tp:member-ref>AuthorizationIdentity</tp:member-ref>": "announcements@example.com } +</pre></blockquote> + + <p>A sufficiently elaborate UI could give the opportunity + to override the username from "announcements" to "user". + The user's simple username is still "user", and the password is + still "password", but this time he or she is trying to authorize + to act as <tt>announcements@example.com</tt>, so the UI would + have to perform SASL PLAIN with this string: + "<tt>announcements@example.com\0user\0password</tt>", where + "announcements@example.com" is the + <tp:member-ref>AuthorizationIdentity</tp:member-ref>.</p> + </tp:docstring> + </property> + + <property name="DefaultRealm" tp:name-for-bindings="Default_Realm" + type="s" access="read" tp:immutable="yes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The default realm (as defined in + <a href="http://tools.ietf.org/html/rfc2831#section-2.1.1">RFC + 2831</a>) to use for authentication, if the server does not + supply one.</p> + + <tp:rationale> + <p>The server is not required to provide a realm; if it doesn't, + the client is expected to ask the user or provide a sensible + default, typically the requested DNS name of the server. + In some implementations of <code>DIGEST-MD5</code>, the + server does not specify a realm, but expects that the client + will choose a particular default, and authentication will + fail if the client's default is different. Connection + managers for protocols where this occurs are more easily able + to work around these implementations than a generic client + would be.</p> + </tp:rationale> + </tp:docstring> + </property> + + <method name="StartMechanism" tp:name-for-bindings="Start_Mechanism"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, without + sending initial data (an "initial response" as defined in RFC + 4422).</p> + + <tp:rationale> + <p>This method is appropriate for mechanisms where the client + cannot send anything until it receives a challenge from the + server, such as + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> + in "initial authentication" mode.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism. Choose a SASL mechanism from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="StartMechanismWithData" + tp:name-for-bindings="Start_Mechanism_With_Data"> + <arg direction="in" name="Mechanism" type="s" tp:type="SASL_Mechanism"> + <tp:docstring> + The chosen mechanism. + </tp:docstring> + </arg> + <arg direction="in" name="Initial_Data" type="ay"> + <tp:docstring> + Initial data (an "initial response" in RFC 4422's terminology) to send + with the mechanism. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Start an authentication try using <var>Mechanism</var>, and send + <var>Initial_Data</var> as the "initial response" defined in + <a href="http://tools.ietf.org/html/rfc4422#section-3.3">RFC 4422 + §3.3</a>.</p> + + <tp:rationale> + <p>This method is appropriate for mechanisms where the client may + send data first, such as <code>PLAIN</code>, or must send data + first, such as + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code> + in "subsequent authentication" mode.</p> + + <p>Having two methods allows any mechanism where it makes a difference + to distinguish between the absence of an initial response + (<tp:member-ref>StartMechanism</tp:member-ref>) and a zero-byte + initial response (StartMechanismWithData, with Initial_Data + empty).</p> + </tp:rationale> + + <p>If the <tp:member-ref>HasInitialData</tp:member-ref> + property is false, this indicates that the underlying protocol + does not make it possible to send initial data. In such protocols, + this method may only be used for the <code>X-TELEPATHY-</code> + pseudo-mechanisms (such as <code>X-TELEPATHY-PASSWORD</code>), + and will fail if used with an ordinary SASL mechanism.</p> + + <tp:rationale> + <p>For instance, the IRC SASL extension implemented in Charybdis and + Atheme does not support initial data - the first message in the + exchange only carries the mechanism. This is significant if using + <code><a href="http://tools.ietf.org/html/rfc2831">DIGEST-MD5</a></code>, + which cannot be used in the faster "subsequent authentication" + mode on a protocol not supporting initial data.</p> + </tp:rationale> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The channel is not in a state where starting authentication makes + sense (i.e. SASL_Status_Not_Started, or (if + <tp:member-ref>CanTryAgain</tp:member-ref> is true) + SASL_Status_Server_Failed or + SASL_Status_Client_Failed). You should call + <tp:member-ref>AbortSASL</tp:member-ref> and wait for + SASL_Status_Client_Failed before starting another attempt. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The server or connection manager doesn't implement the given + SASL mechanism (choose one from + <tp:member-ref>AvailableMechanisms</tp:member-ref>, or abort + authentication if none of them are suitable), or doesn't allow + initial data to be sent (as indicated by + <tp:member-ref>HasInitialData</tp:member-ref>; call + <tp:member-ref>StartMechanism</tp:member-ref> instead). + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Respond" tp:name-for-bindings="Respond"> + <arg direction="in" name="Response_Data" type="ay"> + <tp:docstring> + The response data. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Send a response to the the last challenge received via + <tp:member-ref>NewChallenge</tp:member-ref>.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is not In_Progress, or no challenge has been + received yet, or you have already responded to the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AcceptSASL" tp:name-for-bindings="Accept_SASL"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If the channel's status is SASL_Status_Server_Succeeded, + this method confirms successful authentication and advances + the status of the channel to SASL_Status_Succeeded.</p> + + <p>If the channel's status is SASL_Status_In_Progress, calling this + method indicates that the last + <tp:member-ref>NewChallenge</tp:member-ref> signal was in fact + additional data sent after a successful SASL negotiation, and + declares that from the client's point of view, authentication + was successful. This advances the state of the channel to + SASL_Status_Client_Accepted.</p> + + <p>In mechanisms where the server authenticates itself to the client, + calling this method indicates that the client considers this to have + been successful. In the case of <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channels, this means that the connection manager MAY continue to + connect, and MAY advance the <tp:dbus-ref + namespace="ofdT">Connection.Status</tp:dbus-ref> to Connected.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + Either the state is neither In_Progress nor Server_Succeeded, or no + challenge has been received yet, or you have already responded to + the last challenge. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + + <method name="AbortSASL" tp:name-for-bindings="Abort_SASL"> + <arg direction="in" name="Reason" type="u" tp:type="SASL_Abort_Reason"> + <tp:docstring> + Reason for abort. + </tp:docstring> + </arg> + <arg direction="in" name="Debug_Message" type="s"> + <tp:docstring> + Debug message for abort. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Abort the current authentication try.</p> + + <p>If the current status is SASL_Status_Server_Failed or + SASL_Status_Client_Failed, this method returns successfully, but has + no further effect. If the current status is SASL_Status_Succeeded + or SASL_Status_Client_Accepted then NotAvailable is raised. + Otherwise, it changes the channel's state to + SASL_Status_Client_Failed, with an appropriate error name and + reason code.</p> + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The current state is either Succeeded or Client_Accepted. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="SASLStatusChanged" tp:name-for-bindings="SASL_Status_Changed"> + <tp:docstring> + Emitted when the status of the channel changes. + </tp:docstring> + <arg type="u" tp:type="SASL_Status" name="Status"> + <tp:docstring> + The new value of <tp:member-ref>SASLStatus</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="s" tp:type="DBus_Error_Name" name="Reason"> + <tp:docstring> + The new value of <tp:member-ref>SASLError</tp:member-ref>. + </tp:docstring> + </arg> + <arg type="a{sv}" tp:type="String_Variant_Map" name="Details"> + <tp:docstring> + The new value of <tp:member-ref>SASLErrorDetails</tp:member-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="NewChallenge" tp:name-for-bindings="New_Challenge"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a new challenge is received from the server, or when + a message indicating successful authentication and containing + additional data is received from the server.</p> + + <p>When the channel's handler is ready to proceed, it should respond + to the challenge by calling <tp:member-ref>Respond</tp:member-ref>, + or respond to the additional data by calling + <tp:member-ref>AcceptSASL</tp:member-ref>. Alternatively, it may call + <tp:member-ref>AbortSASL</tp:member-ref> to abort authentication.</p> + </tp:docstring> + <arg name="Challenge_Data" type="ay"> + <tp:docstring> + The challenge data or additional data from the server. + </tp:docstring> + </arg> + </signal> + + <tp:enum name="SASL_Abort_Reason" type="u"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A reason why SASL authentication was aborted by the client.</p> + </tp:docstring> + + <tp:enumvalue suffix="Invalid_Challenge" value="0"> + <tp:docstring> + The server sent an invalid challenge or data. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="User_Abort" value="1"> + <tp:docstring> + The user aborted the authentication. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:enum name="SASL_Status" type="u" plural="SASL_Statuses"> + <tp:enumvalue suffix="Not_Started" value="0"> + <tp:docstring> + The initial state. The Handler SHOULD either + call <tp:member-ref>AbortSASL</tp:member-ref>, or connect to the + <tp:member-ref>NewChallenge</tp:member-ref> signal then call + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref>. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="In_Progress" value="1"> + <tp:docstring> + The challenge/response exchange is in progress. The Handler SHOULD + call either <tp:member-ref>Respond</tp:member-ref> or + <tp:member-ref>AcceptSASL</tp:member-ref> exactly once per emission + of <tp:member-ref>NewChallenge</tp:member-ref>, or call + <tp:member-ref>AbortSASL</tp:member-ref> at any time. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Succeeded" value="2"> + <tp:docstring> + The server has indicated successful authentication, and the + connection manager is waiting for confirmation from the Handler. + The Handler must call either <tp:member-ref>AcceptSASL</tp:member-ref> or + <tp:member-ref>AbortSASL</tp:member-ref> to indicate whether it + considers authentication to have been successful. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Accepted" value="3"> + <tp:docstring> + The Handler has indicated successful authentication, and the + connection manager is waiting for confirmation from the server. + The state will progress to either Succeeded or Server_Failed when + confirmation is received. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Succeeded" value="4"> + <tp:docstring> + Everyone is happy (the server sent success, and the client has called + <tp:member-ref>AcceptSASL</tp:member-ref>). Connection to the server + will proceed as soon as this state is reached. The Handler SHOULD + call <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + to close the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Server_Failed" value="5"> + <tp:docstring> + The server has indicated an authentication failure. + If <tp:member-ref>CanTryAgain</tp:member-ref> is true, + the client may try to authenticate again, by calling + <tp:member-ref>StartMechanism</tp:member-ref> or + <tp:member-ref>StartMechanismWithData</tp:member-ref> again. + Otherwise, it should give up completely, by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channel. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Client_Failed" value="6"> + <tp:docstring> + The client has indicated an authentication failure. The + possible actions are the same as for Server_Failed. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Interface_SMS.xml b/spec/Channel_Interface_SMS.xml index b0dce66..4cfe3f2 100644 --- a/spec/Channel_Interface_SMS.xml +++ b/spec/Channel_Interface_SMS.xml @@ -27,9 +27,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. documentation tidied up.</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>This interface contains SMS-specific properties for text channels. - This currently only includes whether the SMSes received on the channel - should be displayed immediately to the user, without prompting.</p> + <p>This interface contains SMS-specific properties for text + channels.</p> + + <p>The presence of this interface on a channel does not imply that + messages will be delivered via SMS.</p> + + <p>This interface MAY appear in the + <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref> property + of channels where <tp:member-ref>SMSChannel</tp:member-ref> would be + immutable and false. It SHOULD appear on channels where + <tp:member-ref>SMSChannel</tp:member-ref> is immutable and true, and + also on channels where <tp:member-ref>SMSChannel</tp:member-ref> is + mutable (i.e. channels that might fall back to sending SMS at any + time, such as on MSN).</p> <h4>Handler filters</h4> @@ -51,7 +62,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> <property name="Flash" tp:name-for-bindings="Flash" - type="b" access="read" > + type="b" access="read" tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If <code>True</code>, then this channel is exclusively for receiving class 0 SMSes (and no SMSes can be sent using <tp:dbus-ref @@ -89,5 +100,80 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:rationale> </tp:docstring> </property> + + <property name="SMSChannel" + tp:name-for-bindings="SMS_Channel" + type="b" + access="read" tp:requestable="yes" tp:immutable="sometimes"> + <tp:added version="0.21.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If TRUE, messages sent and received on this channel are transmitted + via SMS.</p> + + <p>If this property is included in the channel request, the + Connection Manager MUST return an appropriate channel (i.e. if TRUE + the channel must be for SMSes, if FALSE it must not), or else fail + to provide the requested channel with the + <tp:error-ref>NotCapable</tp:error-ref> + error.</p> + + <p>For example, to explicitly request an SMS channel to a contact. + You might construct a channel request like:</p> + + <blockquote><pre>{ + Channel.Type: Channel.Type.Text, + Channel.TargetHandleType: Handle_Type_Contact, + Channel.TargetID: escher.cat, + Channel.Interface.SMS.SMSChannel: True, +}</pre></blockquote> + + <tp:rationale> + Some protocols allow us to send SMSes to a remote contact, without + knowing the phone number to which those SMSes will be sent. This + provides a mechanism to request such channels. + </tp:rationale> + + <p>If this property is not included in the channel request, the + Connection Manager MAY return an SMS channel if that is the most + appropriate medium (i.e. if the channel target is a phone + number).</p> + + <tp:rationale> + To some types of identifiers (i.e. phone numbers) it only makes + sense to return an SMS channel, this is what happens currently with + telepathy-ring. We don't want to break this behaviour when we are + not explicit about the type of channel we want. Alternatively, for + protocols where there is an SMS fallback for IM messages, it's + possible that we don't care what sort of channel we get, and simply + want notification of the transport. + </tp:rationale> + + <p>Some protocols have a fallback to deliver IM messages via SMS. + On these protocols, the Connection Manager SHOULD set the property + value as appropriate, and notify its change with + <tp:member-ref>SMSChannelChanged</tp:member-ref>.</p> + + <tp:rationale> + Protocols such as MSN can fall back to delivering IM messages via + SMS. Where possible we want clients to be able to inform the user + that their messages are going to be redirected to the remote + contact's phone. + </tp:rationale> + </tp:docstring> + </property> + + <signal name="SMSChannelChanged" + tp:name-for-bindings="SMS_Channel_Changed"> + <tp:added version="0.21.7"/> + <arg name="SMSChannel" type="b"> + <tp:docstring> + The new value for <tp:member-ref>SMSChannel</tp:member-ref>. + </tp:docstring> + </arg> + <tp:docstring> + This signal indicates a change in the + <tp:member-ref>SMSChannel</tp:member-ref> property. + </tp:docstring> + </signal> </interface> </node> diff --git a/spec/Channel_Interface_Securable.xml b/spec/Channel_Interface_Securable.xml new file mode 100644 index 0000000..d9d9713 --- /dev/null +++ b/spec/Channel_Interface_Securable.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Securable" + 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.Channel.Interface.Securable"> + <tp:added version="0.21.5">as stable API</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to expose security information about + <tp:dbus-ref namespace="ofdT">Channel</tp:dbus-ref>s. The two + properties are sometimes immutable and can be used to make + decisions on how cautious to be about transferring sensitive + data. The special case of <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channels is one example of where the two properties are + immutable.</p> + + <p>For example, clients MAY use these properties to decide + whether the <code>PLAIN</code> mechanism is acceptable for a + <tp:dbus-ref + namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref> + channel.</p> + </tp:docstring> + + <property name="Encrypted" + tp:name-for-bindings="Encrypted" type="b" + access="read" tp:immutable="sometimes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel occurs over an encrypted + connection. This <strong>does not</strong> imply that steps + have been taken to avoid man-in-the-middle attacks.</p> + + <tp:rationale> + <p>For future support for <a + href="http://tools.ietf.org/html/rfc5056">RFC 5056 Channel + Binding</a> it is desirable to be able to use some SASL + mechanisms over an encrypted connection to an unverified peer, + which can prove that it is the desired destination during + the SASL negotiation.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="Verified" + tp:name-for-bindings="Verified" type="b" + access="read" tp:immutable="sometimes"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel occurs over a connection that is + protected against tampering, and has been verified to be with + the desired destination: for instance, one where TLS was + previously negotiated, and the TLS certificate has been + verified against a configured certificate authority or + accepted by the user.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml index 1d59eb8..1a9c397 100644 --- a/spec/Channel_Request.xml +++ b/spec/Channel_Request.xml @@ -209,6 +209,92 @@ </tp:docstring> </signal> + <property name="Hints" tp:name-for-bindings="Hints" + type="a{sv}" access="read"> + <tp:added version="0.21.5"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary of metadata provided by the channel + requester, which the handler and other clients MAY choose to + interpret. Currently no standard keys are defined; clients MAY + choose to use platform-specific keys for their own purposes, but MUST + ignore unknown keys and MUST cope with expected keys being + missing. Clients SHOULD namespace hint names by having them + start with a reversed domain name, in the same way as D-Bus + interface names.</p> + + <tp:rationale>This property might be used to pass a contact ID for a + telephone number shared between two contacts from the address book to + the call UI, so that if you try to call “Mum”, the call UI knows this + rather than having to guess or show “Calling Mum or Dad”. The format + of these contact IDs would be platform-specific, so we leave the + definition of the dictionary entry up to the platform in question. + But third-party channel requesters might not include the contact ID, + so the call UI has to be able to deal with it not being + there.</tp:rationale> + + <p>The channel dispatcher does not currently interpret any of these + hints: they are solely for communication between cooperating + clients. If hints that do affect the channel dispatcher are added in + future, their names will start with an appropriate reversed domain + name (e.g. <code>org.freedesktop.Telepathy</code> for hints defined + by this specification, or an appropriate vendor name for third-party + plugins).</p> + + <p>This property may be set when the channel request is created, and + can never change. Since it is immutable, it SHOULD be included in the + dictionary of properties passed to <tp:dbus-ref + namespace="ofdT.Client.Interface.Requests">AddRequest</tp:dbus-ref> + by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>.</p> + </tp:docstring> + </property> + + <signal name="SucceededWithChannel" tp:name-for-bindings="Succeeded_With_Channel"> + <tp:added version="0.21.5"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Variant of the <tp:dbus-ref + namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal + allowing to get the channel which has been created.</p> + + <p>This signal MUST be emitted if the + <tp:dbus-ref namespace="ofdT">ChannelDispatcher</tp:dbus-ref>'s + <tp:dbus-ref + namespace="ofdT.ChannelDispatcher">SupportsRequestHints</tp:dbus-ref> + property is true. If supported, it MUST be emitted before + the <tp:member-ref>Succeeded</tp:member-ref> signal.</p> + </tp:docstring> + + <arg name="Connection" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Connection owning the channel.</p> + </tp:docstring> + </arg> + + <arg name="Connection_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A subset of the Connection's properties, currently unused. + This parameter may be used in future.</p> + </tp:docstring> + </arg> + + <arg name="Channel" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel which has been created.</p> + </tp:docstring> + </arg> + + <arg name="Channel_Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same immutable properties of the Channel that would appear + in a <tp:dbus-ref namespace="ofdT.Connection.Interface.Requests" + >NewChannels</tp:dbus-ref> signal.</p> + </tp:docstring> + </arg> + + </signal> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Call.xml b/spec/Channel_Type_Call.xml index a45d956..039c1f9 100644 --- a/spec/Channel_Type_Call.xml +++ b/spec/Channel_Type_Call.xml @@ -1163,12 +1163,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </property> <property name="InitialTransport" tp:name-for-bindings="Initial_Transport" - type="s" access="read" tp:requestable="yes" tp:immutable="yes"> + type="u" tp:type="Stream_Transport_Type" access="read" + tp:requestable="yes" tp:immutable="yes"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If set on a requested channel, this indicates the transport that should be used for this call. Where not applicable, this property - is defined to be the empty string, in particular, on CMs with - hardware streaming.</p> + is defined to be <tp:type>Stream_Transport_Type</tp:type>_Unknown, + in particular, on CMs with hardware streaming.</p> <tp:rationale> When implementing a voip gateway one wants the outgoing leg of the diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml index 335c71f..fefa77a 100644 --- a/spec/Channel_Type_Contact_Search.xml +++ b/spec/Channel_Type_Contact_Search.xml @@ -31,7 +31,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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.</p> + found. Channels of this type should have <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> + <code>None</code> (and hence <tp:dbus-ref + namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and + <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref> + <code>""</code>). Requests for channels of this type need only + optionally specify the <tp:member-ref>Server</tp:member-ref> property + (if it is an allowed property in the connection's <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p> <p>Before searching, the <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be @@ -240,8 +248,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:simple-type> - <property name="Limit" type="u" access="read" - tp:name-for-bindings="Limit"> + <property name="Limit" type="u" access="read" tp:name-for-bindings="Limit" + tp:immutable='yes' tp:requestable='sometimes'> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If supported by the protocol, the maximum number of results that should be returned, where <code>0</code> represents no limit. If the @@ -254,23 +262,20 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <code>2</code>, the search service SHOULD only return <i>Antonius</i> and <i>Bridget</i>.</p> - <p>This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - <tp:type>Requestable_Channel_Class</tp:type> if and only if the - protocol supports specifying a limit; implementations SHOULD use + <p>This property SHOULD be requestable if and only if the protocol + supports specifying a limit; implementations SHOULD use <code>0</code> as the default if possible, or a protocol-specific sensible default otherwise.</p> </tp:docstring> </property> <property name="AvailableSearchKeys" type="as" access="read" - tp:name-for-bindings="Available_Search_Keys"> + tp:name-for-bindings="Available_Search_Keys" tp:immutable='yes'> <tp:docstring> The set of search keys supported by this channel. Example values include [""] (for protocols where several address fields are implicitly searched) or ["x-n-given", "x-n-family", "nickname", "email"] (for XMPP XEP-0055, without extensibility via Data Forms). - This property cannot change during the lifetime of a channel. <tp:rationale> It can be in the <tp:dbus-ref @@ -426,7 +431,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <property name="Server" tp:name-for-bindings="Server" - type="s" access="read"> + type="s" access="read" tp:requestable='sometimes' tp:immutable='yes'> <tp:docstring> <p>For protocols which support searching for contacts on multiple servers with different DNS names (like XMPP), the DNS name of the @@ -439,9 +444,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ User Directory").</p> </tp:rationale> - <p>This property cannot change during the lifetime of the channel. - This property SHOULD be in the Allowed_Properties of a - <tp:type>Requestable_Channel_Class</tp:type> if and only if the + <p>This property SHOULD be requestable if and only if the protocol supports querying multiple different servers; implementations SHOULD use a sensible default if possible if this property is not specified in a channel request.</p> diff --git a/spec/Channel_Type_Server_Authentication.xml b/spec/Channel_Type_Server_Authentication.xml new file mode 100644 index 0000000..76599aa --- /dev/null +++ b/spec/Channel_Type_Server_Authentication.xml @@ -0,0 +1,121 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Server_Authentication" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> Copyright © 2010 Collabora Limited </tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.Channel.Type.ServerAuthentication"> + <tp:added version="0.21.5">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type for a channel representing an authentication step with the + server. The actual authentication functionality is implemented by + the additional interface named in + <tp:member-ref>AuthenticationMethod</tp:member-ref>, + such as <tp:dbus-ref namespace="ofdT" + >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> + + <p>Future authentication steps also supported by this channel type might + include solving a captcha and/or agreeing to an EULA or terms-of-use + document; each of these would be represented by a channel with this + type, but a different + <tp:member-ref>AuthenticationMethod</tp:member-ref>.</p> + + <p>Channels of this type will normally be be signalled and dispatched + while the <tp:dbus-ref namespace="ofdT">Connection</tp:dbus-ref> + owning them is in the CONNECTING state. They MAY also appear on a + Connection in the CONNECTED state, for instance if periodic + re-authentication is required.</p> + + <p>Normally, only one channel of this type will + exist on a given Connection; if there is more than one, the handler + must complete authentication with each of them in turn.</p> + + <p>Channels of this type cannot be requested with methods such as + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>. + They always have <tp:dbus-ref + namespace="ofdT.Channel">Requested</tp:dbus-ref> = False, + <tp:dbus-ref + namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> = None + and <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + = 0.</p> + + <p>While it is CONNECTING, the Connection MUST NOT proceed with + connection, or signal + <tp:dbus-ref namespace="ofdT.Connection">StatusChanged</tp:dbus-ref> + to the CONNECTED state, until each channel of this type has either + been accepted as having a positive result (for instance, on SASL + channels this is done with the <tp:dbus-ref + namespace="ofdT.Channel.Interface.SASLAuthentication" + >AcceptSASL</tp:dbus-ref> method), or closed with the <tp:dbus-ref + namespace="ofdT.Channel">Close</tp:dbus-ref> method.</p> + + <tp:rationale> + <p>ServerAuthentication channels normally represent the client + authenticating itself to the server, but can also be used for the + server to authenticate itself to the client (i.e. prove that it is + in fact the desired server and not an imposter). Until the + authentication handler has confirmed this, connection should not + continue.</p> + </tp:rationale> + + <p>If a channel of this type is closed with the <tp:dbus-ref + namespace="ofdT.Channel">Close</tp:dbus-ref> method before + authentication has succeeded, this indicates that the Handler has + given up its attempts to authenticate or that no Handler is + available.</p> + + <p>If this occurs, the connection manager MAY attempt to continue + connection (for instance, performing SASL authentication by using any + credentials passed to <tp:dbus-ref + namespace="ofdT.ConnectionManager">RequestConnection</tp:dbus-ref>, + for instance from the <tp:dbus-ref + namespace="ofdT">Account.Parameters</tp:dbus-ref>). If this fails + or has already been tried, the <tp:dbus-ref + namespace="ofdT">Connection</tp:dbus-ref> will + disconnect.</p> + + <tp:rationale> + <p>In particular, the <tp:dbus-ref + namespace="ofdT">ChannelDispatcher</tp:dbus-ref> will close the + channel if it cannot find a handler.</p> + </tp:rationale> + + <p>When the connection is done with the channel and it is no + longer needed, it is left open until either the connection state + turns to DISCONNECTED or the handler closes the channel. The + channel SHOULD NOT close itself once finished with.</p> + </tp:docstring> + + <property name="AuthenticationMethod" + tp:name-for-bindings="Authentication_Method" + type="s" tp:type="DBus_Interface" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This property defines the method used for the authentication step + represented by this channel, which MUST be one of this channel's + <tp:dbus-ref namespace="ofdT.Channel">Interfaces</tp:dbus-ref>.</p> + + <p>The initially-defined interface that can be used here is + <tp:dbus-ref namespace="ofdT" + >Channel.Interface.SASLAuthentication</tp:dbus-ref>.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml index 9cbfea2..0cd4d5b 100644 --- a/spec/Channel_Type_Text.xml +++ b/spec/Channel_Type_Text.xml @@ -20,6 +20,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:license> <interface name="org.freedesktop.Telepathy.Channel.Type.Text"> <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires + interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/> + <tp:changed version="0.21.5">The Messages interface is now + mandatory</tp:changed> <tp:simple-type name="Message_ID" type="u" array-name="Message_ID_List"> <tp:docstring> @@ -31,6 +35,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:simple-type> <tp:struct name="Pending_Text_Message" array-name="Pending_Text_Message_List"> + <tp:deprecated version="0.21.5">New APIs should use + an array of <tp:type>Message_Part</tp:type> instead.</tp:deprecated> <tp:docstring>A struct (message ID, timestamp in seconds since 1970-01-01 00:00 UTC, sender's handle, message type, flags, text) representing a pending text message, as returned by @@ -67,6 +73,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <method name="GetMessageTypes" tp:name-for-bindings="Get_Message_Types"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageTypes</tp:dbus-ref> is preferred. + </tp:deprecated> <arg direction="out" type="au" tp:type="Channel_Text_Message_Type[]" name="Available_Types"> <tp:docstring> @@ -81,6 +91,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <method name="ListPendingMessages" tp:name-for-bindings="List_Pending_Messages"> + <tp:deprecated version="0.21.5">Consulting + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> is preferred. + </tp:deprecated> <arg direction="in" name="Clear" type="b"> <tp:docstring> If true, behave as if @@ -114,6 +128,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </method> <signal name="LostMessage" tp:name-for-bindings="Lost_Message"> + <tp:deprecated version="0.21.5">In practice, this signal + was not emitted, and does not have useful semantics.</tp:deprecated> <tp:docstring> This signal is emitted to indicate that an incoming message was not able to be stored and forwarded by the connection manager @@ -122,6 +138,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <signal name="Received" tp:name-for-bindings="Received"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal is more informative. + </tp:deprecated> <arg name="ID" type="u"> <tp:docstring> A numeric identifier for acknowledging the message @@ -162,6 +182,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <method name="Send" tp:name-for-bindings="Send"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> method is more flexible. + </tp:deprecated> <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type"> <tp:docstring> An integer indicating the type of the message @@ -231,6 +255,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enum> <signal name="SendError" tp:name-for-bindings="Send_Error"> + <tp:deprecated version="0.21.5">Delivery reporting is now + provided by the <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface. + </tp:deprecated> <arg name="Error" type="u" tp:type="Channel_Text_Send_Error"> <tp:docstring> The error that occurred @@ -266,6 +294,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </signal> <signal name="Sent" tp:name-for-bindings="Sent"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageSent</tp:dbus-ref> signal is more informative. + </tp:deprecated> <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> Unix timestamp indicating when the message was sent @@ -335,6 +367,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:enum> <tp:flags name="Channel_Text_Message_Flags" value-prefix="Channel_Text_Message_Flag" type="u"> + <tp:deprecated version="0.21.5">The + <tp:dbus-ref namespace="ofdT.Channel.Interface" + >Messages</tp:dbus-ref> interface has an extensible data structure + including separate booleans for most of these flags. + </tp:deprecated> <tp:flag suffix="Truncated" value="1"> <tp:docstring> The incoming message was truncated to a shorter length by the @@ -480,77 +517,98 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:property> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A channel type for sending and receiving messages in plain text, - with no formatting. In future specifications, channels for sending - and receiving messages that can be reduced to plain text (i.e. - formatted text) should also have this type.</p> + <p>A channel type for sending and receiving messages. This channel type + is primarily used for textual messages, but can also be used for + formatted text, text with "attachments", or binary messages on some + protocols.</p> + + <p>Most of the methods and signals on this interface are deprecated, + since they only support plain-text messages with limited metadata. + See the mandatory <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages</tp:dbus-ref> + interface for the modern equivalents.</p> <p>When a message is received, an identifier is assigned and a - <tp:member-ref>Received</tp:member-ref> signal emitted, and the message - placed in a pending queue which can be inspected with - <tp:member-ref>ListPendingMessages</tp:member-ref>. A client which has - handled the message by showing it to the user (or equivalent) should - acknowledge the receipt using the - <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> method, - and the message will then be removed from the pending queue. Numeric - identifiers for received messages may be reused over the lifetime of - the channel.</p> - - <p>Each message has an associated 'type' value, which should be one - of the values allowed by - <tp:type>Channel_Text_Message_Type</tp:type>.</p> - - <p>Each message also has a flags value, which is a bitwise OR of the - flags given in <tp:type>Channel_Text_Message_Flags</tp:type>.</p> + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >MessageReceived</tp:dbus-ref> signal emitted, and the message + is placed in a pending queue represented by the + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >PendingMessages</tp:dbus-ref> property. + When the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + for a channel has handled the message by showing it to the user + (or equivalent), it should acknowledge the receipt of that message + using the <tp:member-ref>AcknowledgePendingMessages</tp:member-ref> + method, and the message will then be removed from the pending queue. + Numeric identifiers for received messages may be reused over the + lifetime of the channel.</p> <p>Sending messages can be requested using the - <tp:member-ref>Send</tp:member-ref> method, which will return - successfully and emit the <tp:member-ref>Sent</tp:member-ref> signal - when the message has been delivered to the server, or return an error - with no signal emission if there is a failure. If a message is sent but - delivery of the message later fails, this is indicated with the - <tp:member-ref>SendError</tp:member-ref> signal.</p> - - <p>On protocols where additional contacts cannot be invited into - a one-to-one chat, or where a one-to-one chat is just a series of - individual personal messages rather than being represented by some - object on the server (i.e. most protocols), one-to-one chats should be - represented by a Text channel with <tp:type>Handle_Type</tp:type> - CONTACT.</p> + <tp:dbus-ref namespace="ofdT.Channel.Interface.Messages" + >SendMessage</tp:dbus-ref> method, which will return + successfully when the message has been submitted for sending, or + return an error with no signal emission if there is an immediate + failure. If a message is submitted for sending but delivery of the + message later fails, this is indicated by a delivery report, which + is received in the same way as an incoming message.</p> + + <p>Simple one-to-one chats (such as streams of private messages in + XMPP or IRC) should be represented by a Text channel whose + <tp:dbus-ref namespace="ofdT.Channel">TargetHandleType</tp:dbus-ref> + is <tp:type>Handle_Type</tp:type>_Contact. The expected way to + request such a channel is to set the ChannelType, TargetHandleType, + and either TargetHandle or TargetID in a call to EnsureChannel.</p> <p>Named chat rooms whose identity can be saved and used again later (IRC channels, Jabber MUCs) are expected to be represented by Text - channels with <tp:type>Handle_Type</tp:type> ROOM and the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> - interface; they should usually also have the Properties interface.</p> - - <p>Unnamed, transient chat rooms defined only by their members (e.g. on - MSN) are expected to be represented by Text channels with handle type - 0, handle 0, the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> - interface, and optionally the Properties interface.</p> - - <p>On protocols where a conversation with a user is actually just - a nameless chat room starting with exactly two members, to which - more members can be invited, calling - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> - with type Text - and handle type CONTACT should continue to succeed, but may return - a channel with handle type 0, handle 0, the group interface, - and the local and remote contacts in its members.</p> + channels with <tp:type>Handle_Type</tp:type>_Room and the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface. In protocols where a chatroom can be used as a continuation + of one or more one-to-one chats, these channels should also have the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>Unnamed, transient chat rooms which cannot be rejoined by their + unique identifier (e.g. a conversation on MSN which has, or once had, + three or more participants) are expected to be represented by Text + channels with Handle_Type_None (and hence TargetHandle 0), the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface, and optionally the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> + interface.</p> + + <p>On protocols like MSN where a conversation with a user is actually + just a nameless chat room starting with exactly two members, to which + more members can be invited, the initial one-to-one conversation + SHOULD be represented with Handle_Type_Contact. If a third participant + joins or is invited, this SHOULD be represented by signalling + a new <tp:dbus-ref + namespace="ofdT.Channel.Interface">Conference</tp:dbus-ref> channel + with the one-to-one channel in its <tp:dbus-ref + namespace="ofdT.Channel.Interface.Conference" + >InitialChannels</tp:dbus-ref>, migrating the underlying protocol + object from the one-to-one channel to the Conference channel, + and creating a new protocol-level conversation if the one-to-one + channel is re-used. See the Conference interface for more details.</p> + + <tp:rationale> + <p>This keeps the presentation of all one-to-one conversations + uniform, and makes it easier to hand over a conversation from a + 1-1-specific UI to a more elaborate multi-user UI; while it does + require UIs to understand Conference to follow the + upgrade, UIs that will deal with XMPP need to understand Conference + anyway.</p> + </tp:rationale> <p>If a channel of type Text is closed while it has pending messages, - the connection manager MUST allow this, but SHOULD open a new, - identical channel to deliver those messages, signalling it as a new - channel with the - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">NewChannel</tp:dbus-ref> - signal (with the suppress_handler parameter set to FALSE).</p> - - <p>If messages were sent on the old channel but the - <tp:member-ref>Sent</tp:member-ref>signal has not yet been emitted - for those messages, the new channel SHOULD emit Sent for those - messages when appropriate - it behaves like a continuation of the - old channel.</p> + the connection manager MUST allow this, but SHOULD open a new channel + to deliver those messages, signalling it as a new channel with the + <tp:dbus-ref + namespace="ofdT.Connection.Interface.Requests">NewChannels</tp:dbus-ref> + signal. The new channel should resemble the old channel, but have + Requested = FALSE regardless of its previous value; the InitiatorHandle + and InitiatorID should correspond to the sender of one of the pending + messages.</p> <tp:rationale> <p>In effect, this turns this situation, in which a client @@ -573,16 +631,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <li>UI calls Close on text channel</li> <li>text channel emits Closed and closes</li> <li>message arrives</li> - <li>new text channel is created, connection emits NewChannel</li> + <li>new text channel is created, connection emits NewChannels</li> <li>(the same or a different) UI handles it</li> </ul> - <p>suppress_handler must be set to FALSE so the replacement channel + <p>Requested must be set to FALSE so the replacement channel will be handled by something.</p> + + <p>In practice, connection managers usually implement this by keeping + the same internal object that represented the old channel, adjusting + its properties, signalling that it was closed, then immediately + re-signalling it as a new channel.</p> </tp:rationale> <p>As a result, Text channels SHOULD implement <tp:dbus-ref - namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable</tp:dbus-ref>.</p> + namespace="ofdT">Channel.Interface.Destroyable</tp:dbus-ref>.</p> <tp:rationale> <p>This "respawning" behaviour becomes problematic if there is no diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml index 2cceed1..3a922e8 100644 --- a/spec/Client_Handler.xml +++ b/spec/Client_Handler.xml @@ -103,8 +103,7 @@ <code>/org/freedesktop/Telepathy/Client/Empathy/_1/_42/Bundle1</code> with BypassApproval = TRUE, whose <tp:member-ref>HandlerChannelFilter</tp:member-ref> - matches closely related Text channels by their Bundle property. - (This is use-case dis5)</p> + matches closely related Text channels by their Bundle property.</p> </tp:rationale> <p>For service-activatable handlers, this property should be specified diff --git a/spec/Client_Interface_Requests.xml b/spec/Client_Interface_Requests.xml index cfab58d..3cecfce 100644 --- a/spec/Client_Interface_Requests.xml +++ b/spec/Client_Interface_Requests.xml @@ -125,8 +125,8 @@ and <tp:dbus-ref namespace="org.freedesktop.Telepathy.ChannelRequest">Account</tp:dbus-ref> MUST be included, and <tp:dbus-ref - namespace="ofdT.ChannelRequest.FUTURE">Hints</tp:dbus-ref> - SHOULD be included if implemented.</p> + namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref> + MUST be included if implemented.</p> </tp:docstring> </arg> </method> diff --git a/spec/Connection.xml b/spec/Connection.xml index a694e24..51ec1ab 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -222,6 +222,9 @@ USA.</p> </method> <method name="HoldHandles" tp:name-for-bindings="Hold_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer does anything.</tp:changed> <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> <tp:docstring> The type of handle to be held @@ -235,7 +238,13 @@ USA.</p> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Notify the connection manger that your client is holding a copy + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.</p> + + <p>In older connection managers, this method + notifies the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the <tp:member-ref>RequestHandles</tp:member-ref> method. For @@ -390,6 +399,9 @@ USA.</p> </signal> <method name="ReleaseHandles" tp:name-for-bindings="Release_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer does anything.</tp:changed> <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> <tp:docstring> An integer handle type (as defined in RequestHandle) @@ -403,10 +415,17 @@ USA.</p> </arg> <tp:docstring> - Explicitly notify the connection manager that your client is no + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + this method does nothing and returns successfully, unless + the given handle type or any of the given handles is invalid.</p> + + <p>In older connection managers, this method + explicitly notifies the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or - referenced by any existing channels. See HoldHandles for notes. + referenced by any existing channels. See + <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p> </tp:docstring> <tp:possible-errors> @@ -421,11 +440,6 @@ USA.</p> One of the given handles is not valid </tp:docstring> </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - One of the given handles is not held by this client - </tp:docstring> - </tp:error> </tp:possible-errors> </method> @@ -622,6 +636,9 @@ USA.</p> </tp:simple-type> <method name="RequestHandles" tp:name-for-bindings="Request_Handles"> + <tp:changed version="0.21.6">If + <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + this method no longer has its reference-counting effect.</tp:changed> <arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type"> <tp:docstring> The type of handle required @@ -641,17 +658,23 @@ USA.</p> </tp:docstring> </arg> - <tp:docstring> - Request several handles from the connection manager which represent a - number of contacts, rooms or server-stored lists on the service. The - connection manager should record that these handles are in use by the + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request several handles from the connection manager which represent a + number of contacts, rooms or server-stored lists on the service.</p> + + <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, + which SHOULD always be the case in this version of telepathy-spec, + the handles remain valid until the connection disconnects.</p> + + <p>The implementation of this method in older connection managers + must record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the <tp:member-ref>ReleaseHandles</tp:member-ref> method. Where the identifier refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection - manager. + manager.</p> </tp:docstring> <tp:possible-errors> @@ -1169,6 +1192,18 @@ USA.</p> </arg> </method> + <property name="HasImmortalHandles" + tp:name-for-bindings="Has_Immortal_Handles" + access="read" type="b"> + <tp:added version="0.21.6"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if handles last for the whole lifetime of the Connection. + This SHOULD be the case in all connection managers, but clients + MUST interoperate with older connection managers + (which reference-count handles).</p> + </tp:docstring> + </property> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This models a connection to a single user account on a communication service. Its basic capability is to provide the facility to request and diff --git a/spec/Connection_Interface_Communication_Policy.xml b/spec/Connection_Interface_Communication_Policy.xml index 9a92fa0..31343de 100644 --- a/spec/Connection_Interface_Communication_Policy.xml +++ b/spec/Connection_Interface_Communication_Policy.xml @@ -146,13 +146,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:rationale> </tp:docstring> <tp:member type="as" tp:type="DBus_Interface[]" - name="Chanel_Types"> + name="Channel_Types"> <tp:docstring> A list of channel interfaces that support these policies. </tp:docstring> </tp:member> <tp:member type="au" tp:type="Access_Control_Type[]" - name="Supported Policies"> + name="Supported_Policies"> <tp:docstring> A list of supported policies. </tp:docstring> diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml index ce77a56..527d325 100644 --- a/spec/Connection_Interface_Contact_Info.xml +++ b/spec/Connection_Interface_Contact_Info.xml @@ -470,6 +470,36 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ any parameters may be used.</p> </tp:docstring> </tp:flag> + + <tp:flag suffix="Overwritten_By_Nickname" value="2"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Indicates that this field will be overwritten when the user's alias + is changed with <tp:dbus-ref + namespace="ofdT.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref> + or when the Account's <tp:dbus-ref + namespace="ofdT.Account">Nickname</tp:dbus-ref> + is updated. Clients that allow the editing of the Alias and the + ContactInfo in the same location should hide fields with this flag.</p> + <tp:rationale> + <p>If a client allowed the user to edit both the nickname and the + ContactInfo field at the same time, the user could set them to two + different values even though they map to the same property. This + would result in surprising behavior where the second value would + win over the first.</p> + </tp:rationale> + <p>In addition to hiding this field when editing ContactInfo together + with the user's nickname, it is recommended that clients call + <tp:member-ref>SetContactInfo</tp:member-ref> before setting the + user's nickname.</p> + <tp:rationale> + <p>This ensures that if the user changes the nickname, the correct + value will get set even if the stale nickname is mistakenly sent + along with <tp:member-ref>SetContactInfo</tp:member-ref>.</p> + </tp:rationale> + <p>If used, this flag typically appears on either the 'nickname' or + 'fn' field.</p> + </tp:docstring> + </tp:flag> </tp:flags> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/Connection_Interface_Contact_List.xml b/spec/Connection_Interface_Contact_List.xml index d602c19..e0cccd5 100644 --- a/spec/Connection_Interface_Contact_List.xml +++ b/spec/Connection_Interface_Contact_List.xml @@ -173,10 +173,12 @@ <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>If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. + (If <tp:dbus-ref namespace="ofdT.Connection" + >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the + case in all new connection managers, this has no effect.)</p> </tp:docstring> </arg> @@ -652,15 +654,27 @@ subscribe to their presence, i.e. that their subscribe attribute becomes Yes.</p> + <p>Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically allow the contacts to see the local user's + presence). User interfaces that require mutual subscription + MAY call <tp:member-ref>AuthorizePublication</tp:member-ref> + at the same time as this method.</p> + + <tp:rationale> + <p>Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.</p> + </tp:rationale> + <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>. + >SetAliases</tp:dbus-ref>.</p> - The user MAY be + <p>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 @@ -793,6 +807,19 @@ presence is sent to that contact, i.e. that their publish attribute becomes Yes.</p> + <p>Connection managers SHOULD NOT attempt to enforce a + mutual-subscription policy (i.e. when this method is called, they + should not automatically request that the contacts allow the user to + subscribe to their presence). User interfaces that require mutual + subscription MAY call + <tp:member-ref>RequestSubscription</tp:member-ref> at the same time + as this method.</p> + + <tp:rationale> + <p>Whether to enforce mutual subscription is a matter of policy, + so it is left to the user interface and/or the server.</p> + </tp:rationale> + <p>For contacts with publish=Yes, this method has no effect; it MUST return successfully if all contacts given have this state.</p> diff --git a/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml index cd769ce..1020190 100644 --- a/spec/Connection_Interface_Contacts.xml +++ b/spec/Connection_Interface_Contacts.xml @@ -152,13 +152,16 @@ </arg> <arg direction="in" name="Hold" type="b"> - <tp:docstring> - If true, all handles in the result have been held on behalf of the - calling process, as if by a call to - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.HoldHandles</tp:dbus-ref>. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, all handles that appear as keys in the result have been + held on behalf of the calling process, as if by a call to + <tp:dbus-ref namespace="ofdT">Connection.HoldHandles</tp:dbus-ref>. + (If <tp:dbus-ref namespace="ofdT.Connection" + >HasImmortalHandles</tp:dbus-ref> is true, which SHOULD be the + case in all new connection managers, this has no effect.)</p> <tp:rationale> - For further round-trip avoidance. + <p>For further round-trip avoidance.</p> </tp:rationale> </tp:docstring> </arg> diff --git a/spec/Connection_Interface_Mail_Notification.xml b/spec/Connection_Interface_Mail_Notification.xml index 1ac6d1a..395e101 100644 --- a/spec/Connection_Interface_Mail_Notification.xml +++ b/spec/Connection_Interface_Mail_Notification.xml @@ -23,6 +23,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:requires interface="org.freedesktop.Telepathy.Connection"/> <tp:added version="0.21.3">(as stable API)</tp:added> + <tp:client-interest> + <tp:docstring> + A client MUST notify interest in this feature before it will be + enabled. + </tp:docstring> + </tp:client-interest> + <tp:flags name="Mail_Notification_Flags" value-prefix="Mail_Notification_Flag" type="u" > <tp:flag suffix="Supports_Unread_Mail_Count" value="1"> <tp:docstring> diff --git a/spec/Connection_Interface_Power_Saving.xml b/spec/Connection_Interface_Power_Saving.xml index ae82d2f..571bf6d 100644 --- a/spec/Connection_Interface_Power_Saving.xml +++ b/spec/Connection_Interface_Power_Saving.xml @@ -2,7 +2,7 @@ <node name="/Connection_Interface_Power_Saving" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" > - <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright> + <tp:copyright> Copyright © 2007-2010 Collabora Limited </tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -19,9 +19,8 @@ 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.PowerSaving.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.19.12"/> + name="org.freedesktop.Telepathy.Connection.Interface.PowerSaving"> + <tp:added version="0.21.5">(as stable API)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Some protocols support mechanisms for reducing bandwidth usage—and hence power usage, on mobile devices—when the user is not directly diff --git a/spec/Protocol.xml b/spec/Protocol.xml index e37fe22..5e2c9b1 100644 --- a/spec/Protocol.xml +++ b/spec/Protocol.xml @@ -65,6 +65,7 @@ RequestableChannelClasses=text; VCardField=x-example EnglishName=Example Icon=im-example +AuthenticationTypes=org.freedesktop.Telepathy.Channel.Type.ServerTLSConnection;org.freedesktop.Telepathy.Channel.Interface.SASLAuthentication; [text] org.freedesktop.Telepathy.Channel.ChannelType s=org.freedesktop.Telepathy.Channel.Type.Text @@ -74,11 +75,12 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </tp:docstring> <property name="Interfaces" tp:name-for-bindings="Interfaces" - access="read" type="as" tp:type="DBus_Interface[]"> + access="read" type="as" tp:type="DBus_Interface[]" + tp:immutable="yes"> <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 + <p>This property 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> @@ -94,12 +96,13 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </property> <property name="Parameters" tp:name-for-bindings="Parameters" - access="read" type="a(susv)" tp:type="Param_Spec[]"> + access="read" type="a(susv)" tp:type="Param_Spec[]" + tp:immutable="yes"> <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> + given protocol.</p> <p>Connection managers with a <code>.manager</code> file (as described as part of the @@ -115,7 +118,8 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy <property name="ConnectionInterfaces" tp:name-for-bindings="Connection_Interfaces" - access="read" type="as" tp:type="DBus_Interface[]"> + access="read" type="as" tp:type="DBus_Interface[]" + tp:immutable="yes"> <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" @@ -125,7 +129,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy 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 + <p>This property should not be confused with <tp:member-ref>Interfaces</tp:member-ref>.</p> <p>Connection managers with a <code>.manager</code> file @@ -138,7 +142,8 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy <property name="RequestableChannelClasses" tp:name-for-bindings="Requestable_Channel_Classes" - access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]"> + access="read" type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" + tp:immutable="yes"> <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" @@ -152,8 +157,6 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy 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 @@ -206,7 +209,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </property> <property name="VCardField" tp:name-for-bindings="VCard_Field" - access="read" type="s"> + access="read" type="s" tp:immutable="yes"> <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 @@ -251,7 +254,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </property> <property name="EnglishName" tp:name-for-bindings="English_Name" - access="read" type="s"> + access="read" type="s" tp:immutable="yes"> <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 @@ -285,7 +288,7 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </property> <property name="Icon" tp:name-for-bindings="Icon" - access="read" type="s"> + access="read" type="s" tp:immutable="yes"> <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> @@ -429,6 +432,54 @@ allowed=org.freedesktop.Telepathy.Channel.TargetHandle;org.freedesktop.Telepathy </tp:possible-errors> </method> + <property name="AuthenticationTypes" + tp:name-for-bindings="Authentication_Types" access="read" type="as" + tp:type="DBus_Interface[]" tp:immutable="yes"> + <tp:added version="0.21.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of D-Bus interfaces which provide information as to + what kind of authentication channels can possibly appear + before the connection reaches the CONNECTED state.</p> + + <p>These can either be channel types, or where the channel + type isn't enough information to be useful, interfaces + indicating a specific use of a channel type. For example, + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> + channels are obviously about TLS certificates so the channel + type would appear in this list. However, a + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel type alone does not explain enough about the authentication type + in use as it is merely a base for the channel interfaces that appear in + said channels. In this case, CMs should use the value of the + <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref> + property in this list.</p> + + <p>For example, if a protocol's + <tp:member-ref>AuthenticationTypes</tp:member-ref> contains + two values:</p> + + <blockquote> + <pre> +[ ...<tp:dbus-ref namespace="ofdT">Channel.Type.ServerTLSConnection</tp:dbus-ref>, + ...<tp:dbus-ref namespace="ofdT">Channel.Interface.SASLAuthentication</tp:dbus-ref> ]</pre></blockquote> + + <p>This tells a client that before the connection status + reached CONNECTED, a <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerTLSConnection</tp:dbus-ref> + could appear carrying a TLS certificate. It also tells the + client that before the connection status reaches CONNECTED, a + <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref> + channel could also appear, where <tp:dbus-ref + namespace="ofdT.Channel.Type">ServerAuthentication.AuthenticationMethod</tp:dbus-ref>=<tp:dbus-ref + namespace="ofdT.Channel.Interface">SASLAuthentication</tp:dbus-ref>. A + hypothetical future Channel.Interface.Captcha interface would + also appear in this list if the CM might require the user + solve a captcha before connecting.</p> + + </tp:docstring> + </property> + </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 index 262741e..cd91351 100644 --- a/spec/Protocol_Interface_Avatars.xml +++ b/spec/Protocol_Interface_Avatars.xml @@ -20,9 +20,8 @@ 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> + <interface name="org.freedesktop.Telepathy.Protocol.Interface.Avatars"> + <tp:added version="0.21.5">(as stable API)</tp:added> <tp:requires interface="org.freedesktop.Telepathy.Protocol"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> diff --git a/spec/all.xml b/spec/all.xml index afb48df..61a97c7 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.21.4</tp:version> +<tp:version>0.21.7</tp:version> <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright> <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright> @@ -40,36 +40,72 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:section name="Connection Object"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p> - Connections represent active protocol sessions. + Connections represent active protocol sessions. There are a number of core + interfaces which all connections should implement, and a number of optional + interfaces which provide various functionality related to contacts and to + the connection itself. </p> </tp:docstring> <xi:include href="Connection.xml"/> <xi:include href="Connection_Future.xml"/> - <xi:include href="Connection_Interface_Addressing.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_Client_Types.xml"/> - <xi:include href="Connection_Interface_Communication_Policy.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_Keepalive.xml"/> - <xi:include href="Connection_Interface_Location.xml"/> - <xi:include href="Connection_Interface_Mail_Notification.xml"/> - <xi:include href="Connection_Interface_Power_Saving.xml"/> - <xi:include href="Connection_Interface_Presence.xml"/> - <xi:include href="Connection_Interface_Renaming.xml"/> - <xi:include href="Connection_Interface_Resources.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 name="Contact list interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + On protocols that support contact lists, these interface expose the user's + contact lists, along with presence subscription information and contact + list groups (if supported). + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Contact_List.xml"/> + <xi:include href="Connection_Interface_Contact_Groups.xml"/> + </tp:section> + + <tp:section name="Contact metadata interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + These optional Connection interfaces expose metadata about contacts on + this connection—from their current presence through to the type of client + they're connected with—and allow the local user to publish such metadata + back to their contacts. + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Aliasing.xml"/> + <xi:include href="Connection_Interface_Avatars.xml"/> + <xi:include href="Connection_Interface_Capabilities.xml"/> + <xi:include href="Connection_Interface_Client_Types.xml"/> + <xi:include href="Connection_Interface_Contact_Capabilities.xml"/> + <xi:include href="Connection_Interface_Contact_Info.xml"/> + <xi:include href="Connection_Interface_Location.xml"/> + <xi:include href="Connection_Interface_Presence.xml"/> + <xi:include href="Connection_Interface_Renaming.xml"/> + <xi:include href="Connection_Interface_Resources.xml"/> + <xi:include href="Connection_Interface_Simple_Presence.xml"/> + </tp:section> + + <tp:section name="Connection feature interfaces"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + These optional Connection interfaces expose protocol-specific features, + and allow configuring the running connection. + </p> + </tp:docstring> + + <xi:include href="Connection_Interface_Addressing.xml"/> + <xi:include href="Connection_Interface_Anonymity.xml"/> + <xi:include href="Connection_Interface_Balance.xml"/> + <xi:include href="Connection_Interface_Cellular.xml"/> + <xi:include href="Connection_Interface_Communication_Policy.xml"/> + <xi:include href="Connection_Interface_Forwarding.xml"/> + <xi:include href="Connection_Interface_Keepalive.xml"/> + <xi:include href="Connection_Interface_Mail_Notification.xml"/> + <xi:include href="Connection_Interface_Power_Saving.xml"/> + <xi:include href="Connection_Interface_Service_Point.xml"/> + </tp:section> </tp:section> <xi:include href="Channel_Bundle.xml"/> @@ -102,6 +138,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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_Server_Authentication.xml"/> <xi:include href="Channel_Type_Server_TLS_Connection.xml"/> <xi:include href="Channel_Type_Stream_Tube.xml"/> <xi:include href="Channel_Type_Streamed_Media.xml"/> @@ -131,7 +168,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Messages.xml"/> <xi:include href="Channel_Interface_Password.xml"/> <xi:include href="Channel_Interface_Room.xml"/> + <xi:include href="Channel_Interface_SASL_Authentication.xml"/> <xi:include href="Channel_Interface_SMS.xml"/> + <xi:include href="Channel_Interface_Securable.xml"/> <xi:include href="Channel_Interface_Service_Point.xml"/> <xi:include href="Channel_Interface_Splittable.xml"/> <xi:include href="Channel_Interface_Tube.xml"/> @@ -180,6 +219,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> <xi:include href="Account_Manager.xml"/> <xi:include href="Account.xml"/> + <xi:include href="Account_Interface_Addressing.xml"/> <xi:include href="Account_Interface_Avatar.xml"/> <xi:include href="Account_Interface_Storage.xml"/> <xi:include href="Account_Interface_Minimum_Presence.xml"/> @@ -194,11 +234,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </p> </tp:docstring> <xi:include href="Channel_Dispatcher.xml"/> - <xi:include href="Channel_Dispatcher_Future.xml"/> <xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/> <xi:include href="Channel_Dispatch_Operation.xml"/> <xi:include href="Channel_Request.xml"/> - <xi:include href="Channel_Request_Future.xml"/> </tp:section> <tp:section name="Clients"> diff --git a/spec/errors.xml b/spec/errors.xml index 268087b..eccbd09 100644 --- a/spec/errors.xml +++ b/spec/errors.xml @@ -508,6 +508,42 @@ </tp:docstring> </tp:error> + <tp:error name="Service Confused"> + <tp:added version="0.21.5"/> + <tp:docstring> + Raised when a server or other piece of infrastructure indicates an + internal error, or when a message that makes no sense is received from + a server or other piece of infrastructure. + + <tp:rationale> + For instance, this is appropriate for XMPP's + <code>internal-server-error</code>, and is also appropriate if + you receive sufficiently inconsistent information from a server that + you cannot continue. + </tp:rationale> + </tp:docstring> + </tp:error> + + <tp:error name="Confused"> + <tp:added version="0.21.5"/> + <tp:docstring> + Raised if a server rejects protocol messages from a connection manager + claiming that they do not make sense, two local processes fail to + understand each other, or an apparently impossible situation is + reached. + + <tp:rationale> + For instance, this would be an appropriate mapping for XMPP's + errors bad-format, invalid-xml, etc., which can't happen unless + the local (or remote) XMPP implementation is faulty. This is + also analogous to + <tp:type>Media_Stream_Error</tp:type>_Invalid_CM_Behavior, + <code>TP_DBUS_ERROR_INCONSISTENT</code> in telepathy-glib, and + <code>TELEPATHY_QT4_ERROR_INCONSISTENT</code> in telepathy-qt4. + </tp:rationale> + </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"> |