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 Library 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 0 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.

The connection is already connecting or connected

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object. An array of D-Bus interface names Get the optional interfaces supported by this connection.

A string identifier for the protocol Get the protocol this connection is using. An integer handle representing the user Get 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 Renamed signal on the Renaming interface (if present). This is always a CONTACT type handle.

An integer representing the current status Get the current status as defined in the StatusChanged signal. The type of handle to be held A array of integer handles to hold

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 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 ReleaseHandle 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 handle names in the same order as the given numbers 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

An array of structs representing channels. List all the channels which currently exist on this connection.

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, which is zero if no handle is specified A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched Emitted when a new Channel object is created, either through user request or incoming information from the service. The suppress_handler boolean indicates if the channel was requested by an existing client, or is an incoming communication and needs to have a handler launched. An integer handle type (as defined in RequestHandle) An array of integer handles being held by the client 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.

The handle type is invalid One of the given handles is not valid One of the given handles is not held by this client

A D-Bus interface name representing base channel type An integer representing the handle type, or zero if no handle is being specified A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is zero If true, the requesting client intends to take responsibility for displaying the channel to the user, so no other handler needs to be launched 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 GetHandle() returns 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

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) The type of handle required An array of names of entities to request handles for An array of integer handle numbers in the same order as the given strings 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 ReleaseHandle method. Where the name 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 handle type is invalid The given name is not a valid entity of the given type

The connection is alive and all methods are available. The connection has not yet been established, or has been severed and reconnection is being attempted. Some methods may fail until the connection has been established. The connection has been severed and no method calls are valid. The object may be removed from the bus at any time. There is no reason set for this state change. The change is in response to a user request. There was an error sending or receiving on the network socket. The username or password was invalid. There was an error negotiating SSL on this connection, or encryption was unavailable and require-encryption was set when the connection was created. Someone is already connected to the server using the name you are trying to connect with. The server did not provide a SSL certificate. The server's SSL certificate could not be trusted. The server's SSL certificate has expired. The server's SSL certificate is not yet valid. The server's SSL certificate did not match its hostname. The server's SSL certificate does not have the expected fingerprint. The server's SSL certificate is self-signed. There was some other error validating the server's SSL certificate. 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.

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.

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.Presence 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 GetInterfaces after the connection, has been established and must not change subsequently at runtime.

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