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.

A struct representing a channel, as returned by ListChannels on the Connection interface. The object path of the channel, which is on the same bus name as the connection The channel's type The type of the handle that the channel communicates with, or Handle_Type_None if there is no associated handle The handle that the channel communicates with, or 0 if there is no associated handle

Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals.

Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

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.

Clients SHOULD fall back to calling GetInterfaces if this property is not supported. The value of the Interfaces property

Returns the set of optional interfaces supported by this connection. See Interfaces for more details.

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.

A string identifier for the protocol Get the protocol this connection is using. Emitted whenever the SelfHandle property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted. Clients MAY assume that if the SelfHandle property exists, this signal will be emitted when necessary. The new value of the SelfHandle property. 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 SelfHandleChanged signal. If the connection is not yet in the CONNECTED state, the value of this property MAY be zero. For compatibility with older versions, clients should fall back to calling the GetSelfHandle method. The value of the SelfHandle property Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

The current status of the connection. Change notification is via the StatusChanged signal.

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.

Clients SHOULD fall back to calling GetStatus if this property is not supported. The value of the Status property Get the current status as defined in the StatusChanged signal. If HasImmortalHandles is true, this method no longer does anything. The type of handle to be held A array of integer handles to hold

If HasImmortalHandles is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.

In older connection managers, this method notifies 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 RequestHandles 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 ReleaseHandles method is called, or the clients disappear from the bus.

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.

The handle type is invalid One of the given handles is not valid

The type of handle to be inspected An array of integer handles of this type An array of identifiers corresponding to the given handles, in the same order. Return a string representation for a number of handles of a given type.

The handle type is invalid One of the given handles is not valid

Use the Requests.Channels property instead. An array of structs representing channels. List all the channels which currently exist on this connection.

Connection managers MUST still emit this signal, but clients SHOULD listen for the Requests.NewChannels signal instead. A D-Bus object path for the channel object on this service A D-Bus interface name representing the channel type An integer representing the type of handle this channel communicates with, or Handle_Type_None if no handle is specified A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified

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 RequestChannel method), so no other handler should be launched. Clients MAY assume that channels where this is true were created by a user request.

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.

Emitted when a new Channel object is created, either through user request or incoming information from the service. If HasImmortalHandles is true, this method no longer does anything. An integer handle type (as defined in RequestHandle) An array of integer handles being held by the client

In older connection managers, this method explicitly notifies 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.

The handle type is invalid One of the given handles is not valid

Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API. A D-Bus interface name representing base channel type An integer representing the handle type, or Handle_Type_None if no handle is specified A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is Handle_Type_None

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 NewChannel signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler.

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).

The D-Bus object path for the channel created or retrieved

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 TargetHandleType and TargetHandle properties are the requested handle type and handle), or a newly created "anonymous" channel associated with the requested handle in some implementation-specific way.

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.

Unknown channel type The given handle does not exist or cannot be created The requested channel type cannot be created with the given handle The requested channel cannot be created because contact doesn't have the required capabilities.

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. A contact A chat room A server-generated contact list (see Channel.Interface.Group) A user-defined contact list (see Channel.Interface.Group)

An unsigned 32-bit integer representing a handle

An unsigned 32-bit integer representing a handle of type Handle_Type_Contact

An unsigned 32-bit integer representing a handle of type Handle_Type_Room

An unsigned 32-bit integer representing a handle of type Handle_Type_List

An unsigned 32-bit integer representing a handle of type Handle_Type_Group

If HasImmortalHandles is true, this method no longer has its reference-counting effect. The type of handle required An array of identifiers of entities to request handles for An array of integer handle numbers in the same order as the given identifiers.

Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service.

If HasImmortalHandles is true, which SHOULD always be the case in this version of telepathy-spec, the handles remain valid until the connection disconnects.

The implementation of this method in older connection managers must 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 ReleaseHandles 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.

The given identifier does not identify a valid entity of the given type. 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. The given handle type is not valid, or is not implemented on this connection. 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.

The connection is fully connected and all methods are available. Connect has been called but the connection has not yet been established. Some methods may fail until the connection has been established. If this is retrieved from GetStatus or Status, it indicates that connection has not yet been attempted. If seen in a StatusChanged 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.

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:

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 org.freedesktop.Telepathy.Error.RegistrationExists.
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 org.freedesktop.Telepathy.Error.AlreadyConnected. 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.
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 org.freedesktop.Telepathy.Error.ConnectionReplaced. In some protocols, like MSNP (when connecting twice with the same Passport), the new connection "wins" and the existing one is automatically disconnected.

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 StatusChanged signal with status Connection_Status_Disconnected and an appropriate reason code.

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 Connection_Status_Reason is not given here, since it will be signalled in StatusChanged. 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.

The name of a D-Bus error describing the error that occurred, which may correspond to a Connection_Status_Reason, or may be a more specific Telepathy error (such as org.freedesktop.Telepathy.Error.ConnectionRefused for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. 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.

Additional information about the error, which may include the following well-known keys:

debug-message (s): 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
user-requested (b), expected-hostname (s), certificate-hostname (s): The same details defined in TLS_Certificate_Rejection.

An integer indicating the new status, as defined by ConnectionStatus An integer indicating the reason for the status change, as defined by ConnectionStatusReason Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

The same string that would be returned by InspectHandles. As a special case, this is always present in the result of GetContactAttributes, whether it was explicitly requested or not.

Groups of notifications are identified by a token which is either a D-Bus interface name, or a string that starts with a D-Bus interface name. The meaning of each token is given by that D-Bus interface, which MUST define it in its documentation.

Initially, all interests are in entire interface, but allowing other strings allows subscription to part of an interface; for instance, an interest in ...MailNotification/count could track the number of messages without caring about their detailed content.

For each token with which this method interacts, the Connection tracks an "interest count" (like a reference count) for each unique bus name that has called this method. When a client calls this method, for each token, the interest count for its unique bus name is incremented; when RemoveClientInterest is called, all interest counts for that unique bus name are decremented. If the unique bus name leaves the bus (for instance, if the client crashes or exits), all interest counts for that unique bus name are set to zero.

The Connection can then use these reference counts to avoid subscribing to protocol-level notifications unless at least one client has a non-zero interest count for the relevant token.

This method exists to reduce memory and network overhead when there is no active subscription.

One situation where this is useful is Location: on XMPP, location updates are received over PEP. If the Connection advertises the geoloc+notify capability, it will be sent location updates for all contacts. To avoid consuming resources for this, the connection should avoid advertising that capability until a client has expressed an interest in contacts' locations.

Another example of a protocol that benefits from this method is the Google XMPP Mail Notification extension, which can be used to implement MailNotification. In this protocol, the CM receives a notification that something has changed, but to get more information, the CM must request this information. Knowing that nobody is currently interested in this information, the CM can avoid generating useless network traffic. Similarly, the CM may free the list of unread messages to reduce memory overhead.

If this method is called for an interface that might require protocol-level subscription, but the connection cannot set up that subscription yet (for instance because the Status is not Connected yet), the Connection MUST remember the client's interest, and attempt to subscribe to the appropriate protocol feature when this becomes possible.

Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.

The only reason it could fail is if it's unimplemented, in which case the only thing the client can usefully do is to proceed as if it had succeeded.

Interfaces or parts of interfaces in which to register an interest, represented by either a DBus_Interface, or a string prefixed with a DBus_Interface.

If the Connection does not support one of these tokens, this is not considered to be an error; the unsupported token is simply ignored.

Release an interest registered using AddClientInterest. See that method's documentation for details.

Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.

The only reasons it could fail are if it's unimplemented, or if the client's reference-counting is wrong and it has tried to remove a client interest that it did not add. In both cases, there's nothing the client could do about it.

Interfaces or parts of interfaces that were previously passed to AddClientInterest.

True if handles last for the whole lifetime of the Connection. This SHOULD be the case in all connection managers, but clients MUST interoperate with older connection managers (which reference-count handles).

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:

cmname is the same Connection_Manager_Name that appears in the connection manager's object path and well-known bus name
proto is the Protocol name as seen in ListProtocols, but with "-" replaced with "_" to get a valid object path/bus name
account is some non-empty sequence of ASCII letters, digits and underscores not starting with a digit

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 GetInterfaces method.

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 RequestHandles method, inspect the entity identifier with the InspectHandles method, keep handles from being released with HoldHandles, and notify that they are no longer storing handles with ReleaseHandles.

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. The Requests and Contacts interfaces are now mandatory. Their functionality will be merged into the main Connection interface at some point in future.