TpProxy

TpProxy — base class for Telepathy client proxy objects

Functions

Properties

gchar * bus-name Read / Write / Construct Only
DBusGConnection * dbus-connection Read / Write / Construct Only
TpDBusDaemon * dbus-daemon Read / Write / Construct Only
TpSimpleClientFactory * factory Read / Write / Construct Only
GStrv interfaces Read
gchar * object-path Read / Write / Construct Only

Signals

void interface-added Has Details
void invalidated Has Details

Types and Values

Object Hierarchy

    GEnum
    ╰── TpDBusError
    GObject
    ╰── TpProxy
        ├── TpAccount
        ├── TpAccountManager
        ├── TpChannel
        ├── TpCallContent
        ├── TpCallStream
        ├── TpChannelDispatchOperation
        ├── TpChannelDispatcher
        ├── TpChannelRequest
        ├── TpClient
        ├── TpConnection
        ├── TpConnectionManager
        ├── TpDBusDaemon
        ├── TpDebugClient
        ├── TpMediaSessionHandler
        ├── TpMediaStreamHandler
        ├── TpProtocol
        ╰── TpTLSCertificate

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

TpProxy is a base class for Telepathy client-side proxies, which represent an object accessed via D-Bus and provide access to its methods and signals.

Functions

TpProxyPrepareAsync ()

void
(*TpProxyPrepareAsync) (TpProxy *proxy,
                        const TpProxyFeature *feature,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Function called when feature has to be prepared for proxy .

Parameters

proxy

the object on which feature has to be prepared

 

feature

a GQuark representing the feature to prepare

 

callback

called when the feature has been prepared, or the preparation failed

 

user_data

data to pass to callback

 

TpProxyClassFeatureListFunc ()

const TpProxyFeature *
(*TpProxyClassFeatureListFunc) (TpProxyClass *cls);

A function called to list the features supported by tp_proxy_prepare_async(). Currently, only code inside telepathy-glib can implement this.

Parameters

cls

a subclass of TpProxyClass

 

Returns

an array of feature descriptions

Since: 0.11.3


tp_proxy_has_interface ()

gboolean
tp_proxy_has_interface (gpointer self,
                        const gchar *iface);

Return whether this proxy is known to have a particular interface. In versions older than 0.11.11, this was a macro wrapper around tp_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 tp_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.

Parameters

self

the TpProxy (or subclass)

 

iface

the D-Bus interface required, as a string

 

Returns

TRUE if this proxy implements the given interface.

Since: 0.7.1


tp_proxy_has_interface_by_id ()

gboolean
tp_proxy_has_interface_by_id (gpointer self,
                              GQuark iface);

Return whether this proxy is known to have a particular interface, by its quark ID. This is equivalent to using g_quark_to_string() followed by tp_proxy_has_interface(), but more efficient.

Parameters

self

the TpProxy (or subclass)

 

iface

quark representing the D-Bus interface required

 

Returns

TRUE if this proxy implements the given interface.

Since: 0.7.1


tp_proxy_is_prepared ()

gboolean
tp_proxy_is_prepared (gpointer self,
                      GQuark feature);

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 TpChannel in a protocol that doesn't actually implement chat states, or is not a TpChannel at all, then this method will return FALSE.)

To prepare features, call tp_proxy_prepare_async().

Parameters

self

an instance of a TpProxy subclass

 

feature

a feature that is supported by self 's class

 

Returns

TRUE if feature has been prepared successfully

Since: 0.11.3


tp_proxy_prepare_async ()

void
tp_proxy_prepare_async (gpointer self,
                        const GQuark *features,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

TpProxy itself does not support any features, but subclasses like TpChannel 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 tp_proxy_prepare_async(), the proxy starts to do the necessary setup to use those features.

tp_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 TpChannel,

1
2
3
TpChannel *channel = ...;

tp_proxy_prepare_async (channel, NULL, callback, user_data);

is equivalent to

1
2
3
4
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 tp_proxy_prepare_async() finishing unsuccessfully: if failure to prepare the feature indicates that the proxy is no longer useful, it will also emit “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: tp_proxy_prepare_async() will complete successfully, but tp_proxy_is_prepared() will still return FALSE for the feature, and accessor methods for the feature will typically return a dummy value.

Some TpProxy 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 tp_proxy_prepare_async() and wait for the result.

Parameters

self

an instance of a TpProxy subclass

 

features

an array of desired features, ending with 0; NULL is equivalent to an array containing only 0.

[transfer none][array zero-terminated=1][allow-none]

callback

if not NULL, called exactly once, when the features have all been prepared or failed to prepare, or after the proxy is invalidated

 

user_data

user data for callback

 

Since: 0.11.3


tp_proxy_prepare_finish ()

gboolean
tp_proxy_prepare_finish (gpointer self,
                         GAsyncResult *result,
                         GError **error);

Check for error in a call to tp_proxy_prepare_async(). An error here generally indicates that either the asynchronous call was cancelled, or self has emitted “invalidated”.

Parameters

self

an instance of a TpProxy subclass

 

result

the result passed to the callback of tp_proxy_prepare_async()

 

error

used to return an error if FALSE is returned

 

Returns

FALSE (setting error ) if tp_proxy_prepare_async() failed or was cancelled

Since: 0.11.3


tp_proxy_pending_call_cancel ()

void
tp_proxy_pending_call_cancel (TpProxyPendingCall *pc);

Cancel the given pending call. After this function returns, you must not assume that the pending call remains valid, but you must not explicitly free it either.

Parameters

pc

a pending call

 

Since: 0.7.1


tp_proxy_signal_connection_disconnect ()

void
tp_proxy_signal_connection_disconnect (TpProxySignalConnection *sc);

Disconnect the given signal connection. After this function returns, you must not assume that the signal connection remains valid, but you must not explicitly free it either.

It is not safe to call this function if sc has been disconnected already, which happens in each of these situations:

  • the weak_object used when sc was created has been destroyed
  • tp_proxy_signal_connection_disconnect has already been used
  • the proxy has been invalidated

Parameters

sc

a signal connection

 

Since: 0.7.1


tp_proxy_get_factory ()

TpSimpleClientFactory *
tp_proxy_get_factory (gpointer self);

Parameters

self

a TpProxy or subclass

 

Returns

the same value as “factory” property.

[transfer none]

Since: 0.15.5


tp_proxy_get_dbus_daemon ()

TpDBusDaemon *
tp_proxy_get_dbus_daemon (gpointer self);

Parameters

self

a TpProxy or subclass

 

Returns

a borrowed reference to the TpDBusDaemon for this object, if any; always NULL if this object is itself a TpDBusDaemon. The caller must reference the returned object with g_object_ref() if it will be kept.

[transfer none]

Since: 0.7.17


tp_proxy_get_dbus_connection ()

DBusGConnection *
tp_proxy_get_dbus_connection (gpointer self);

[skip]

Parameters

self

a TpProxy or subclass

 

Returns

a borrowed reference to the D-Bus connection used by this object. The caller must reference the returned pointer with dbus_g_connection_ref() if it will be kept.

Since: 0.7.17


tp_proxy_get_bus_name ()

const gchar *
tp_proxy_get_bus_name (gpointer self);

Parameters

self

a TpProxy or subclass

 

Returns

the bus name of the application exporting the object. The caller must copy the string with g_strdup() if it will be kept.

Since: 0.7.17


tp_proxy_get_object_path ()

const gchar *
tp_proxy_get_object_path (gpointer self);

Parameters

self

a TpProxy or subclass

 

Returns

the object path of the remote object. The caller must copy the string with g_strdup() if it will be kept.

Since: 0.7.17


tp_proxy_get_invalidated ()

const GError *
tp_proxy_get_invalidated (gpointer self);

Parameters

self

a TpProxy or subclass

 

Returns

the reason this proxy was invalidated, or NULL if has not been invalidated. The caller must copy the error, for instance with g_error_copy(), if it will be kept.

Since: 0.7.17


tp_proxy_dbus_error_to_gerror ()

void
tp_proxy_dbus_error_to_gerror (gpointer self,
                               const char *dbus_error,
                               const char *debug_message,
                               GError **error);

Convert a D-Bus error name into a GError 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.

Parameters

self

a TpProxy or subclass

 

dbus_error

a D-Bus error name, for instance from the callback for tp_cli_connection_connect_to_connection_error()

 

debug_message

a debug message that accompanied the error name, or NULL

 

error

used to return the corresponding GError

 

Since: 0.7.24

Types and Values

struct TpProxy

struct TpProxy;

Structure representing a Telepathy client-side proxy.

Since: 0.7.1


struct TpProxyFeature

struct TpProxyFeature {
    GQuark name;
    gboolean core;

    TpProxyPrepareAsync prepare_async;
    TpProxyPrepareAsync prepare_before_signalling_connected_async;

    const GQuark *interfaces_needed;
    /* Features we depend on */
    const GQuark *depends_on;

    gboolean can_retry;
};

Structure representing a feature.

Members

GQuark name;

a GQuark representing the name of the feature

 

gboolean core;

if TRUE, every non-core feature of the class depends on this one, and every feature (core or not) in subclasses depends on this one

 

TpProxyPrepareAsync prepare_async;

called when the feature has to be prepared

 

TpProxyPrepareAsync prepare_before_signalling_connected_async;

only relevant for TpConnection sub-classes; same as prepare_async but for features wanting to have a chance to prepare themself before the TpConnection object announce its TP_CONNECTION_STATUS_CONNECTED status

 

const GQuark *interfaces_needed;

an array of GQuark representing interfaces which have to be implemented on the object in order to be able to prepare the feature

 

const GQuark *depends_on;

an array of GQuark representing other features which have to be prepared before trying to prepare this feature

 

gboolean can_retry;

If TRUE, allow retrying preparation of this feature even if it failed once already; if FALSE any attempt of preparing the feature after the preparation already failed once will immediately fail with re-calling prepare_async

 

Since: 0.11.3


struct TpProxyClass

struct TpProxyClass {
    GObjectClass parent_class;

    GQuark interface;

    unsigned int must_have_unique_name:1;
};

The class of a TpProxy. The struct fields not documented here are reserved.

Members

GObjectClass parent_class;

The parent class structure

 

GQuark interface;

If set non-zero by a subclass, TpProxy will automatically add this interface in its constructor

 

unsigned int must_have_unique_name :1;

If set TRUE by a subclass, the TpProxy constructor will fail if a well-known bus name is given

 

Since: 0.7.1


TpProxyPendingCall

typedef struct _TpProxyPendingCall TpProxyPendingCall;

Opaque structure representing a pending D-Bus call.

Since: 0.7.1


TpProxySignalConnection

typedef struct _TpProxySignalConnection TpProxySignalConnection;

Opaque structure representing a D-Bus signal connection.

Since: 0.7.1


TP_DBUS_ERRORS

#define TP_DBUS_ERRORS (tp_dbus_errors_quark ())

GError domain representing D-Bus errors not directly related to Telepathy, for use by TpProxy. The code in a GError with this domain must be a member of TpDBusError.

This macro expands to a function call returning a GQuark.

Since: 0.7.1


enum TpDBusError

GError codes for use with the TP_DBUS_ERRORS domain.

Since 0.11.5, there is a corresponding GEnumClass type, TP_TYPE_DBUS_ERROR.

Members

TP_DBUS_ERROR_UNKNOWN_REMOTE_ERROR

Raised if the error raised by a remote D-Bus object is not recognised

 

TP_DBUS_ERROR_PROXY_UNREFERENCED

Emitted in “invalidated” when the TpProxy has lost its last reference

 

TP_DBUS_ERROR_NO_INTERFACE

Raised by TpProxy methods if the remote object does not appear to have the required interface

 

TP_DBUS_ERROR_NAME_OWNER_LOST

Emitted in “invalidated” if the remote process loses ownership of its bus name, and raised by any TpProxy methods that have not had a reply at that time or are called after the proxy becomes invalid in this way (usually meaning it crashed)

 

TP_DBUS_ERROR_INVALID_BUS_NAME

Raised if a D-Bus bus name given is not valid, or is of an unacceptable type (e.g. well-known vs. unique)

 

TP_DBUS_ERROR_INVALID_INTERFACE_NAME

Raised if a D-Bus interface or error name given is not valid

 

TP_DBUS_ERROR_INVALID_OBJECT_PATH

Raised if a D-Bus object path given is not valid

 

TP_DBUS_ERROR_INVALID_MEMBER_NAME

Raised if a D-Bus method or signal name given is not valid

 

TP_DBUS_ERROR_OBJECT_REMOVED

A generic error which can be used with “invalidated” to indicate an application-specific indication that the remote object no longer exists, if no more specific error is available.

 

TP_DBUS_ERROR_CANCELLED

Raised from calls that re-enter the main loop (*_run_*) if they are cancelled

 

TP_DBUS_ERROR_INCONSISTENT

Raised if information received from a remote object is inconsistent or otherwise obviously wrong (added in 0.7.17). See also TP_ERROR_CONFUSED.

 

Since: 0.7.1


NUM_TP_DBUS_ERRORS

#define NUM_TP_DBUS_ERRORS TP_NUM_DBUS_ERRORS

1 more than the highest valid TpDBusError at the time of compilation. In new code, use TP_NUM_DBUS_ERRORS instead.

Since: 0.7.1


TP_NUM_DBUS_ERRORS

#define TP_NUM_DBUS_ERRORS (TP_DBUS_ERROR_INCONSISTENT + 1)

1 more than the highest valid TpDBusError at the time of compilation

Since: 0.19.0


TP_TYPE_DBUS_ERROR

#define TP_TYPE_DBUS_ERROR (tp_dbus_error_get_type ())

The GEnumClass type of a TpDBusError.

Since: 0.11.5

Property Details

The “bus-name” property

  “bus-name”                 gchar *

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

Owner: TpProxy

Flags: Read / Write / Construct Only

Default value: NULL


The “dbus-connection” property

  “dbus-connection”          DBusGConnection *

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

[skip]

Owner: TpProxy

Flags: Read / Write / Construct Only


The “dbus-daemon” property

  “dbus-daemon”              TpDBusDaemon *

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

Owner: TpProxy

Flags: Read / Write / Construct Only


The “factory” property

  “factory”                  TpSimpleClientFactory *

The TpSimpleClientFactory used to create this proxy, or NULL if this proxy was not created through a factory.

Owner: TpProxy

Flags: Read / Write / Construct Only


The “interfaces” property

  “interfaces”               GStrv

Known D-Bus interface names for this object.

Owner: TpProxy

Flags: Read


The “object-path” property

  “object-path”              gchar *

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

Owner: TpProxy

Flags: Read / Write / Construct Only

Default value: NULL

Signal Details

The “interface-added” signal

void
user_function (TpProxy    *self,
               guint       id,
               DBusGProxy *proxy,
               gpointer    user_data)

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

[skip]

Parameters

self

the proxy object

 

id

the GQuark representing the interface

 

proxy

the dbus-glib proxy representing the interface

 

user_data

user data set when the signal handler was connected.

 

Flags: Has Details


The “invalidated” signal

void
user_function (TpProxy *self,
               guint    domain,
               gint     code,
               gchar   *message,
               gpointer user_data)

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

Parameters

self

the proxy object

 

domain

domain of a GError indicating why this proxy was invalidated

 

code

error code of a GError indicating why this proxy was invalidated

 

message

a message associated with the error

 

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

See Also

TpChannel, TpConnection, TpConnectionManager