<?xml version="1.0" ?>
<node name="/Connection"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
>
<tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
<tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright>
<tp:copyright>Copyright (C) 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.Connection">
<tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Requests"/>
<tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.Contacts"/>
<tp:struct name="Channel_Info" array-name="Channel_Info_List">
<tp:deprecated version="0.17.23"/>
<tp:docstring>A struct representing a channel, as returned by
ListChannels on the Connection interface.</tp:docstring>
<tp:member type="o" name="Channel">
<tp:docstring>The object path of the channel, which is on the
same bus name as the connection</tp:docstring>
</tp:member>
<tp:member type="s" tp:type="DBus_Interface" name="Channel_Type">
<tp:docstring>The channel's type</tp:docstring>
</tp:member>
<tp:member type="u" tp:type="Handle_Type" name="Handle_Type">
<tp:docstring>The type of the handle that the channel communicates
with, or Handle_Type_None if there is no associated
handle</tp:docstring>
</tp:member>
<tp:member type="u" tp:type="Handle" name="Handle">
<tp:docstring>The handle that the channel communicates with,
or 0 if there is no associated handle</tp:docstring>
</tp:member>
</tp:struct>
<method name="Connect" tp:name-for-bindings="Connect">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Request that the connection be established. This will be done
asynchronously and errors will be returned by emitting
<tp:member-ref>StatusChanged</tp:member-ref> signals.</p>
<p>Calling this method on a Connection that is already connecting
or connected is allowed, and has no effect.</p>
</tp:docstring>
</method>
<method name="Disconnect" tp:name-for-bindings="Disconnect">
<tp:docstring>
Request that the connection be closed. This closes the connection if
it's not already in DISCONNECTED state, and destroys the connection
object.
</tp:docstring>
</method>
<property name="Interfaces" tp:name-for-bindings="Interfaces"
access="read" type="as" tp:type="DBus_Interface[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The set of optional interfaces supported by this connection.
Before the connection status changes to CONNECTED,
this property may change at any time, but it is guaranteed that
interfaces will only be added, not removed. After the connection
status changes to CONNECTED, this property cannot
change further.</p>
<p>There is no explicit change notification; reasonable behaviour
for a client would be to retrieve the interfaces list once
initially, and once more when it becomes CONNECTED.</p>
<tp:rationale>
<p>In some connection managers, certain capabilities of a connection
are known to be implemented for all connections (e.g. support
for SimplePresence), and some interfaces (like SimplePresence) can
even be used before connecting. Other capabilities may
or may not exist, depending on server functionality; by the time
the connection goes CONNECTED, the connection manager is expected
to have evaluated the server's functionality and enabled any extra
interfaces for the remainder of the Connection's lifetime.</p>
</tp:rationale>
</tp:docstring>
<tp:added version="0.19.2">Clients SHOULD fall back
to calling <tp:member-ref>GetInterfaces</tp:member-ref> if this
property is not supported.</tp:added>
</property>
<method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
<arg direction="out" type="as" tp:type="DBus_Interface[]"
name="Interfaces">
<tp:docstring>
The value of the <tp:member-ref>Interfaces</tp:member-ref> property
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Returns the set of optional interfaces supported by this
connection. See <tp:member-ref>Interfaces</tp:member-ref> for more
details.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected">
<tp:docstring>
Before version 0.17.8 calling GetInterfaces while
on a connection that is not yet CONNECTED wasn't allowed. If a
CM returns this error, its list of interfaces should be regarded
as empty until it becomes CONNECTED.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="GetProtocol" tp:name-for-bindings="Get_Protocol">
<arg direction="out" type="s" tp:type="Protocol" name="Protocol">
<tp:docstring>
A string identifier for the protocol
</tp:docstring>
</arg>
<tp:docstring>
Get the protocol this connection is using.
</tp:docstring>
</method>
<signal name="SelfHandleChanged"
tp:name-for-bindings="Self_Handle_Changed">
<tp:docstring>
Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
changes. If the connection
is not yet in the CONNECTED state, this signal is not guaranteed
to be emitted.
</tp:docstring>
<tp:added version="0.17.10">Clients MAY assume that if the
SelfHandle property exists, this signal will be emitted when
necessary.</tp:added>
<arg type="u" tp:type="Contact_Handle" name="Self_Handle">
<tp:docstring>
The new value of the SelfHandle property.
</tp:docstring>
</arg>
</signal>
<property name="SelfHandle" tp:name-for-bindings="Self_Handle"
type="u" tp:type="Contact_Handle" access="read">
<tp:docstring>
The handle which represents the user on this connection, which will
remain valid for the lifetime of this connection, or until a change
in the user's identifier is signalled by the
<tp:member-ref>SelfHandleChanged</tp:member-ref> signal.
If the connection is not yet in the CONNECTED state, the value of
this property MAY be zero.
</tp:docstring>
<tp:added version="0.17.10">For compatibility with older
versions, clients should fall back to calling the
<tp:member-ref>GetSelfHandle</tp:member-ref>
method.</tp:added>
</property>
<method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
<arg direction="out" type="u" tp:type="Contact_Handle"
name="Self_Handle">
<tp:docstring>
The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
</tp:docstring>
</arg>
<tp:docstring>
Returns the value of the SelfHandle property. Change notification
is via the SelfHandleChanged signal.
</tp:docstring>
<tp:deprecated version="0.17.10">Use GetAll to get the
SelfHandle property (and all other Connection properties)
instead.</tp:deprecated>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
<property name="Status" tp:name-for-bindings="Status"
access="read" type="u" tp:type="Connection_Status">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The current status of the connection. Change notification is via
the <tp:member-ref>StatusChanged</tp:member-ref> signal.</p>
<p>If retrieval of property succeeds and yields the value Disconnected,
this indicates that the connection has not yet been established.
If connection has been attempted and failed, the Connection object
SHOULD be removed from the bus entirely, meaning that retrieval of
this property SHOULD fail.</p>
</tp:docstring>
<tp:added version="0.19.2">Clients SHOULD fall back
to calling <tp:member-ref>GetStatus</tp:member-ref> if this
property is not supported.</tp:added>
</property>
<method name="GetStatus" tp:name-for-bindings="Get_Status">
<arg direction="out" type="u" tp:type="Connection_Status"
name="Status">
<tp:docstring>
The value of the <tp:member-ref>Status</tp:member-ref> property
</tp:docstring>
</arg>
<tp:docstring>
Get the current status as defined in the
<tp:member-ref>StatusChanged</tp:member-ref> signal.
</tp:docstring>
</method>
<method name="HoldHandles" tp:name-for-bindings="Hold_Handles">
<arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle to be held
</tp:docstring>
</arg>
<arg direction="in" name="Handles" type="au" tp:type="Handle[]">
<tp:docstring>
A array of integer handles to hold
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Notify the connection manger that your client is holding a copy
of handles which may not be in use in any existing channel or
list, and were not obtained by using the
<tp:member-ref>RequestHandles</tp:member-ref> method. For
example, a handle observed in an emitted signal, or displayed
somewhere in the UI that is not associated with a channel. The
connection manager must not deallocate a handle where any clients
have used this method to indicate it is in use until the
<tp:member-ref>ReleaseHandles</tp:member-ref>
method is called, or the clients disappear from the bus.</p>
<p>Note that HoldHandles is idempotent - calling it multiple times
is equivalent to calling it once. If a handle is "referenced" by
several components which share a D-Bus unique name, the client
should perform reference counting internally, and only call
ReleaseHandles when none of the cooperating components need the
handle any longer.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
The handle type is invalid
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
One of the given handles is not valid
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="InspectHandles" tp:name-for-bindings="Inspect_Handles">
<arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle to be inspected
</tp:docstring>
</arg>
<arg direction="in" name="Handles" type="au" tp:type="Handle[]">
<tp:docstring>
An array of integer handles of this type
</tp:docstring>
</arg>
<arg direction="out" type="as" name="Identifiers">
<tp:docstring>
An array of identifiers corresponding to the given handles, in the same order.
</tp:docstring>
</arg>
<tp:docstring>
Return a string representation for a number of handles of a given
type.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
The handle type is invalid
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
One of the given handles is not valid
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="ListChannels" tp:name-for-bindings="List_Channels">
<tp:deprecated version="0.17.23">Use the
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.Channels</tp:dbus-ref>
property instead.
</tp:deprecated>
<arg direction="out" type="a(osuu)" tp:type="Channel_Info[]"
name="Channel_Info">
<tp:docstring>
An array of structs representing channels.
</tp:docstring>
</arg>
<tp:docstring>
List all the channels which currently exist on this connection.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
<signal name="NewChannel" tp:name-for-bindings="New_Channel">
<tp:deprecated version="0.17.23">Connection managers MUST still
emit this signal, but clients SHOULD listen for the <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.NewChannels</tp:dbus-ref>
signal instead.
</tp:deprecated>
<arg name="Object_Path" type="o">
<tp:docstring>
A D-Bus object path for the channel object on this service
</tp:docstring>
</arg>
<arg name="Channel_Type" type="s" tp:type="DBus_Interface">
<tp:docstring>
A D-Bus interface name representing the channel type
</tp:docstring>
</arg>
<arg name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
An integer representing the type of handle this channel
communicates with, or Handle_Type_None if no handle is specified
</tp:docstring>
</arg>
<arg name="Handle" type="u" tp:type="Handle">
<tp:docstring>
A handle indicating the specific contact, room or list this
channel communicates with, or zero if no handle is specified
</tp:docstring>
</arg>
<arg name="Suppress_Handler" type="b">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<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 <tp:member-ref>RequestChannel</tp:member-ref> method), so no
other handler should be
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
(this usage is deprecated).</p>
<p>Clients MUST NOT assume that only incoming channels will have
this flag set to false.</p>
</tp:docstring>
</arg>
<tp:docstring>
Emitted when a new Channel object is created, either through user
request or incoming information from the service.
</tp:docstring>
</signal>
<method name="ReleaseHandles" tp:name-for-bindings="Release_Handles">
<arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
An integer handle type (as defined in RequestHandle)
</tp:docstring>
</arg>
<arg direction="in" name="Handles" type="au" tp:type="Handle[]">
<tp:docstring>
An array of integer handles being held by the client
</tp:docstring>
</arg>
<tp:docstring>
Explicitly notify the connection manager that your client is no
longer holding any references to the given handles, and that they
may be deallocated if they are not held by any other clients or
referenced by any existing channels. See HoldHandles for notes.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
The handle type is invalid
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
One of the given handles is not valid
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
One of the given handles is not held by this client
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="RequestChannel" tp:name-for-bindings="Request_Channel">
<tp:deprecated version="0.17.23">Use
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.CreateChannel</tp:dbus-ref>
or <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
instead. Connection managers MAY implement RequestChannel by
raising NotImplemented, or implement fewer types of channel via
this API.</tp:deprecated>
<arg direction="in" name="Type" type="s" tp:type="DBus_Interface">
<tp:docstring>
A D-Bus interface name representing base channel type
</tp:docstring>
</arg>
<arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
An integer representing the handle type, or Handle_Type_None if
no handle is specified
</tp:docstring>
</arg>
<arg direction="in" name="Handle" type="u" tp:type="Handle">
<tp:docstring>
A nonzero integer handle representing a contact, room, list etc.
according to handle_type, or zero if the handle_type is
Handle_Type_None
</tp:docstring>
</arg>
<arg direction="in" name="Suppress_Handler" type="b">
<tp:docstring>
<p>Clients SHOULD always set this to true.</p>
<tp:rationale>
<p>The historical meaning was that clients that did not
intend to take responsibility for displaying the channel to
the user could set this to FALSE, in which case the channel
dispatcher would launch an appropriate channel handler.</p>
<p>However, clients whose functionality relies on having a
working channel dispatcher should obtain that functionality by
calling methods on the channel dispatcher, so that they will
get an appropriate error if the channel dispatcher is missing
or not working.</p>
<p>The channel dispatcher itself should set this to true too,
so that it will ignore the
<tp:member-ref>NewChannel</tp:member-ref> signal that results
from the creation of the channel. It can then dispatch the
channel returned from this method to an
appropriate handler.</p>
<p>So, there is no sensible use-case for setting this to false,
and setting it to false can result in unhandled channels (in
the case where clients assume that a channel dispatcher is
present, but it isn't).</p>
</tp:rationale>
</tp:docstring>
</arg>
<arg direction="out" type="o" name="Object_Path">
<tp:docstring>
The D-Bus object path for the channel created or retrieved
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Request a channel satisfying the specified type and communicating
with the contact, room, list etc. indicated by the given
handle_type and handle. The handle_type and handle may both be
zero to request the creation of a new, empty channel, which may
or may not be possible, depending on the protocol and channel
type.</p>
<p>On success, the returned channel will always be of the requested
type (i.e. implement the requested channel-type interface).</p>
<p>If a new, empty channel is requested, on success the returned
channel will always be an "anonymous" channel for which the type
and handle are both zero.</p>
<p>If a channel to a contact, room etc. is requested, on success, the
returned channel may either be a new or existing channel to
the requested entity (i.e. its
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
and <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
properties are the
requested handle type and handle), or a newly created "anonymous"
channel associated with the requested handle in some
implementation-specific way.</p>
<p>For example, for a contact handle, the returned channel
might be "anonymous", but implement the groups interface and have
the requested contact already present among the members.</p>
<p>If the request cannot be satisfied, an error is raised and no
channel is created.</p>
</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>
Unknown channel type
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
The given handle does not exist or cannot be created
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
The requested channel type cannot be created with the given handle
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotCapable">
<tp:docstring>
The requested channel cannot be created because contact doesn't
have the required capabilities.
</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>
<tp:enum name="Handle_Type" type="u">
<tp:enumvalue suffix="None" value="0">
<tp:docstring>
A "null" handle type used to indicate the absence of a handle.
When a handle type and a handle appear as a pair, if the handle
type is zero, the handle must also be zero.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Contact" value="1">
<tp:docstring>
A contact
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Room" value="2">
<tp:docstring>
A chat room
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="List" value="3">
<tp:docstring>
A server-generated contact list (see Channel.Interface.Group)
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Group" value="4">
<tp:docstring>
A user-defined contact list (see Channel.Interface.Group)
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:simple-type name="Handle" type="u" array-name="Handle_List">
<tp:docstring>An unsigned 32-bit integer representing a
handle</tp:docstring>
</tp:simple-type>
<tp:simple-type name="Contact_Handle" type="u"
array-name="Contact_Handle_List">
<tp:docstring>An unsigned 32-bit integer representing a handle of type
Handle_Type_Contact</tp:docstring>
</tp:simple-type>
<tp:simple-type name="Room_Handle" type="u"
array-name="Room_Handle_List">
<tp:docstring>An unsigned 32-bit integer representing a handle of type
Handle_Type_Room</tp:docstring>
</tp:simple-type>
<tp:simple-type name="List_Handle" type="u"
array-name="List_Handle_List">
<tp:docstring>An unsigned 32-bit integer representing a handle of type
Handle_Type_List</tp:docstring>
</tp:simple-type>
<tp:simple-type name="Group_Handle" type="u"
array-name="Group_Handle_List">
<tp:docstring>An unsigned 32-bit integer representing a handle of type
Handle_Type_Group</tp:docstring>
</tp:simple-type>
<method name="RequestHandles" tp:name-for-bindings="Request_Handles">
<arg direction="in" name="Handle_Type" type="u" tp:type="Handle_Type">
<tp:docstring>
The type of handle required
</tp:docstring>
</arg>
<arg direction="in" name="Identifiers" type="as">
<tp:docstring>
An array of identifiers of entities to request handles for
</tp:docstring>
</arg>
<arg direction="out" type="au" tp:type="Handle[]"
name="Handles">
<tp:docstring>
An array of integer handle numbers in the same order as the given identifiers.
</tp:docstring>
</arg>
<tp:docstring>
Request several handles from the connection manager which represent a
number of contacts, rooms or server-stored lists on the service. The
connection manager should record that these handles are in use by the
client who invokes this method, and must not deallocate the handles
until the client disconnects from the bus or calls the
<tp:member-ref>ReleaseHandles</tp:member-ref>
method. Where the identifier refers to an entity that already has a
handle in this connection manager, this handle should be returned
instead. The handle number 0 must not be returned by the connection
manager.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
The given identifier does not identify a valid entity of the given
type.
<tp:rationale>
For instance, an XMPP connection would raise this error for
identifiers with type Handle_Type_Room that do not contain
exactly one '@' character, that contain spaces, and so on.
</tp:rationale>
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
<tp:docstring>
The given handle type is not valid, or is not implemented on this
connection.
<tp:rationale>
For instance, a connection to a protocol that doesn't have
chat rooms would raise this error for room handles, and all CMs
would raise this error for Handle_Type_None.
</tp:rationale>
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<tp:enum name="Connection_Status" plural="Connection_Statuses" type="u">
<tp:enumvalue suffix="Connected" value="0">
<tp:docstring>
The connection is fully connected and all methods are available.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Connecting" value="1">
<tp:docstring>
<tp:member-ref>Connect</tp:member-ref> has been called but the
connection has not yet been established. Some methods may fail
until the connection has been established.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Disconnected" value="2">
<tp:docstring>
If this is retrieved from <tp:member-ref>GetStatus</tp:member-ref> or
<tp:member-ref>Status</tp:member-ref>, it indicates that connection
has not yet been attempted. If seen in a
<tp:member-ref>StatusChanged</tp:member-ref> signal, it indicates
that the connection has failed; the Connection object SHOULD be
removed from D-Bus immediately, and all subsequent method calls
SHOULD fail.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:enum name="Connection_Status_Reason" type="u">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A reason why the status of the connection changed. Apart from
Requested, the values of this enumeration only make sense as
reasons why the status changed to Disconnected.</p>
</tp:docstring>
<tp:enumvalue suffix="None_Specified" value="0">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There is no reason set for this state change. Unknown status
reasons SHOULD be treated like this reason.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Disconnected</code>.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Requested" value="1">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The change is in response to a user request. Changes to the
Connecting or Connected status SHOULD always indicate this reason;
changes to the Disconnected status SHOULD indicate this reason
if and only if the disconnection was requested by the user.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Network_Error" value="2">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error sending or receiving on the network socket.</p>
<p>When the status changes from Connecting to Disconnected for this
reason, the equivalent D-Bus error is either
<code>org.freedesktop.Telepathy.Error.NetworkError</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionRefused</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionFailed</code>
or some more specific error.</p>
<p>When the status changes from Connected to Disconnected for this
reason, the equivalent D-Bus error is either
<code>org.freedesktop.Telepathy.Error.NetworkError</code>,
<code>org.freedesktop.Telepathy.Error.ConnectionLost</code>
or some more specific error.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Authentication_Failed" value="3">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The username or password was invalid.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.AuthenticationFailed</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Encryption_Error" value="4">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There was an error negotiating SSL on this connection, or
encryption was unavailable and require-encryption was set when the
connection was created.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.EncryptionNotAvailable</code>
if encryption was not available at all, or
<code>org.freedesktop.Telepathy.Error.EncryptionError</code>
if encryption failed.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Name_In_Use" value="5">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>In general, this reason indicates that the requested account
name or other identification could not be used due to conflict
with another connection. It can be divided into three cases:</p>
<ul>
<li>If the status change is from Connecting to Disconnected
and the 'register' parameter to RequestConnection was present
and true, the requested account could not be created on the
server because it already exists.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.RegistrationExists</code>.
</li>
<li>If the status change is from Connecting to Disconnected
but the 'register' parameter is absent or false, the connection
manager could not connect to the specified account because
a connection to that account already exists.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.AlreadyConnected</code>.
<tp:rationale>
In some protocols, like XMPP (when connecting with the same
JID and resource as an existing connection), the existing
connection "wins" and the new one fails to connect.
</tp:rationale>
</li>
<li>If the status change is from Connected to Disconnected,
the existing connection was automatically disconnected because
a new connection to the same account (perhaps from a different
client or location) was established.
The equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.ConnectionReplaced</code>.
<tp:rationale>
In some protocols, like MSNP (when connecting twice with the
same Passport), the new connection "wins" and the
existing one is automatically disconnected.
</tp:rationale>
</li>
</ul>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Not_Provided" value="6">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server did not provide a SSL certificate.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.NotProvided</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Untrusted" value="7">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is signed by an untrusted certifying
authority. This error SHOULD NOT be used to represent a self-signed
certificate: use the more specific Cert_Self_Signed reason for
that.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Untrusted</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Expired" value="8">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate has expired.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Expired</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Not_Activated" value="9">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is not yet valid.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.NotActivated</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Hostname_Mismatch" value="10">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate did not match its hostname.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Fingerprint_Mismatch" value="11">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate does not have the expected
fingerprint.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Self_Signed" value="12">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The server's SSL certificate is self-signed.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.HostnameMismatch</code>.
</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Cert_Other_Error" value="13">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>There was some other error validating the server's SSL
certificate.</p>
<p>When disconnected for this reason, the equivalent D-Bus error is
<code>org.freedesktop.Telepathy.Error.Cert.Invalid</code>.
</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<signal name="ConnectionError" tp:name-for-bindings="Connection_Error">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when an error occurs that renders this connection unusable.
</p>
<p>Whenever this signal is emitted, it MUST immediately be followed by
a <tp:member-ref>StatusChanged</tp:member-ref> signal with status
Connection_Status_Disconnected and an appropriate reason
code.</p>
<p>Connection managers SHOULD emit this signal on disconnection, but
need not do so. Clients MUST support connection managers that emit
StatusChanged(Disconnected, ...) without first emitting
ConnectionError.</p>
<tp:rationale>
<p>This signal provides additional information about the reason
for disconnection. The reason for connection is always
straightforward - it was requested - so it does not need further
explanation. However, on errors, it can be useful to provide
additional information.</p>
<p>The <tp:type>Connection_Status_Reason</tp:type> is not given
here, since it will be signalled in
<tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client
implementation would be to store the information given by this
signal until StatusChanged is received, at which point the
information given by this signal can be used to supplement the
StatusChanged signal.</p>
</tp:rationale>
</tp:docstring>
<arg name="Error" type="s" tp:type="DBus_Error_Name">
<tp:docstring>
The name of a D-Bus error describing the error that occurred,
which may correspond to a
<tp:type>Connection_Status_Reason</tp:type>, or may be a more
specific Telepathy error
(such as
<code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code>
for Connection_Status_Reason_Network_Error)
or a protocol-specific or connection-manager-specific error in a
suitable namespace.
<tp:rationale>
For instance, a SIP connection manager could signal
"402 Payment Required" as an error in a
connection-manager-specific namespace, or a link-local
XMPP implementation that used Avahi could provide the error
given to it by the avahi-daemon.
</tp:rationale>
</tp:docstring>
</arg>
<arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Additional information about the error, which may include
the following well-known keys:</p>
<dl>
<dt>debug-message (s)</dt>
<dd>Debugging information on the change, corresponding to the
message part of a D-Bus error message, which SHOULD NOT be
displayed to users under normal circumstances</dd>
</dl>
<tp:rationale>
<p>This argument allows for future extensions. For instance,
if indicating DNS lookup failure, we could define a key
that indicates the hostname that could not be found.</p>
</tp:rationale>
</tp:docstring>
</arg>
</signal>
<signal name="StatusChanged" tp:name-for-bindings="Status_Changed">
<arg name="Status" type="u" tp:type="Connection_Status">
<tp:docstring>
An integer indicating the new status, as defined by ConnectionStatus
</tp:docstring>
</arg>
<arg name="Reason" type="u" tp:type="Connection_Status_Reason">
<tp:docstring>
An integer indicating the reason for the status change, as defined
by ConnectionStatusReason
</tp:docstring>
</arg>
<tp:docstring>
Emitted when the status of the connection changes. All states and
reasons have numerical values, as defined in ConnectionStatus
and ConnectionStatusReason.
</tp:docstring>
</signal>
<tp:contact-attribute name="contact-id" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same string that would be returned by
<tp:member-ref>InspectHandles</tp:member-ref>. As a special case,
this is always present in the result of <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Contacts">GetContactAttributes</tp:dbus-ref>,
whether it was explicitly requested or not.</p>
</tp:docstring>
</tp:contact-attribute>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This models a connection to a single user account on a communication
service. Its basic capability is to provide the facility to request and
receive channels of differing types (such as text channels or streaming
media channels) which are used to carry out further communication.</p>
<p>In order to allow Connection objects to be discovered by new clients,
the object path and well-known bus name MUST be of the form
<code>/org/freedesktop/Telepathy/Connection/cmname/proto/account</code>
and
<code>org.freedesktop.Telepathy.Connection.cmname.proto.account</code>
where:</p>
<ul>
<li><em>cmname</em> is the same
<tp:type>Connection_Manager_Name</tp:type> that appears
in the connection manager's object path and well-known bus name</li>
<li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
<tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">ListProtocols</tp:dbus-ref>,
but with "-" replaced with "_" to get a valid
object path/bus name</li>
<li><em>account</em> is some non-empty sequence of ASCII letters,
digits and underscores not starting with a digit</li>
</ul>
<p><em>account</em> SHOULD be formed such that any valid distinct
connection instance on this protocol has a distinct name. This
might be formed by including the server name followed by the user
name (escaped via some suitable mechanism like telepathy-glib's
tp_escape_as_identifier() function to preserve uniqueness); on
protocols where connecting multiple times is permissable, a
per-connection identifier might be necessary to ensure
uniqueness.</p>
<p>Clients MAY parse the object path to determine the connection
manager name and the protocol, but MUST NOT attempt to parse the
<em>account</em> part. Connection managers MAY use any unique string
for this part.</p>
<p>As well as the methods and signatures below, arbitrary interfaces may be
provided by the Connection object to represent extra connection-wide
functionality, such as the Connection.Interface.SimplePresence for
receiving and
reporting presence information, and Connection.Interface.Aliasing for
connections where contacts may set and change an alias for themselves.
These interfaces can be discovered using the
<tp:member-ref>GetInterfaces</tp:member-ref> method.</p>
<p>Contacts, rooms, and server-stored lists (such as subscribed contacts,
block lists, or allow lists) on a service are all represented by
immutable <em>handles</em>, which are unsigned non-zero integers which are
valid only for the lifetime of the connection object, and are used
throughout the protocol where these entities are represented, allowing
simple testing of equality within clients.</p>
<p>Zero as a handle value is sometimes used as a "null" value to mean
the absence of a contact, room, etc.</p>
<p>Handles have per-type uniqueness, meaning that
every (handle type, handle number) tuple is guaranteed to be unique within
a connection and that a handle alone (without its type) is meaningless or
ambiguous. Connection manager implementations should reference count these
handles to determine if they are in use either by any active clients or any
open channels, and may deallocate them when this ceases to be true. Clients
may request handles of a given type and identifier with the
<tp:member-ref>RequestHandles</tp:member-ref> method, inspect the entity
identifier with the <tp:member-ref>InspectHandles</tp:member-ref>
method, keep handles from being released with
<tp:member-ref>HoldHandles</tp:member-ref>, and notify that they are no
longer storing handles with
<tp:member-ref>ReleaseHandles</tp:member-ref>.</p>
</tp:docstring>
<tp:changed version="0.17.10">Previously, the account part of
Connection bus names/object paths was allowed to have more than one
component (i.e. contain dots or slashes), resulting in Connection
bus names and object paths with more than 7 components. We now restrict
Connection bus names/object paths to have exactly 7
components.</tp:changed>
<tp:changed version="0.17.23">The Requests and Contacts interfaces
are now mandatory. Their functionality will be merged into the main
Connection interface at some point in future.</tp:changed>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->