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

Object Hierarchy

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

Properties

  "bus-name"                 gchar*                : Read / Write / Construct Only
  "dbus-connection"          DBusGConnection*      : Read / Write / Construct Only
  "dbus-daemon"              TpDBusDaemon*         : Read / Write / Construct Only
  "interfaces"               GStrv*                : Read
  "object-path"              gchar*                : 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 _TpProxy TpProxy;

Structure representing a Telepathy client-side proxy.

Since 0.7.1

TpProxyClass

typedef struct {
    GObjectClass parent_class;

    GQuark interface;

    unsigned int 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
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
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.

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

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,
    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
TP_DBUS_ERROR_INCONSISTENT Raised if information received from a remote object is inconsistent or otherwise obviously wrong (added in 0.7.17)
NUM_TP_DBUS_ERRORS 1 more than the highest valid TpDBusError at the time of compilation

Since 0.7.1

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 "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)      : 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
Generated by GTK-Doc V1.10