TelepathyGLib.BaseConnection¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`add_client_interest` (unique_name, token, only_if_uninterested)
	`add_possible_client_interest` (token)
	`change_status` (status, reason)
	`check_connected` ()
	`get_account_path_suffix` ()
	`get_bus_name` ()
	`get_handles` (handle_type)
	`get_object_path` ()
	`get_status` ()
	`is_destroyed` ()
	`register` (cm_name)
	`set_self_handle` (self_handle)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_connected` ()
	`do_connecting` ()
	`do_disconnected` ()
	`do_get_unique_connection_name` ()
	`do_shut_down` ()
	`do_start_connecting` ()

Properties¶

Name	Type	Flags	Short Description
`account-path-suffix`	`str`	r/w/co	The suffix of the account path
`has-immortal-handles`	`bool`	r	Always `True`

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`clients-interested`	Emitted when a client becomes interested in any token that was added with `TelepathyGLib.BaseConnection.add_possible_client_interest`().
`clients-uninterested`	Emitted when no more clients are interested in an interface added with `TelepathyGLib.BaseConnection.add_possible_client_interest`(), for which `TelepathyGLib.BaseConnection` `::clients-interested` was previously emitted.
`shutdown-finished`	Emitted by tp_base_connection_finish_shutdown() when the underlying network connection has been closed; #TpBaseConnectionManager listens for this signal and removes connections from its table of active connections when it is received.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access
bus_name	`str`	r
object_path	`str`	r
parent	`GObject.Object`	r
self_handle	`int`	r
status	`TelepathyGLib.ConnectionStatus`	r

Class Details¶

class TelepathyGLib.BaseConnection(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: TelepathyGLib.BaseConnectionClass

Data structure representing a generic #TpSvcConnection implementation.

Since 0.19.1, accessing the fields of this structure is deprecated. Use TelepathyGLib.BaseConnection.get_bus_name(), TelepathyGLib.BaseConnection.get_object_path(), TelepathyGLib.BaseConnection.get_status(), tp_base_connection_get_self_handle() instead.

add_client_interest(unique_name, token, only_if_uninterested)¶

Parameters:

unique_name (str) – the unique bus name of a D-Bus client
token (str) – a D-Bus interface or a token representing part of an interface, added with TelepathyGLib.BaseConnection.add_possible_client_interest()
only_if_uninterested (bool) – only add to the interest count if the client is not already interested (appropriate for APIs that implicitly subscribe on first use if this has not been done already, like Location)

Add a “client interest” for token on behalf of the given client.

This emits TelepathyGLib.BaseConnection ::clients-interested if this was the first time a client expressed an interest in this token.

add_possible_client_interest(token)¶

Parameters:: token (int) – a quark corresponding to a D-Bus interface, or a token representing part of a D-Bus interface, for which this connection wishes to be notified when clients register an interest

Add token to the set of tokens for which this connection will emit TelepathyGLib.BaseConnection ::clients-interested and TelepathyGLib.BaseConnection ::clients-uninterested.

This method must be called from the GObject.ObjectClass .constructed or GObject.ObjectClass .constructor callback (otherwise, it will run too late to be useful).

change_status(status, reason)¶

Parameters:

status (TelepathyGLib.ConnectionStatus) – The new status
reason (TelepathyGLib.ConnectionStatusReason) – The reason for the status change

Change the status of the connection. The allowed state transitions are:

TelepathyGLib.INTERNAL_CONNECTION_STATUS_NEW → TelepathyGLib.ConnectionStatus.CONNECTING
TelepathyGLib.ConnectionStatus.CONNECTING → TelepathyGLib.ConnectionStatus.CONNECTED
TelepathyGLib.INTERNAL_CONNECTION_STATUS_NEW → TelepathyGLib.ConnectionStatus.CONNECTED (exactly equivalent to both of the above one after the other; see below)
anything except TelepathyGLib.ConnectionStatus.DISCONNECTED → TelepathyGLib.ConnectionStatus.DISCONNECTED

Before the transition to TelepathyGLib.ConnectionStatus.CONNECTED, the implementation must have discovered the handle for the local user and passed it to TelepathyGLib.BaseConnection.set_self_handle().

Changing from NEW to CONNECTED is implemented by doing the transition from NEW to CONNECTING, followed by the transition from CONNECTING to CONNECTED; it’s exactly equivalent to calling TelepathyGLib.BaseConnection.change_status for those two transitions one after the other.

Any other valid transition does the following, in this order:

Update TelepathyGLib.BaseConnection .status;
If the new state is TelepathyGLib.ConnectionStatus.DISCONNECTED, call tp_channel_factory_iface_close_all() on all channel factories
Emit the D-Bus StatusChanged signal;
Call TelepathyGLib.BaseConnectionClass.connecting, TelepathyGLib.BaseConnectionClass.connected or TelepathyGLib.BaseConnectionClass.disconnected as appropriate;
Call the channel factories’ status change callbacks;
If the new state is TelepathyGLib.ConnectionStatus.DISCONNECTED, call the subclass’ TelepathyGLib.BaseConnectionClass.shut_down callback.

To provide more details about what happened when moving to status TelepathyGLib.ConnectionStatus.DISCONNECTED due to an error, consider calling tp_base_connection_disconnect_with_dbus_error() instead of this function.

Changed in 0.7.35: the self_handle member of TelepathyGLib.BaseConnection was previously set to 0 at this stage. It now remains non-zero until the object is disposed.

check_connected()¶

Raises:: GLib.Error
Returns:: True if this connection is connected
Return type:: bool

Return whether this connection is fully active and connected. If it is not, raise TelepathyGLib.Error.DISCONNECTED.

This is equivalent to checking whether TelepathyGLib.BaseConnection.get_status() returns TelepathyGLib.ConnectionStatus.CONNECTED; it is provided because methods on the connection often need to make this check, and return a GLib.Error if it fails.

New in version 0.19.1.

get_account_path_suffix()¶

Returns:: the same value has the TelepathyGLib.BaseConnection :account-path-suffix property.
Return type:: str

New in version 0.23.2.

get_bus_name()¶

Returns:: the bus name of this connection, or None
Return type:: str or None

Return the bus name starting with TelepathyGLib.CONN_BUS_NAME_BASE that represents this connection on D-Bus.

The returned string belongs to the TelepathyGLib.BaseConnection and must be copied by the caller if it will be kept.

If this connection has never been present on D-Bus (TelepathyGLib.BaseConnection.register() has never been called), return None instead.

New in version 0.19.1.

get_handles(handle_type)¶

Parameters:: handle_type (TelepathyGLib.HandleType) – The handle type
Returns:: the handle repository corresponding to the given handle type, or None if it’s unsupported or invalid.
Return type:: TelepathyGLib.HandleRepoIface

<!—->

get_object_path()¶

Returns:: the object path of this connection, or None
Return type:: str or None

Return the object path starting with TelepathyGLib.CONN_OBJECT_PATH_BASE that represents this connection on D-Bus.

The returned string belongs to the TelepathyGLib.BaseConnection and must be copied by the caller if it will be kept.

If this connection has never been present on D-Bus (TelepathyGLib.BaseConnection.register() has never been called), return None instead.

New in version 0.19.1.

get_status()¶

Returns:: the value of TelepathyGLib.BaseConnection :dbus-status
Return type:: TelepathyGLib.ConnectionStatus

Return the status of this connection, as set by TelepathyGLib.BaseConnection.change_status() or similar functions like tp_base_connection_disconnect_with_dbus_error().

Like the corresponding D-Bus property, this method returns TelepathyGLib.ConnectionStatus.DISCONNECTED in two situations: either the connection is newly-created (and has never emitted #TpSvcConnection::status-changed), or D-Bus clients have already been told that it has been destroyed (by the Disconnect D-Bus method, a failed attempt to connect, or loss of an established connection). Use TelepathyGLib.BaseConnection.is_destroyed() to distinguish between the two.

New in version 0.19.1.

is_destroyed()¶

Returns:: True if this connection is disappearing from D-Bus
Return type:: bool

Return whether this connection has already emitted the D-Bus signal indicating that it has been destroyed.

In particular, this can be used to distinguish between the two reasons why TelepathyGLib.BaseConnection.get_status() would return TelepathyGLib.ConnectionStatus.DISCONNECTED: it will return False if the connection is newly-created, and True if the Disconnect D-Bus method has been called, an attempt to connect has failed, or an established connection has encountered an error.

New in version 0.19.1.

register(cm_name)¶

Parameters:

cm_name (str) – The name of the connection manager in the Telepathy protocol

Raises:

GLib.Error

Returns:

True on success, False on error.

bus_name:: Used to return the bus name corresponding to the connection if True is returned. To be freed by the caller.
object_path:: Used to return the object path of the connection if True is returned. To be freed by the caller.

Return type:

(bool, bus_name: str, object_path: str)

Make the connection object appear on the bus, returning the bus name and object path used. If True is returned, the connection owns the bus name, and will release it when destroyed.

Since 0.11.11, bus_name and object_path may be None if the strings are not needed.

set_self_handle(self_handle)¶

Parameters:: self_handle (int) – The new self handle for the connection.

Sets the TelepathyGLib.BaseConnection :self-handle property. self_handle may not be 0 once the connection has moved to the CONNECTED state.

New in version 0.7.15.

do_connected() virtual¶: If set by subclasses, will be called just after the state changes to CONNECTED. May be None if nothing special needs to happen.

do_connecting() virtual¶: If set by subclasses, will be called just after the state changes to CONNECTING. May be None if nothing special needs to happen.

do_disconnected() virtual¶: If set by subclasses, will be called just after the state changes to DISCONNECTED. May be None if nothing special needs to happen.

do_get_unique_connection_name() virtual¶

Returns:: a name for this connection which will be unique within this connection manager process, as a string which the caller must free with GLib.free.
Return type:: str

Construct a unique name for this connection (for example using the protocol’s format for usernames). If None (the default), a unique name will be generated. Subclasses should usually override this to get more obvious names, to aid debugging and prevent multiple connections to the same account.

do_shut_down() virtual¶: Called after disconnected() is called, to clean up the connection. Must start the shutdown process for the underlying network connection, and arrange for tp_base_connection_finish_shutdown() to be called after the underlying connection has been closed. May not be left as None.

do_start_connecting() virtual¶

Returns:: False if failure has already occurred, else True.
Return type:: bool

Asynchronously start connecting - called to implement the Connect D-Bus method. See TelepathyGLib.BaseConnectionStartConnectingImpl for details. May not be left as None.

Signal Details¶

TelepathyGLib.BaseConnection.signals.clients_interested(base_connection, token)¶

Signal Name:

clients-interested

Flags:

RUN_LAST, DETAILED

Parameters:

base_connection (TelepathyGLib.BaseConnection) – The object which received the signal
token (str) – the interface or part of an interface in which clients are newly interested

Emitted when a client becomes interested in any token that was added with TelepathyGLib.BaseConnection.add_possible_client_interest().

The “signal detail” is a GQuark representing token. Modules implementing an interface (Location, say) should typically connect to a detailed signal like “clients-interested::org.freedesktop.Telepathy.Connection.Interface.Location” rather than receiving all emissions of this signal.

TelepathyGLib.BaseConnection.signals.clients_uninterested(base_connection, token)¶

Signal Name:

clients-uninterested

Flags:

RUN_LAST, DETAILED

Parameters:

base_connection (TelepathyGLib.BaseConnection) – The object which received the signal
token (str) – the interface or part of an interface in which clients are no longer interested

Emitted when no more clients are interested in an interface added with TelepathyGLib.BaseConnection.add_possible_client_interest(), for which TelepathyGLib.BaseConnection ::clients-interested was previously emitted.

As with TelepathyGLib.BaseConnection ::clients-interested, the “signal detail” is a GQuark representing token. Modules implementing an interface (Location, say) should typically connect to a detailed signal like “clients-uninterested::org.freedesktop.Telepathy.Connection.Interface.Location” rather than receiving all emissions of this signal.

TelepathyGLib.BaseConnection.signals.shutdown_finished()¶

Signal Name:: shutdown-finished
Flags:: RUN_LAST, DETAILED

Emitted by tp_base_connection_finish_shutdown() when the underlying network connection has been closed; #TpBaseConnectionManager listens for this signal and removes connections from its table of active connections when it is received.

Property Details¶

TelepathyGLib.BaseConnection.props.account_path_suffix¶

Name:: account-path-suffix
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The suffix of the account object path such as “gabble/jabber/chris_40example_2ecom0” for the account whose object path is TelepathyGLib.ACCOUNT_OBJECT_PATH_BASE + “gabble/jabber/chris_40example_2ecom0”. The same as returned by TelepathyGLib.Account.get_path_suffix().

It is given by the AccountManager in the connection parameters. Or None if the ConnectionManager or the AccountManager are too old.

New in version 0.23.2.

TelepathyGLib.BaseConnection.props.has_immortal_handles¶

Name:: has-immortal-handles
Type:: bool
Default Value:: True
Flags:: READABLE

This property is not useful to use directly. Its value is True, to indicate that this version of telepathy-glib never unreferences handles until the connection becomes disconnected.

New in version 0.13.8.