TpProxy

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

## Synopsis

    #include <telepathy-glib/proxy.h>

                        TpProxy;
                        TpProxyClass;
    #define             tp_proxy_has_interface              (self, interface)
    gboolean            tp_proxy_has_interface_by_id        (gpointer self,
                                                             GQuark interface);
                        TpProxyPendingCall;
    void                tp_proxy_pending_call_cancel        (TpProxyPendingCall *pc);
                        TpProxySignalConnection;
    void                tp_proxy_signal_connection_disconnect
                                                            (TpProxySignalConnection *sc);
    #define             TP_DBUS_ERRORS
    enum                TpDBusError;

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpChannel
             +----TpConnection
             +----TpConnectionManager
             +----TpDBusDaemon
             +----TpMediaSessionHandler
             +----TpMediaStreamHandler

## Properties

      "bus-name"                 gchararray            : Read / Write / Construct Only
      "dbus-connection"          DBusGConnection       : Read / Write / Construct Only
      "dbus-daemon"              TpDBusDaemon          : Read / Write / Construct Only
      "interfaces"               GStrv                 : Read
      "object-path"              gchararray            : Read / Write / Construct Only

## Signals

      "interface-added"                                : Run Last / Has Details
      "invalidated"                                    : Run Last / 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

### TpProxy

    typedef struct {
        GObject parent;

        TpDBusDaemon *dbus_daemon;
        DBusGConnection *dbus_connection;
        gchar *bus_name;
        gchar *object_path;

        GError *invalidated /* initialized to NULL by g_object_new */;

        TpProxyPrivate *priv;
    } TpProxy;

Structure representing a Telepathy client-side proxy.

GObject `parent`; | parent object
TpDBusDaemon *`dbus_daemon`; | the TpDBusDaemon for this object, if any; always `NULL` if this object is a TpDBusDaemon (read-only)
DBusGConnection *`dbus_connection`; | the D-Bus connection used by this object (read-only)
gchar *`bus_name`; | the bus name of the application exporting the object (read-only)
gchar *`object_path`; | the object path of the remote object (read-only)
GError *`invalidated`; | if not `NULL`, the reason this proxy was invalidated (read-only)
TpProxyPrivate *`priv`; | private internal data

Since 0.7.1

### TpProxyClass

    typedef struct {
        GObjectClass parent_class;

        GQuark interface;

        gboolean must_have_unique_name:1;
        guint _reserved_flags:31;

        GCallback _reserved[4];
        gpointer priv;
    } TpProxyClass;

The class of a TpProxy.

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
gboolean `must_have_unique_name` :1; | If set `TRUE` by a subclass, the TpProxy constructor will fail if a well-known bus name is given
guint `_reserved_flags` :31; | Reserved for future expansion
GCallback `_reserved`[4]; | Reserved for future expansion
gpointer `priv`; | Opaque pointer for private data

Since 0.7.1

### tp_proxy_has_interface()

    #define             tp_proxy_has_interface(self, interface)

A macro wrapping `tp_proxy_has_interface_by_id()`. Returns `TRUE` if this proxy implements the given interface.

`self` : | the TpProxy (or subclass)
`interface` : | the interface required, as a string

Since 0.7.1

### tp_proxy_has_interface_by_id ()

    gboolean            tp_proxy_has_interface_by_id        (gpointer self,
                                                             GQuark interface);

`self` : | the TpProxy (or subclass)
`interface` : | quark representing the interface required
Returns : | `TRUE` if this proxy implements the given interface.

Since 0.7.1

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

`sc` : | a 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

    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,
        NUM_TP_DBUS_ERRORS
    } TpDBusError;

GError codes for use with the `TP_DBUS_ERRORS` domain.

`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
`NUM_TP_DBUS_ERRORS` | 1 more than the highest valid TpDBusError

Since 0.7.1

## Property Details

### The `"bus-name"` property

      "bus-name"                 gchararray            : 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 `"interfaces"` property

      "interfaces"               GStrv                 : Read

Known D-Bus interface names for this object.

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

      "object-path"              gchararray            : 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)      : Run Last / 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)      : Run Last / Has Details

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

`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