TelepathyGLib.Proxy¶

Subclasses:: TelepathyGLib.Account, TelepathyGLib.AccountManager, TelepathyGLib.CallContent, TelepathyGLib.CallStream, TelepathyGLib.Channel, TelepathyGLib.ChannelDispatchOperation, TelepathyGLib.ChannelDispatcher, TelepathyGLib.ChannelRequest, TelepathyGLib.Connection, TelepathyGLib.ConnectionManager, TelepathyGLib.DBusDaemon, TelepathyGLib.DebugClient, TelepathyGLib.Protocol, TelepathyGLib.TLSCertificate

Methods¶

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

	`dbus_error_to_gerror` (dbus_error, debug_message)
	`get_bus_name` ()
	`get_dbus_daemon` ()
	`get_factory` ()
	`get_invalidated` ()
	`get_object_path` ()
	`has_interface` (iface)
	`has_interface_by_id` (iface)
	`is_prepared` (feature)
	`prepare_async` (features, callback, *user_data)
	`prepare_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`bus-name`	`str`	r/w/co	The D-Bus bus name for this object
`dbus-daemon`	`TelepathyGLib.DBusDaemon`	r/w/co	The D-Bus daemon used by this object, or this object itself if it’s a `TelepathyGLib.DBusDaemon`
`factory`	`TelepathyGLib.SimpleClientFactory`	r/w/co	The `TelepathyGLib.SimpleClientFactory` used to create this proxy
`interfaces`	[`str`]	r	Known D-Bus interface names for this object
`object-path`	`str`	r/w/co	The D-Bus object path for this object

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`interface-added`	Emitted when this proxy has gained an interface.
`invalidated`	Emitted when this proxy has been become invalid for whatever reason.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access
bus_name	`str`	r
dbus_connection	`object`	r
dbus_daemon	`TelepathyGLib.DBusDaemon`	r
invalidated	`GLib.Error`	r
object_path	`str`	r
parent	`GObject.Object`	r

Class Details¶

class TelepathyGLib.Proxy(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: TelepathyGLib.ProxyClass

Structure representing a Telepathy client-side proxy.

New in version 0.7.1.

dbus_error_to_gerror(dbus_error, debug_message)¶

Parameters:

dbus_error (str) – a D-Bus error name, for instance from the callback for tp_cli_connection_connect_to_connection_error()
debug_message (str) – a debug message that accompanied the error name, or None

Raises:

GLib.Error

Convert a D-Bus error name into a GLib.Error as if it was returned by a method on this proxy. This method is useful when D-Bus error names are emitted in signals, such as Connection.ConnectionError and Group.MembersChangedDetailed.

New in version 0.7.24.

get_bus_name()¶

Returns:: the bus name of the application exporting the object. The caller must copy the string with GLib.strdup() if it will be kept.
Return type:: str

New in version 0.7.17.

get_dbus_daemon()¶

Returns:: a borrowed reference to the TelepathyGLib.DBusDaemon for this object, if any; always None if this object is itself a TelepathyGLib.DBusDaemon. The caller must reference the returned object with GObject.Object.ref() if it will be kept.
Return type:: TelepathyGLib.DBusDaemon

New in version 0.7.17.

get_factory()¶

Returns:: the same value as TelepathyGLib.Proxy :factory property
Return type:: TelepathyGLib.SimpleClientFactory

New in version 0.15.5.

get_invalidated()¶

Returns:: the reason this proxy was invalidated, or None if has not been invalidated. The caller must copy the error, for instance with GLib.Error.copy(), if it will be kept.
Return type:: GLib.Error

New in version 0.7.17.

get_object_path()¶

Returns:: the object path of the remote object. The caller must copy the string with GLib.strdup() if it will be kept.
Return type:: str

New in version 0.7.17.

has_interface(iface)¶

Parameters:: iface (str) – the D-Bus interface required, as a string
Returns:: True if this proxy implements the given interface.
Return type:: bool

Return whether this proxy is known to have a particular interface. In versions older than 0.11.11, this was a macro wrapper around TelepathyGLib.Proxy.has_interface_by_id().

For objects that discover their interfaces at runtime, this method will indicate that interfaces are missing until they are known to be present. In subclasses that define features for use with TelepathyGLib.Proxy.prepare_async(), successfully preparing the “core” feature for that subclass (such as %TP_CHANNEL_FEATURE_CORE or %TP_CONNECTION_FEATURE_CORE) implies that the interfaces are known.

New in version 0.7.1.

has_interface_by_id(iface)¶

Parameters:: iface (int) – quark representing the D-Bus interface required
Returns:: True if this proxy implements the given interface.
Return type:: bool

Return whether this proxy is known to have a particular interface, by its quark ID. This is equivalent to using GLib.quark_to_string() followed by TelepathyGLib.Proxy.has_interface(), but more efficient.

New in version 0.7.1.

is_prepared(feature)¶

Parameters:: feature (int) – a feature that is supported by self's class
Returns:: True if feature has been prepared successfully
Return type:: bool

Return True if feature has been prepared successfully, or False if feature has not been requested, has not been prepared yet, or is not available on this object at all.

(For instance, if feature is %TP_CHANNEL_FEATURE_CHAT_STATES and self is a TelepathyGLib.Channel in a protocol that doesn’t actually implement chat states, or is not a TelepathyGLib.Channel at all, then this method will return False.)

To prepare features, call TelepathyGLib.Proxy.prepare_async().

New in version 0.11.3.

prepare_async(features, callback, *user_data)¶

Parameters:

features ([int] or None) – an array of desired features, ending with 0; None is equivalent to an array containing only 0
callback (Gio.AsyncReadyCallback or None) – if not None, called exactly once, when the features have all been prepared or failed to prepare, or after the proxy is invalidated
user_data (object or None) – user data for callback

TelepathyGLib.Proxy itself does not support any features, but subclasses like TelepathyGLib.Channel can support features, which can either be core functionality like %TP_CHANNEL_FEATURE_CORE, or extended functionality like %TP_CHANNEL_FEATURE_CHAT_STATES.

Proxy instances start with no features prepared. When features are requested via TelepathyGLib.Proxy.prepare_async(), the proxy starts to do the necessary setup to use those features.

TelepathyGLib.Proxy.prepare_async() always waits for core functionality of the proxy’s class to be prepared, even if it is not specifically requested: for instance, because %TP_CHANNEL_FEATURE_CORE is core functionality of a TelepathyGLib.Channel,

TpChannel *channel = ...;

tp_proxy_prepare_async (channel, NULL, callback, user_data);

is equivalent to

TpChannel *channel = ...;
GQuark features[] = { TP_CHANNEL_FEATURE_CORE, 0 };

tp_proxy_prepare_async (channel, features, callback, user_data);

If a feature represents core functionality (like %TP_CHANNEL_FEATURE_CORE), failure to prepare it will result in TelepathyGLib.Proxy.prepare_async() finishing unsuccessfully: if failure to prepare the feature indicates that the proxy is no longer useful, it will also emit TelepathyGLib.Proxy ::invalidated.

If a feature represents non-essential functionality (like %TP_CHANNEL_FEATURE_CHAT_STATES), or is not supported by the object at all, then failure to prepare it is not fatal: TelepathyGLib.Proxy.prepare_async() will complete successfully, but TelepathyGLib.Proxy.is_prepared() will still return False for the feature, and accessor methods for the feature will typically return a dummy value.

Some TelepathyGLib.Proxy subclasses automatically start to prepare their core features when instantiated, and features will sometimes become prepared as a side-effect of other actions, but to ensure that a feature is present you must generally call TelepathyGLib.Proxy.prepare_async() and wait for the result.

New in version 0.11.3.

prepare_finish(result)¶

Parameters:: result (Gio.AsyncResult) – the result passed to the callback of TelepathyGLib.Proxy.prepare_async()
Raises:: GLib.Error
Returns:: False (setting error) if TelepathyGLib.Proxy.prepare_async() failed or was cancelled
Return type:: bool

Check for error in a call to TelepathyGLib.Proxy.prepare_async(). An error here generally indicates that either the asynchronous call was cancelled, or self has emitted TelepathyGLib.Proxy ::invalidated.

New in version 0.11.3.

Signal Details¶

TelepathyGLib.Proxy.signals.interface_added()¶

Signal Name:: interface-added
Flags:: RUN_LAST, DETAILED

Emitted when this proxy has gained an interface. It is not guaranteed to be emitted immediately, but will be emitted before the interface is first used (at the latest: before it’s returned from tp_proxy_get_interface_by_id(), any signal is connected, or any method is called).

The intended use is to call dbus_g_proxy_add_signals(). This signal should only be used by TpProy implementations

TelepathyGLib.Proxy.signals.invalidated(proxy, domain, code, message)¶

Signal Name:

invalidated

Flags:

RUN_LAST, DETAILED

Parameters:

proxy (TelepathyGLib.Proxy) – The object which received the signal
domain (int) – domain of a GLib.Error indicating why this proxy was invalidated
code (int) – error code of a GLib.Error indicating why this proxy was invalidated
message (str) – a message associated with the error

Emitted when this proxy has been become invalid for whatever reason. Any more specific signal should be emitted first.

An invalidated proxy is one which can make no more method calls and will emit no more D-Bus signals. This is typically because the D-Bus object represented by the proxy ceased to exist, or there was some error obtaining the initial state.

Any pending or future method calls made on this proxy will fail gracefully with the same error as returned by TelepathyGLib.Proxy.get_invalidated().

Property Details¶

TelepathyGLib.Proxy.props.bus_name¶

Name:: bus-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The D-Bus bus name for this object. Read-only except during construction.

TelepathyGLib.Proxy.props.dbus_daemon¶

Name:: dbus-daemon
Type:: TelepathyGLib.DBusDaemon
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The D-Bus daemon for this object (this object itself, if it is a TelepathyGLib.DBusDaemon). Read-only except during construction.

TelepathyGLib.Proxy.props.factory¶

Name:: factory
Type:: TelepathyGLib.SimpleClientFactory
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The TelepathyGLib.SimpleClientFactory used to create this proxy, or None if this proxy was not created through a factory.

TelepathyGLib.Proxy.props.interfaces¶

Name:: interfaces
Type:: [str]
Default Value:: []
Flags:: READABLE

Known D-Bus interface names for this object.

TelepathyGLib.Proxy.props.object_path¶

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

The D-Bus object path for this object. Read-only except during construction.