telepathy-glib API Reference Manual: TpProxy subclasses and mixins

TpProxy subclasses and mixins

TpProxy subclasses and mixins — Providing extra functionality for a TpProxy or subclass, or subclassing it

Functions

void	tp_proxy_add_interface_by_id ()
void	tp_proxy_add_interfaces ()
gboolean	tp_proxy_check_interface_by_id ()
void	tp_proxy_invalidate ()
void	(*TpProxyWrapperFunc) ()
TpProxyPendingCall *	tp_proxy_pending_call_v1_new ()
TpProxySignalConnection *	tp_proxy_signal_connection_v1_new ()

Object Hierarchy

Includes

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

Description

The implementations of TpProxy subclasses and "mixin" functions need access to the underlying GDBus objects used to implement the TpProxy API.

Mixin functions to implement particular D-Bus interfaces should usually be auto-generated, by copying tools/glib-client-gen.py from telepathy-glib.

Functions

tp_proxy_add_interface_by_id ()

void
tp_proxy_add_interface_by_id (TpProxy *self,
                              GQuark iface);

Declare that this proxy supports a given interface.

To use methods and signals of that interface, use the tp_cli_* wrapper functions or GDBus.

If the interface is the proxy's "main interface", or has already been added, then do nothing.

Parameters

self	the TpProxy, which must not have become “invalidated”.
iface	quark representing the interface to be added

Since 0.7.1

tp_proxy_add_interfaces ()

void
tp_proxy_add_interfaces (TpProxy *self,
                         const gchar * const *interfaces);

Declare that this proxy supports the given interfaces. Equivalent to calling g_quark_from_string() followed by tp_proxy_add_interface_by_id() for each of the interface names.

Parameters

self	the TpProxy, which must not have become “invalidated”.
interfaces	the names of the interfaces to be added

Since 0.14.4

tp_proxy_check_interface_by_id ()

gboolean
tp_proxy_check_interface_by_id (gpointer proxy,
                                GQuark iface,
                                GError **error);

Return whether this proxy is known to have a particular interface, by its quark ID.

Parameters

proxy	the TpProxy (or subclass)
iface	quark representing the D-Bus interface required
error	used to raise an error in the TP_DBUS_ERRORS domain if `iface` is invalid, `self` has been invalidated or `self` does not implement `iface`

Returns

TRUE if this proxy implements the given interface.

tp_proxy_invalidate ()

void
tp_proxy_invalidate (TpProxy *self,
                     const GError *error);

Mark self as having been invalidated - no further calls will work, and if not already invalidated, the “invalidated” signal will be emitted with the given error.

Parameters

self	a proxy
error	an error causing the invalidation

Since 0.7.1

TpProxyWrapperFunc ()

void
(*TpProxyWrapperFunc) (TpProxy *self,
                       const GError *error,
                       GVariant *args,
                       GCallback callback,
                       gpointer user_data,
                       GObject *weak_object);

A simplified reinvention of GClosureMarshal for TpProxy subclasses. Functions with this signature are intended to be programmatically-generated; there should be no need to use it in hand-written code, other than the implementation of TpProxy.

Parameters

self	a proxy
error	an error, or `NULL` for a successful reply.	[allow-none]
args	the arguments of a successful reply, or `NULL` on error.	[allow-none]
callback	the callback to call
user_data	user data to pass to the callback
weak_object	object to pass to the callback

tp_proxy_pending_call_v1_new ()

TpProxyPendingCall *
tp_proxy_pending_call_v1_new (TpProxy *self,
                              gint timeout_ms,
                              GQuark iface,
                              const gchar *member,
                              GVariant *args,
                              const GVariantType *reply_type,
                              TpProxyWrapperFunc wrapper,
                              GCallback callback,
                              gpointer user_data,
                              GDestroyNotify destroy,
                              GObject *weak_object);

Make a D-Bus call. If it is not cancelled, call wrapper when it completes. The wrapper will usually call callback , but is not required to do so.

If the call is cancelled with tp_proxy_pending_call_cancel() or by finalization of the weak_object , then wrapper is not called at all, but destroy will still be called.

This function is intended to be called by generated code. If possible, use g_dbus_connection_call() or g_dbus_proxy_call() instead.

Parameters

self	the proxy
timeout_ms	the timeout in milliseconds, usually -1 to use a default
iface	a quark representing the D-Bus interface name
member	the method name
args	arguments for the call; if this is a floating reference, this method will take ownership as if via `g_variant_ref_sink()`
reply_type	the expected type of the reply, which must be a tuple type
wrapper	a wrapper function to call when the call completes, or `NULL` if the method reply/error should be ignored.	[allow-none]
callback	callback to pass to the wrapper function. If it is non-`NULL`, `wrapper` must also be non-`NULL`.	[allow-none]
user_data	user data to pass to the wrapper function.	[allow-none]
destroy	callback to destroy `user_data` .	[allow-none]
weak_object	object to pass to the wrapper function; if this object is finalized before the call completes, `wrapper` will not be called at all.	[allow-none]

tp_proxy_signal_connection_v1_new ()

TpProxySignalConnection *
tp_proxy_signal_connection_v1_new (TpProxy *self,
                                   GQuark iface,
                                   const gchar *member,
                                   const GVariantType *expected_types,
                                   TpProxyWrapperFunc wrapper,
                                   GCallback callback,
                                   gpointer user_data,
                                   GDestroyNotify destroy,
                                   GObject *weak_object,
                                   GError **error);

Allocate a new structure representing a signal connection, and connect to the signal, arranging for wrapper to be called when it arrives.

This function is for use by TpProxy subclass implementations only, and should usually only be called from code generated by tools/glib-client-gen.py.

Parameters

self	a proxy
iface	a quark whose string value is the D-Bus interface
member	the name of the signal to which we're connecting
expected_types	an array of expected GTypes for the arguments, terminated by `G_TYPE_INVALID`
wrapper	a function which will be called with `error` = `NULL`, which should invoke `callback` with `user_data` , `weak_object` and other appropriate arguments taken from `args`
callback	user callback to be invoked by `wrapper`
user_data	user-supplied data for the callback
destroy	user-supplied destructor for the data, which will be called when the signal connection is disconnected for any reason, or will be called before this function returns if an error occurs
weak_object	if not `NULL`, a GObject which will be weakly referenced by the signal connection - if it is destroyed, the signal connection will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a signal connection structure, or NULL if the proxy does not have the desired interface or has become invalid

Since 0.7.1

TpProxy subclasses and mixins

Functions

Object Hierarchy

Includes

Description

Functions

tp_proxy_add_interface_by_id ()

Parameters

tp_proxy_add_interfaces ()

Parameters

tp_proxy_check_interface_by_id ()

Parameters

Returns

tp_proxy_invalidate ()

Parameters

TpProxyWrapperFunc ()

Parameters

tp_proxy_pending_call_v1_new ()

Parameters

tp_proxy_signal_connection_v1_new ()

Parameters

Returns

Types and Values

See Also