diff options
Diffstat (limited to 'qt4/spec/Channel.xml')
| -rw-r--r-- | qt4/spec/Channel.xml | 557 |
1 files changed, 557 insertions, 0 deletions
diff --git a/qt4/spec/Channel.xml b/qt4/spec/Channel.xml new file mode 100644 index 000000000..11d3e509c --- /dev/null +++ b/qt4/spec/Channel.xml @@ -0,0 +1,557 @@ +<?xml version="1.0" ?> +<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright> + <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright> + <tp:copyright>Copyright © 2006 INdT</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +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"> + + <property name="ChannelType" type="s" tp:type="DBus_Interface" + access="read" tp:name-for-bindings="Channel_Type"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The channel's type. This cannot change once the channel has + been created.</p> + + <p>For compatibility between older connection managers and newer + clients, if this is unavailable or is an empty string, + clients MUST use the result of calling + <tp:member-ref>GetChannelType</tp:member-ref>.</p> + + <tp:rationale> + 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" 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 + the channel type and the Channel interface itself, and cannot + change once the channel has been created.</p> + + <p>For compatibility between older connection managers and newer + clients, if this is unavailable, or if this is an empty list and + <tp:member-ref>ChannelType</tp:member-ref> is an empty string, + clients MUST use the result of calling + <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an + empty list but ChannelType is non-empty, clients SHOULD NOT call + GetInterfaces; this implies that connection managers that implement + the ChannelType property MUST also implement the Interfaces property + correctly.</p> + + <tp:rationale> + 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> + + <property name="TargetHandle" type="u" access="read" tp:type="Handle" + tp:name-for-bindings="Target_Handle"> + <tp:added version="0.17.7"/> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The handle (a representation for the identifier) of the contact, + chatroom, etc. with which this handle communicates. Its type + is given by the <tp:member-ref>TargetHandleType</tp:member-ref> + property.</p> + + <p>This is fixed for the lifetime of the channel, so channels which + could potentially be used to communicate with multiple contacts, + and do not have an identity of their own (such as a Handle_Type_Room + handle), must have TargetHandleType set to Handle_Type_None and + TargetHandle set to 0.</p> + + <p>Unlike in the telepathy-spec 0.16 API, there is no particular + uniqueness guarantee - there can be many channels with the same + (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. Properties from + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-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 <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [T])</li> + <li>Channel C closes, removing the last reference to handle T</li> + <li><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(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. Properties from + <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-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 xmlns="http://www.w3.org/1999/xhtml"> + <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</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" tp:name-for-bindings="Close"> + <tp:docstring> + Request that the channel be closed. This is not the case until + the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and + depending on the connection + manager this may simply remove you from the channel on the server, + rather than causing it to stop existing entirely. Some channels + such as contact list channels may not be closed. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + This channel may never be closed, e.g. a contact list + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + This channel is not currently in a state where it can be closed, + e.g. a non-empty user-defined contact group + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <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, + and the connection manager may then remove the object from the bus + at any point. + </tp:docstring> + </signal> + + <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type"> + <tp:deprecated version="0.17.7">Use the ChannelType + property if possible.</tp:deprecated> + <arg direction="out" type="s" tp:type="DBus_Interface" + name="Channel_Type"> + <tp:docstring>The interface name</tp:docstring> + </arg> + <tp:docstring> + Returns the interface name for the type of this channel. Clients + SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property + instead, falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </tp:docstring> + </method> + + <method name="GetHandle" tp:name-for-bindings="Get_Handle"> + <tp:deprecated version="0.17.7">Use the TargetHandleType + and TargetHandle properties if possible.</tp:deprecated> + <arg direction="out" type="u" tp:type="Handle_Type" + name="Target_Handle_Type"> + <tp:docstring> + The same as TargetHandleType. + </tp:docstring> + </arg> + <arg direction="out" type="u" tp:type="Handle" name="Target_Handle"> + <tp:docstring> + The same as TargetHandle. + </tp:docstring> + </arg> + <tp:docstring> + Returns the handle type and number if this channel represents a + communication with a particular contact, room or server-stored list, or + zero if it is transient and defined only by its contents. Clients + SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetHandleType</tp:member-ref> properties instead, + falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </tp:docstring> + </method> + + <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces"> + <tp:deprecated version="0.17.7">Use the Interfaces + property if possible.</tp:deprecated> + <arg direction="out" type="as" tp:type="DBus_Interface[]" + name="Interfaces"> + <tp:docstring> + An array of the D-Bus interface names + </tp:docstring> + </arg> + <tp:docstring> + Get the optional interfaces implemented by the channel. + Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref> + property instead, falling back to this method only if necessary. + + <tp:rationale> + The GetAll method lets clients retrieve all properties in one + round-trip. + </tp:rationale> + </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> + + <p>It does not make sense for this property to be in channel + requests—it will always be true for channels returned by + CreateChannel, and callers of EnsureChannel cannot control whether an + existing channel was originally requested locally—so it MUST NOT + be accepted.</p> + </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 instance, the contact + who invited the local user to a chatroom, or the contact who + initiated a call.</p> + + <p>This does <em>not</em> necessarily represent the contact who + created the underlying protocol-level construct. For instance, if + Rob creates a chatroom, Will joins that chatroom, and Will invites Simon + to join it, then Simon will see Will as the InitiatorHandle of the + channel representing the chatroom.</p> + + <tp:rationale> + <p>The room creator is generally a less useful piece of information + than the inviter, is less likely to be available at invitation + time (i.e. can't necessarily be an immutable property), and is + less likely to be available at all. The creator of a chatroom + is not currently available via Telepathy; if added in future, it + is likely to be made available as a property on the Chatroom + interface (<a + href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p> + </tp:rationale> + + <p>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>On some protocols, the SelfHandle may change (as signalled by + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>), + but this property is immutable. Hence, locally-requested channels' + InitiatorHandle and InitiatorID may not match the current + SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to + determine whether the channel was created locally.</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 <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref> + 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 <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT, + [I])</li> + <li>Channel C closes, removing the last reference to handle I</li> + <li><tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(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 + be implemented by all channel objects, along with one single channel type, + such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref> + which represents a list of people (such as a buddy list) or <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which + represents a channel over which textual messages are sent and received.</p> + + <p>Each Channel's object path MUST start with the object path of + its associated <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, 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 has a number of immutable properties (which cannot vary + after the channel has been announced with <tp:dbus-ref + namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>), + provided to clients in the + <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>, + <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and + <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref> + methods to permit immediate identification of the channel. This interface + contains immutable properties common to all channels. In brief:</p> + + <ul> + <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of + communication carried out on this channel;</li> + <li><tp:member-ref>TargetHandleType</tp:member-ref>, + <tp:member-ref>TargetHandle</tp:member-ref> and + <tp:member-ref>TargetID</tp:member-ref> specify the entity with which + this channel communicates, such as the other party in a 1-1 call, or + the name of a multi-user chat room;</li> + <li><tp:member-ref>InitiatorHandle</tp:member-ref> and + <tp:member-ref>InitiatorID</tp:member-ref> specify who created this + channel;</li> + <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local + user requested this channel, or whether it is an incoming call, a text + conversation started by a remote contact, a chatroom invitation, + etc.</li> + </ul> + + <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be + implemented to indicate other available + functionality, such as <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> + if the channel contains a number of contacts, <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref> + to indicate that a channel may have a password set to require entry, and + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref> + for typing notifications. The interfaces implemented may not vary after + the channel has been created. These other interfaces (along with the + interface named by <tp:member-ref>ChannelType</tp:member-ref>) may + themselves specify immutable properties to be announced up-front along + with the properties on this interface.</p> + + <p>Some channels are “anonymous”, with + <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>, + which indicates that the channel is defined by some other properties. For + instance, transient ad-hoc chat rooms may be defined only by their members (as visible + through the <tp:dbus-ref + namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> + interface), and <tp:dbus-ref + namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref> + channels represent a single search attempt for a particular <tp:dbus-ref + namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p> + + <p>Specific connection manager implementations may implement channel types and + interfaces which are not contained within this specification in order to + support further functionality. To aid interoperability between client and + connection manager implementations, the interfaces specified here should be + used wherever applicable, and new interfaces made protocol-independent + wherever possible. Because of the potential for 3rd party interfaces adding + methods or signals with conflicting names, the D-Bus interface names should + always be used to invoke methods and bind signals.</p> + </tp:docstring> + + <tp:changed version="0.17.7">Previously we guaranteed that, for + any handle type other than Handle_Type_None, and for any channel type + and any handle, there would be no more than one channel with that + combination of channel type, handle type and handle. This guarantee + 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: --> |