TpProxy

## TpProxy TpProxy — base class for Telepathy client proxy objects |

## Synopsis

    #include <telepathy-glib/proxy.h>

    struct              TpProxy;
    void                (*TpProxyPrepareAsync)              (TpProxy *proxy,
                                                             const TpProxyFeature *feature,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    struct              TpProxyFeature;
    const TpProxyFeature * (*TpProxyClassFeatureListFunc)   (TpProxyClass *cls);
    struct              TpProxyClass;
    gboolean            tp_proxy_has_interface              (gpointer self,
                                                             const gchar *iface);
    gboolean            tp_proxy_has_interface_by_id        (gpointer self,
                                                             GQuark iface);
    gboolean            tp_proxy_is_prepared                (gpointer self,
                                                             GQuark feature);
    void                tp_proxy_prepare_async              (gpointer self,
                                                             const GQuark *features,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_proxy_prepare_finish             (gpointer self,
                                                             GAsyncResult *result,
                                                             GError **error);
                        TpProxyPendingCall;
    void                tp_proxy_pending_call_cancel        (TpProxyPendingCall *pc);
                        TpProxySignalConnection;
    void                tp_proxy_signal_connection_disconnect
                                                            (TpProxySignalConnection *sc);
    TpSimpleClientFactory * tp_proxy_get_factory            (gpointer self);
    TpDBusDaemon *      tp_proxy_get_dbus_daemon            (gpointer self);
    DBusGConnection *   tp_proxy_get_dbus_connection        (gpointer self);
    const gchar *       tp_proxy_get_bus_name               (gpointer self);
    const gchar *       tp_proxy_get_object_path            (gpointer self);
    const GError *      tp_proxy_get_invalidated            (gpointer self);
    void                tp_proxy_dbus_error_to_gerror       (gpointer self,
                                                             const char *dbus_error,
                                                             const char *debug_message,
                                                             GError **error);
    #define             TP_DBUS_ERRORS
    enum                TpDBusError;
    #define             NUM_TP_DBUS_ERRORS
    #define             TP_TYPE_DBUS_ERROR

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpAccount
             +----TpAccountManager
             +----TpChannel
             +----TpCallContent
             +----TpCallStream
             +----TpChannelDispatchOperation
             +----TpChannelDispatcher
             +----TpChannelRequest
             +----TpClient
             +----TpConnection
             +----TpConnectionManager
             +----TpDBusDaemon
             +----TpMediaSessionHandler
             +----TpMediaStreamHandler
             +----TpProtocol

      GEnum
       +----TpDBusError

## Properties

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

## Signals

      "interface-added"                                : Has Details
      "invalidated"                                    : Has Details

## 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.

## Details

### struct TpProxy

    struct TpProxy;

Structure representing a Telepathy client-side proxy.

Since 0.7.1

### TpProxyPrepareAsync ()

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

Function called when `feature` has to be prepared for `proxy`.

`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`

### 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.

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

### 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.

`cls` : | a subclass of TpProxyClass
Returns : | an array of feature descriptions

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.

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

### 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.

`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.

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

`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.

`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".

`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

### TpProxyPendingCall

    typedef struct _TpProxyPendingCall TpProxyPendingCall;

Opaque structure representing a pending D-Bus call.

Since 0.7.1

### 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.

`pc` : | a pending call

Since 0.7.1

### TpProxySignalConnection

    typedef struct _TpProxySignalConnection TpProxySignalConnection;

Opaque structure representing a D-Bus signal connection.

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

`sc` : | a signal connection

Since 0.7.1

### tp_proxy_get_factory ()

    TpSimpleClientFactory * tp_proxy_get_factory            (gpointer self);

`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);

`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);

`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);

`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);

`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);

`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.

`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

### 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

    typedef enum {
        TP_DBUS_ERROR_UNKNOWN_REMOTE_ERROR = 0,
        TP_DBUS_ERROR_PROXY_UNREFERENCED = 1,
        TP_DBUS_ERROR_NO_INTERFACE = 2,
        TP_DBUS_ERROR_NAME_OWNER_LOST = 3,
        TP_DBUS_ERROR_INVALID_BUS_NAME = 4,
        TP_DBUS_ERROR_INVALID_INTERFACE_NAME = 5,
        TP_DBUS_ERROR_INVALID_OBJECT_PATH = 6,
        TP_DBUS_ERROR_INVALID_MEMBER_NAME = 7,
        TP_DBUS_ERROR_OBJECT_REMOVED = 8,
        TP_DBUS_ERROR_CANCELLED = 9,
        TP_DBUS_ERROR_INCONSISTENT = 10,
    } 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`.

`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_DBUS_ERROR_INCONSISTENT + 1)

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

Since 0.7.1

### 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*                : Read / Write / Construct Only

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

Default value: NULL

### The `"dbus-connection"` property

      "dbus-connection"          DBusGConnection*      : Read / Write / Construct Only

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

### The `"dbus-daemon"` property

      "dbus-daemon"              TpDBusDaemon*         : Read / Write / Construct Only

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

### The `"factory"` property

      "factory"                  TpSimpleClientFactory*  : Read / Write / Construct Only

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

### The `"interfaces"` property

      "interfaces"               GStrv                 : Read

Known D-Bus interface names for this object.

### The `"object-path"` property

      "object-path"              gchar*                : Read / Write / Construct Only

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

Default value: NULL

## Signal Details

### The `"interface-added"` signal

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

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_borrow_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

`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.

### The `"invalidated"` signal

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

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

`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.

## See Also

TpChannel, TpConnection, TpConnectionManager