diff options
| author | Olli Salli <olli.salli@collabora.co.uk> | 2008-10-31 13:11:02 +0200 |
|---|---|---|
| committer | Olli Salli <olli.salli@collabora.co.uk> | 2008-10-31 13:11:02 +0200 |
| commit | 6843fe74d0c5736a281d1938ed772de3c80d5a89 (patch) | |
| tree | e3cbc7a1be332aff0cec529611fdda49c356601e /qt4/spec | |
| parent | 7ee24d41c29944da8a8773f82b41c8c71484c405 (diff) | |
Update to spec 0.17.4
Diffstat (limited to 'qt4/spec')
37 files changed, 3652 insertions, 304 deletions
diff --git a/qt4/spec/Account.xml b/qt4/spec/Account.xml index a274bc2b9..5f7b5b7a6 100644 --- a/qt4/spec/Account.xml +++ b/qt4/spec/Account.xml @@ -104,20 +104,21 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. are the ones given special status by the source, and we have all of them --> - <property name="Interfaces" type="as" access="read"> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> <tp:docstring> A list of the extra interfaces provided by this account. </tp:docstring> </property> - <method name="Remove"> + <method name="Remove" tp:name-for-bindings="Remove"> <tp:docstring>Delete the account.</tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> </tp:possible-errors> </method> - <signal name="Removed"> + <signal name="Removed" tp:name-for-bindings="Removed"> <tp:docstring> This account has been removed. @@ -163,7 +164,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Icon" type="s" access="readwrite"> + <property name="Icon" tp:name-for-bindings="Icon" + type="s" access="readwrite"> <tp:docstring> The name of an icon in the system's icon theme, such as "im-msn", or the empty string to not specify an icon. If the icon is set to @@ -179,7 +181,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Valid" type="b" access="read"> + <property name="Valid" tp:name-for-bindings="Valid" + type="b" access="read"> <tp:docstring> If true, this account is considered by the account manager to be complete and usable. If false, user action is required to make it @@ -198,7 +201,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Enabled" type="b" access="readwrite"> + <property name="Enabled" tp:name-for-bindings="Enabled" + type="b" access="readwrite"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This property gives the users the possibility to prevent an account from being used. This flag does not change the validity of the @@ -231,7 +235,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Nickname" type="as" access="readwrite"> + <property name="Nickname" tp:name-for-bindings="Nickname" + type="as" access="readwrite"> <tp:docstring> The nickname to set on this account for display to other contacts, as set by the user. When the account becomes connected, the @@ -249,7 +254,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Parameters" type="a{sv}" access="read"> + <property name="Parameters" tp:name-for-bindings="Parameters" + type="a{sv}" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A map from connection manager parameter names (as in the ConnectionManager interface) to their values. This property includes @@ -339,10 +345,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> </property> - <property name="Connection" type="s" access="read"> + <property name="Connection" tp:name-for-bindings="Connection" + type="o" access="read"> <tp:docstring> - Either the well-known bus name of the connection to this account, - or the empty string if there is no connection. + Either the object path of the connection to this account, + or the special value '/' if there is no connection. + + <tp:rationale> + Object paths aren't nullable, so we can't use an empty string. + </tp:rationale> </tp:docstring> </property> diff --git a/qt4/spec/Account_Interface_Avatar.xml b/qt4/spec/Account_Interface_Avatar.xml index 4ffb8f5cd..9bf31a99b 100644 --- a/qt4/spec/Account_Interface_Avatar.xml +++ b/qt4/spec/Account_Interface_Avatar.xml @@ -35,7 +35,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:docstring> <tp:added version="0.17.6"/> - <property name="Avatar" type="(ays)" access="readwrite"> + <property name="Avatar" tp:name-for-bindings="Avatar" + type="(ays)" access="readwrite"> <tp:docstring> The avatar to set on this account for display to other contacts, represented as a structure containing the bytes of the avatar, diff --git a/qt4/spec/Account_Manager.xml b/qt4/spec/Account_Manager.xml index 841601ac0..b92913e29 100644 --- a/qt4/spec/Account_Manager.xml +++ b/qt4/spec/Account_Manager.xml @@ -29,6 +29,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. the session bus. This process must export an /org/freedesktop/Telepathy/AccountManager object with the AccountManager interface.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of AccountManager implementation, implementations SHOULD NOT + register as an activatable service for the AccountManager's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs can + detect whether Telepathy is in use by checking whether the + AccountManager's well-known name is in use at runtime.</p> </tp:docstring> <tp:added version="0.17.2"/> @@ -43,7 +52,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * register filters (completely out of scope: Channel Dispatcher again) --> - <property name="Interfaces" type="as" access="read"> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> <tp:docstring> A list of the interfaces provided by the account manager object. </tp:docstring> diff --git a/qt4/spec/Channel.xml b/qt4/spec/Channel.xml index dcd28f065..f560ed8fb 100644 --- a/qt4/spec/Channel.xml +++ b/qt4/spec/Channel.xml @@ -35,11 +35,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale> + + <p>When requesting a channel, the request MUST specify a channel + type, and the request MUST fail if the specified channel type + cannot be supplied.</p> + + <tp:rationale> + Common sense. + </tp:rationale> </tp:docstring> </property> - <property name="Interfaces" type="as" tp:type="DBus_Interface[]" - access="read"> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" tp:type="DBus_Interface[]" access="read"> <tp:added version="0.17.7"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Extra interfaces provided by this channel. This SHOULD NOT include @@ -59,6 +67,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The GetAll method lets clients retrieve all properties in one round-trip, which is desirable. </tp:rationale> + + <p>When requesting a channel with a particular value for this + property, the request must fail without side-effects unless the + connection manager expects to be able to provide a channel whose + interfaces include at least the interfaces requested.</p> </tp:docstring> </property> @@ -80,18 +93,89 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ uniqueness guarantee - there can be many channels with the same (channel type, handle type, handle) tuple. This is necessary to support conversation threads in XMPP and SIP, for example.</p> + + <p>If this is present in a channel request, it must be nonzero, + <tp:member-ref>TargetHandleType</tp:member-ref> + MUST be present and not Handle_Type_None, and + <tp:member-ref>TargetID</tp:member-ref> MUST NOT be + present.</p> + + <p>The channel that satisfies the request MUST either:</p> + + <ul> + <li>have the specified TargetHandle property; or</li> + <li>have <tp:member-ref>TargetHandleType</tp:member-ref> = + Handle_Type_None, TargetHandle = 0, and be configured such that + it could communicate with the specified handle in some other way + (e.g. have the requested contact handle in its Group + interface)</li> + </ul> + </tp:docstring> + </property> + + <property name="TargetID" tp:name-for-bindings="Target_ID" + type="s" access="read"> + <tp:added version="0.17.9"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string that would result from inspecting the + <tp:member-ref>TargetHandle</tp:member-ref> + property (i.e. the identifier in the IM protocol of the contact, + room, etc. with which this channel communicates), or the empty + string if the TargetHandle is 0.</p> + + <tp:rationale> + <p>The presence of this property avoids the following race + condition:</p> + + <ul> + <li>New channel C is signalled with target handle T</li> + <li>Client calls InspectHandles(CONTACT, [T])</li> + <li>Channel C closes, removing the last reference to handle T</li> + <li>InspectHandles(CONTACT, [T]) returns an error</li> + </ul> + </tp:rationale> + + <p>If this is present in a channel request, + <tp:member-ref>TargetHandleType</tp:member-ref> + MUST be present and not Handle_Type_None, and + <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be + present. The request MUST fail with error InvalidHandle, without + side-effects, if the requested TargetID would not be accepted by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p> + + <p>The returned channel must be related to the handle corresponding + to the given identifier, in the same way as if TargetHandle + had been part of the request instead.</p> + + <tp:rationale> + <p>Requesting channels with a string identifier saves a round-trip + (the call to RequestHandles). It also allows the channel + dispatcher to accept a channel request for an account that is not + yet connected (and thus has no valid handles), bring the account + online, and pass on the same parameters to the new connection's + CreateChannel method.</p> + </tp:rationale> </tp:docstring> </property> <property name="TargetHandleType" type="u" access="read" tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type"> <tp:added version="0.17.7"/> - <tp:docstring> - The type of TargetHandle. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of TargetHandle.</p> + + <p>If this is omitted from a channel request, connection managers + SHOULD treat this as equivalent to Handle_Type_None.</p> + + <p>If this is omitted or is Handle_Type_None, + <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the + request.</p> </tp:docstring> </property> - <method name="Close"> + <method name="Close" tp:name-for-bindings="Close"> <tp:docstring> Request that the channel be closed. This is not the case until the Closed signal has been emitted, and depending on the connection @@ -116,7 +200,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> - <signal name="Closed"> + <signal name="Closed" tp:name-for-bindings="Closed"> <tp:docstring> Emitted when the channel has been closed. Method calls on the channel are no longer valid after this signal has been emitted, @@ -190,6 +274,129 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </method> + <property name="Requested" tp:name-for-bindings="Requested" + type="b" access="read"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel was created in response to a local request, + such as a call to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> + or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p> + + <tp:rationale> + <p>The idea of this property is to distinguish between "incoming" + and "outgoing" channels, in a way that doesn't break down when + considering special cases like contact lists that are automatically + created on connection to the server, or chatrooms that an + IRC proxy/bouncer like irssi-proxy or bip was already in.</p> + + <p>The reason we want to make that distinction is that UIs for + things that the user explicitly requested should start up + automatically, whereas for incoming messages and VoIP calls we + should first ask the user whether they want to open the messaging + UI or accept the call.</p> + </tp:rationale> + + <p>If the channel was not explicitly requested (even if it was + created as a side-effect of a call to one of those functions, + e.g. because joining a Tube in a MUC context on XMPP implies + joining that MUC), then this property is false.</p> + + <p>For compatibility with older connection managers, clients SHOULD + assume that this property is true if they see a channel announced + by the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal with the suppress_handler parameter set to true.</p> + + <tp:rationale> + <p>In a correct connection manager, the only way to get such a + channel is to request it.</p> + </tp:rationale> + + <p>Clients MAY additionally assume that this property is false + if they see a channel announced by the NewChannel signal with the + suppress_handler parameter set to false.</p> + + <tp:rationale> + <p>This is more controversial, since it's possible to get that + parameter set to false by requesting a channel. However, there's + no good reason to do so, and we've deprecated this practice.</p> + + <p>In the particular case of the channel dispatcher, the only + side-effect of wrongly thinking a channel is unrequested + is likely to be that the user has to confirm that they want to + use it, so it seems fairly harmless to assume in the channel + dispatcher that channels with suppress_handler false are + indeed unrequested.</p> + </tp:rationale> + </tp:docstring> + </property> + + <property name="InitiatorHandle" type="u" tp:type="Contact_Handle" + access="read" tp:name-for-bindings="Initiator_Handle"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contact who initiated the channel. For channels requested by the + local user, this MUST be the value of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref> + at the time the channel was created (i.e. not a channel-specific + handle).</p> + + <tp:rationale> + <p>The careful wording about the self-handle is because the Renaming + interface can cause the return from Connection.GetSelfHandle to + change. It's something of a specification bug that we don't signal + this in the Connection interface yet.</p> + </tp:rationale> + + <p>For channels requested by a remote user, this MUST be their handle. + If unavailable or not applicable, this MUST be 0 (for instance, + contact lists are not really initiated by anyone in particular, and + it's easy to imagine a protocol where chatroom invitations can be + anonymous).</p> + + <p>For channels with the Group interface, this SHOULD be the same + contact who is signalled as the "Actor" causing the self-handle + to be placed in the local-pending set.</p> + + <p>This SHOULD NOT be a channel-specific handle, if possible.</p> + + <p>It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.</p> + </tp:docstring> + </property> + + <property name="InitiatorID" type="s" access="read" + tp:name-for-bindings="Initiator_ID"> + <tp:added version="0.17.13">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The string that would result from inspecting the + <tp:member-ref>InitiatorHandle</tp:member-ref> + property (i.e. the initiator's identifier in the IM protocol).</p> + + <tp:rationale> + <p>The presence of this property avoids the following race + condition:</p> + + <ul> + <li>New StreamedMedia channel C is signalled with initiator + handle I</li> + <li>Client calls InspectHandles(CONTACT, [I])</li> + <li>Channel C closes, removing the last reference to handle I</li> + <li>InspectHandles(CONTACT, [I]) returns an error</li> + <li>Client can indicate that a call was missed, but not who + called!</li> + </ul> + </tp:rationale> + + <p>It does not make sense for this property to be in channel + requests - the initiator will always be the local user - so it + MUST NOT be accepted.</p> + </tp:docstring> + </property> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>All communication in the Telepathy framework is carried out via channel objects which are created and managed by connections. This interface must @@ -198,6 +405,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ as a buddy list) or a Channel.Type.Text which represents a channel over which textual messages are sent and received.</p> + <p>Each Channel's object path MUST start with the object path of + its associated Connection, followed by '/'. There MAY be any number + of additional object-path components, which clients MUST NOT attempt + to parse.</p> + + <tp:rationale> + <p>This ensures that Channel object paths are unique, even between + Connections and CMs, because Connection object paths are + guaranteed-unique via their link to the well-known bus name.</p> + + <p>If all connection managers in use are known to comply with at least + spec version 0.17.10, then the Connection's object path can + even be determined from the Channel's without any additional + information, by taking the first 7 components.</p> + </tp:rationale> + <p>Each channel may have an immutable handle associated with it, which may be any handle type, such as a contact, room or list handle, indicating that the channel is for communicating with that handle.</p> @@ -234,6 +457,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ has now been removed in order to accommodate features like message threads. </tp:changed> + + <tp:changed version="0.17.10">Previously we did not explicitly + guarantee that Channels' object paths had the Connection's object path + as a prefix. + </tp:changed> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Bundle.xml b/qt4/spec/Channel_Bundle.xml new file mode 100644 index 000000000..d211525a4 --- /dev/null +++ b/qt4/spec/Channel_Bundle.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" ?> +<node name="/Channel_Bundle" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> +<p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +</p> + </tp:license> + <interface name="org.freedesktop.Telepathy.ChannelBundle.DRAFT" + tp:causes-havoc="experimental"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A group of related channels, which should all be dispatched to the + same handler if possible.</p> + + <p>Bundles currently have no functionality of their own, so clients + SHOULD NOT examine this interface, but should instead treat the + bundle object-path as an opaque identifier. If more functionality is + added to bundles in future, this interface will be used for capability + discovery.</p> + + <p>The lifetime of a bundle is defined by its component channels - + as long as one or more channels whose Bundle property is <em>B</em> + exist, the bundle <em>B</em> will also exist.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel bundle. + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatch_Operation.xml b/qt4/spec/Channel_Dispatch_Operation.xml new file mode 100644 index 000000000..c9f559273 --- /dev/null +++ b/qt4/spec/Channel_Dispatch_Operation.xml @@ -0,0 +1,342 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatch_Operation" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, + MA 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel dispatch operation is an object in the ChannelDispatcher + representing a bundle of unrequested channels being announced to + client + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver.DRAFT</tp:dbus-ref> + processes.</p> + + <p>These objects can result from new incoming channels or channels + which are automatically created for some reason, but cannot result + from outgoing requests for channels.</p> + + <p>More specifically, whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> + signal contains channels whose + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + property is false, or whenever the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal contains a channel with suppress_handler false, + one or more ChannelDispatchOperation objects are created for those + channels.</p> + + <p>(If some channels in a NewChannels signal are in different bundles, + this is an error. The channel dispatcher SHOULD recover by treating + the NewChannels signal as if it had been several NewChannels signals + each containing one channel.)</p> + + <p>First, the channel dispatcher SHOULD construct a list of all the + channel handlers that could handle all the channels, ordered by + priority in some implementation-dependent way. If there are handlers + which could handle all the channels, one channel dispatch operation + SHOULD be created for all the channels. If there are not, one channel + dispatch operation SHOULD be created for each channel, each with + a list of channel handlers that could handle that channel.</p> + + <p>When listing channel handlers, priority SHOULD be given to + channel handlers that are already handling channels from the same + bundle.</p> + + <p>Processing of a channel dispatch operation proceeds as follows. + If the channels in a channel dispatch operation are in the same + bundle as a channel that is already being handled, and the handler + could also handle the channels being dispatched, the channel + dispatcher SHOULD call the handler's + HandleAdditionalChannels + method to see whether the handler will accept the new channels too. + If the handler takes responsibility for the channels, + processing stops, and no approvers are run.</p> + + <p>(FIXME: this is far too subtle and everyone will get it wrong. + Open issue: how else do we address this use case?)</p> + + <tp:rationale> + <p>Some channel types can be picked up "quietly" by an existing + channel handler. If a Text channel is added to an existing + bundle containing a StreamedMedia channel, there shouldn't be + any approvers, flashing icons or notification bubbles, if the + the UI for the StreamedMedia channel can just add a text box + and display the message.</p> + </tp:rationale> + + <p>If not, the channel dispatcher SHOULD send the channel dispatch + operation to all relevant approvers (in parallel) and wait for an + approver to claim the channels or request that they are handled. + See + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref> + for more details on this.</p> + + <p>Finally, if the approver requested it, the channel dispatcher SHOULD + send the channels to a handler.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatch + operation. This property cannot change. + </tp:docstring> + </property> + + <property name="Connection" tp:name-for-bindings="Connection" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the <tp:member-ref>Channels</tp:member-ref> are + associated. The well-known bus name to use can be derived from + this object path by removing the leading '/' and replacing all + subsequent '/' by '.'. This property cannot change. + </tp:docstring> + </property> + + <property name="Account" tp:name-for-bindings="Account" + type="o" access="read"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the <tp:member-ref>Connection</tp:member-ref> + and <tp:member-ref>Channels</tp:member-ref> are + associated. This property cannot change. + </tp:docstring> + </property> + + <property name="Channels" tp:name-for-bindings="Channels" + type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + to be dispatched, and their properties. Change notification is via + the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels + cannot be added to this property, only removed). + </tp:docstring> + </property> + + <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost"> + <tp:docstring> + A channel has closed before it could be claimed or handled. If this + is emitted for the last remaining channel in a channel dispatch + operation, it MUST immediately be followed by + <tp:member-ref>Finished</tp:member-ref>. + </tp:docstring> + + <arg name="Channel" type="o"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> + that closed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error indicating why the channel closed. If + no better reason can be found, + <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY + be used as a fallback; this means that this error SHOULD NOT be + given any more specific meaning.</p> + + <p>FIXME: or should we invent a new OtherError for that purpose?</p> + + <p>FIXME: we need to specify errors for these situations:</p> + + <ul> + <li>kicked from a chatroom</li> + <li>outgoing call rejected</li> + <li>outgoing call timed out</li> + <li>incoming call terminated</li> + </ul> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + A string associated with the D-Bus error. + </tp:docstring> + </arg> + </signal> + + <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers" + type="as" access="read" tp:type="DBus_Well_Known_Name[]"> + <tp:docstring> + The well known bus names (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the possible + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s + for these channels. The channel dispatcher MUST place the most + preferred handlers first, according to some reasonable heuristic. + As a result, approvers SHOULD use the first handler by default. + </tp:docstring> + </property> + + <method name="HandleWith" tp:name-for-bindings="Handle_With"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to accept a channel bundle and request that + the given handler be used to handle it.</p> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>.</p> + + <p>However, this method may fail because the dispatch has already been + completed and the object has already gone. If this occurs, it + indicates that another approver has asked for the bundle to be + handled by a particular handler. The approver MUST NOT attempt + to interact with the channels further in this case, unless it is + separately invoked as the handler.</p> + + <p>Approvers which are also channel handlers SHOULD use Claim instead + of HandleWith to request that they can handle a channel bundle + themselves.</p> + + <p>(FIXME: list some possible errors)</p> + + <p>If the channel handler raises an error from Handle, this method + MAY respond by raising that same error, even if it is not + specifically documented here.</p> + </tp:docstring> + + <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The well-known bus name (starting with + <code>org.freedesktop.Telepathy.Client.</code>) of the channel + handler that should handle the channel.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The selected handler is not a syntactically correct + <tp:type>DBus_Bus_Name</tp:type> or does not start with + "<code>org.freedesktop.Telepathy.Client.</code>". + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The selected handler is temporarily unable to handle these + channels. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The selected handler is syntactically correct, but will never + be able to handle these channels (for instance because the channels + do not match its HandlerChannelFilter, or because HandleChannels + raised NotImplemented). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that HandleWith was called, this dispatch operation was + processing an earlier call to HandleWith. The earlier call has + now succeeded, so some Handler nominated by another approver is + now responsible for the channels. In this situation, the second + call to HandleWith MUST NOT return until the first one has + returned successfully or unsuccessfully, and if the first call + to HandleChannels fails, the channel dispatcher SHOULD try to obey + the choice of Handler made by the second call to HandleWith. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Claim" tp:name-for-bindings="Claim"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by an approver to claim channels for handling + internally. If this method is called successfully, the process + calling this method becomes the handler for the channel, but + <em>does not</em> have the HandleChannels method called on it.</p> + <!-- FIXME: tp:dbus-ref --> + + <p>Clients that call Claim on channels but do not immediately + close them SHOULD implement the Handler interface and its + CurrentlyHandledChannels property.</p> + <!-- FIXME: tp:dbus-ref --> + + <p>Approvers wishing to reject channels MUST call this method to + claim ownership of them, and MUST NOT call + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> + on the channels unless/until this method returns successfully.</p> + + <tp:rationale> + <p>The channel dispatcher can't know how best to close arbitrary + channel types, so it leaves it up to the approver to do so. + For instance, for Text channels it is necessary + to acknowledge any messages that have already been displayed to + the user first - ideally, the approver would display and then + acknowledge the messages.</p> + </tp:rationale> + + <p>If successful, this method will cause the ChannelDispatchOperation + object to disappear, emitting + <tp:member-ref>Finished</tp:member-ref>, in the same way as for + <tp:member-ref>HandleWith</tp:member-ref>.</p> + + <p>This method may fail because the dispatch operation has already + been completed. Again, see HandleWith for more details. The approver + MUST NOT attempt to interact with the channels further in this + case.</p> + + <p>(FIXME: list some other possible errors)</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.NotYours"> + <tp:docstring> + At the time that Claim was called, this dispatch operation was + processing a call to HandleWith which has now succeeded, so + some Handler nominated by another approver is now responsible for + the channel. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="Finished" tp:name-for-bindings="Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when this dispatch operation finishes. The dispatch + operation is no longer present and further methods must not be + called on it.</p> + + <p>Its object path SHOULD NOT be reused for a subsequent dispatch + operation; the ChannelDispatcher MUST choose object paths + in a way that avoids immediate re-use.</p> + + <tp:rationale> + <p>Otherwise, clients might accidentally call HandleWith or Claim + on a new dispatch operation instead of the one they + intended to handle.</p> + </tp:rationale> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatcher.xml b/qt4/spec/Channel_Dispatcher.xml new file mode 100644 index 000000000..c9b8a2bc7 --- /dev/null +++ b/qt4/spec/Channel_Dispatcher.xml @@ -0,0 +1,361 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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.ChannelDispatcher.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel dispatcher is responsible for responding to new + channels and launching client processes to handle them. It also + provides functionality for client processes to request that new + channels are created.</p> + + <p>If a channel dispatcher is running, it is responsible for dispatching + new channels on all + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s + created by the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + Connections not created by the AccountManager are outside the scope + of the channel dispatcher.</p> + + <tp:rationale> + <p>Connections created by standalone Telepathy clients + that do not intend to interact with the channel dispatcher + should be ignored - otherwise, the channel dispatcher would try + to launch handlers for channels that the standalone client + was already handling internally.</p> + </tp:rationale> + + <p>The current channel dispatcher is defined to be the process that + owns the well-known bus name + <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on + the session bus. This process MUST export an object with this + interface at the object path + <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p> + + <p>Until a mechanism exists for making a reasonable automatic choice + of ChannelDispatcher implementation, implementations SHOULD NOT + register as an activatable service for the ChannelDispatcher's + well-known bus name. Instead, it is RECOMMENDED that some component + of the user's session will select and activate a particular + implementation, and that other Telepathy-enabled programs + can detect whether channel request/dispatch functionality is available + by checking whether the ChannelDispatcher's well-known name is in use + at runtime.</p> + + <p>There are three categories of client process defined by this + specification:</p> + + <dl> + <dt>Observer</dt> + <dd><p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p></dd> + + <dt>Approver</dt> + <dd> + <p>Approvers notify the user that new channels have been created, + and also select which channel handler will be used for the channel, + either by asking the user or by choosing the most appropriate + channel handler.</p> + </dd> + + <dt>Handler</dt> + <dd> + <p>Each new channel or set of channels is passed to exactly one + handler as its final destination. A typical channel handler is a + user interface process handling channels of a particular type.</p> + </dd> + </dl> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring> + A list of the extra interfaces provided by this channel dispatcher. + </tp:docstring> + </property> + + <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> + <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.DRAFT</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <tp:rationale> + <p>The request can take a long time - in the worst case, the + channel dispatcher has to ask the account manager to put the + account online, the account manager has to ask the operating + system to obtain an Internet connection, and the operating + system has to ask the user whether to activate an Internet + connection using an on-demand mechanism like dialup.</p> + + <p>This means that using a single D-Bus method call and response + to represent the whole request will tend to lead to that call + timing out, which is not the behaviour we want.</p> + </tp:rationale> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>This means there's only one code path for errors, apart from + InvalidArgument for "that request makes no sense".</p> + + <p>It also means that the request will proceed if the account is + enabled after calling CreateChannel, but before calling + Proceed.</p> + </tp:rationale> + </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. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="t" + tp:type="Unix_Timestamp64"> + <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. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> + property will be set to this value, and it will eventually be + passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-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 channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler.</p> + + <tp:rationale> + <p>This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.</p> + + <p>This is partly so the channel dispatcher can call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</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>Start a request to ensure that a channel exists, creating it if + necessary. This initially just creates a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref> + object, which can be used to continue the request and track its + success or failure.</p> + + <p>If this method is called for an Account that is disabled, invalid + or otherwise unusable, no error is signalled until + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Proceed</tp:dbus-ref> + is called, at which point + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT.Failed</tp:dbus-ref> + is emitted with an appropriate error.</p> + + <tp:rationale> + <p>The rationale is as for <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>CreateChannel</tp:dbus-ref>.</p> + </tp:rationale> + </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. This has the same + semantics as the corresponding parameter to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>. + </p> + + <p>Certain properties will not necessarily make sense in this + dictionary: for instance, + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> + can only be given if the requester is able to interact with a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + to the desired account.</p> + </tp:docstring> + </arg> + + <arg direction="in" name="User_Action_Time" type="t" + tp:type="Unix_Timestamp64"> + <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. + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelRequest.DRAFT">UserActionTime</tp:dbus-ref> + property will be set to this value, and it will eventually be + passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-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> + + <tp:rationale> + <p>This must be the well-known bus name, not the unique name, + to ensure that all handlers do indeed have the Client API, + and the Client object on the handler can be located easily.</p> + + <p>This is partly so the channel dispatcher can call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + on it, and partly so the channel dispatcher + can recover state if it crashes and is restarted.</p> + </tp:rationale> + + <p>If any new channels are created in response to this + request, the channel dispatcher SHOULD dispatch as many as + possible of the resulting channels (ideally, all of them) + to that handler, and SHOULD remember the preferred handler + so it can try to dispatch subsequent channels in the same bundle + to the same handler. If the requested channel already exists (that + is, <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref> + returns <code>Yours=False</code>) then the channel dispatcher + SHOULD re-dispatch the channel to its existing handler, and MUST + NOT dispatch it to this client (unless it is the existing handler); + the request is still deemed to have succeeded in this case.</p> + + <tp:rationale> + <p>An address book application, for example, might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref> + to ensure that a text channel with a particular contact is + displayed to the user; it does not care whether a new channel was + made. An IM client might call <tp:dbus-ref + namespace='org.freedesktop.Telepathy.ChannelDispatcher.DRAFT'>EnsureChannel</tp:dbus-ref> + in response to the user double-clicking an entry in the contact + list, with itself as the <code>Preferred_Handler</code>; if the + user already has a conversation with that contact in another + application, they would expect the existing window to be + presented, rather than their double-click leading to an error + message. So the request should succeed, even if its + <code>Preferred_Handler</code> is not used.</p> + </tp:rationale> + + </tp:docstring> + </arg> + + <arg direction="out" name="Request" type="o"> + <tp:docstring> + A + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</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> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml b/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml new file mode 100644 index 000000000..40cd86e54 --- /dev/null +++ b/qt4/spec/Channel_Dispatcher_Interface_Operation_List.xml @@ -0,0 +1,138 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Interface_Operation_List" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList.DRAFT" + tp:causes-havoc="experimental"> + + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface allows users of the ChannelDispatcher to enumerate + all the pending dispatch operations, with change notification.</p> + + <tp:rationale> + <p>The existence of the DispatchOperations property allows a newly + started approver to pick up existing dispatch operations.</p> + + <p>This is on a separate interface so clients that aren't interested + in doing this aren't woken up by its signals.</p> + </tp:rationale> + </tp:docstring> + + <tp:struct name="Dispatch_Operation_Details" + array-name="Dispatch_Operation_Details_List"> + + <tp:docstring> + Details of a channel dispatch operation. + </tp:docstring> + + <tp:member name="Channel_Dispatch_Operation" type="o"> + <tp:docstring> + The object path of the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>. + </tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel dispatch operation.</p> + + <p>Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.</p> + + <tp:rationale> + <p>The rationale is the same as for + <tp:type-ref>Channel_Details</tp:type-ref>.</p> + </tp:rationale> + + <p>Each dictionary MUST contain at least the following keys:</p> + <ul> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Interfaces</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Connection</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Account</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.Channels</tp:dbus-ref></li> + <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT.PossibleHandlers</tp:dbus-ref></li> + </ul> + </tp:docstring> + </tp:member> + </tp:struct> + + <property + name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations" + type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The list of ChannelDispatchOperation objects currently being + processed. Change notification is via the NewDispatch and + DispatchFinished signals.</p> + </tp:docstring> + </property> + + <signal name="NewDispatchOperation" + tp:name-for-bindings="New_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Emitted when a dispatch operation is added to + <tp:member-ref>DispatchOperations</tp:member-ref>.</p> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was created. + </tp:docstring> + </arg> + + <arg name="Properties" + type="a{sv}" tp:type="Qualified_Property_Value_Map"> + <tp:docstring> + The same properties that would appear in the Properties member of + <tp:type-ref>Dispatch_Operation_Details</tp:type-ref>. + </tp:docstring> + </arg> + </signal> + + <signal name="DispatchOperationFinished" + tp:name-for-bindings="Dispatch_Operation_Finished"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + Emitted when a dispatch operation finishes (i.e. exactly once per + emission of <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT.Finished</tp:dbus-ref>). + + <tp:rationale> + Strictly speaking this is redundant with + ChannelDispatchOperation.Finished, but it provides full + change-notification for the DispatchOperations property. + </tp:rationale> + </tp:docstring> + + <arg name="Dispatch_Operation" type="o"> + <tp:docstring> + The dispatch operation that was closed. + </tp:docstring> + </arg> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Future.xml b/qt4/spec/Channel_Future.xml index 50f3b37b5..235ff2c4d 100644 --- a/qt4/spec/Channel_Future.xml +++ b/qt4/spec/Channel_Future.xml @@ -42,80 +42,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:rationale> </tp:docstring> - <property name="TargetID" type="s" access="read" - tp:name-for-bindings="Target_ID"> - <tp:added version="0.17.7">(in Channel.FUTURE - pseudo-interface)</tp:added> - <tp:docstring> - The string that would result from inspecting the TargetHandle - property (i.e. the identifier in the IM protocol of the contact, - room, etc. with which this channel communicates). - - <tp:rationale> - See InitiatorID; the rationale is the same. - </tp:rationale> - </tp:docstring> - </property> - - <property name="InitiatorHandle" type="u" tp:type="Contact_Handle" - access="read" tp:name-for-bindings="Initiator_Handle"> - <tp:added version="0.17.7">(in Channel.FUTURE - pseudo-interface)</tp:added> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The contact who initiated the channel. For channels requested by the - local user, this MUST be the same thing as would be returned - by Connection.GetSelfHandle() at the time the channel was - created.</p> - - <tp:rationale> - <p>The careful wording about the self-handle is because the Renaming - interface can cause the return from Connection.GetSelfHandle to - change. It's something of a specification bug that we don't signal - this in the Connection interface yet.</p> - </tp:rationale> - - <p>For channels requested by a remote user, this MUST be their handle. - If unavailable or not applicable, this MUST be 0 (for instance, - contact lists are not really initiated by anyone in particular, and - it's easy to imagine a protocol where chatroom invitations can be - anonymous).</p> - - <p>For channels with the Group interface, this SHOULD be the same - contact who is signalled as the "Actor" causing the self-handle - to be placed in the local-pending set.</p> - - <p>This SHOULD NOT be a channel-specific handle, if possible.</p> - - <p>It does not make sense for this property to be passed to the - RequestChannels method on Channel.Interface.Requests.</p> - </tp:docstring> - </property> - - <property name="InitiatorID" type="s" access="read" - tp:name-for-bindings="Initiator_ID"> - <tp:added version="0.17.7">(in Channel.FUTURE + <property name="Bundle" tp:name-for-bindings="Bundle" + type="o" access="read"> + <tp:added version="0.17.9">(in Channel.FUTURE pseudo-interface)</tp:added> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The string that would result from inspecting the InitiatorHandle - property (i.e. the initiator's identifier in the IM protocol).</p> - - <tp:rationale> - <p>The presence of this property avoids the following race - condition:</p> + <p>The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle</tp:dbus-ref> + to which this channel belongs.</p> - <ul> - <li>New StreamedMedia channel C is signalled with initiator - handle I</li> - <li>Client calls InspectHandles(CONTACT, [I])</li> - <li>Channel C closes, removing the last reference to handle I</li> - <li>InspectHandles(CONTACT, [I]) returns an error</li> - <li>Client can indicate that a call was missed, but not who - called!</li> - </ul> - </tp:rationale> + <p>A channel's Bundle property can never change.</p> - <p>It does not make sense for this property to be passed to the - RequestChannels method on Channel.Interface.Requests.</p> + <p>Older connection managers might not have this property. Clients + (particularly the channel dispatcher) SHOULD recover by considering + each channel to be in a bundle containing only that channel, + distinct from all other bundles, which has no additional + interfaces.</p> </tp:docstring> </property> diff --git a/qt4/spec/Channel_Interface_Call_Merging.xml b/qt4/spec/Channel_Interface_Call_Merging.xml index 23f955859..a98daf12c 100644 --- a/qt4/spec/Channel_Interface_Call_Merging.xml +++ b/qt4/spec/Channel_Interface_Call_Merging.xml @@ -29,7 +29,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. in the same sort of way as in GSM or PBX telephony.</p> </tp:docstring> - <method name="Merge"> + <method name="Merge" tp:name-for-bindings="Merge"> <arg direction="in" type="o" name="Other"> <tp:docstring> The other channel to merge into this one @@ -49,7 +49,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. </tp:possible-errors> </method> - <method name="Split"> + <method name="Split" tp:name-for-bindings="Split"> <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> <tp:docstring> The handle of the contact to split off a conversation with, who diff --git a/qt4/spec/Channel_Interface_Call_State.xml b/qt4/spec/Channel_Interface_Call_State.xml index 132137eda..0df6e3472 100644 --- a/qt4/spec/Channel_Interface_Call_State.xml +++ b/qt4/spec/Channel_Interface_Call_State.xml @@ -101,6 +101,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ unhold the call again. </tp:docstring> </tp:flag> + + <tp:flag suffix="Forwarded" value="8"> + <tp:docstring> + The initiator of the call originally called a contact other than the + current recipient of the call, but the call was then forwarded or + diverted. + </tp:docstring> + </tp:flag> </tp:flags> </interface> diff --git a/qt4/spec/Channel_Interface_Destroyable.xml b/qt4/spec/Channel_Interface_Destroyable.xml new file mode 100644 index 000000000..ce5592327 --- /dev/null +++ b/qt4/spec/Channel_Interface_Destroyable.xml @@ -0,0 +1,82 @@ +<?xml version="1.0" ?> +<node name="/Channel_Interface_Destroyable" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.Channel.Interface.Destroyable"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:added version="0.17.14">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>This interface exists to support channels where + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + is insufficiently destructive. At the moment this means + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref>, + but the existence of this interface means that unsupported channels + can be terminated in a non-channel-type-specific way.</p> + </tp:docstring> + + <method name="Destroy" tp:name-for-bindings="Destroy"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Close the channel abruptly, possibly with loss of data. The + connection manager MUST NOT re-create the channel unless/until + more events occur.</p> + + <tp:rationale> + <p>The main motivating situation for this method is that when a Text + channel with pending messages is closed with Close, it comes back + as an incoming channel (to avoid a race between Close and an + incoming message). If Destroy is called on a Text channel, the CM + should delete all pending messages and close the channel, and + the channel shouldn't be re-created until/unless another message + arrives.</p> + </tp:rationale> + + <p>Most clients SHOULD call + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref> + instead. However, if a client explicitly intends to destroy the + channel with possible loss of data, it SHOULD call this method + if this interface is supported (according to the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref> + property), falling back to Close if not.</p> + + <p>In particular, channel dispatchers SHOULD use this method if + available when terminating channels that cannot be handled + correctly (for instance, if no handler has been installed for + a channel type, or if the handler crashes repeatedly).</p> + + <p>Connection managers do not need to implement this interface on + channels where Close and Destroy would be equivalent.</p> + + <tp:rationale> + <p>Callers need to be able to fall back to Close in any case.</p> + </tp:rationale> + </tp:docstring> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Interface_Group.xml b/qt4/spec/Channel_Interface_Group.xml index 21b535e28..4e69b88d0 100644 --- a/qt4/spec/Channel_Interface_Group.xml +++ b/qt4/spec/Channel_Interface_Group.xml @@ -87,7 +87,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:deprecated version="0.17.6">Use GetAll on the D-Bus Properties D-Bus interface to get properties including Members, RemotePendingMembers and LocalPendingMembers instead, falling back to - this method and GetLocalPendingMembers if necessary.</tp:deprecated> + this method and GetLocalPendingMembersWithInfo if necessary. + </tp:deprecated> <arg direction="out" type="au" tp:type="Contact_Handle[]"> <tp:docstring> @@ -410,7 +411,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ from that to the deprecated GetAllMembers method.</tp:added> </property> - <property name="Members" access="read" type="au" tp:type="Contact_Handle[]"> + <property name="Members" tp:name-for-bindings="Members" + access="read" type="au" tp:type="Contact_Handle[]"> <tp:docstring> The members of this channel. </tp:docstring> diff --git a/qt4/spec/Channel_Interface_Messages.xml b/qt4/spec/Channel_Interface_Messages.xml index fa3e79174..7fefabbb5 100644 --- a/qt4/spec/Channel_Interface_Messages.xml +++ b/qt4/spec/Channel_Interface_Messages.xml @@ -36,10 +36,6 @@ USA.</p> <li>any extra types of message we need in future</li> </ul> - <p>It also provides a hook for improved sent - message status notification, to be used by the DeliveryReporting - interface.</p> - <p>Although this specification supports formatted (rich-text) messages with unformatted alternatives, implementations SHOULD NOT attempt to send formatted messages until the Telepathy specification @@ -55,20 +51,63 @@ USA.</p> unfriendly to offer the user controls that may have no effect. </tp:rationale> + <p>This interface also replaces Text.SendError, adding support for + protocols where the message content is not echoed back to the sender on + failure, adding support for receiving positive acknowledgements, + and using the Messages queue for state-recovery + (ensuring that incoming delivery reports are not lost if there is not + currently a process handling them).</p> + <p>If this interface is present, clients that support it SHOULD listen for the MessageSent and MessageReceived signals, and - ignore the Sent and Received signal on the Text interface + ignore the Sent, SendError and Received signal on the Text interface (which are guaranteed to duplicate signals from this interface).</p> </tp:docstring> <property name="SupportedContentTypes" type="as" access="read" tp:name-for-bindings="Supported_Content_Types"> - <tp:docstring> - A list of MIME types supported by this channel, with more preferred - MIME types appearing earlier in the list. The list MAY include "*/*" - to indicate that attachments with arbitrary MIME types can be sent. - If the list is empty, this indicates that messages may only include - a single "text/plain" part. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of MIME types supported by this channel, with more preferred + MIME types appearing earlier in the list. The list MAY include "*/*" + to indicate that attachments with arbitrary MIME types can be sent. + This list MUST NOT be empty, since all Messages implementations + MUST accept messages containing a single "text/plain" part.</p> + + <p>Some examples of how this property interacts with the + <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p> + + <dl> + <dt>A simple IM implementation: only plain text messages are + allowed</dt> + <dd>SupportedContentTypes = ['text/plain'], + MessagePartSupportFlags = 0</dd> + + <dt>Formatted text with a plain text alternative is allowed (see the + HTML interface draft)</dt> + <dd>SupportedContentTypes = ['text/html', 'text/plain'], + MessagePartSupportFlags = 0</dd> + + <dt>JPEG or PNG images may be sent, but without any attached + text</dt> + <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = 0</dd> + + <dt>Unformatted text to which an optional JPEG or PNG image may be + attached</dt> + <dd>SupportedContentTypes = ['text/plain', 'image/jpeg', + 'image/png'], MessagePartSupportFlags = One_Attachment</dd> + + <dt>Formatted text to which arbitrarily many images may be + attached</dt> + <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg', + 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments</dd> + + <dt>A full SIP implementation: arbitrary MIME messages are + allowed</dt> + <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags = + One_Attachment | Multiple_Attachments</dd> + </dl> </tp:docstring> </property> @@ -88,9 +127,9 @@ USA.</p> channel. They are designed such that setting more flags always implies that the channel has more capabilities.</p> - <p>It is assumed that messages containing a textual message body - (only), like the messages the Text interface was designed for, are - always supported.</p> + <p>If no flags are set, this indicates that messages may contain + a single message part whose content-type is any of the types + from SupportedContentTypes, possibly with some alternatives.</p> <p>There is no flag indicating support for alternatives. This is because the SendMessage implementation can always accept messages @@ -99,21 +138,17 @@ USA.</p> that is supported.</p> <tp:rationale> - Each of the flags 1, 2, 4 implies the previous flag, so we could + Each of the flags so far implies the previous flag, so we could have used a simple enumeration here; however, we've defined the message-part support indicator as a flag set for future expansion. </tp:rationale> + + <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some + examples.</p> </tp:docstring> - <tp:flag suffix="Data_Only" value="1"> - <tp:docstring> - SendMessage will accept messages containing a single part of any - type listed in the SupportedContentTypes property, with no - accompanying text. - </tp:docstring> - </tp:flag> - <tp:flag suffix="One_Attachment" value="2"> + <tp:flag suffix="One_Attachment" value="1"> <tp:docstring> SendMessage will accept messages containing a textual message body, plus a single attachment of any type listed in the @@ -123,7 +158,7 @@ USA.</p> part if necessary). </tp:docstring> </tp:flag> - <tp:flag suffix="Multiple_Attachments" value="4"> + <tp:flag suffix="Multiple_Attachments" value="2"> <tp:docstring> SendMessage will accept messages containing a textual message body, plus an arbitrary number of attachments of any type listed in the @@ -146,24 +181,25 @@ USA.</p> <pre> [ { + 'message-token': '9de9546a-3400-4419-a505-3ea270cb834c', 'message-sender': 42, 'message-sent': 1210067943, 'message-received': 1210067947, - 'message-type': 0, + 'message-type': 0, # = Channel_Text_Message_Type_Normal 'pending-message-id': 437, }, { 'alternative': 'main', - 'type': 'text/html', + 'content-type': 'text/html', 'content': 'Here is a photo of my cat:<br />' + '<img src="cid:catphoto" alt="lol!" />' + '<br />Isn't it cute?', }, { 'alternative': 'main', - 'type': 'text/plain', + 'content-type': 'text/plain', 'content': 'Here is a photo of my cat:\n[IMG: lol!]\nIsn't it cute?', }, { 'identifier': 'catphoto', - 'type': 'image/jpeg', + 'content-type': 'image/jpeg', 'size': 101000, 'needs-retrieval': True, }, @@ -179,24 +215,39 @@ USA.</p> Message_Part, but clients MUST recover from this error by ignoring these keys in the second and subsequent parts.</p> + <tp:rationale> + <p>Instead of representing messages as aa{sv} where the first + dictionary is special (a dictionary of headers), we could have + used a signature like (a{sv}aa{sv}) to separate out the headers + and the body parts.</p> + + <p>However, this would make access to the messages more awkward. + In Python, the syntax for access to a header field would remain + <code>message[0]['message-type']</code>, but access to a body + field in the second body part would change from + message[2]['content'] to message[1][1]['content']. In GLib, + the message would change from being a + GPtrArray(GHashTable) to being a + GValueArray(GHashTable, GPtrArray(GHashTable)) which is rather + inconvenient to dereference.</p> + </tp:rationale> + <p>Well-known keys for the message as a whole, and the corresponding value types, include:</p> <dl> - <!-- FIXME: if needed we could add: - <dt>message-identifier (s)</dt> + <dt>message-token (s)</dt> <dd>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 - identifier.</dd> - --> + token.</dd> - <dt>message-sent (u - <tp:type>Unix_Timestamp</tp:type>)</dt> + <dt>message-sent (t - <tp:type>Unix_Timestamp64</tp:type>)</dt> <dd>The time the message was sent (if unavailable, the time it arrived at a central server MAY be used). Omitted if no reasonable approximation is available</dd> - <dt>message-received (u - <tp:type>Unix_Timestamp</tp:type>)</dt> + <dt>message-received (t - <tp:type>Unix_Timestamp64</tp:type>)</dt> <dd>The time the message was received locally. SHOULD always be present.</dd> @@ -207,7 +258,7 @@ USA.</p> <dt>message-type (u - <tp:type>Channel_Text_Message_Type</tp:type>) </dt> <dd>The type of message; if omitted, - Channel_Text_Message_Type_Normal MUST be assumed. SHOULD + Channel_Text_Message_Type_Normal MUST be assumed. MAY be omitted for normal chat messages.</dd> <dt>pending-message-id (u - <tp:type>Message_ID</tp:type>)</dt> @@ -222,6 +273,23 @@ USA.</p> can also appear on the second and subsequent parts, where it indicates that that part (only) should be ignored if unsupported.)</dd> + + <dt>scrollback (b)</dt> + <dd>If present and true, the incoming message was part of a + replay of message history (this matches the Scrollback flag in + <tp:type>Channel_Text_Message_Flags</tp:type>). This flag + does not make sense on outgoing messages and SHOULD NOT + appear there.</dd> + + <dt>rescued (b)</dt> + <dd>If present and true, the incoming message has been seen in + a previous channel during the lifetime of the Connection, + but had not been acknowledged when that channel closed, causing + an identical channel (in which the message now appears) to open. + This matches the Rescued flag in + <tp:type>Channel_Text_Message_Flags</tp:type>; it + does not make sense on outgoing messages, and SHOULD NOT + appear there.</dd> </dl> </div> @@ -230,6 +298,11 @@ USA.</p> content, including plain text, formatted text and/or attached files.</p> + <p>It is an error for a connection manager to put keys referring + to the message body in the first Message_Part; + clients MUST recover from this error by ignoring + these keys in first part.</p> + <p>In any group of parts with the same non-empty value for the "alternative" key (which represent alternative versions of the same content), more faithful versions of the intended message MUST @@ -238,10 +311,18 @@ USA.</p> display the first alternative that they understand.</p> <tp:rationale> - Specifying the preference order means that if the underlying - protocol doesn't support alternatives, the CM can safely delete - everything apart from the first supported alternative when sending - messages. + <p>Specifying the preference order means that if the underlying + protocol doesn't support alternatives, the CM can safely delete + everything apart from the first supported alternative when + sending messages.</p> + + <p>The order is the reverse of MIME because MIME's rationale for + placing the "plainest" part first (legibility in pre-MIME UAs) + does not apply to us, and placing the most preferred part + first simplifies display (a client can iterate the message + in order, display the first alternative that it understands, + and skip displaying all subsequent parts with the same + "alternative" key).</p> </tp:rationale> <p>Clients SHOULD present all parts that are not redundant @@ -299,20 +380,20 @@ USA.</p> scheme.</p> </dd> - <dt>type (s)</dt> + <dt>content-type (s)</dt> <dd> <p>The MIME type of this part. See the documentation for ReceivedMessage for notes on the special status of "text/plain" parts.</p> - <p>Connection managers MUST NOT signal parts without a 'type' - key; if a protocol provides no way to determine the MIME type, - the connection manager is responsible for guessing it, but - MAY fall back to "text/plain" for text and + <p>Connection managers MUST NOT signal parts without a + 'content-type' key; if a protocol provides no way to determine + the MIME type, the connection manager is responsible for + guessing it, but MAY fall back to "text/plain" for text and "application/octet-stream" for non-text.</p> - <p>Clients MUST ignore parts without a 'type' key, which are - reserved for future expansion.</p> + <p>Clients MUST ignore parts without a 'content-type' key, which + are reserved for future expansion.</p> </dd> <dt>lang (s)</dt> @@ -378,10 +459,208 @@ USA.</p> entire message should be ignored if unsupported.)</dd> </dl> - <p>It is an error for a connection manager to put these keys - in the first <tp:type>Message_Part</tp:type>, but clients MUST be - able to recover from this error by ignoring these keys in the - first part.</p> + </div> + + + <div> + <p>Delivery reports are also represented as messages, of type + Channel_Text_Message_Type_Delivery_Report, with the + Non_Text_Content flag in the Text interface.</p> + + <p>Whenever a message of type + Channel_Text_Message_Type_Delivery_Report is signalled for a + delivery error report, Channel.Type.Text.SendError SHOULD also + be emitted; whenever Channel.Type.Text.SendError is emitted by a + channel which supports this interface, a message of type + Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p> + + <p>The corresponding message in the Messages interface MUST contain + "headers" for the delivery report, as specified below, in its + first Message_Part.</p> + + <dl> + <dt>message-sender (u - Contact_Handle as defined above)</dt> + <dd>MUST be the intended recipient of the original message, if + available (zero or omitted if the intended recipient is + unavailable or is not a contact, e.g. a chatroom), even if the + delivery report actually came from an intermediate server.</dd> + + <dt>message-type (u - Channel_Text_Message_Type as defined + above)</dt> + <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd> + + <dt>delivery-status (u - Delivery_Status)</dt> + <dd>The status of the message. All delivery reports MUST contain + this key in the first Message_Part.</dd> + + <dt>delivery-token (s - Sent_Message_Token)</dt> + + <dd> + <p>An identifier for the message to which this delivery report + refers. MUST NOT be an empty string. Omitted if not + available.</p> + + <p>Clients may match this against the token produced by the + SendMessage method and MessageSent signal. A status report + with no token could match any sent message, and a sent + message with an empty token could match any status report. + If multiple sent messages match, clients SHOULD use some + reasonable heuristic.</p> + + <tp:rationale> + In an ideal world, we could unambiguously match reports + against messages; however, deployed protocols are not ideal, + and not all reports and messages can be matched. + </tp:rationale> + </dd> + + <dt>delivery-error (u - Channel_Text_Send_Error)</dt> + <dd> + The reason for the failure. MUST be omitted if this was a + successful delivery; SHOULD be omitted if it would be + Channel_Text_Send_Error_Unknown. + </dd> + + <dt>delivery-echo (aa{sv} - Message_Part[])</dt> + <dd> + <p>The message content, as defined by the Messages interface. + Omitted if no content is available. Content MAY have been + truncated, message parts MAY have been removed, and message + parts MAY have had their content removed (i.e. the message part + metadata is present, but the 'content' key is not).</p> + + <tp:rationale> + Some protocols, like XMPP, echo the failing message back to + the sender. This is sometimes the only way to match it + against the sent message, so we include it here. + </tp:rationale> + + <p>Unlike in the Messages interface, content not visible + in the value for this key cannot be retrieved by another + means, so the connection manager SHOULD be more + aggressive about including (possibly truncated) message + content in the 'content' key.</p> + + <tp:rationale> + The Messages interface needs to allow all content to be + retrieved, but in this interface, the content we provide is + merely a hint; so some is better than none, and it doesn't + seem worth providing an API as complex as Messages' + GetPendingMessageContent for the echoed message. + </tp:rationale> + </dd> + + </dl> + + <p>The second and subsequent Message_Part dictionaries, if present, + are a human-readable report from the IM service.</p> + + <p>Clients MUST NOT attempt to send delivery reports using the + SendMessage method in the Messages API, and connection managers + MUST NOT allow this to be done. If support for sending delivery + reports is later added, it will be part of this interface.</p> + + <p>Some example delivery reports in a Python-like syntax (in which + arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2}) + follow.</p> + + <dl> + <dt>A minimal delivery report indicating permanent failure of the + sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown + reason</dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +] +</pre></dd> + + <dt>A delivery report where the failed message is echoed back to the + sender rather than being referenced by ID, and the failure reason + is that this protocol cannot send messages to offline contacts + such as the contact with handle 123</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Temporarily_Failed, +'delivery-error': Channel_Text_Send_Error_Offline, +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], + +# no body +] +</pre></dd> + + <dt>A maximally complex delivery report: the server reports a + bilingual human-readable failure message because the user sent + a message "Hello, world!" with token + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact + with handle 123, but that handle represents a contact who does not + actually exist</dt> + <dd><pre> +[{ # header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Permanently_Failed, +'delivery-error': Channel_Text_Send_Error_Invalid_Contact, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +'delivery-echo': + [{ # header of original message + 'message-sender': 1, + 'message-sent': 1210067943, + }, + { # body of original message + 'content-type': 'text/plain', + 'content': 'Hello, world!', + }] + ], +}, +{ # message from server (alternative in English) +'alternative': '404', +'content-type': 'text/plain', +'lang': 'en', +'content': 'I have no contact with that name', +}, +{ # message from server (alternative in German) +'alternative': '404'. +'content-type': 'text/plain', +'lang': 'de', +'content', 'Ich habe keinen Kontakt mit diesem Namen', +} +] +</pre></dd> + + <dt>A minimal delivery report indicating successful delivery + of the sent message whose token was + <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt> + <dd><pre> +[{ +# header +'message-sender': 123, +'message-type': Channel_Text_Message_Type_Delivery_Report, +'delivery-status': Delivery_Status_Delivered, +'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4', +} +# no body +] +</pre></dd> + + </dl> </div> </tp:docstring> @@ -418,12 +697,6 @@ USA.</p> as matching on message content or timestamp (if available), or assuming that the delivery report refers to the most recent message with that ID.</p> - - <tp:rationale> - <p>This is a hook for the DeliveryReporting interface, - to avoid having to introduce a - SendMultiPartMessageAndReturnToken method in that interface.</p> - </tp:rationale> </tp:docstring> </tp:simple-type> @@ -434,6 +707,17 @@ USA.</p> to the server and the MessageSent signal is emitted. A corresponding Sent signal on the Text interface MUST also be emitted.</p> + <p>This method MUST return before the MessageSent signal is + emitted.</p> + + <tp:rationale> + <p>This means that the process sending the message is the first + to see the <tp:type>Sent_Message_Token</tp:type>, and can + relate the message to the corresponding + <tp:member-ref>MessageSent</tp:member-ref> signal by comparing + message tokens (if supported by the protocol).</p> + </tp:rationale> + <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> @@ -480,42 +764,55 @@ USA.</p> </tp:docstring> <tp:flag suffix="Report_Delivery" value="1"> - <tp:docstring> - Provide a delivery report via the DeliveryReporting interface, if - possible, even if this is not the default for this protocol. - Ignored if delivery reports are not possible on this protocol. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Provide a successful delivery report if possible, even if this is + not the default for this protocol. Ignored if delivery reports are + not possible on this protocol.</p> <tp:rationale> - In some protocols, like XMPP, it is not conventional to request - or send delivery notifications. + <p>In some protocols, like XMPP, it is not conventional to request + or send positive delivery notifications.</p> </tp:rationale> + + <p>Delivery failure reports SHOULD always be sent, but if this flag + is present, the connection manager MAY also try harder to obtain + failed delivery reports or allow them to be matched to outgoing + messages.</p> </tp:docstring> </tp:flag> </tp:flags> <signal name="MessageSent" tp:name-for-bindings="Message_Sent"> - <tp:docstring> - Signals that a message has been submitted for sending. This - MUST be emitted exactly once per emission of the Sent signal on the - Text interface. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that a message has been submitted for sending. This + MUST be emitted exactly once per emission of the Sent signal on the + Text interface.</p> <tp:rationale> - This signal allows a process that is not the caller of - SendMessage to log sent messages. The double signal-emission - means that clients can safely follow the following rule: - if the channel has the Messages interface, listen for - Messages.MessageSent only; otherwise, listen for Text.Sent only. + <p>This signal allows a process that is not the caller of + SendMessage to log sent messages. The double signal-emission + provides compatibility with older clients. Clients supporting + Messages should listen for Messages.MessageSent only (if the + channel has the Messages interface) or Text.Sent only + (otherwise).</p> </tp:rationale> </tp:docstring> <arg type="aa{sv}" tp:type="Message_Part[]" name="Content"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - The message content (see <tp:type>Message_Part</tp:type> for full - details). If the message that was passed to SendMessage has a - formatted text part that the connection manager recognises, but no - text/plain alternative, the CM MUST use the formatted text part to - generate a text/plain alternative which is also included in this - signal argument. + <p>The message content (see <tp:type>Message_Part</tp:type> for full + details). If the message that was passed to SendMessage has a + formatted text part that the connection manager recognises, but no + text/plain alternative, the CM MUST use the formatted text part to + generate a text/plain alternative which is also included in this + signal argument.</p> + + <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 + argument to SendMessage (if the message is truncated, + formatting or alternatives are dropped, etc., then the edited + version SHOULD appear in this signal).</p> </tp:docstring> </arg> @@ -593,9 +890,9 @@ USA.</p> the <tp:type>Message_Part</tp:type> mappings.</p> <p>If the one of the requested part numbers was greater than zero - but referred to a part that had no content (i.e. it had no 'type' - key or no 'content' key), it is simply omitted from this mapping; - this is not considered to be an error condition.</p> + but referred to a part that had no content (i.e. it had no + 'content-type' key or no 'content' key), it is simply omitted from + this mapping; this is not considered to be an error condition.</p> </tp:docstring> </arg> @@ -619,10 +916,10 @@ USA.</p> Received signal on the Text interface. <tp:rationale> - The double signal-emission means that clients can safely follow - the following rule: if the channel has the Messages interface, - listen for Messages.MessageReceived only; otherwise, listen for - Text.Received only. + The double signal-emission provides compatibility with older + clients. Clients supporting Messages should listen for + Messages.MessageReceived only (if the channel has the Messages + interface) or Text.Received only (otherwise). </tp:rationale> </tp:docstring> @@ -633,6 +930,104 @@ USA.</p> </arg> </signal> + <tp:enum name="Delivery_Status" value-prefix="Delivery_Status" type="u"> + <tp:docstring> + <p>The status of a message as indicated by a delivery report.</p> + + <p>If this enum is extended in future specifications, this should + only be to add new, non-overlapping conditions (i.e. all failures + should still be signalled as either Temporarily_Failed + or Permanently_Failed). If additional detail is required (e.g. + distinguishing between the various types of permanent failure) this + will be done using additional keys in the Message_Part.</p> + </tp:docstring> + + <tp:enumvalue suffix="Unknown" value="0"> + <tp:docstring> + The message's disposition is unknown. + Clients SHOULD consider all messages to have status + Delivery_Status_Unknown unless otherwise specified; connection + managers SHOULD NOT signal this delivery status explicitly. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Delivered" value="1"> + <tp:docstring> + The message has been delivered to the intended recipient. + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Temporarily_Failed" value="2"> + <tp:docstring> + Delivery of the message has failed. Clients SHOULD notify the user, + but MAY automatically try sending another copy of the message. + + <tp:rationale> + Similar to errors with type="wait" in XMPP; analogous to + 4xx errors in SMTP. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + + <tp:enumvalue suffix="Permanently_Failed" value="3"> + <tp:docstring> + Delivery of the message has failed. Clients SHOULD NOT try again + unless by specific user action. If the user does not modify the + message or alter configuration before re-sending, this error is + likely to happen again. + + <tp:rationale> + Similar to errors with type="cancel", type="modify" + or type="auth" in XMPP; analogous to 5xx errors in SMTP. + </tp:rationale> + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <tp:flags name="Delivery_Reporting_Support_Flags" + value-prefix="Delivery_Reporting_Support_Flag" type="u"> + <tp:docstring> + Flags indicating the level of support for delivery reporting on this + channel. Any future flags added to this set will conform to the + convention that the presence of an extra flag implies that + more operations will succeed. + </tp:docstring> + + <tp:flag suffix="Receive_Failures" value="1"> + <tp:docstring> + Clients MAY expect to receive negative delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + + <tp:rationale> + If senders want delivery reports, they should ask for them. + If they don't want delivery reports, they can just ignore them, + so there's no need to have capability discovery for what will + happen if a delivery report isn't requested. + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Receive_Successes" value="2"> + <tp:docstring> + Clients MAY expect to receive positive delivery reports if + Message_Sending_Flag_Report_Delivery is specified when sending. + + <tp:rationale> + Same rationale as Receive_Failures. + </tp:rationale> + </tp:docstring> + </tp:flag> + + </tp:flags> + + <property name="DeliveryReportingSupport" access="read" + tp:type="Delivery_Reporting_Support_Flags" type="u" + tp:name-for-bindings="Delivery_Reporting_Support"> + <tp:docstring> + A bitfield indicating features supported by this channel. + </tp:docstring> + </property> + </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Request.xml b/qt4/spec/Channel_Request.xml new file mode 100644 index 000000000..08b291f74 --- /dev/null +++ b/qt4/spec/Channel_Request.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" ?> +<node name="/Channel_Request" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp: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.ChannelRequest.DRAFT" + tp:causes-havoc="experimental"> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel request is an object in the ChannelDispatcher representing + an ongoing request for some channels to be created or found. There + can be any number of ChannelRequest objects at the same time.</p> + + <p>Its well-known bus name is the same as that of the ChannelDispatcher, + "org.freedesktop.Telepathy.ChannelDispatcher".</p> + + <tp:rationale> + <p>See + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT.CreateChannel</tp:dbus-ref> + for rationale for ChannelRequest being a separate object.</p> + </tp:rationale> + </tp:docstring> + + <property name="UserActionTime" tp:name-for-bindings="User_Action_Time" + type="t" tp:type="Unix_Timestamp64" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The time at which user action occurred, or 0 if this channel + request is for some reason not involving user action.</p> + + <p>This corresponds to the _NET_WM_USER_TIME property in + <a href="http://standards.freedesktop.org/wm-spec/wm-spec-latest.html">EWMH</a>.</p> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <property name="Requests" tp:name-for-bindings="Requests" type="aa{sv}" + tp:type="Qualified_Property_Value_Map[]" + access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An array of dictionaries containing desirable properties for + the channel or channels to be created.</p> + + <tp:rationale> + <p>This is an array so that we could add a CreateChannels method in + future without redefining the API of ChannelRequest.</p> + </tp:rationale> + + <p>This property is set when the channel request is created, + and can never change.</p> + </tp:docstring> + </property> + + <method name="Proceed" tp:name-for-bindings="Proceed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Proceed with the channel request.</p> + + <tp:rationale> + <p>The client that created this object calls this method + when it has connected signal handlers for + <tp:member-ref>Succeeded</tp:member-ref> and + <tp:member-ref>Failed</tp:member-ref>.</p> + </tp:rationale> + + <p>Clients other than the client which created the ChannelRequest + MUST NOT call this method.</p> + + <p>This method SHOULD return immediately; on success, the request + might still fail, but this will be indicated asynchronously + by the <tp:member-ref>Failed</tp:member-ref> signal.</p> + + <p>Proceed cannot fail, unless clients have got the life-cycle + of a ChannelRequest seriously wrong (e.g. a client calls this + method twice, or a client that did not create the ChannelRequest + calls this method). If it fails, clients SHOULD assume that the + whole ChannelRequest has become useless.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable"> + <tp:docstring> + This method has already been called, so it is no longer + available. Stop calling it. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <method name="Cancel" tp:name-for-bindings="Cancel"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Cancel the channel request. The precise effect depends on the + current progress of the request.</p> + + <p>If the connection manager has not already been asked to create + a channel, then <tp:member-ref>Failed</tp:member-ref> is emitted + immediately, and the channel request is removed.</p> + + <p>If the connection manager has already been asked to create a + channel but has not produced one yet (e.g. if <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref> + has been called, but has not yet returned), then the + ChannelDispatcher will remember that the request has been cancelled. + When the channel appears, it will be closed (if it was newly + created and can be closed), and will not be dispatched to a + handler.</p> + + <p>If the connection manager has already returned a channel, but the + channel has not yet been dispatched to a handler + then the channel dispatcher will not dispatch that + channel to a handler. If the channel was newly created for this + request, the channel dispatcher will close it with Close; otherwise, + the channel dispatcher will ignore it. In either case, + <tp:member-ref>Failed</tp:member-ref> will be emitted when processing + has been completed.</p> + + <p>If Failed is emitted in response to this method, the error SHOULD be + <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p> + + <p>If the channel has already been dispatched to a handler, then + it's too late to call this method, and the channel request will + no longer exist.</p> + </tp:docstring> + </method> + + <signal name="Failed" tp:name-for-bindings="Failed"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has failed. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + + <arg name="Error" type="s" tp:type="DBus_Error_Name"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of a D-Bus error. This can come from various sources, + including the error raised by CreateChannel, or an error generated + to represent failure to establish the Connection.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s"> + <tp:docstring> + If the first argument of the D-Bus error message was a string, + that string. Otherwise, an empty string. + </tp:docstring> + </arg> + </signal> + + <signal name="Succeeded" tp:name-for-bindings="Succeeded"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel request has succeeded. It is no longer present, + and further methods must not be called on it.</p> + </tp:docstring> + </signal> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Channel_Type_Contact_List.xml b/qt4/spec/Channel_Type_Contact_List.xml index 577f250c2..9c0935144 100644 --- a/qt4/spec/Channel_Type_Contact_List.xml +++ b/qt4/spec/Channel_Type_Contact_List.xml @@ -41,11 +41,34 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ one of the following identifiers:</p> <ul> - <li>subscribe - the group of contacts for whom you wish to receive presence</li> + <li>subscribe - the group of contacts for whom you receive presence</li> <li>publish - the group of contacts who may receive your presence</li> <li>hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence</li> <li>allow - a group of contacts who may send you messages</li> <li>deny - a group of contacts who may not send you messages</li> + <li>stored - on protocols where the user's contacts are stored, this + contact list contains all stored contacts regardless of subscription + status.</li> + </ul> + + <p>A contact can be in several server-defined lists. All lists are optional + to implement. If RequestHandles or RequestChannel for a particular contact + list raises an error, this indicates that the connection manager makes no + particular statement about the list's contents; clients MUST NOT consider + this to be fatal.</p> + + <p>If a client wants to list all of a user's contacts, it is appropriate to + use the union of the subscribe, publish and stored lists, including the + local and remote pending members.</p> + + <p>For example in XMPP, contacts who have the subscription type "none", + "from", "to" and "both" can be respectively in the lists:</p> + + <ul> + <li>"none": stored</li> + <li>"from": stored and publish</li> + <li>"to": stored and subscribe</li> + <li>"both": stored, publish and subscribe</li> </ul> <p>These contact list channels may not be closed.</p> diff --git a/qt4/spec/Channel_Type_Room_List.xml b/qt4/spec/Channel_Type_Room_List.xml index e98651d7f..6636ce0d2 100644 --- a/qt4/spec/Channel_Type_Room_List.xml +++ b/qt4/spec/Channel_Type_Room_List.xml @@ -27,7 +27,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Info"/> </tp:struct> - <property name="Server" type="s" access="read"> + <property name="Server" tp:name-for-bindings="Server" + type="s" access="read"> <tp:docstring> <p>For protocols with a concept of chatrooms on multiple servers with different DNS names (like XMPP), the DNS name of the server diff --git a/qt4/spec/Channel_Type_Text.xml b/qt4/spec/Channel_Type_Text.xml index cdccd3ff6..8340305ff 100644 --- a/qt4/spec/Channel_Type_Text.xml +++ b/qt4/spec/Channel_Type_Text.xml @@ -117,7 +117,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> - <signal name="Received"> + <signal name="Received" tp:name-for-bindings="Received"> <arg name="ID" type="u"> <tp:docstring> A numeric identifier for acknowledging the message @@ -157,7 +157,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </signal> - <method name="Send"> + <method name="Send" tp:name-for-bindings="Send"> <arg direction="in" name="Type" type="u" tp:type="Channel_Text_Message_Type"> <tp:docstring> An integer indicating the type of the message @@ -168,11 +168,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ The message to send </tp:docstring> </arg> - <tp:docstring> - Request that a message be sent on this channel. When the message has - been submitted for delivery, this method will return and the Sent - signal will be emitted. If the message cannot be submitted for - delivery, the method returns an error and no signal is emitted. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that a message be sent on this channel. When the message has + been submitted for delivery, this method will return and the Sent + signal will be emitted. If the message cannot be submitted for + delivery, the method returns an error and no signal is emitted.</p> + + <p>This method SHOULD return before the Sent signal is + emitted.</p> + + <tp:rationale> + <p>When a Text channel implements the Messages interface, that + "SHOULD" becomes a "MUST".</p> + </tp:rationale> </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -251,7 +259,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ actually implemented.</tp:changed> </signal> - <signal name="Sent"> + <signal name="Sent" tp:name-for-bindings="Sent"> <arg name="Timestamp" type="u" tp:type="Unix_Timestamp"> <tp:docstring> Unix timestamp indicating when the message was sent @@ -265,11 +273,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </arg> <arg name="Text" type="s"> <tp:docstring> - The text of the message + The text of the message. If the message was, or will be, altered + during transmission, this argument SHOULD reflect what other + contacts will receive rather than being a copy of the argument + to Send. </tp:docstring> </arg> - <tp:docstring> - Signals that a message has been submitted for sending. + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Signals that a message has been submitted for sending.</p> </tp:docstring> </signal> @@ -335,6 +346,38 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ the user that part of the message was not understood.</p> </tp:docstring> </tp:flag> + + <tp:flag suffix="Scrollback" value="4"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message was part of a replay of message history.</p> + + <tp:rationale> + <p>In XMPP multi-user chat, a few past messages are replayed + when you join a chatroom. A sufficiently capable IRC connection + manager could also set this flag on historical messages when + connected to a proxy like bip or irssi-proxy. The existence + of this flag allows loggers and UIs to use better heuristics + when eliminating duplicates (a simple implementation made + possible by this flag would be to avoid logging scrollback + at all).</p> + </tp:rationale> + </tp:docstring> + </tp:flag> + + <tp:flag suffix="Rescued" value="8"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The incoming message has been seen in a previous channel during + the lifetime of the Connection, but had not been acknowledged + when that channel closed, causing an identical channel (the + channel in which the message now appears) to open.</p> + + <tp:rationale> + <p>This means that a logger (which should already have seen the + message in the previous channel) is able to recognise and ignore + these replayed messages.</p> + </tp:rationale> + </tp:docstring> + </tp:flag> </tp:flags> <tp:property name="anonymous" type="b"> @@ -465,6 +508,68 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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> + + <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> + + <tp:rationale> + <p>In effect, this turns this situation, in which a client + is likely to lose messages:</p> + + <ul> + <li>UI window is closed</li> + <li>message arrives</li> + <li>text channel emits Received</li> + <li>UI calls Close on text channel before it has seen the + Received signal</li> + <li>text channel emits Closed and closes</li> + </ul> + + <p>into something nearly equivalent to this situation, which is + fine:</p> + + <ul> + <li>UI window is closed</li> + <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>(the same or a different) UI handles it</li> + </ul> + + <p>suppress_handler must be set to FALSE so the replacement channel + will be handled by something.</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> + + <tp:rationale> + <p>This "respawning" behaviour becomes problematic if there is no + suitable handler for Text channels, or if a particular message + repeatedly crashes the Text channel handler; a channel dispatcher + can't just Close() the channel in these situations, because + it will come back.</p> + + <p>In these situations, the channel dispatcher needs a last-resort + way to destroy the channel and stop it respawning. It could either + acknowledge the messages itself, or use the Destroyable interface; + the Destroyable interface has the advantage that it's not + channel-type-dependent, so the channel dispatcher only has to + understand one extra interface, however many channel types + eventually need a distinction between Close and Destroy.</p> + </tp:rationale> + </tp:docstring> </interface> </node> diff --git a/qt4/spec/Client.xml b/qt4/spec/Client.xml new file mode 100644 index 000000000..d0bb8e5f5 --- /dev/null +++ b/qt4/spec/Client.xml @@ -0,0 +1,123 @@ +<?xml version="1.0" ?> +<node name="/Client" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.12">(as a draft)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Telepathy clients use connection managers, the channel dispatcher + and optionally the account manager to provide useful + functionality.</p> + + <p>User interface processes are the obvious example of Telepathy + clients, but they can provide other functionality, such as + address-book synchronization.</p> + + <p>Every running or activatable process with a well-known + name of the form org.freedesktop.Telepathy.Client.<em>clientname</em> + should be probed by the channel dispatcher to discover its + capabilities. Each client is either an <em>observer</em>, an + <em>approver</em>, a <em>channel handler</em>, or some combination + of these.</p> + + <tp:rationale> + <p>Activatable services (those with a D-Bus <code>.service</code> + file) must be supported so that we can run clients + in response to channel creation.</p> + + <p>Non-activatable services (those that do not register a D-Bus + <code>.service</code> file for their well-known name, but do + request it at runtime) must be supported so that we can have + programs that process channels, but only if they are already + running - for instance, a full-screen media centre + application might do this.</p> + </tp:rationale> + + <p>The client name, <em>clientname</em>, MUST be a non-empty string of + ASCII digits, letters, dots and/or underscores, starting with a + letter, and without sets of two consecutive dots or a dot + followed by a digit. For non-activatable services, it MAY contain a + part that is generated per instance at runtime.</p> + + <tp:rationale> + <p>If each of a client Foo's instances should be able to manipulate + channels separately, the instance with unique name + <code>:1.25</code> might request a well-known name like + <code>org.freedesktop.Telepathy.Client.Foo._1._25</code>.</p> + + <p>(Note that well-known bus-name components may not start with a + digit, so o.f.T.Client.Foo.1.25 would not be acceptable.)</p> + </tp:rationale> + + <p>Each Client MUST export an object whose object path may be + determined by replacing '.' with '/' in the well-known name and + prepending '/'. This object represents its API as a Telepathy + client; the channel dispatcher will call its methods and read + its properties when appropriate.</p> + + <p>As an optimization, activatable clients SHOULD install a file + <code><a href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">$XDG_DATA_DIRS</a>/telepathy/clients/<em>clientname</em>.client</code> + containing a cached version of its immutable properties, + so that for most clients, the channel dispatcher can + just read a file to discover capabilities, instead of + having to service-activate the client immediately in order to fetch + its read-only properties. However, the D-Bus API is canonical, and + the channel dispatcher MUST support clients without such a file.</p> + + <p>Non-activatable clients MAY install a <code>.client</code> file, + but there's not much point in them doing so.</p> + + <p>The .client files MUST contain UTF-8 text with the same syntax + as + <a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop + Entry files</a> (although the allowed groups, keys and values differ). + Every <code>.client</code> file MUST contain a group whose name is + the name of this interface.</p> + + <p>The groups, keys and values in the <code>.client</code> file are + defined by individual interfaces. Each interface that can usefully + cache information in the <code>.client</code> file SHOULD correspond + to a group with the same name.</p> + </tp:docstring> + + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read" tp:type="DBus_Interface[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the extra interfaces provided by this client. + This SHOULD include at least one of + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer</tp:dbus-ref>, + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Approver</tp:dbus-ref> or + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>.</p> + + <p>In the <code>.client</code> file, this is represented by key + "<code>Interfaces</code>" in the group named after this interface. + The value of the key is a list of interface names each followed by + a semicolon (so it always ends with a semicolon unless it is empty), + i.e. a key of type "strings" as described in the Desktop Entry + specification.</p> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Approver.xml b/qt4/spec/Client_Approver.xml new file mode 100644 index 000000000..8f59a1939 --- /dev/null +++ b/qt4/spec/Client_Approver.xml @@ -0,0 +1,137 @@ +<?xml version="1.0" ?> +<node name="/Client_Approver" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Approver.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.12">(as a draft)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Approvers notify the user that new channels have been created, + and allow the user to accept or reject those channels.</p> + + <p>They can also select which channel handler will be used for the + channel, for instance by offering the user a list of possible + handlers rather than just an accept/reject choice.</p> + + <p>However, the Channel Dispatcher must be able to prioritize + possible handlers on its own using some reasonable heuristic, + probably based on user configuration.</p> + + <p>It is possible (and useful) to have an approver and + a channel handler in the same process; this is particularly useful + if a channel handler wants to claim responsibility for particular + channels itself.</p> + + <p>All approvers are notified simultaneously. For instance, in a + desktop system, there might be one approver that displays a + notification-area icon, one that is part of a contact list + window and highlights contacts there, and one that is part + of a full-screen media player.</p> + + <p>Any approver can approve the handling of a channel with a + particular channel handler. Approvers can also request that the + channel is rejected. The first approver to reply gets its decision + acted on; any other approvers that reply at the same time will + get a D-Bus error, indicating that the channel has already been + dealt with.</p> + + <p>Approvers should usually prompt the user and ask for + confirmation, rather than dispatching the channel to a handler + straight away.</p> + </tp:docstring> + + <property name="ApproverChannelFilter" + tp:name-for-bindings="Approver_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this approver is + interested. The <tp:member-ref>AddDispatchOperation</tp:member-ref> + method should be called by the channel dispatcher whenever the + channels in a channel dispatch operation + match this description.</p> + + <p>(FIXME: what happens if some but not all of the channels + match this?)</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref> + property. In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + ApproverChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <method name="AddDispatchOperation" + tp:name-for-bindings="Add_Dispatch_Operation"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when a ChannelDispatchOperation + in which the approver has registered an interest is created, + or when the approver starts up while such channel dispatch + operations already exist.</p> + + <p>The channel dispatcher SHOULD call this method on all approvers + at the same time. If no approvers return from this method + successfully (including situations where there are no matching + approvers at all), the channel dispatcher SHOULD consider this + to be an error, and recover by dispatching the channel to the + most preferred handler.</p> + + <tp:rationale> + Processes that aren't approvers shouldn't be making connections + anyway - there should always be at least one approver running. + </tp:rationale> + </tp:docstring> + + <arg name="DispatchOperation" type="o" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref> + to be processed.</p> + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + Properties of the channel dispatch operation. This MUST NOT include + properties that could change, SHOULD include as many properties as + possible given that constraint, and MUST include at least the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Account</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Connection</tp:dbus-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Channels</tp:dbus-ref> + and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">PossibleHandlers</tp:dbus-ref> + properties. + </tp:docstring> + </arg> + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Handler.xml b/qt4/spec/Client_Handler.xml new file mode 100644 index 000000000..8793f3eca --- /dev/null +++ b/qt4/spec/Client_Handler.xml @@ -0,0 +1,268 @@ +<?xml version="1.0" ?> +<node name="/Client_Handler" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Handler.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.12">(as a draft)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Channel handlers are the eventual handler for a channel or a + channel bundle; a typical channel handler is a user interface + process handling channels of a particular type.</p> + + <p>When a new incoming channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + = FALSE) is offered to + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s + by the channel dispatcher, it also offers the Approvers a list of all + the running or activatable ChannelHandlers whose + <tp:member-ref>HandlerChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they + are able to handle the channel. The Approvers can choose one of + those channel handlers to handle the channel.</p> + + <p>When a new outgoing channel (one with + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + = TRUE) appears, the channel dispatcher passes it to an appropriate + channel handler automatically. + </p> + + </tp:docstring> + + <property name="HandlerChannelFilter" + tp:name-for-bindings="Handler_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels that this channel handler can + deal with. It will be offered to approvers as a potential + channel handler for bundles that contain only suitable channels, + or for suitable channels that must be handled separately.</p> + + <p>This property works in exactly the same way as the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Client.Observer.DRAFT.ObserverChannelFilter</tp:dbus-ref> + property. In the .client file, it is represented in the + same way as ObserverChannelFilter, but the group has the same + name as this interface and the keys start with + HandlerChannelFilter instead of ObserverChannelFilter.</p> + </tp:docstring> + </property> + + <property name="BypassApproval" tp:name-for-bindings="Bypass_Approval" + type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If true, channels destined for this handler are automatically + handled, without invoking approvers.</p> + + <tp:rationale> + <p>The intended usage is to allow a client handling one channel to + pick up closely related channels. Suppose a client capable of + handling both Text and StreamedMedia, + <code>org.freedesktop.Telepathy.Client.Empathy</code>, is + handling a StreamedMedia channel. That client can take a second + well-known bus name, say + <code>org.freedesktop.Telepathy.Client.Empathy._1._42.Bundle1</code>, + and configure an object at + <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> + </tp:rationale> + </tp:docstring> + </property> + + <method name="HandleChannels" tp:name-for-bindings="Handle_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when this client should handle these + channels, or when this client should present channels that it is already + handling to the user (e.g. bring them into the foreground).</p> + + <tp:rationale> + <p>Clients are expected to know what channels they're already handling, + and which channel object path corresponds to which window or tab. + This can easily be done using a hash table keyed by channels' object + paths.</p> + </tp:rationale> + + <p>This method can raise any D-Bus error. If it does, or if the + handler loses its bus name before all the channels have closed, the + handler is assumed to have failed or crashed, and the channel + dispatcher MUST recover in an implementation-specific way.</p> + + <p>It is RECOMMENDED that the channel dispatcher attempts to + close the channels using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>, + but resorts to calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref> + (if available) or ignoring the channel (if not) if the same handler + repeatedly fails to handle channels.</p> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The Connection with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" direction="in"> + <tp:docstring> + The channels and their immutable properties. Their well-known + bus name is the same as that of the Connection. + </tp:docstring> + </arg> + + <arg name="Requests_Satisfied" type="ao" direction="in"> + <tp:docstring> + The requests satisfied by these channels. + + <tp:rationale> + There can be more than one, if they were EnsureChannel + requests. + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="User_Action_Time" type="t" direction="in"> + <tp:docstring> + The time at which user action occurred, or 0 if this channel + is to be handled for some reason not involving user action. + Handlers SHOULD use this for focus-stealing prevention, + if applicable. + </tp:docstring> + </arg> + + <!-- FIXME: invent a way to say "any error is possible" in spec markup --> + </method> + + <method name="AddRequest" tp:name-for-bindings="Add_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that channels have been + requested, and that if the request is successful, they will be + handled by this Handler.</p> + + <tp:rationale> + <p>This allows the UI to start preparing to handle the channels + in advance (e.g. render a window with an "in progress" message), + improving perceived responsiveness.</p> + </tp:rationale> + + <p>(FIXME: how do we know the returned channels will be handled by + this handler? Do we just assume that they'll match the + HandlerChannelFilter iff the request does?)</p> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The <tp:dbus-ref + namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref> + object. + </tp:docstring> + </arg> + + <arg name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map" direction="in"> + <tp:docstring> + <p>Some of the properties of the ChannelRequest. To avoid race + conditions, this dictionary MUST NOT include properties whose + values could subsequently change. It SHOULD include as many + properties as possible, given that constraint.</p> + + <p>In particular, the properties Requests and UserActionTimestamp + MUST be included.</p> + </tp:docstring> + </arg> + </method> + + <method name="RemoveFailedRequest" + tp:name-for-bindings="Remove_Failed_Request"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the ChannelDispatcher to indicate that a request + previously passed to <tp:member-ref>AddRequest</tp:member-ref> + has failed and should be disregarded.</p> + </tp:docstring> + + <arg name="Request" type="o" direction="in"> + <tp:docstring> + The request that failed. + </tp:docstring> + </arg> + + <arg name="Error" type="s" tp:type="DBus_Error_Name" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The name of the D-Bus error with which the request failed.</p> + + <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>, + this indicates that the request succeeded, but all the resulting + channels were given to some other handler.</p> + </tp:docstring> + </arg> + + <arg name="Message" type="s" direction="in"> + <tp:docstring> + Any message supplied with the D-Bus error. + </tp:docstring> + </arg> + </method> + + <property name="HandledChannels" tp:name-for-bindings="Handled_Channels" + type="ao" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A list of the channels that this Handler is currently handling. + </p> + + <p>There is no change notification.</p> + + <tp:rationale> + <p>This property exists for state recovery - it makes it possible + for channel handling to survive a ChannelDispatcher crash.</p> + + <p>If the channel dispatcher is automatically replaced, the + replacement can discover all Handlers by looking for the Client + well-known bus names, and discover which channels they are + currently handling. Once this has been done, all unhandled + channels can be re-dispatched, and the only issue visible to + the user is that unhandled channels that they have already + approved might be sent back to Approvers.</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Client_Observer.xml b/qt4/spec/Client_Observer.xml new file mode 100644 index 000000000..89709e2af --- /dev/null +++ b/qt4/spec/Client_Observer.xml @@ -0,0 +1,230 @@ +<?xml version="1.0" ?> +<node name="/Client_Observer" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA + 02110-1301, USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Client.Observer.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.17.12">(as a draft)</tp:added> + + <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Observers monitor the creation of new channels. This + functionality can be used for things like message logging. + All observers are notified simultaneously.</p> + + <p>Observers SHOULD NOT modify the state of a channel except + via user interaction.</p> + + <tp:rationale> + <p>We want Observer UIs for file transfer channels (a progress + bar for the transfer) to be able to have a Cancel button.</p> + </tp:rationale> + + <p>Observers MUST NOT carry out actions that exactly one process + must take responsibility for (e.g. acknowledging Text + messages, or carrying out the actual transfer in a file transfer + channel).</p> + + <tp:rationale> + <p>Since arbitrarily many observers can be activated for + each channel, it would not make sense for observers to do things + that can only be done by one process (acknowledging + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref> + messages, carrying out streaming for + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref> + channels, doing the actual data transfer for file transfers, + setting up the out-of-band connection for Tubes). The + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref> + is responsible for such tasks.</p> + + <p>Handlers MAY, of course, delegate responsibility for these + tasks to other processes (including those run as observers), + but this MUST be done explicitly via a request from the Handler + to the Observer.</p> + </tp:rationale> + + <p>Whenever new channels are signalled, the channel dispatcher + will notify all running or activatable observers whose + <tp:member-ref>ObserverChannelFilter</tp:member-ref> property + (possibly as cached in the .client file) indicates that they are + interested in the channel.</p> + + <p>Observers are activated for all channels in which they have + registered an interest - incoming, outgoing or automatically created - + although of course the ObserverChannelFilter property can be set + to filter on the + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref> + property.</p> + </tp:docstring> + + <property name="ObserverChannelFilter" + tp:name-for-bindings="Observer_Channel_Filter" + type="aa{sv}" access="read" tp:type="Channel_Class[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A specification of the channels in which this observer is + interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method + should be called by the channel dispatcher whenever any of the new + channels in a NewChannels signal match this description.</p> + + <p>(FIXME: open issue: do we want this, and the corresponding + Approver and Handler properties, to be able to change at + runtime?)</p> + + <p>Only certain D-Bus types have useful semantics for matching like this, + so only certain types are allowed:</p> + + <dl> + <dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt> + <dd>Matched by numeric value, regardless of type (e.g. 42 as a + 16-bit signed integer 'n' is considered equal to 42 as a 32-bit + unsigned integer 'u')</dd> + + <dt>Booleans (b)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Strings (s)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + <dt>Object paths (o)</dt> + <dd>Matched by equality in the obvious way; not considered equal to any + other type</dd> + + </dl> + + <p>This property never changes while the observer process is + running. For activatable processes, the filter can change due to an + upgrade - the channel dispatcher SHOULD observe changes to .client files + using a mechanism like inotify.</p> + + <p>For observers that have a .client file, the channel dispatcher + may discover this property from keys of the form + <code><em>propertyname</em>/<em>type</em></code>, + in groups in the .client file whose name is the name of this + interface followed by <code>.ObserverChannelFilter</code>, + a space and an ASCII decimal number starting from 0.</p> + + <p>Integers in the .client file are encoded in ASCII decimal, booleans + are encoded as "true" or "false", and strings are encoded in the usual + way for desktop files (including the C-style backslash escapes + documented in the Desktop Entry specification).</p> + + <p>For instance, a .client file for an observer that is only interested + in Text channels, with CONTACT or ROOM handles, that were requested by + a local client:</p> + +<pre> +[org.freedesktop.Telepathy.Client.DRAFT] +Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT; + +[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0] +org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=1 +org.freedesktop.Telepathy.Channel.Requested b=true + +[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 1] +org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text +org.freedesktop.Telepathy.Channel.TargetHandleType u=2 +org.freedesktop.Telepathy.Channel.Requested b=true +</pre> + + </tp:docstring> + </property> + + <method name="ObserveChannels" tp:name-for-bindings="Observe_Channels"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Called by the channel dispatcher when channels in which the + observer has registered an interest are created.</p> + + <p>The observer MUST NOT return from this method call until it is ready + for a handler for the channel to run (which may change the channel's + state).</p> + + <tp:rationale> + <p>The channel dispatcher must wait for observers to start up, + to avoid the following race: text channel logger (observer) gets + ObserveChannel, text channel handler gets + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref> + channel handler starts up faster and acknowledges messages, + logger never sees those messages.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Account" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use is that of the + <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>. + </tp:docstring> + </arg> + + <arg name="Connection" type="o" direction="in"> + <tp:docstring> + The + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + with which the channels are associated. The + well-known bus name to use can be derived from this object + path by removing the leading '/' and replacing all subsequent + '/' by '.'. + </tp:docstring> + </arg> + + <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]" + direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s + and their properties. Their well-known bus names are all the same + as that of the Connection.</p> + + <tp:rationale> + <p>The ChannelDispatchOperation is <em>not</em> supplied: for + requests, there isn't one, and for incoming channels, it hasn't + been created yet.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Observer_Info" type="a{sv}" direction="in"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Additional information about these channels. No keys are + currently defined.</p> + + <p>If keys are defined for this dictionary, all will be optional; + observers MAY safely ignore any entry in this dictionary.</p> + </tp:docstring> + </arg> + + </method> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection.xml b/qt4/spec/Connection.xml index 2a70afb81..f543a16ad 100644 --- a/qt4/spec/Connection.xml +++ b/qt4/spec/Connection.xml @@ -44,7 +44,7 @@ USA.</p> </tp:member> </tp:struct> - <method name="Connect"> + <method name="Connect" tp:name-for-bindings="Connect"> <tp:docstring> Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged @@ -58,7 +58,7 @@ USA.</p> </tp:possible-errors> </method> - <method name="Disconnect"> + <method name="Disconnect" tp:name-for-bindings="Disconnect"> <tp:docstring> Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection @@ -100,7 +100,7 @@ USA.</p> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"> <tp:docstring> - Before version 0.17.UNRELEASED calling GetInterfaces while + Before version 0.17.8 calling GetInterfaces while on a connection that is not yet CONNECTED wasn't allowed. If a CM returns this error, its list of interfaces should be regarded as empty until it becomes CONNECTED. @@ -121,19 +121,52 @@ USA.</p> </tp:docstring> </method> + <signal name="SelfHandleChanged" + tp:name-for-bindings="Self_Handle_Changed"> + <tp:docstring> + Emitted whenever the SelfHandle property changes. If the connection + is not yet in the CONNECTED state, this signal is not guaranteed + to be emitted. + </tp:docstring> + <tp:added version="0.17.10">Clients MAY assume that if the + SelfHandle property exists, this signal will be emitted when + necessary.</tp:added> + + <arg type="u" tp:type="Contact_Handle" name="Self_Handle"> + <tp:docstring> + The new value of the SelfHandle property. + </tp:docstring> + </arg> + </signal> + + <property name="SelfHandle" tp:name-for-bindings="Self_Handle" + type="u" tp:type="Contact_Handle" access="read"> + <tp:docstring> + The handle which represents the user on this connection, which will + remain valid for the lifetime of this connection, or until a change + in the user's identifier is signalled by the SelfHandleChanged signal. + If the connection is not yet in the CONNECTED state, the value of + this property MAY be zero. + </tp:docstring> + <tp:added version="0.17.10">For compatibility with older + versions, clients should fall back to calling the GetSelfHandle + method.</tp:added> + </property> + <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle"> <arg direction="out" type="u" tp:type="Contact_Handle"> <tp:docstring> - An integer handle representing the user + The value of the SelfHandle property </tp:docstring> </arg> <tp:docstring> - Get the handle which represents the user on this connection, which will - remain valid for the lifetime of this connection, or until a change - in the user's identifier is signalled by the Renamed signal on the - Renaming interface (if present). + Returns the value of the SelfHandle property. Change notification + is via the SelfHandleChanged signal. </tp:docstring> + <tp:deprecated version="0.17.10">Use GetAll to get the + SelfHandle property (and all other Connection properties) + instead.</tp:deprecated> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -277,15 +310,13 @@ USA.</p> <p>If true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the RequestChannel method), so no other handler should be - launched.</p> + launched. Clients MAY assume that channels where this is true + were created by a user request.</p> <p>If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself - (a typical use-case is an address-book viewer that does not itself - implement chat or VoIP functionality, starting a channel that - will be handled by the same user interface that would handle - incoming channels).</p> + (this usage is deprecated).</p> <p>Clients MUST NOT assume that only incoming channels will have this flag set to false.</p> @@ -362,9 +393,32 @@ USA.</p> <arg direction="in" name="Suppress_Handler" type="b"> <tp:docstring> - If true, the requesting client intends to take responsibility for - displaying the channel to the user, so no other handler needs to - be launched + <p>Clients SHOULD always set this to true.</p> + + <tp:rationale> + <p>The historical meaning was that clients that did not + intend to take responsibility for displaying the channel to + the user could set this to FALSE, in which case the channel + dispatcher would launch an appropriate channel handler.</p> + + <p>However, clients whose functionality relies on having a + working channel dispatcher should obtain that functionality by + calling methods on the channel dispatcher, so that they will + get an appropriate error if the channel dispatcher is missing + or not working.</p> + + <p>The channel dispatcher itself should set this to true too, + so that it will ignore the + <tp:member-ref>NewChannel</tp:member-ref> signal that results + from the creation of the channel. It can then dispatch the + channel returned from this method to an + appropriate handler.</p> + + <p>So, there is no sensible use-case for setting this to false, + and setting it to false can result in unhandled channels (in + the case where clients assume that a channel dispatcher is + present, but it isn't).</p> + </tp:rationale> </tp:docstring> </arg> @@ -647,19 +701,51 @@ USA.</p> </signal> <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 - receive channels of differing types (such as text channels or streaming - media channels) which are used to carry out further communication.</p> + <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 + receive channels of differing types (such as text channels or streaming + media channels) which are used to carry out further communication.</p> + + <p>In order to allow Connection objects to be discovered by new clients, + the object path and well-known bus name MUST be of the form + <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code> + and + <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code> + where:</p> + + <ul> + <li><em>cmname</em> is the same + <tp:type>Connection_Manager_Name</tp:type> that appears + in the connection manager's object path and well-known bus name</li> + <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in + <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>, + but with "-" replaced with "_" to get a valid + object path/bus name</li> + <li><em>account</em> is some non-empty sequence of ASCII letters, + digits and underscores not starting with a digit</li> + </ul> + + <p><em>account</em> SHOULD be formed such that any valid distinct + connection instance on this protocol has a distinct name. This + might be formed by including the server name followed by the user + name (escaped via some suitable mechanism like telepathy-glib's + tp_escape_as_identifier() function to preserve uniqueness); on + protocols where connecting multiple times is permissable, a + per-connection identifier might be necessary to ensure + uniqueness.</p> + + <p>Clients MAY parse the object path to determine the connection + manager name and the protocol, but MUST NOT attempt to parse the + <em>account</em> part. Connection managers MAY use any unique string + for this part.</p> <p>As well as the methods and signatures below, arbitrary interfaces may be provided by the Connection object to represent extra connection-wide functionality, such as the Connection.Interface.Presence for receiving and reporting presence information, and Connection.Interface.Aliasing for connections where contacts may set and change an alias for themselves. - These interfaces can be discovered using GetInterfaces after the - connection, has been established and must not change subsequently at - runtime.</p> + These interfaces can be discovered using the + <tp:member-ref>GetInterfaces</tp:member-ref> method.</p> <p>Contacts, rooms, and server-stored lists (such as subscribed contacts, block lists, or allow lists) on a service are all represented by @@ -682,6 +768,13 @@ USA.</p> keep handles from being released with HoldHandles, and notify that they are no longer storing handles with ReleaseHandles.</p> </tp:docstring> + + <tp:changed version="0.17.10">Previously, the account part of + Connection bus names/object paths was allowed to have more than one + component (i.e. contain dots or slashes), resulting in Connection + bus names and object paths with more than 7 components. We now restrict + Connection bus names/object paths to have exactly 7 + components.</tp:changed> </interface> </node> <!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Aliasing.xml b/qt4/spec/Connection_Interface_Aliasing.xml index 15c4a657f..ee14fa70f 100644 --- a/qt4/spec/Connection_Interface_Aliasing.xml +++ b/qt4/spec/Connection_Interface_Aliasing.xml @@ -103,6 +103,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> </tp:possible-errors> </method> + <method name="GetAliases" tp:name-for-bindings="Get_Aliases"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of handles representing contacts + </tp:docstring> + </arg> + <arg direction="out" type="a{us}" tp:type="Alias_Map"> + <tp:docstring> + A dictionary mapping contact handles to aliases + </tp:docstring> + </arg> + <tp:docstring> + Request the value of several contacts' aliases at once. This SHOULD + only return cached aliases, falling back on the handle name if none is + present. Also if there was no cached alias, a request SHOULD be started + of which the result is later signalled by + <tp:member-ref>AliasesChanged</tp:member-ref>. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + </tp:possible-errors> + </method> <method name="SetAliases" tp:name-for-bindings="Set_Aliases"> <arg direction="in" name="Aliases" type="a{us}" tp:type="Alias_Map"> <tp:docstring> diff --git a/qt4/spec/Connection_Interface_Avatars.xml b/qt4/spec/Connection_Interface_Avatars.xml index 018f80ec9..76b85f3be 100644 --- a/qt4/spec/Connection_Interface_Avatars.xml +++ b/qt4/spec/Connection_Interface_Avatars.xml @@ -156,10 +156,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <tp:docstring> Get the unique tokens for the given contacts' avatars. These tokens can be persisted across connections, and should be used by the client - to check whether the avatars have been updated. A CM must always have - the tokens for the self handle if one is set (even if it is set to no - avatar). Otherwise, only tokens that are already known are returned. An - empty token means the given contact has no avatar. + to check whether the avatars have been updated. For handles other than + the self handle, only tokens that are already known are returned; an + empty token means the given contact has no avatar. However, a CM must + always have the tokens for the self handle if one is set (even if it is + set to no avatar). On protocols where the avatar does not persist + between connections, a CM should omit the self handle from the returned + map until an avatar is explicitly set or cleared. </tp:docstring> <tp:possible-errors> <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> @@ -284,8 +287,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ the avatar is persistent, but on others it is transferred via a peer to peer mechanism, so needs to be set every connection. Hence, on every connection, clients should inspect the avatar token of the connection's - self handle, and set the avatar if it is an empty string (and may - optionally replace it if the token corresponds to a different avatar).</p> + self handle using GetKnownAvatarTokens; if the self handle is not in the + returned map, the client should re-set the avatar. If the self handle's + avatar token is known, but the avatar has been changed locally since the + last connection, the client should upload the new avatar; if the avatar has + not changed locally, then the client should download the avatar from the + server if its token differs from the that of the local avatar.</p> <p>To remove the published avatar on protocols which have persistent avatars, a client should use the ClearAvatar method. This method can safely be used diff --git a/qt4/spec/Connection_Interface_Capabilities.xml b/qt4/spec/Connection_Interface_Capabilities.xml index 88d16840c..d57793479 100644 --- a/qt4/spec/Connection_Interface_Capabilities.xml +++ b/qt4/spec/Connection_Interface_Capabilities.xml @@ -47,7 +47,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ to them which are implemented by available client processes.</p> </tp:docstring> - <tp:changed version="0.17.UNRELEASED">Previously, this interface + <tp:changed version="0.17.8">Previously, this interface also expressed capabilities of the connection itself, indicating what sorts of channels could be requested (for instance, the ability to open chatroom lists or chatrooms). However, this was never very diff --git a/qt4/spec/Connection_Interface_Contacts.xml b/qt4/spec/Connection_Interface_Contacts.xml index ecd5a7557..590c33959 100644 --- a/qt4/spec/Connection_Interface_Contacts.xml +++ b/qt4/spec/Connection_Interface_Contacts.xml @@ -1,5 +1,5 @@ <?xml version="1.0" ?> -<node name="/Connection_Interface_Contact_Attributes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> +<node name="/Connection_Interface_Contacts" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright> <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright> <tp:copyright> Copyright (C) 2006 INdT </tp:copyright> @@ -18,9 +18,9 @@ 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.Contacts.DRAFT" - tp:causes-havoc="experimental"> + <interface name="org.freedesktop.Telepathy.Connection.Interface.Contacts"> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.9"/> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>This interface allows many attributes of many contacts to be @@ -30,33 +30,34 @@ (<tp:type>Contact_Attribute</tp:type>), which is namespaced by the D-Bus interface which defines it.</p> - <p>While this interface is a draft, an initial set of contact - attributes is defined here. The definitions of these attributes - will be moved to the spec for individual interfaces when this interface - is finalized.</p> + <p>An initial set of contact attributes is defined here:</p> <dl> <dt>org.freedesktop.Telepathy.Connection/contact-id (type s)</dt> - <dd>The same string that would be returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> + <dd>The same string that would be returned by + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref> (always present in the result) </dd> <dt>org.freedesktop.Telepathy.Connection.Interface.Aliasing/alias (type s)</dt> - <dd>The contact's alias as defined by the <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface">Aliasing</tp:dbus-ref> - interface (always present with some value, possibly the + <dd>The same string that would be returned by <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">GetAliases</tp:dbus-ref> + (always present with some value, possibly the same as Connection/contact-id, if information from the Aliasing interface was requested) </dd> <dt>org.freedesktop.Telepathy.Connection.Interface.Avatars/token - (type s</dt> + (type s)</dt> <dd>The same string that would be returned by <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetAvatarTokens</tp:dbus-ref> + namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref> (omitted from the result if the contact's avatar token is not known, present as an empty string if the contact is known not to have - an avatar) + an avatar). Unlike in the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface.Avatars">GetKnownAvatarTokens</tp:dbus-ref> + method, the avatar tokens for the self handle aren't required to be + present. This attribute should not be used to determine whether or + not the Avatar needs to be set. </dd> <dt>org.freedesktop.Telepathy.Connection.Interface.SimplePresence/presence (type (uss), <tp:type>Simple_Presence</tp:type>)</dt> @@ -109,7 +110,7 @@ </tp:mapping> <tp:mapping name="Contact_Attributes_Map"> - <tp:docstring>Mapping returned by InspectContacts, representing a + <tp:docstring>Mapping returned by GetContactAttributes, representing a collection of Contacts and their requested attributes.</tp:docstring> <tp:member type="u" tp:type="Contact_Handle" name="Contact"> @@ -126,16 +127,18 @@ </tp:member> </tp:mapping> - <property name="InspectableInterfaces" access="read" type="as" - tp:type="DBus_Interface[]" tp:name-for-bindings="Inspectable_Interfaces"> + <property name="ContactAttributeInterfaces" access="read" type="as" + tp:type="DBus_Interface[]" + tp:name-for-bindings="Contact_Attribute_Interfaces"> <tp:docstring> A list of D-Bus interfaces for which - <tp:member-ref>InspectContacts</tp:member-ref> is expected to work. + <tp:member-ref>GetContactAttributes</tp:member-ref> is expected to work. This cannot change during the lifetime of the Connection. </tp:docstring> </property> - <method name="InspectContacts" tp:name-for-bindings="Inspect_Contacts"> + <method name="GetContactAttributes" + tp:name-for-bindings="Get_Contact_Attributes"> <tp:docstring> Return any number of contact attributes for the given handles. </tp:docstring> @@ -156,7 +159,8 @@ <p>It is an error to request interfaces that are not supported by this Connection (i.e. mentioned in the - <tp:member-ref>InspectableInterfaces</tp:member-ref> property).</p> + <tp:member-ref>ContactAttributeInterfaces</tp:member-ref> + property).</p> <tp:rationale> <p>This makes it possible to distinguish between interfaces for @@ -215,7 +219,7 @@ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> <tp:docstring> One of the requested interfaces is not supported (mentioned in - <tp:member-ref>InspectableInterfaces</tp:member-ref>). + <tp:member-ref>ContactAttributeInterfaces</tp:member-ref>). </tp:docstring> </tp:error> </tp:possible-errors> diff --git a/qt4/spec/Connection_Interface_Presence.xml b/qt4/spec/Connection_Interface_Presence.xml index bc750c1b8..58ad34e6c 100644 --- a/qt4/spec/Connection_Interface_Presence.xml +++ b/qt4/spec/Connection_Interface_Presence.xml @@ -368,14 +368,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Unknown" value="7"> - <tp:added version="0.17.UNRELEASED"/> + <tp:added version="0.17.8"/> <tp:docstring> Unknown, unable to determine presence for this contact, for example if the protocol only allows presence of subscribed contacts. </tp:docstring> </tp:enumvalue> <tp:enumvalue suffix="Error" value="8"> - <tp:added version="0.17.UNRELEASED"/> + <tp:added version="0.17.8"/> <tp:docstring> Error, an error occurred while trying to determine presence. The message, if set, is an error from the server. diff --git a/qt4/spec/Connection_Interface_Renaming.xml b/qt4/spec/Connection_Interface_Renaming.xml index 840128847..998118468 100644 --- a/qt4/spec/Connection_Interface_Renaming.xml +++ b/qt4/spec/Connection_Interface_Renaming.xml @@ -21,7 +21,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <interface name="org.freedesktop.Telepathy.Connection.Interface.Renaming" tp:causes-havoc='not well-tested'> <tp:requires interface="org.freedesktop.Telepathy.Connection"/> - <signal name="Renamed"> + <signal name="Renamed" tp:name-for-bindings="Renamed"> <arg name="Original" type="u" tp:type="Contact_Handle"> <tp:docstring> The handle of the original identifier diff --git a/qt4/spec/Connection_Interface_Requests.xml b/qt4/spec/Connection_Interface_Requests.xml new file mode 100644 index 000000000..264a3b5df --- /dev/null +++ b/qt4/spec/Connection_Interface_Requests.xml @@ -0,0 +1,557 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Requests" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" + > + <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface name="org.freedesktop.Telepathy.Connection.Interface.Requests"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.11">(as stable API)</tp:added> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An enhanced version of the Telepathy connection interface, which can + represent bundles of channels that should be dispatched together, and + does not assume any particular properties by which channels are + uniquely identifiable.</p> + </tp:docstring> + + <tp:struct name="Channel_Details" array-name="Channel_Details_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + + <tp:docstring> + Enough details of a channel that clients can work out how to dispatch + or handle it. + </tp:docstring> + + <tp:member name="Channel" type="o"> + <tp:docstring> + The object path of the channel. + </tp:docstring> + </tp:member> + + <tp:member name="Properties" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel.</p> + + <p>Connection managers MUST NOT include properties in this mapping + if their values can change. Clients MUST ignore properties + that appear in this mapping if their values can change.</p> + + <tp:rationale> + <p>If properties that could change were included, the following + race condition would be likely to exist in some cases:</p> + + <ul> + <li>NewChannels or Get("Channels") includes a property P with + value V1</li> + <li>Client creates a proxy object for the channel</li> + <li>The value of P changes to V2</li> + <li>Client connects to PChanged signal</li> + <li>Client should call Get("P") or GetAll here, to avoid the + race, but client's author has forgotten to do so</li> + <li>Proxy object thinks P == V1, but actually P == V2</li> + </ul> + + <p>We've taken the opportunity to make the API encourage the + client author to get it right. Where possible, we intend that + properties whose value will be used in channel dispatching + or other "early" processing will be defined so that they are + immutable (can never change).</p> + </tp:rationale> + + <p>Each dictionary MUST contain the keys + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>, + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref> + and + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.Requested</tp:dbus-ref>. + </p> + + <tp:rationale> + <p>We expect these to be crucial to the channel-dispatching + process.</p> + </tp:rationale> + </tp:docstring> + </tp:member> + </tp:struct> + + <method name="CreateChannel" tp:name-for-bindings="Create_Channel"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:changed version="0.17.14">It is now guaranteed that + CreateChannel returns the channel before NewChannels announces it + (the reverse was previously guaranteed).</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that an entirely new channel is created.</p> + + <tp:rationale> + <p>There is deliberately no flag corresponding to the + suppress_handler argument to + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>, + because passing a FALSE value for that argument is deprecated. + Requests made using this interface always behave as though + suppress_handler was TRUE.</p> + </tp:rationale> + + </tp:docstring> + + <arg direction="in" name="Request" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties. Some properties + are defined such that only an exact match makes sense, and + connection managers MUST NOT satisfy a request with a channel + where that property does not match; some properties are defined + such that the connection manager MAY treat the request as merely + a hint, and make a best-effort attempt to satisfy it. This is + documented separately for each property.</p> + + <p>If this dictionary contains a property whose semantics + are not known to the connection manager, this method MUST fail + without side-effects (in particular it must not create a new + channel).</p> + + <tp:rationale> + <p>This is necessary if we want to be able to invent properties + in future that, when used in a request, are hard requirements + rather than just hints. A connection manager that did not know + the semantics of those properties could incorrectly return a + new channel that did not satisfy the requirements.</p> + </tp:rationale> + + <p>The connection manager MUST NOT respond successfully, + and SHOULD NOT create a new channel or cause any other + side-effects, unless it can create a new channel that satisfies + the client's requirements.</p> + + <p>Properties that will be set by this argument need not have write + access after the channel has been created - indeed, it is + expected that most will be read-only.</p> + </tp:docstring> + </arg> + + <arg name="Channel" direction="out" type="o"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The Channel object, which MUST NOT be signalled with + <tp:member-ref>NewChannels</tp:member-ref> until after this method + returns.</p> + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" direction="out" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel that was produced, equivalent to + the properties in <tp:type>Channel_Details</tp:type>. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + <tp:type>Channel_Details</tp:type>.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + An invalid handle was requested as the value of a property whose + value is a handle (like + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like TargetID). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The requested channel cannot be created, but in + principle, a similar request might succeed in future. + For instance, this might be because:</p> + + <ul> + <li>the requested contact is using a client + that lacks a particular feature</li> + <li>a channel matching the request already exists and the + protocol requires that only one such channel can exist at a + time</li> + <li>a channel matching the request has already been requested + (by a previous call to CreateChannel, + <tp:member-ref>EnsureChannel</tp:member-ref>, + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref> + or similar) and the protocol requires that only one such + channel can exist at a time</li> + </ul> + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + </tp:possible-errors> + </method> + + <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel"> + <tp:added version="0.17.12"/> + <tp:changed version="0.17.14">It is now guaranteed that if + the channel was created by this call to EnsureChannel, it's returned + before NewChannels announces it (the reverse was previously + guaranteed).</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that channels are ensured to exist.</p> + + <tp:rationale> + <p>The connection manager is in the best position to determine which + existing channels could satisfy which requests.</p> + </tp:rationale> + + </tp:docstring> + + <arg direction="in" name="Request" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A dictionary containing desirable properties, with the same + semantics as the corresponding parameter to + <tp:member-ref>CreateChannel</tp:member-ref>.</p> + </tp:docstring> + </arg> + + <arg name="Yours" direction="out" type="b"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>If false, the caller of EnsureChannel MUST assume that some + other process is handling this channel; if true, the caller of + EnsureChannel SHOULD handle it themselves or delegate it to another + client.</p> + + <p>If the creation of a channel makes several calls to EnsureChannel + (and no other requests) successful, exactly one of those calls MUST + return a true value for this argument.</p> + + <p>If the creation of a channel makes other requests successful, + the value returned for this argument MUST be such that exactly + one of the clients making requests ends up responsible for the + channel. In particular, if CreateChannel returns a channel + <em>C</em>, any EnsureChannel calls that also return <em>C</em> + MUST return a false value for this argument.</p> + </tp:docstring> + </arg> + + <arg name="Channel" direction="out" type="o"> + <tp:docstring> + The Channel object. If it was created as a result of this method + call, it MUST NOT be signalled by + <tp:member-ref>NewChannels</tp:member-ref> until after this method + returns. + + <tp:rationale> + <p>This allows the requester to alter its handling of + NewChannels by knowing whether one of the channels satisfied + a request it made.</p> + </tp:rationale> + </tp:docstring> + </arg> + + <arg name="Properties" direction="out" type="a{sv}" + tp:type="Qualified_Property_Value_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties of the channel that was produced, equivalent to + the properties in <tp:type>Channel_Details</tp:type>. + Connection managers MUST NOT include properties here whose + values can change, for the same reasons as in + <tp:type>Channel_Details</tp:type>.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The channel request was one that can never succeed, + such as requesting an unsupported channel type, or requesting + a channel type which this connection manager does not support with + the given target handle type. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + An invalid handle was requested as the value of a property whose + value is a handle (like + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.TargetHandle</tp:dbus-ref>), + or a syntactically invalid identifier was requested as the value + of a property whose value is the string corresponding to a handle + (like TargetID). + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel cannot be created, but in + principle, a similar request might succeed in future. For instance, + this might be because the requested contact is using a client + that lacks a particular feature. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/> + <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/> + </tp:possible-errors> + </method> + + <signal name="NewChannels" tp:name-for-bindings="New_Channels"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:changed version="0.17.14">Added a guarantee of ordering + relative to NewChannel</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>New channels have been created. The connection manager SHOULD emit + a single signal for any group of closely related channels that are + created at the same time, so that the channel dispatcher can try to + dispatch them to a handler as a unit.</p> + + <p>In particular, if additional channels are created as a side-effect + of a call to <tp:member-ref>CreateChannel</tp:member-ref>, + these channels SHOULD appear in the same NewChannels signal as + the channel that satisfies the request.</p> + + <tp:rationale> + <p>Joining a MUC Tube in XMPP requires joining the corresponding + MUC (chatroom), so a Text channel can be created as a + side-effect.</p> + </tp:rationale> + + <p>Every time NewChannels is emitted, it MUST be followed by + a <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref> + signal for each channel.</p> + + <tp:rationale> + <p>The double signal emission is for the benefit of older Telepathy + clients, which won't be listening for NewChannels.</p> + + <p>The more informative NewChannels signal comes first so that + clients that did not examine the connection to find + out whether Requests is supported will see the more informative + signal for each channel first, and then ignore the less + informative signal because it announces a new channel of which + they are already aware.</p> + </tp:rationale> + </tp:docstring> + + <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"> + <tp:docstring> + The channels and their details. All channels that are signalled + together like this MUST have the same + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> + property, which may + either refer to an existing bundle, or establish a new bundle. + </tp:docstring> + </arg> + </signal> + + <property name="Channels" tp:name-for-bindings="Channels" + type="a(oa{sv})" access="read" tp:type="Channel_Details[]"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring> + A list of all the channels which currently exist on this connection. + Change notification is via the + <tp:member-ref>NewChannels</tp:member-ref> and + <tp:member-ref>ChannelClosed</tp:member-ref> signals. + </tp:docstring> + </property> + + <signal name="ChannelClosed" tp:name-for-bindings="Channel_Closed"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring> + Emitted when a channel is closed and hence disappears from the + Channels property. + + <tp:rationale> + This is redundant with the Close signal on the channel itself, but + it does provide full change notification for the Channels property. + </tp:rationale> + </tp:docstring> + + <arg name="Removed" type="o"> + <tp:docstring> + The channel which has been removed from the Channels property + </tp:docstring> + </arg> + </signal> + + <tp:mapping name="Channel_Class" array-name="Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Mapping representing a class of channels that can be requested + from a connection manager, can be handled by a user interface, + are supported by a contact, etc.</p> + + <p>Classes of channel are identified by the fixed values of + a subset of their properties.</p> + + <p>Channel classes SHOULD always include the keys + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref> + and + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>. + </p> + </tp:docstring> + + <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> + <tp:docstring> + A D-Bus interface name, followed by a dot and a D-Bus property name. + </tp:docstring> + </tp:member> + + <tp:member type="v" name="Value"> + <tp:docstring> + The value of the property. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:struct name="Requestable_Channel_Class" + array-name="Requestable_Channel_Class_List"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Structure representing a class of channels that can be requested, + identified by a set of properties that identify that class of + channel.</p> + + <tp:rationale> + <p>This will often just be the channel type and the handle type, + but can include other properties of the channel - for instance, + encrypted channels might require properties that + unencrypted channels do not, like an encryption key.</p> + </tp:rationale> + + <p>In some cases, these classes of channel may overlap, in the sense + that one class fixes all the properties that another class does, + plus some more properties.</p> + + <tp:rationale> + <p>For older clients to still be able to understand how to request + channels in the presence of a hypothetical "encryption" interface, + we'd need to represent it like this:</p> + + <ul> + <li>class 1: ChannelType = Text, TargetHandleType = CONTACT</li> + <li>class 2: Channel.ChannelType = Text, + Channel.TargetHandleType = CONTACT, + Encryption.Encrypted = TRUE</li> + </ul> + </tp:rationale> + </tp:docstring> + + <tp:member name="Fixed_Properties" type="a{sv}" + tp:type="Channel_Class"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The property values that identify this requestable channel class. + These properties MUST be included in requests for a channel of this + class, and MUST take these values.</p> + + <p>Clients that do not understand the semantics of all the + Fixed_Properties MUST NOT request channels of this class, since + they would be unable to avoid making an incorrect request.</p> + + <p>This implies that connection managers wishing to make channels + available to old or minimal clients SHOULD have a channel class + with the minimum number of Fixed_Properties, and MAY additionally + have channel classes with extra Fixed_Properties.</p> + </tp:docstring> + </tp:member> + + <tp:member name="Allowed_Properties" type="as" + tp:type="DBus_Qualified_Member[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Properties that MAY be set when requesting a channel of this + channel type and handle type.</p> + + <p>This array MUST NOT include properties that are in the + Fixed_Properties mapping.</p> + + <p>Properties in this array may either be required or optional, + according to their documented semantics.</p> + + <tp:rationale> + <p>For instance, if + TargetHandleType takes a value that is not Handle_Type_None, + one or the other of TargetHandle and TargetID is required. + Clients are expected to understand the documented relationship + between the properties, so we do not have separate arrays + of required and optional properties.</p> + </tp:rationale> + + <p>If this array contains the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.FUTURE">Bundle</tp:dbus-ref> + property, then this class of channel can be combined with other + channels with that property in a request, or added to an existing + bundle. If not, this signifies that the connection manager is + unable to mark channels of this class as part of a bundle - this + means that to the remote contact they are likely to be + indistinguishable from channels requested separately.</p> + </tp:docstring> + </tp:member> + </tp:struct> + + <property name="RequestableChannelClasses" access="read" + type="a(a{sv}as)" tp:type="Requestable_Channel_Class[]" + tp:name-for-bindings="Requestable_Channel_Classes"> + <tp:added version="0.17.11">(as stable API)</tp:added> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The classes of channel that are expected to be available on this + connection, i.e. those for which + <tp:member-ref>CreateChannel</tp:member-ref> can reasonably + be expected to succeed. User interfaces can use this information + to show or hide UI components.</p> + + <p>This property cannot change after the connection has gone to + state Connection_Status_Connected, so there is no change + notification (if the connection has context-dependent capabilities, + it SHOULD advertise support for all classes of channel that it might + support during its lifetime). Before this state has been reached, + the value of this property is undefined.</p> + + <tp:rationale> + <p>This is not on an optional interface, because connection + managers can always offer some sort of clue about the channel + classes they expect to support (at worst, they can announce + support for everything for which they have code).</p> + </tp:rationale> + </tp:docstring> + </property> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/qt4/spec/Connection_Interface_Simple_Presence.xml b/qt4/spec/Connection_Interface_Simple_Presence.xml index 8e38f48e5..92614e0a3 100644 --- a/qt4/spec/Connection_Interface_Simple_Presence.xml +++ b/qt4/spec/Connection_Interface_Simple_Presence.xml @@ -55,8 +55,8 @@ translation of "Available" from a menu. It is more informative for his English-speaking colleagues to see the English translation of "Available" (as localized - by their own clients) than to see the Welsh version (which they - don't understand anyway). + by their own clients) than to see "Ar Gael" (which they don't + understand anyway). </tp:rationale> </tp:docstring> </tp:member> @@ -228,7 +228,7 @@ </tp:possible-errors> </method> - <property name="Statuses" access="read" + <property name="Statuses" tp:name-for-bindings="Statuses" access="read" type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A dictionary where the keys are the presence statuses that the user diff --git a/qt4/spec/Connection_Manager.xml b/qt4/spec/Connection_Manager.xml index dc96e248a..e3cfa8d30 100644 --- a/qt4/spec/Connection_Manager.xml +++ b/qt4/spec/Connection_Manager.xml @@ -220,39 +220,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </arg> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Request a Connection object representing a given account on a given - protocol with the given parameters. The method returns the bus name - and the object path where the new Connection object can be found, which - should have the status of Connection_Status_Disconnected, to allow - signal handlers to be attached before connecting is started with the - Connect method.</p> - - <p>In order to allow Connection objects to be discovered by new clients, - the object path and well-known bus name must be of the form - <code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code> - and - <code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code> - where:</p> - - <ul> - <li><em>cmname</em> is the same connection manager name that appears - in the connection manager's object path and well-known bus name</li> - <li><em>proto</em> is the protocol name as seen in - ListProtocols, but with "-" replaced with "_" to get a valid - object path/bus name</li> - <li><em>account</em> SHOULD be a series of elements formed such that - any valid distinct connection instance on this protocol has a - distinct name; this might be formed by including the server name - followed by the user name (escaped via some suitable mechanism like - telepathy-glib's tp_escape_as_identifier() function to preserve - uniqueness), or on protocols where connecting multiple times - is permissable, a per-connection identifier might be necessary to - ensure uniqueness</li> - </ul> - - <p>Clients MUST NOT attempt to parse the <em>account</em> part of the - bus name. Connection managers MAY use any unique string for this - part.</p> + <p>Request a + <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> + object representing a given account on a given + protocol with the given parameters. The method returns the bus name + and the object path where the new Connection object can be found, + which should have the status of Connection_Status_Disconnected, to + allow signal handlers to be attached before connecting is started + with the + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref> + method.</p> <p>The parameters which must and may be provided in the parameters dictionary can be discovered with the GetParameters method. These @@ -320,7 +297,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:possible-errors> </method> - <property name="Interfaces" type="as" access="read"> + <property name="Interfaces" tp:name-for-bindings="Interfaces" + type="as" access="read"> <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>A list of the extra interfaces provided by this connection manager (i.e. extra functionality that can be provided even before a @@ -334,7 +312,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ this property fails, clients SHOULD assume that its value is an empty list.</p> </tp:docstring> - <tp:added version="0.17.UNRELEASED"/> + <tp:added version="0.17.8"/> </property> <!-- FIXME: One thing we could perhaps use Interfaces for would be a diff --git a/qt4/spec/Media_Session_Handler.xml b/qt4/spec/Media_Session_Handler.xml index f4dcf929a..a6cf5192f 100644 --- a/qt4/spec/Media_Session_Handler.xml +++ b/qt4/spec/Media_Session_Handler.xml @@ -19,7 +19,7 @@ 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.Media.SessionHandler"> - <method name="Error"> + <method name="Error" tp:name-for-bindings="Error"> <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error"/> <arg direction="in" name="Message" type="s"/> @@ -60,7 +60,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ session. </tp:docstring> </signal> - <method name="Ready"> + <method name="Ready" tp:name-for-bindings="Ready"> <tp:docstring> Inform the connection manager that a client is ready to handle this session handler (i.e. that it has connected to the diff --git a/qt4/spec/Media_Stream_Handler.xml b/qt4/spec/Media_Stream_Handler.xml index 1d45f9e2b..e47647971 100644 --- a/qt4/spec/Media_Stream_Handler.xml +++ b/qt4/spec/Media_Stream_Handler.xml @@ -71,7 +71,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ client of a new remote candidate. </tp:docstring> </signal> - <signal name="Close"> + <signal name="Close" tp:name-for-bindings="Close"> <tp:docstring> Signal emitted when the connection manager wishes the stream to be closed. @@ -83,7 +83,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ Inform the connection manager of the current codec choice. </tp:docstring> </method> - <method name="Error"> + <method name="Error" tp:name-for-bindings="Error"> <arg direction="in" name="Error_Code" type="u" tp:type="Media_Stream_Error"> <tp:docstring> ID of error, from the MediaStreamError enumeration @@ -184,7 +184,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:docstring> </tp:enumvalue> </tp:enum> - <method name="Ready"> + <method name="Ready" tp:name-for-bindings="Ready"> <arg direction="in" name="Codecs" type="a(usuuua{ss})" tp:type="Media_Stream_Handler_Codec[]"> <tp:docstring> diff --git a/qt4/spec/all.xml b/qt4/spec/all.xml index 586beb331..5eb421763 100644 --- a/qt4/spec/all.xml +++ b/qt4/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.8.1</tp:version> +<tp:version>0.17.14.1</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -31,21 +31,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Connection_Interface_Avatars.xml"/> <xi:include href="Connection_Interface_Capabilities.xml"/> <xi:include href="Connection_Interface_Contacts.xml"/> -<!-- Never implemented, is a terrible API -<xi:include href="Connection_Interface_Contact_Info.xml"/> --> -<!-- Never implemented, insufficient (needs conditions) -<xi:include href="Connection_Interface_Forwarding.xml"/> --> <xi:include href="Connection_Interface_Simple_Presence.xml"/> <xi:include href="Connection_Interface_Presence.xml"/> -<!-- Never implemented, vague -<xi:include href="Connection_Interface_Privacy.xml"/> --> <xi:include href="Connection_Interface_Renaming.xml"/> +<xi:include href="Connection_Interface_Requests.xml"/> + +<xi:include href="Channel_Bundle.xml"/> <xi:include href="Channel.xml"/> <xi:include href="Channel_Future.xml"/> <xi:include href="Channel_Type_Contact_List.xml"/> -<!-- Never implemented, can't be implemented with current dbus-glib, vague -<xi:include href="Channel_Type_Contact_Search.xml"/> --> <xi:include href="Channel_Type_Streamed_Media.xml"/> <xi:include href="Channel_Type_Room_List.xml"/> <xi:include href="Channel_Type_Text.xml"/> @@ -54,14 +49,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Channel_Interface_Call_Merging.xml"/> <xi:include href="Channel_Interface_Call_State.xml"/> <xi:include href="Channel_Interface_Chat_State.xml"/> -<xi:include href="Channel_Interface_Delivery_Reporting.xml"/> +<xi:include href="Channel_Interface_Destroyable.xml"/> <xi:include href="Channel_Interface_DTMF.xml"/> <xi:include href="Channel_Interface_Group.xml"/> <xi:include href="Channel_Interface_Hold.xml"/> <xi:include href="Channel_Interface_HTML.xml"/> <xi:include href="Channel_Interface_Password.xml"/> -<!-- Causes havoc, never implemented, unclear requirements -<xi:include href="Channel_Interface_Transfer.xml"/> --> <xi:include href="Channel_Interface_Media_Signalling.xml"/> <xi:include href="Channel_Interface_Messages.xml"/> @@ -72,10 +65,32 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <xi:include href="Account_Manager.xml"/> <xi:include href="Account.xml"/> +<xi:include href="Account_Interface_Avatar.xml"/> + +<xi:include href="Channel_Dispatcher.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="Client.xml"/> +<xi:include href="Client_Observer.xml"/> +<xi:include href="Client_Approver.xml"/> +<xi:include href="Client_Handler.xml"/> <xi:include href="Channel_Handler.xml"/> <xi:include href="errors.xml"/> <xi:include href="generic-types.xml"/> +<!-- Never implemented, is a terrible API +<xi:include href="Connection_Interface_Contact_Info.xml"/> --> +<!-- Never implemented, insufficient (needs conditions) +<xi:include href="Connection_Interface_Forwarding.xml"/> --> +<!-- Never implemented, vague +<xi:include href="Connection_Interface_Privacy.xml"/> --> +<!-- Never implemented, can't be implemented with current dbus-glib, vague +<xi:include href="Channel_Type_Contact_Search.xml"/> --> +<!-- Causes havoc, never implemented, unclear requirements +<xi:include href="Channel_Interface_Transfer.xml"/> --> + </tp:spec> diff --git a/qt4/spec/errors.xml b/qt4/spec/errors.xml index 81ab440e7..679e3f4e2 100644 --- a/qt4/spec/errors.xml +++ b/qt4/spec/errors.xml @@ -1,5 +1,8 @@ <?xml version="1.0" ?> <tp:errors xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" namespace="org.freedesktop.Telepathy.Error"> + <!-- Don't re-order these errors until fd.o #17588 is fixed, or you will + break telepathy-glib's ABI. + --> <tp:error name="Network Error"> <tp:docstring> Raised when there is an error reading from or writing to the network. @@ -60,8 +63,22 @@ </tp:docstring> </tp:error> - <tp:copyright>Copyright (C) 2005, 2006, 2007 Collabora Limited</tp:copyright> - <tp:copyright>Copyright (C) 2005, 2006, 2007 Nokia Corporation</tp:copyright> + <tp:error name="Not Yours"> + <tp:docstring> + The requested channel or other resource already exists, and another + client is responsible for it + </tp:docstring> + </tp:error> + + <tp:error name="Cancelled"> + <tp:docstring> + Raised by an ongoing request if it is cancelled by user request before + it has completed. + </tp:docstring> + </tp:error> + + <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> + <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> <tp:license xmlns="http://www.w3.org/1999/xhtml"> <p>This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public diff --git a/qt4/spec/generic-types.xml b/qt4/spec/generic-types.xml index c0a000d07..9d8501de9 100644 --- a/qt4/spec/generic-types.xml +++ b/qt4/spec/generic-types.xml @@ -2,7 +2,19 @@ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> <tp:simple-type name="Unix_Timestamp" type="u"> - <tp:docstring>An unsigned 32-bit integer representing time since 1970</tp:docstring> + <tp:docstring>An unsigned 32-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z)</tp:docstring> + </tp:simple-type> + + <tp:simple-type name="Unix_Timestamp64" type="t"> + <tp:docstring>An unsigned 64-bit integer representing time as the number + of seconds elapsed since the Unix epoch + (1970-01-01T00:00:00Z)</tp:docstring> + + <tp:rationale>The Text interface is the only user of Unix_Timestamp so + far, and we'd like to be Y2038 compatible in future + interfaces.</tp:rationale> </tp:simple-type> <tp:simple-type name="DBus_Bus_Name" type="s"> @@ -11,6 +23,11 @@ like ":1.123"</tp:docstring> </tp:simple-type> + <tp:simple-type name="DBus_Well_Known_Name" type="s"> + <tp:docstring>A string representing a D-Bus well-known + name like "org.freedesktop.Telepathy.MissionControl".</tp:docstring> + </tp:simple-type> + <tp:simple-type name="DBus_Unique_Name" type="s"> <tp:docstring>A string representing a D-Bus unique name, such as ":1.123"</tp:docstring> @@ -24,6 +41,12 @@ "org.freedesktop.DBus.Peer".</tp:docstring> </tp:simple-type> + <tp:simple-type name="DBus_Error_Name" type="s"> + <tp:docstring>An ASCII string representing a D-Bus error. This is + syntactically the same as a <tp:type>DBus_Interface</tp:type>, but the + meaning is different.</tp:docstring> + </tp:simple-type> + <tp:simple-type name="DBus_Signature" type="s"> <tp:docstring>A string representing a D-Bus signature (the 'g' type isn't used because of poor interoperability, particularly @@ -44,7 +67,8 @@ "org.freedesktop.DBus.Peer.Ping".</tp:docstring> </tp:simple-type> - <tp:mapping name="Qualified_Property_Value_Map"> + <tp:mapping name="Qualified_Property_Value_Map" + array-name="Qualified_Property_Value_Map_List"> <tp:docstring>A mapping from strings representing D-Bus properties (by their namespaced names) to their values.</tp:docstring> <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member"> |