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.
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.
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.
Request that the connection be established. This will be done
asynchronously and errors will be returned by emitting
Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.
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.
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.
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.
Returns the set of optional interfaces supported by this
connection. See
The current status of the connection. Change notification is via
the
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.
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
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.
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
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).
Clients MUST NOT assume that only incoming channels will have this flag set to false.
Clients SHOULD always set this to true.
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.
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.
The channel dispatcher itself should set this to true too,
so that it will ignore the
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).
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.
On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).
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.
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
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.
If the request cannot be satisfied, an error is raised and no channel is created.
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.
There is no reason set for this state change. Unknown status reasons SHOULD be treated like this reason.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Disconnected
.
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.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cancelled
.
There was an error sending or receiving on the network socket.
When the status changes from Connecting to Disconnected for this
reason, the equivalent D-Bus error is either
org.freedesktop.Telepathy.Error.NetworkError
,
org.freedesktop.Telepathy.Error.ConnectionRefused
,
org.freedesktop.Telepathy.Error.ConnectionFailed
or some more specific error.
When the status changes from Connected to Disconnected for this
reason, the equivalent D-Bus error is either
org.freedesktop.Telepathy.Error.NetworkError
,
org.freedesktop.Telepathy.Error.ConnectionLost
or some more specific error.
The username or password was invalid.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.AuthenticationFailed
.
There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.EncryptionNotAvailable
if encryption was not available at all, or
org.freedesktop.Telepathy.Error.EncryptionError
if encryption failed.
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:
org.freedesktop.Telepathy.Error.RegistrationExists
.
org.freedesktop.Telepathy.Error.AlreadyConnected
.
org.freedesktop.Telepathy.Error.ConnectionReplaced
.
The server did not provide a SSL certificate.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.NotProvided
.
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.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.Untrusted
.
The server's SSL certificate has expired.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.Expired
.
The server's SSL certificate is not yet valid.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.NotActivated
.
The server's SSL certificate did not match its hostname.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.HostnameMismatch
.
The server's SSL certificate does not have the expected fingerprint.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.FingerprintMismatch
.
The server's SSL certificate is self-signed.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.SelfSigned
.
There was some other error validating the server's SSL certificate.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.Invalid
.
The server's SSL certificate has been revoked.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.Revoked
.
The server's SSL certificate uses an insecure algorithm, or is cryptographically weak.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.Insecure
.
The length in bytes of the server certificate, or the depth of the sever certificate chain exceed the limits imposed by the crypto library.
When disconnected for this reason, the equivalent D-Bus error is
org.freedesktop.Telepathy.Error.Cert.LimitExceeded
Emitted when an error occurs that renders this connection unusable.
Whenever this signal is emitted, it MUST immediately be followed by
a
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.
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.
The
org.freedesktop.Telepathy.Errors.ConnectionRefused
for Connection_Status_Reason_Network_Error)
or a protocol-specific or connection-manager-specific error in a
suitable namespace.
Additional information about the error, which may include the following well-known keys:
The same string that would be returned by
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.
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
/org/freedesktop/Telepathy/Connection/cmname/proto/account
and
org.freedesktop.Telepathy.Connection.cmname.proto.account
where:
account 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.
Clients MAY parse the object path to determine the connection manager name and the protocol, but MUST NOT attempt to parse the account part. Connection managers MAY use any unique string for this part.
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
Contacts, rooms, and server-stored lists (such as subscribed contacts, block lists, or allow lists) on a service are all represented by immutable handles, 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.
Zero as a handle value is sometimes used as a "null" value to mean the absence of a contact, room, etc.
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