diff options
| -rw-r--r-- | spec/Channel.xml | 87 | ||||
| -rw-r--r-- | spec/Channel_Bundle.xml | 48 | ||||
| -rw-r--r-- | spec/Channel_Future.xml | 86 | ||||
| -rw-r--r-- | spec/Connection.xml | 8 | ||||
| -rw-r--r-- | spec/Connection_Interface_Aliasing.xml | 2 | ||||
| -rw-r--r-- | spec/Connection_Interface_Avatars.xml | 19 | ||||
| -rw-r--r-- | spec/Connection_Interface_Contacts.xml | 8 | ||||
| -rw-r--r-- | spec/Connection_Interface_Requests.xml | 400 | ||||
| -rw-r--r-- | spec/all.xml | 5 |
9 files changed, 631 insertions, 32 deletions
diff --git a/spec/Channel.xml b/spec/Channel.xml index 61da13412..b9b8f3b78 100644 --- a/spec/Channel.xml +++ b/spec/Channel.xml @@ -35,6 +35,14 @@ 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> @@ -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> @@ -79,14 +92,84 @@ 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" 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: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> diff --git a/spec/Channel_Bundle.xml b/spec/Channel_Bundle.xml new file mode 100644 index 000000000..0b1a6c132 --- /dev/null +++ b/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" 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/spec/Channel_Future.xml b/spec/Channel_Future.xml index 09d116ff6..ad18879bc 100644 --- a/spec/Channel_Future.xml +++ b/spec/Channel_Future.xml @@ -42,16 +42,58 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </tp:rationale> </tp:docstring> - <property name="TargetID" type="s" access="read"> - <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). + <property name="Requested" type="b" access="read"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>True if this channel was created in response to 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.DRAFT.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> - See InitiatorID; the rationale is the same. + <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> @@ -85,8 +127,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <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> + <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> @@ -112,8 +155,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ </ul> </tp:rationale> - <p>It does not make sense for this property to be passed to the - RequestChannels method on Channel.Interface.Requests.</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="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 + <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle</tp:dbus-ref> + to which this channel belongs.</p> + + <p>A channel's Bundle property can never change.</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/spec/Connection.xml b/spec/Connection.xml index f5d914e07..4dac8d057 100644 --- a/spec/Connection.xml +++ b/spec/Connection.xml @@ -277,15 +277,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> diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index 5f3a7df17..5d6eb5396 100644 --- a/spec/Connection_Interface_Aliasing.xml +++ b/spec/Connection_Interface_Aliasing.xml @@ -118,7 +118,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ 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 signal by + of which the result is later signalled by <tp:member-ref>AliasesChanged</tp:member-ref>. </tp:docstring> <tp:possible-errors> diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml index 9395a6efd..53d31082f 100644 --- a/spec/Connection_Interface_Avatars.xml +++ b/spec/Connection_Interface_Avatars.xml @@ -154,10 +154,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"/> @@ -282,8 +285,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/spec/Connection_Interface_Contacts.xml b/spec/Connection_Interface_Contacts.xml index 327d80981..3f5b5ea57 100644 --- a/spec/Connection_Interface_Contacts.xml +++ b/spec/Connection_Interface_Contacts.xml @@ -20,6 +20,7 @@ </tp:license> <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 @@ -29,10 +30,7 @@ (<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 @@ -50,7 +48,7 @@ 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">GetKnownAvatarTokens</tp:dbus-ref> (omitted from the result if the contact's avatar token is not known, diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml new file mode 100644 index 000000000..ea1eeeb13 --- /dev/null +++ b/spec/Connection_Interface_Requests.xml @@ -0,0 +1,400 @@ +<?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.DRAFT" + tp:causes-havoc="experimental"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:added version="0.17.9"/> + + <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: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> + and + <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>. + </p> + <!-- FIXME: maybe also Requested, InitiatorHandle, + InitiatorID once they leave the FUTURE pseudo-interface --> + + <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:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that channels are 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> + The Channel object, which MUST already have been signalled with + <tp:member-ref>NewChannels</tp:member-ref> by the time this method + returns. + </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, or because a channel matching the + request already exists and the protocol requires that only one + such channel can exist at a time. + </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: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> + </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" type="a(oa{sv})" access="read" + tp:type="Channel_Details[]"> + <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: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"> + <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: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: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/spec/all.xml b/spec/all.xml index 586beb331..eda2e0103 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude"> <tp:title>Telepathy D-Bus Interface Specification</tp:title> -<tp:version>0.17.8.1</tp:version> +<tp:version>0.17.9</tp:version> <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright> <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright> @@ -40,6 +40,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</ <!-- 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"/> |