<?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">Addressing1</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">Addressing1</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: -->