TelepathyGLib.Connection¶

Subclasses:: None

Methods¶

Inherited:: TelepathyGLib.Proxy (11), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`get_feature_quark_aliasing` ()
class	`get_feature_quark_avatar_requirements` ()
class	`get_feature_quark_balance` ()
class	`get_feature_quark_capabilities` ()
class	`get_feature_quark_connected` ()
class	`get_feature_quark_contact_blocking` ()
class	`get_feature_quark_contact_groups` ()
class	`get_feature_quark_contact_info` ()
class	`get_feature_quark_contact_list` ()
class	`get_feature_quark_contact_list_properties` ()
class	`get_feature_quark_core` ()
class	`init_known_interfaces` ()
class	`new` (dbus, bus_name, object_path)
class	`presence_type_cmp_availability` (p1, p2)
	`add_client_interest` (interested_in)
	`add_to_group_async` (group, contacts, callback, *user_data)
	`add_to_group_finish` (result)
	`authorize_publication_async` (contacts, callback, *user_data)
	`authorize_publication_finish` (result)
	`bind_connection_status_to_property` (target, target_property, invert)
	`block_contacts_async` (contacts, report_abusive, callback, *user_data)
	`block_contacts_finish` (result)
	`can_report_abusive` ()
	`can_set_contact_alias` ()
	`disconnect_async` (callback, *user_data)
	`disconnect_finish` (result)
	`dup_contact_by_id_async` (id, features, callback, *user_data)
	`dup_contact_by_id_finish` (result)
	`dup_contact_if_possible` (handle, identifier)
	`dup_contact_info_supported_fields` ()
	`dup_contact_list` ()
	`dup_detailed_error_vardict` ()
	`get_account` ()
	`get_avatar_requirements` ()
	`get_balance` ()
	`get_balance_uri` ()
	`get_blocked_contacts` ()
	`get_can_change_contact_list` ()
	`get_capabilities` ()
	`get_cm_name` ()
	`get_connection_manager_name` ()
	`get_contact_attributes` (timeout_ms, handles, interfaces, hold, callback, user_data, weak_object)
	`get_contact_groups` ()
	`get_contact_info_flags` ()
	`get_contact_info_supported_fields` ()
	`get_contact_list_attributes` (timeout_ms, interfaces, hold, callback, user_data, weak_object)
	`get_contact_list_persists` ()
	`get_contact_list_state` ()
	`get_contacts_by_handle` (handles, features, callback, user_data, weak_object)
	`get_contacts_by_id` (ids, features, callback, user_data, weak_object)
	`get_detailed_error` ()
	`get_disjoint_groups` ()
	`get_group_storage` ()
	`get_protocol_name` ()
	`get_request_uses_message` ()
	`get_self_contact` ()
	`get_self_handle` ()
	`get_status` ()
	`has_immortal_handles` ()
	`hold_handles` (timeout_ms, handle_type, handles, callback, user_data, weak_object)
	`parse_object_path` ()
	`refresh_contact_info` (contacts)
	`remove_contacts_async` (contacts, callback, *user_data)
	`remove_contacts_finish` (result)
	`remove_from_group_async` (group, contacts, callback, *user_data)
	`remove_from_group_finish` (result)
	`remove_group_async` (group, callback, *user_data)
	`remove_group_finish` (result)
	`rename_group_async` (old_name, new_name, callback, *user_data)
	`rename_group_finish` (result)
	`request_handles` (timeout_ms, handle_type, ids, callback, user_data, weak_object)
	`request_subscription_async` (contacts, message, callback, *user_data)
	`request_subscription_finish` (result)
	`set_contact_info_async` (info, callback, *user_data)
	`set_contact_info_finish` (result)
	`set_group_members_async` (group, contacts, callback, *user_data)
	`set_group_members_finish` (result)
	`unblock_contacts_async` (contacts, callback, *user_data)
	`unblock_contacts_finish` (result)
	`unpublish_async` (contacts, callback, *user_data)
	`unpublish_finish` (result)
	`unref_handles` (handle_type, handles)
	`unsubscribe_async` (contacts, callback, *user_data)
	`unsubscribe_finish` (result)
	`upgrade_contacts` (contacts, features, callback, user_data, weak_object)
	`upgrade_contacts_async` (contacts, features, callback, *user_data)
	`upgrade_contacts_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: TelepathyGLib.Proxy (5)

Name	Type	Flags	Short Description
`balance`	`int`	r	The Amount field of the Account Balance
`balance-currency`	`str`	r	The Currency field of the Account Balance
`balance-scale`	`int`	r	The Scale field of the Account Balance
`balance-uri`	`str`	r	The URI for managing the account balance
`blocked-contacts`	`GLib.PtrArray`	r	Blocked contacts
`can-change-contact-list`	`bool`	r	Whether the contact list can change
`can-report-abusive`	`bool`	r	Can report abusive
`capabilities`	`TelepathyGLib.Capabilities`	r	A `TelepathyGLib.Capabilities` object representing the capabilities of the connection
`cm-name`	`str`	r	The connection’s connection manager name
`connection-manager-name`	`str`	r	The connection’s connection manager name `deprecated`
`connection-ready`	`bool`	d/r	Initially `False`; changes to `True` when introspection finishes `deprecated`
`contact-groups`	[`str`]	r	All existing contact groups
`contact-list-persists`	`bool`	r	Whether the contact list persists
`contact-list-state`	`int`	r	The state of the contact list
`disjoint-groups`	`bool`	r	Whether groups are disjoint
`group-storage`	`int`	r	Group storage capabilities
`protocol-name`	`str`	r	The connection’s protocol name
`request-uses-message`	`bool`	r	Whether request uses message
`self-contact`	`TelepathyGLib.Contact`	r	The local user’s Contact object on this connection
`self-handle`	`int`	r	The local user’s Contact handle on this connection `deprecated`
`status`	`int`	r	The status of this connection
`status-reason`	`int`	r	The reason why `TelepathyGLib.Connection` `:status` changed to its current value

Signals¶

Inherited:: TelepathyGLib.Proxy (2), GObject.Object (1)

Name	Short Description
`balance-changed`	Emitted when at least one of the `TelepathyGLib.Connection` `:balance`, `TelepathyGLib.Connection` `:balance-scale` or `TelepathyGLib.Connection` `:balance-currency` property is changed.
`blocked-contacts-changed`	Notify of changes in `TelepathyGLib.Connection` `:blocked-contacts`.
`contact-list-changed`	Notify of changes in the list of contacts as returned by `TelepathyGLib.Connection.dup_contact_list`().
`group-renamed`	Emitted when a group is renamed, in protocols where this can be distinguished from group creation, removal and membership changes.
`groups-created`	Emitted when new, empty groups are created.
`groups-removed`	Emitted when one or more groups are removed.

Fields¶

Inherited:: TelepathyGLib.Proxy (2), GObject.Object (1)

Name	Type	Access	Description
parent	`TelepathyGLib.Proxy`	r

Class Details¶

class TelepathyGLib.Connection(**kwargs)¶

Bases:: TelepathyGLib.Proxy
Abstract:: No
Structure:: TelepathyGLib.ConnectionClass

A proxy object for a Telepathy connection. There are no interesting public struct fields.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

New in version 0.7.1.

classmethod get_feature_quark_aliasing()¶

Return type:: int

classmethod get_feature_quark_avatar_requirements()¶

Return type:: int

classmethod get_feature_quark_balance()¶

Return type:: int

classmethod get_feature_quark_capabilities()¶

Return type:: int

classmethod get_feature_quark_connected()¶

Return type:: int

classmethod get_feature_quark_contact_blocking()¶

Return type:: int

classmethod get_feature_quark_contact_groups()¶

Return type:: int

classmethod get_feature_quark_contact_info()¶

Return type:: int

classmethod get_feature_quark_contact_list()¶

Return type:: int

classmethod get_feature_quark_contact_list_properties()¶

Return type:: int

classmethod get_feature_quark_core()¶

Return type:: int

classmethod init_known_interfaces()¶: Ensure that the known interfaces for TelepathyGLib.Connection have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling tp_proxy_or_subclass_hook_on_interface_add() with first argument %TP_TYPE_CONNECTION.

New in version 0.7.6.

classmethod new(dbus, bus_name, object_path)¶

Parameters:

dbus (TelepathyGLib.DBusDaemon) – a D-Bus daemon; may not be None
bus_name (str or None) – the well-known or unique name of the connection process; if well-known, this function will make a blocking call to the bus daemon to resolve the unique name. May be None if object_path is not, in which case a well-known name will be derived from object_path.
object_path (str or None) – the object path of the connection process. May be None if bus_name is a well-known name, in which case the object path will be derived from bus_name.

Raises:

GLib.Error

Returns:

a new connection proxy, or None if unique-name resolution fails or on invalid arguments

Return type:

TelepathyGLib.Connection

New in version 0.7.1.

Deprecated since version ???: Use TelepathyGLib.SimpleClientFactory.ensure_connection() instead.

classmethod presence_type_cmp_availability(p1, p2)¶

Parameters:

Returns:

-1, 0 or 1, if p1 is <, == or > than p2.

Return type:

int

Compares p1 and p2 like strcmp(). p1 > p2 means p1 is more available than p2.

The order used is: available > busy > away > xa > hidden > offline > error > unknown > unset

New in version 0.7.16.

add_client_interest(interested_in)¶

Parameters:: interested_in (str) – a string identifying an interface or part of an interface to which this connection will subscribe

Subscribe to any opt-in change notifications for interested_in.

For contact information, use TelepathyGLib.Contact instead, which will call this automatically.

New in version 0.11.3.

add_to_group_async(group, contacts, callback, *user_data)¶

Parameters:

group (str) – the group to alter.
contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to include in the group.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Add the given contacts to the given group, creating it if necessary.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

New in version 0.15.5.

add_to_group_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.add_to_group_async()

New in version 0.15.5.

authorize_publication_async(contacts, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to authorize
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

For each of the given contacts, request that the local user’s presence is sent to that contact, i.e. that their TelepathyGLib.Contact :publish-state property becomes TelepathyGLib.SubscriptionState.YES.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

New in version 0.15.5.

authorize_publication_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.authorize_publication_async()

New in version 0.15.5.

bind_connection_status_to_property(target, target_property, invert)¶

Parameters:

target (object or None) – the target GObject.Object
target_property (str) – the property on target to bind (must be GObject.TYPE_BOOLEAN)
invert (bool) – True if you wish to invert the value of target_property (i.e. False if connected)

Returns:

the GObject.Binding instance representing the binding between the self and the target. The binding is released whenever the GObject.Binding reference count reaches zero.

Return type:

GObject.Binding

Binds the :status of self to the boolean property of another object using a GObject.Binding such that the target_property will be set to True when self is connected (and invert is False).

target_property will be synchronised immediately (GObject.BindingFlags.SYNC_CREATE). invert can be interpreted as analogous to GObject.BindingFlags.INVERT_BOOLEAN.

For instance, this function can be used to bind the GtkWidget:sensitive property to only make a widget sensitive when the account is connected.

See GObject.Object.bind_property() for more information.

New in version 0.13.16.

block_contacts_async(contacts, report_abusive, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to block
report_abusive (bool) – If True, report these contacts as abusive to the server administrators as well as blocking them. See TelepathyGLib.Connection :can-report-abusive to discover whether reporting abuse is supported. If TelepathyGLib.Connection :can-report-abusive is False, this parameter will be ignored.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Direct the server to block contacts.

New in version 0.17.0.

block_contacts_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.block_contacts_async()

New in version 0.17.0.

can_report_abusive()¶

Returns:: the value of TelepathyGLib.Connection :can-report-abusive
Return type:: bool

New in version 0.17.0.

can_set_contact_alias()¶

Return type:: bool

disconnect_async(callback, *user_data)¶

Parameters:

callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Disconnect the connection.

This method is intended for use by AccountManager implementations, such as Mission Control. To disconnect a connection managed by an AccountManager, either use TelepathyGLib.Account.request_presence_async() or TelepathyGLib.Account.set_enabled_async(), depending whether the intention is to put the account offline temporarily, or disable it longer-term.

New in version 0.17.5.

disconnect_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the call was successful, otherwise False
Return type:: bool

Interpret the result of TelepathyGLib.Connection.disconnect_async().

New in version 0.17.5.

dup_contact_by_id_async(id, features, callback, *user_data)¶

Parameters:

id (str) – A strings representing the desired contact by its identifier in the IM protocol (an XMPP JID, SIP URI, MSN Passport, AOL screen-name etc.)
features ([TelepathyGLib.ContactFeature] or None) – An array of features that must be ready for use (if supported) before the callback is called (may be None if n_features is 0)
callback (Gio.AsyncReadyCallback or None) – A user callback to call when the contact is ready
user_data (object or None) – Data to pass to the callback

Create a TelepathyGLib.Contact object and make any asynchronous method calls necessary to ensure that all the features specified in features are ready for use (if they are supported at all).

It is not an error to put features in features even if the connection manager doesn’t support them - users of this method should have a static list of features they would like to use if possible, and use it for all connection managers.

New in version 0.19.0.

dup_contact_by_id_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: a TelepathyGLib.Contact or None on error.
Return type:: TelepathyGLib.Contact

Finishes TelepathyGLib.Connection.dup_contact_by_id_async().

New in version 0.19.0.

dup_contact_if_possible(handle, identifier)¶

Parameters:

handle (int) – a handle of type TelepathyGLib.HandleType.CONTACT
identifier (str) – the normalized identifier (XMPP JID, etc.) corresponding to handle, or None if not known

Returns:

a contact or None

Return type:

TelepathyGLib.Contact

Try to return an existing contact object or create a new contact object immediately.

If TelepathyGLib.Connection.has_immortal_handles() would return True and identifier is non-None, this function always succeeds.

On connections without immortal handles, it is not possible to guarantee that handle remains valid without making asynchronous D-Bus calls, so it might be necessary to delay processing of messages or other events until a TelepathyGLib.Contact can be constructed asynchronously, for instance by using TelepathyGLib.Connection.get_contacts_by_id().

Similarly, if identifier is None, it might not be possible to find the identifier for handle without making asynchronous D-Bus calls, so it might be necessary to delay processing of messages or other events until a TelepathyGLib.Contact can be constructed asynchronously, for instance by using TelepathyGLib.Connection.get_contacts_by_handle().

New in version 0.13.9.

dup_contact_info_supported_fields()¶

Returns:: a GLib.List of TelepathyGLib.ContactInfoFieldSpec struct, or None if the feature is not yet prepared or the connection doesn’t have the necessary properties.
Return type:: [TelepathyGLib.ContactInfoFieldSpec]

Returns a newly allocated GLib.List of supported contact info fields for this connection. The list must be freed with tp_contact_info_spec_list_free().

To wait for valid supported fields, call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_INFO.

This property cannot change after self goes to the Connected state.

New in version 0.19.9.

dup_contact_list()¶

Returns:: a new GLib.PtrArray of TelepathyGLib.Contact. Use g_ptr_array_unref() when done.
Return type:: [TelepathyGLib.Contact]

Retrieves the user’s contact list. In general, blocked contacts are not included in this list. The TelepathyGLib.Contact objects returned are guaranteed to have all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

Before calling this method, you must first call TelepathyGLib.Proxy.prepare_async() with the %TP_CONNECTION_FEATURE_CONTACT_LIST feature, and verify that TelepathyGLib.Connection :contact-list-state is set to TelepathyGLib.ContactListState.SUCCESS.

New in version 0.15.5.

dup_detailed_error_vardict()¶

Returns:

a D-Bus error name, or None.

details:: optionally used to return a %G_VARIANT_TYPE_VARDICT with details of the error

Return type:

(str or None, details: GLib.Variant)

If the connection has disconnected, return the D-Bus error name with which it disconnected (in particular, this is %TP_ERROR_STR_CANCELLED if it was disconnected by a user request).

Otherwise, return None, without altering details.

New in version 0.19.0.

get_account()¶

Returns:: the account associated with this connection, or None.
Return type:: TelepathyGLib.Account

Return the the TelepathyGLib.Account associated with this connection. Will return None if self was not acquired from a TelepathyGLib.Account via TelepathyGLib.Account.get_connection(), or if the account object got finalized in the meantime (TelepathyGLib.Connection does not keep a strong ref on its TelepathyGLib.Account).

New in version 0.15.5.

get_avatar_requirements()¶

Returns:: a TelepathyGLib.AvatarRequirements struct, or None if the feature is not yet prepared or the connection doesn’t have the necessary properties.
Return type:: TelepathyGLib.AvatarRequirements

To wait for valid avatar requirements, call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS.

This property cannot change after self goes to the Connected state.

New in version 0.11.4.

get_balance()¶

Returns:

True if the balance is valid (and the values set), False if the balance is invalid.

balance:: a pointer to store the account balance (or None)
scale:: a pointer to store the balance scale (or None)
currency:: a pointer to store the balance currency (or None)

Return type:

(bool, balance: int, scale: int, currency: str)

If self has a valid account balance, returns True and sets the variables pointed to by balance, scale and currency to the appropriate fields of the Balance.AccountBalance property.

The monetary value of the balance is expressed as a fixed-point number, balance, with a decimal scale defined by scale; for instance a balance of 1234 with scale of 2 represents a value of “12.34” in the currency represented by currency.

Requires %TP_CONNECTION_FEATURE_BALANCE to be prepared.

New in version 0.15.1.

get_balance_uri()¶

Returns:: the TelepathyGLib.Connection :balance-uri property.
Return type:: str

The value of Balance.ManageCreditURI.

Requires %TP_CONNECTION_FEATURE_BALANCE to be prepared.

New in version 0.15.1.

get_blocked_contacts()¶

Returns:: the value of TelepathyGLib.Connection :blocked-contacts
Return type:: [TelepathyGLib.Contact]

New in version 0.17.0.

get_can_change_contact_list()¶

Returns:: the value of TelepathyGLib.Connection :can-change-contact-list property
Return type:: bool

New in version 0.15.5.

get_capabilities()¶

Returns:: the same TelepathyGLib.Capabilities as the TelepathyGLib.Connection :capabilities property
Return type:: TelepathyGLib.Capabilities

New in version 0.11.3.

get_cm_name()¶

Returns:: the same as the TelepathyGLib.Connection :cm-name property
Return type:: str

New in version 0.19.3.

get_connection_manager_name()¶

Returns:: the same as the TelepathyGLib.Connection :connection-manager-name property
Return type:: str

New in version 0.13.16.

Deprecated since version ???: Use TelepathyGLib.Connection.get_cm_name() instead.

get_contact_attributes(timeout_ms, handles, interfaces, hold, callback, user_data, weak_object)¶

Parameters:

timeout_ms (int) – the timeout in milliseconds, or -1 to use the default
handles ([int]) – an array of handles
interfaces (str) – a #GStrv of interfaces
hold (bool) – if True, the callback will hold one reference to each valid handle
callback (GObject.Callback) – called on success or failure (unless weak_object has become unreferenced)
user_data (object or None) – arbitrary user-supplied data
weak_object (GObject.Object) – if not None, an object to be weakly referenced: if it is destroyed, callback will not be called

Return (via a callback) any number of attributes of the given handles.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by TelepathyGLib.Proxy ::invalidated). In earlier versions, if hold was True, the callback would hold a reference to them which could be released with TelepathyGLib.Connection.unref_handles().

This is a thin wrapper around the GetContactAttributes D-Bus method, and should be used in preference to tp_cli_connection_interface_contacts_call_get_contact_attributes(); mixing this function, TelepathyGLib.Connection.hold_handles(), TelepathyGLib.Connection.unref_handles(), and TelepathyGLib.Contact with direct use of the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods is unwise, as TelepathyGLib.Connection and TelepathyGLib.Contact perform client-side reference counting of handles. The TelepathyGLib.Contact API provides a higher-level abstraction which should usually be used instead.

callback will later be called with the attributes of those of the given handles that were valid. Invalid handles are simply omitted from the parameter to the callback.

If hold is True, the callback is given one reference to each handle that appears as a key in the callback’s attributes parameter.

Deprecated since version ???: Use TelepathyGLib.SimpleClientFactory.ensure_contact() instead.

get_contact_groups()¶

Returns:: the value of TelepathyGLib.Connection :contact-groups
Return type:: [str]

New in version 0.15.5.

get_contact_info_flags()¶

Returns:: a set of TelepathyGLib.ContactInfoFlags
Return type:: TelepathyGLib.ContactInfoFlags

Returns the flags describing how contact info (vCards) behaves on this connection

To wait for valid contact info flags, call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_INFO.

This property cannot change after self goes to the Connected state.

New in version 0.11.7.

get_contact_info_supported_fields()¶

Returns:: a GLib.List of TelepathyGLib.ContactInfoFieldSpec struct, or None if the feature is not yet prepared or the connection doesn’t have the necessary properties.
Return type:: [TelepathyGLib.ContactInfoFieldSpec]

Returns a newly allocated GLib.List of supported contact info fields for this connection. The list must be freed with g_list_free() after used.

Note that the TelepathyGLib.ContactInfoFieldSpec s in the returned GLib.List are not dupped before returning from this function. One could copy every item in the list using tp_contact_info_field_spec_copy().

To wait for valid supported fields, call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_INFO.

This property cannot change after self goes to the Connected state.

New in version 0.11.7.

Deprecated since version 0.19.9: New code should use TelepathyGLib.Connection.dup_contact_info_supported_fields() instead.

get_contact_list_attributes(timeout_ms, interfaces, hold, callback, user_data, weak_object)¶

Parameters:

timeout_ms (int) – the timeout in milliseconds (using a large timeout is recommended)
interfaces (str) – a #GStrv of interfaces
hold (bool) – if True, the callback will hold one reference to each handle it receives
callback (GObject.Callback) – called on success or failure (unless weak_object has become unreferenced)
user_data (object or None) – arbitrary user-supplied data
weak_object (GObject.Object) – if not None, an object to be weakly referenced: if it is destroyed, callback will not be called

Return (via a callback) the contacts on the contact list and any number of their attributes.

Since telepathy-glib version 0.13.8, the handles will remain valid until connection becomes invalid (signalled by TelepathyGLib.Proxy ::invalidated). In earlier versions, if hold was True, the callback would hold a reference to them which could be released with TelepathyGLib.Connection.unref_handles().

This is a thin wrapper around the RequestContactList D-Bus method, and should be used in preference to lower-level functions; it is similar to TelepathyGLib.Connection.get_contact_attributes().

The TelepathyGLib.Contact API provides a higher-level abstraction which should usually be used instead.

If hold is True, the callback is given a reference to each handle that appears as a key in the callback’s attributes parameter.

Deprecated since version ???: Use TelepathyGLib.Connection.dup_contact_list() instead.

get_contact_list_persists()¶

Returns:: the value of TelepathyGLib.Connection :contact-list-persists property
Return type:: bool

New in version 0.15.5.

get_contact_list_state()¶

Returns:: the value of TelepathyGLib.Connection :contact-list-state property
Return type:: TelepathyGLib.ContactListState

New in version 0.15.5.

get_contacts_by_handle(handles, features, callback, user_data, weak_object)¶

Parameters:

handles ([int]) – An array of handles of type TelepathyGLib.HandleType.CONTACT representing the desired contacts
features ([int] or None) – An array of features that must be ready for use (if supported) before the callback is called (may be None if n_features is 0)
callback (TelepathyGLib.ConnectionContactsByHandleCb) – A user callback to call when the contacts are ready
user_data (object or None) – Data to pass to the callback
weak_object (GObject.Object or None) – An object to pass to the callback, which will be weakly referenced; if this object is destroyed, the operation will be cancelled

Create a number of TelepathyGLib.Contact objects and make asynchronous method calls to hold their handles and ensure that all the features specified in features are ready for use (if they are supported at all).

It is not an error to put features in features even if the connection manager doesn’t support them - users of this method should have a static list of features they would like to use if possible, and use it for all connection managers.

New in version 0.7.18.

Deprecated since version ???: Use TelepathyGLib.SimpleClientFactory.ensure_contact() instead.

get_contacts_by_id(ids, features, callback, user_data, weak_object)¶

Parameters:

ids ([str]) – An array of strings representing the desired contacts by their identifiers in the IM protocol (XMPP JIDs, SIP URIs, MSN Passports, AOL screen-names etc.)
features ([TelepathyGLib.ContactFeature] or None) – An array of features that must be ready for use (if supported) before the callback is called (may be None if n_features is 0)
callback (TelepathyGLib.ConnectionContactsByIdCb) – A user callback to call when the contacts are ready
user_data (object or None) – Data to pass to the callback
weak_object (GObject.Object or None) – An object to pass to the callback, which will be weakly referenced; if this object is destroyed, the operation will be cancelled

Create a number of TelepathyGLib.Contact objects and make asynchronous method calls to obtain their handles and ensure that all the features specified in features are ready for use (if they are supported at all).

It is not an error to put features in features even if the connection manager doesn’t support them - users of this method should have a static list of features they would like to use if possible, and use it for all connection managers.

New in version 0.7.18.

Deprecated since version ???: Use TelepathyGLib.Connection.dup_contact_by_id_async() instead.

get_detailed_error()¶

Returns:

a D-Bus error name, or None.

details:: optionally used to return a map from string to GObject.Value, which must not be modified or destroyed by the caller

Return type:

(str or None, details: {str: GObject.Value})

If the connection has disconnected, return the D-Bus error name with which it disconnected (in particular, this is %TP_ERROR_STR_CANCELLED if it was disconnected by a user request).

Otherwise, return None, without altering details.

New in version 0.11.4.

get_disjoint_groups()¶

Returns:: the value of TelepathyGLib.Connection :disjoint-groups
Return type:: bool

New in version 0.15.5.

get_group_storage()¶

Returns:: the value of TelepathyGLib.Connection :group-storage
Return type:: TelepathyGLib.ContactMetadataStorageType

New in version 0.15.5.

get_protocol_name()¶

Returns:: the same as the TelepathyGLib.Connection :protocol-name property
Return type:: str

New in version 0.13.16.

get_request_uses_message()¶

Returns:: the value of TelepathyGLib.Connection :request-uses-message property
Return type:: bool

New in version 0.15.5.

get_self_contact()¶

Returns:: the value of the TelepathyGLib.Connection :self-contact property, which may be None
Return type:: TelepathyGLib.Contact

Return a TelepathyGLib.Contact representing the local user on this connection.

The returned object is not necessarily valid after the main loop is re-entered; ref it with GObject.Object.ref() if you want to keep it.

New in version 0.13.9.

get_self_handle()¶

Returns:: the value of the TelepathyGLib.Connection :self-handle property
Return type:: int

Return the TelepathyGLib.HandleType.CONTACT handle of the local user on this connection, or 0 if the self-handle is not known yet or the connection has become invalid (the TelepathyGLib.Proxy ::invalidated signal).

The returned handle is not necessarily valid forever (the notify::self-handle signal will be emitted if it changes, which can happen on protocols such as IRC). Construct a TelepathyGLib.Contact object if you want to track the local user’s identifier in the protocol, or other information like their presence status, over time.

New in version 0.7.26.

Deprecated since version ???: Use TelepathyGLib.Connection.get_self_contact() instead.

get_status()¶

Returns:

This connection’s status, or TelepathyGLib.UNKNOWN_CONNECTION_STATUS if we don’t know yet.

reason:: a TelepathyGLib.ConnectionStatusReason, or None

Return type:

(TelepathyGLib.ConnectionStatus, reason: TelepathyGLib.ConnectionStatusReason)

If reason is not None it is set to the reason why “status” changed to its current value, or TelepathyGLib.ConnectionStatusReason.NONE_SPECIFIED if unknown.

New in version 0.7.14.

has_immortal_handles()¶

Returns:: True if handles last as long as the connection itself
Return type:: bool

Return True if this connection is known to not destroy handles (#TpHandle) until it disconnects.

On such connections, if you know that a handle maps to a particular identifier now, then you can rely on that handle mapping to that identifier for the whole lifetime of the connection.

hold_handles(timeout_ms, handle_type, handles, callback, user_data, weak_object)¶

Parameters:

timeout_ms (int) – the timeout in milliseconds, or -1 to use the default
handle_type (TelepathyGLib.HandleType) – the handle type
handles ([int]) – an array of handles
callback (TelepathyGLib.ConnectionHoldHandlesCb) – called on success or failure (unless weak_object has become unreferenced)
user_data (object or None) – arbitrary user-supplied data
weak_object (GObject.Object) – if not None, an object to be weakly referenced: if it is destroyed, callback will not be called

Hold (ensure a reference to) the given handles, if they are valid.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

This function, along with TelepathyGLib.Connection.unref_handles(), TelepathyGLib.Connection.get_contact_attributes() and TelepathyGLib.Contact, keeps a client-side reference count of handles; you should not use the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods directly as well as these functions.

Deprecated since version ???: Holding handles is not needed with Connection Managers having immortal handles (any Connection Manager using telepathy-glib >= 0.13.8). Other Connection Managers are considered deprecated, clients wanting to still support them should continue using this deprecated function.

parse_object_path()¶

Returns:

True if the object path was correctly parsed, False otherwise.

protocol:: If not None, used to return the protocol of the connection
cm_name:: If not None, used to return the connection manager name of the connection

Return type:

(bool, protocol: str, cm_name: str)

If the object path of connection is in the correct form, set protocol and cm_name, return True. Otherwise leave them unchanged and return False.

New in version 0.7.27.

Deprecated since version ???: Use TelepathyGLib.Connection.get_protocol_name() and TelepathyGLib.Connection.get_connection_manager_name() instead.

refresh_contact_info(contacts)¶

Parameters:: contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects associated with self

Requests to refresh the TelepathyGLib.Contact :contact-info property on each contact from contacts, requesting it from the network if an up-to-date version is not cached locally. “notify::contact-info” will be emitted when the contact’s information are updated.

If TelepathyGLib.ContactFeature.CONTACT_INFO is not yet set on a contact, it will be set before its property gets updated.

New in version 0.11.7.

remove_contacts_async(contacts, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to remove
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Remove the given contacts from the contact list entirely. It is protocol-dependent whether this works, and under which circumstances.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

New in version 0.15.5.

remove_contacts_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.remove_contacts_async()

New in version 0.15.5.

remove_from_group_async(group, contacts, callback, *user_data)¶

Parameters:

group (str) – the group to alter.
contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to remove from the group.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Remove the given contacts from the given group. If there are no members left in the group afterwards, the group MAY itself be removed.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

New in version 0.15.5.

remove_from_group_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.remove_from_group_async()

New in version 0.15.5.

remove_group_async(group, callback, *user_data)¶

Parameters:

group (str) – the group to remove.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Remove all members from the given group, then remove the group itself.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

New in version 0.15.5.

remove_group_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.remove_group_async()

New in version 0.15.5.

rename_group_async(old_name, new_name, callback, *user_data)¶

Parameters:

old_name (str) – the group to rename
new_name (str) – the new name for the group
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Rename the given old_name.

On protocols where groups behave like tags, this is an API short-cut for adding all of the group’s members to a group with the new name, then removing the old group.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

New in version 0.15.5.

rename_group_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.rename_group_async()

New in version 0.15.5.

request_handles(timeout_ms, handle_type, ids, callback, user_data, weak_object)¶

Parameters:

timeout_ms (int) – the timeout in milliseconds, or -1 to use the default
handle_type (TelepathyGLib.HandleType) – the handle type
ids ([str]) – an array of string identifiers for which handles are required, terminated by None (must not be None or empty)
callback (TelepathyGLib.ConnectionRequestHandlesCb) – called on success or failure (unless weak_object has become unreferenced)
user_data (object or None) – arbitrary user-supplied data
weak_object (GObject.Object) – if not None, an object to be weakly referenced: if it is destroyed, callback will not be called

Request the handles corresponding to the given identifiers, and if they are valid, hold (ensure a reference to) the corresponding handles.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

Deprecated since version ???: If handle_type is TelepathyGLib.HandleType.CONTACT, use TelepathyGLib.Connection.dup_contact_by_id_async() instead. For channel requests, use TelepathyGLib.AccountChannelRequest.set_target_id() instead.

request_subscription_async(contacts, message, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to whom requests are to be sent.
message (str) – an optional plain-text message from the user, to send to those contacts with the subscription request.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Request that the given contacts allow the local user to subscribe to their presence, i.e. that their TelepathyGLib.Contact :subscribe-state property becomes TelepathyGLib.SubscriptionState.YES.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

New in version 0.15.5.

request_subscription_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.request_subscription_async()

New in version 0.15.5.

set_contact_info_async(info, callback, *user_data)¶

Parameters:

info ([TelepathyGLib.ContactInfoField]) – a GLib.List of TelepathyGLib.ContactInfoField
callback (Gio.AsyncReadyCallback or None) – a callback to call when the request is satisfied
user_data (object or None) – data to pass to callback

Requests an asynchronous set of the contact info of self. When the operation is finished, callback will be called. You can then call TelepathyGLib.Connection.set_contact_info_finish() to get the result of the operation.

This method should not be expected to succeed if the result of TelepathyGLib.Connection.get_contact_info_flags() does not include TelepathyGLib.ContactInfoFlags.CAN_SET.

New in version 0.11.7.

set_contact_info_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the request call was successful, otherwise False
Return type:: bool

Finishes an async set of self info.

New in version 0.11.7.

set_group_members_async(group, contacts, callback, *user_data)¶

Parameters:

group (str) – the group to alter.
contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects members for the group. If this set is empty, this method MAY remove the group.
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Add the given contacts to the given group (creating it if necessary), and remove all other members.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS.

New in version 0.15.5.

set_group_members_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.set_group_members_async()

New in version 0.15.5.

unblock_contacts_async(contacts, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to block
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Direct the server to unblock contacts.

New in version 0.17.0.

unblock_contacts_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.unblock_contacts_async()

New in version 0.17.0.

unpublish_async(contacts, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to remove
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Attempt to set the given contacts' TelepathyGLib.Contact :publish-state property to TelepathyGLib.SubscriptionState.NO, i.e. stop sending presence to them.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

New in version 0.15.5.

unpublish_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.unpublish_async()

New in version 0.15.5.

unref_handles(handle_type, handles)¶

Parameters:

handle_type (TelepathyGLib.HandleType) – a handle type
handles ([int]) – an array of n_handles handles

Do nothing. In versions of telepathy-glib prior to 0.13.8, this released a reference to the handles in handles.

Deprecated since version ???: This is no-op so can be safely removed.

unsubscribe_async(contacts, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects to remove
callback (Gio.AsyncReadyCallback or None) – a callback to call when the operation finishes
user_data (object or None) – data to pass to callback

Attempt to set the given contacts' TelepathyGLib.Contact :subscribe-state property to TelepathyGLib.SubscriptionState.NO, i.e. stop receiving their presence.

For this to work properly self must have interface TelepathyGLib.IFACE_CONNECTION_INTERFACE_CONTACT_LIST.

New in version 0.15.5.

unsubscribe_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True if the operation was successful, otherwise False.
Return type:: bool

Finishes TelepathyGLib.Connection.unsubscribe_async()

New in version 0.15.5.

upgrade_contacts(contacts, features, callback, user_data, weak_object)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects associated with self
features ([TelepathyGLib.ContactFeature]) – An array of features that must be ready for use (if supported) before the callback is called
callback (TelepathyGLib.ConnectionUpgradeContactsCb) – A user callback to call when the contacts are ready
user_data (object or None) – Data to pass to the callback
weak_object (GObject.Object or None) – An object to pass to the callback, which will be weakly referenced; if this object is destroyed, the operation will be cancelled

Given several TelepathyGLib.Contact objects, make asynchronous method calls ensure that all the features specified in features are ready for use (if they are supported at all).

It is not an error to put features in features even if the connection manager doesn’t support them - users of this method should have a static list of features they would like to use if possible, and use it for all connection managers.

New in version 0.7.18.

Deprecated since version ???: Use TelepathyGLib.Connection.upgrade_contacts_async() instead.

upgrade_contacts_async(contacts, features, callback, *user_data)¶

Parameters:

contacts ([TelepathyGLib.Contact]) – An array of TelepathyGLib.Contact objects associated with self
features ([TelepathyGLib.ContactFeature]) – An array of features that must be ready for use (if supported) before the callback is called
callback (Gio.AsyncReadyCallback or None) – A user callback to call when the contacts are ready
user_data (object or None) – Data to pass to the callback

Given several TelepathyGLib.Contact objects, make asynchronous method calls ensure that all the features specified in features are ready for use (if they are supported at all).

It is not an error to put features in features even if the connection manager doesn’t support them - users of this method should have a static list of features they would like to use if possible, and use it for all connection managers.

New in version 0.19.0.

upgrade_contacts_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

True on success, False otherwise.

contacts:: a location to set a GLib.PtrArray of upgraded TelepathyGLib.Contact, or None.

Return type:

(bool, contacts: [TelepathyGLib.Contact])

Finishes TelepathyGLib.Connection.upgrade_contacts_async().

New in version 0.19.0.

Signal Details¶

TelepathyGLib.Connection.signals.balance_changed(connection, balance, balance_scale, balance_currency)¶

Signal Name:

balance-changed

Flags:

RUN_LAST, DETAILED

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
balance (int) – the value of the TelepathyGLib.Connection :balance property
balance_scale (int) – the value of the TelepathyGLib.Connection :balance-scale property
balance_currency (str) – the value of the TelepathyGLib.Connection :balance-currency property

Emitted when at least one of the TelepathyGLib.Connection :balance, TelepathyGLib.Connection :balance-scale or TelepathyGLib.Connection :balance-currency property is changed.

For this signal to be emitted, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_BALANCE.

New in version 0.15.1.

TelepathyGLib.Connection.signals.blocked_contacts_changed(connection, added, removed)¶

Signal Name:

blocked-contacts-changed

Flags:

RUN_LAST

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
added ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact which have been blocked
removed ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact which are no longer blocked

Notify of changes in TelepathyGLib.Connection :blocked-contacts. It is guaranteed that all contacts have desired features prepared. See TelepathyGLib.SimpleClientFactory.add_contact_features() to define which features needs to be prepared.

This signal is also emitted for the initial set of blocked contacts once retrieved.

For this signal to be emitted, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

New in version 0.17.0.

TelepathyGLib.Connection.signals.contact_list_changed(connection, added, removed)¶

Signal Name:

contact-list-changed

Flags:

RUN_LAST

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
added ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact added to contacts list
removed ([TelepathyGLib.Contact]) – a GLib.PtrArray of TelepathyGLib.Contact removed from contacts list

Notify of changes in the list of contacts as returned by TelepathyGLib.Connection.dup_contact_list(). It is guaranteed that all contacts have desired features prepared. See TelepathyGLib.SimpleClientFactory.add_contact_features() to define which features needs to be prepared.

This signal is also emitted for the initial set of contacts once retrieved.

For this signal to be emitted, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_LIST.

New in version 0.15.5.

TelepathyGLib.Connection.signals.group_renamed(connection, old_name, new_name)¶

Signal Name:

group-renamed

Flags:

RUN_LAST

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
old_name (str) – the old name of the group.
new_name (str) – the new name of the group.

Emitted when a group is renamed, in protocols where this can be distinguished from group creation, removal and membership changes.

Immediately after this signal is emitted, TelepathyGLib.Connection ::groups-created signal the creation of a group with the new name, and TelepathyGLib.Connection ::groups-removed signal the removal of a group with the old name. If the group was not empty, immediately after those signals are emitted, TelepathyGLib.Contact ::contact-groups-changed signal that the members of that group were removed from the old name and added to the new name.

When this signal is emitted, TelepathyGLib.Connection :contact-groups property is already updated.

For this signal to be emited, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

TelepathyGLib.Connection.signals.groups_created(connection, added)¶

Signal Name:

groups-created

Flags:

RUN_LAST

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
added ([str]) – a #GStrv with the names of the new groups.

Emitted when new, empty groups are created. This will often be followed by TelepathyGLib.Contact ::contact-groups-changed signals that add some members. When this signal is emitted, TelepathyGLib.Connection :contact-groups property is already updated.

For this signal to be emited, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

TelepathyGLib.Connection.signals.groups_removed(connection, added)¶

Signal Name:

groups-removed

Flags:

RUN_LAST

Parameters:

connection (TelepathyGLib.Connection) – The object which received the signal
added ([str]) – A #GStrv with the names of the groups.

Emitted when one or more groups are removed. If they had members at the time that they were removed, then immediately after this signal is emitted, TelepathyGLib.Contact ::contact-groups-changed signals that their members were removed. When this signal is emitted, TelepathyGLib.Connection :contact-groups property is already updated.

For this signal to be emited, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

Property Details¶

TelepathyGLib.Connection.props.balance¶

Name:: balance
Type:: int
Default Value:: 0
Flags:: READABLE

The Amount field of the Balance.AccountBalance property.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_BALANCE.

TelepathyGLib.Connection.props.balance_currency¶

Name:: balance-currency
Type:: str
Default Value:: None
Flags:: READABLE

The Currency field of the Balance.AccountBalance property.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_BALANCE.

TelepathyGLib.Connection.props.balance_scale¶

Name:: balance-scale
Type:: int
Default Value:: 4294967295
Flags:: READABLE

The Scale field of the Balance.AccountBalance property.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_BALANCE.

TelepathyGLib.Connection.props.balance_uri¶

Name:: balance-uri
Type:: str
Default Value:: None
Flags:: READABLE

The Balance.ManageCreditURI property.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_BALANCE.

TelepathyGLib.Connection.props.blocked_contacts¶

Name:: blocked-contacts
Type:: GLib.PtrArray
Default Value:: None
Flags:: READABLE

A GLib.PtrArray of blocked TelepathyGLib.Contact. Changes are notified using the TelepathyGLib.Connection ::blocked-contacts-changed signal.

These TelepathyGLib.Contact objects have been prepared with the desired features. See TelepathyGLib.SimpleClientFactory.add_contact_features() to define which features needs to be prepared on them.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

New in version 0.17.0.

TelepathyGLib.Connection.props.can_change_contact_list¶

Name:: can-change-contact-list
Type:: bool
Default Value:: False
Flags:: READABLE

If true, presence subscription and publication can be changed using the RequestSubscription, AuthorizePublication and RemoveContacts methods.

Rational: link-local XMPP, presence is implicitly published to everyone in the local subnet, so the user cannot control their presence publication.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or %TP_CONNECTION_FEATURE_CONTACT_LIST.

New in version 0.15.5.

TelepathyGLib.Connection.props.can_report_abusive¶

Name:: can-report-abusive
Type:: bool
Default Value:: False
Flags:: READABLE

If this property is True, contacts may be reported as abusive to the server administrators by setting report_abusive to True when calling TelepathyGLib.Connection.block_contacts_async().

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_BLOCKING.

New in version 0.17.0.

TelepathyGLib.Connection.props.capabilities¶

Name:: capabilities
Type:: TelepathyGLib.Capabilities
Default Value:: None
Flags:: READABLE

The TelepathyGLib.Capabilities object representing the capabilities of this connection, or None if we don’t know yet.

To wait for valid capability information, call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CAPABILITIES.

TelepathyGLib.Connection.props.cm_name¶

Name:: cm-name
Type:: str
Default Value:: None
Flags:: READABLE

This connection’s connection manager name.

New in version 0.19.3.

TelepathyGLib.Connection.props.connection_manager_name¶

Name:: connection-manager-name
Type:: str
Default Value:: None
Flags:: READABLE

This connection’s connection manager name.

New in version 0.13.16.

Deprecated since version ???: Use TelepathyGLib.Connection :cm-name instead.

TelepathyGLib.Connection.props.connection_ready¶

Name:: connection-ready
Type:: bool
Default Value:: False
Flags:: DEPRECATED, READABLE

Initially False; changes to True when the connection has gone to CONNECTED status, introspection has finished and it’s ready for use.

By the time this property becomes True, any extra interfaces will have been set up and the TelepathyGLib.Proxy :interfaces property will have been populated.

This is similar to %TP_CONNECTION_FEATURE_CONNECTED, except that once it has changed to True, it remains True even if the connection has been invalidated.

Deprecated since version 0.17.6: use TelepathyGLib.Proxy.is_prepared() with %TP_CHANNEL_FEATURE_CONNECTED for checks, or TelepathyGLib.Proxy.prepare_async() for notification

TelepathyGLib.Connection.props.contact_groups¶

Name:: contact-groups
Type:: [str]
Default Value:: []
Flags:: READABLE

The names of all groups that currently exist. This may be a larger set than the union of all TelepathyGLib.Contact :contact-groups properties, if the connection allows groups to be empty.

This property’s value is not meaningful until the TelepathyGLib.Connection :contact-list-state property has become TelepathyGLib.ContactListState.SUCCESS.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

TelepathyGLib.Connection.props.contact_list_persists¶

Name:: contact-list-persists
Type:: bool
Default Value:: False
Flags:: READABLE

If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

If false, presence subscriptions on this connection are not stored.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or %TP_CONNECTION_FEATURE_CONTACT_LIST.

New in version 0.15.5.

TelepathyGLib.Connection.props.contact_list_state¶

Name:: contact-list-state
Type:: int
Default Value:: 0
Flags:: READABLE

The progress made in retrieving the contact list.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or %TP_CONNECTION_FEATURE_CONTACT_LIST.

New in version 0.15.5.

TelepathyGLib.Connection.props.disjoint_groups¶

Name:: disjoint-groups
Type:: bool
Default Value:: False
Flags:: READABLE

True if each contact can be in at most one group; false if each contact can be in many groups.

This property cannot change after the connection has moved to the TelepathyGLib.ConnectionStatus.CONNECTED state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

TelepathyGLib.Connection.props.group_storage¶

Name:: group-storage
Type:: int
Default Value:: 0
Flags:: READABLE

Indicates the extent to which contacts’ groups can be set and stored.

This property cannot change after the connection has moved to the TelepathyGLib.ConnectionStatus.CONNECTED state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_GROUPS.

New in version 0.15.5.

TelepathyGLib.Connection.props.protocol_name¶

Name:: protocol-name
Type:: str
Default Value:: None
Flags:: READABLE

The connection’s machine-readable protocol name, such as “jabber”, “msn” or “local-xmpp”. Recommended names for most protocols can be found in the Telepathy D-Bus Interface Specification.

New in version 0.13.16.

TelepathyGLib.Connection.props.request_uses_message¶

Name:: request-uses-message
Type:: bool
Default Value:: False
Flags:: READABLE

If true, the Message parameter to RequestSubscription is likely to be significant, and user interfaces SHOULD prompt the user for a message to send with the request; a message such as “I would like to add you to my contact list”, translated into the local user’s language, might make a suitable default.

For this property to be valid, you must first call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES or %TP_CONNECTION_FEATURE_CONTACT_LIST.

New in version 0.15.5.

TelepathyGLib.Connection.props.self_contact¶

Name:: self-contact
Type:: TelepathyGLib.Contact
Default Value:: None
Flags:: READABLE

A TelepathyGLib.Contact representing the local user on this connection, or None if not yet available.

If the local user’s unique identifier changes (for instance by using /nick on IRC), this property will change to a different TelepathyGLib.Contact object representing the new identifier, and GObject.Object ::notify will be emitted.

The TelepathyGLib.Contact object is guaranteed to have all of the features previously passed to TelepathyGLib.SimpleClientFactory.add_contact_features() prepared.

To wait for a non-None self-contact (and other properties), call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONNECTED.

New in version 0.13.9.

TelepathyGLib.Connection.props.self_handle¶

Name:: self-handle
Type:: int
Default Value:: 0
Flags:: READABLE

The TelepathyGLib.HandleType.CONTACT handle of the local user on this connection, or 0 if we don’t know yet or if the connection has become invalid.

This may change if the local user’s unique identifier changes (for instance by using /nick on IRC), in which case GObject.Object ::notify will be emitted.

To wait for a valid self-handle (and other properties), call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CONNECTED.

Deprecated since version ???: Use TelepathyGLib.Connection :self-contact instead.

TelepathyGLib.Connection.props.status¶

Name:: status
Type:: int
Default Value:: 4294967295
Flags:: READABLE

This connection’s status, or TelepathyGLib.UNKNOWN_CONNECTION_STATUS if we don’t know yet.

To wait for a valid status (and other properties), call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CORE.

Since version 0.11.3, the change to status TelepathyGLib.ConnectionStatus.CONNECTED is delayed slightly, until introspection of the connection has finished.

TelepathyGLib.Connection.props.status_reason¶

Name:: status-reason
Type:: int
Default Value:: 0
Flags:: READABLE

To wait for a valid status (and other properties), call TelepathyGLib.Proxy.prepare_async() with the feature %TP_CONNECTION_FEATURE_CORE.

The reason why TelepathyGLib.Connection :status changed to its current value, or TelepathyGLib.ConnectionStatusReason.NONE_SPECIFIED if unknown. know yet.