diff options
Diffstat (limited to 'qt4/spec/Channel.xml')
| -rw-r--r-- | qt4/spec/Channel.xml | 557 |
1 files changed, 0 insertions, 557 deletions
diff --git a/qt4/spec/Channel.xml b/qt4/spec/Channel.xml deleted file mode 100644 index 11d3e509c..000000000 --- a/qt4/spec/Channel.xml +++ /dev/null @@ -1,557 +0,0 @@ -<?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: --> |