TpProxy Telepathy Properties: telepathy-glib API Reference Manual

TpProxy Telepathy Properties

TpProxy Telepathy Properties — The Telepathy Properties interface

Functions

void	(*tp_cli_properties_interface_callback_for_get_properties) ()
TpProxyPendingCall *	tp_cli_properties_interface_call_get_properties ()
gboolean	tp_cli_properties_interface_run_get_properties ()
void	(*tp_cli_properties_interface_callback_for_list_properties) ()
TpProxyPendingCall *	tp_cli_properties_interface_call_list_properties ()
gboolean	tp_cli_properties_interface_run_list_properties ()
void	(*tp_cli_properties_interface_callback_for_set_properties) ()
TpProxyPendingCall *	tp_cli_properties_interface_call_set_properties ()
gboolean	tp_cli_properties_interface_run_set_properties ()
void	(*tp_cli_properties_interface_signal_callback_properties_changed) ()
TpProxySignalConnection *	tp_cli_properties_interface_connect_to_properties_changed ()
void	(*tp_cli_properties_interface_signal_callback_property_flags_changed) ()
TpProxySignalConnection *	tp_cli_properties_interface_connect_to_property_flags_changed ()

Includes

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

Description

As well as TpProxy, proxy.h includes auto-generated client wrappers for the Telepathy Properties interface, which can be implemented by any type of object.

The Telepathy Properties interface should not be confused with the D-Bus core Properties interface.

Functions

tp_cli_properties_interface_callback_for_get_properties ()

void
(*tp_cli_properties_interface_callback_for_get_properties)
                               (TpProxy *proxy,
                                const GPtrArray *out_Values,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a GetProperties method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Values	Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> <ul> <li>integer identifiers</li> <li>variant boxed values</li> </ul>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_properties_interface_call_get_properties ()

TpProxyPendingCall *
tp_cli_properties_interface_call_get_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                const GArray *in_Properties,
                                tp_cli_properties_interface_callback_for_get_properties callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a GetProperties method call.

Returns an array of (identifier, value) pairs containing the current values of the given properties.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Properties	Used to pass an 'in' argument: An array of property identifiers
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`

Returns

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_properties_interface_run_get_properties ()

gboolean
tp_cli_properties_interface_run_get_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                const GArray *in_Properties,
                                GPtrArray **out_Values,
                                GError **error,
                                GMainLoop **loop);

tp_cli_properties_interface_run_get_properties is deprecated and should not be used in newly-written code.

Call the method GetProperties and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns an array of (identifier, value) pairs containing the current values of the given properties.

Parameters

proxy	A TpProxy or subclass
timeout_ms	Timeout in milliseconds, or -1 for default
in_Properties	Used to pass an 'in' argument: An array of property identifiers
out_Values	Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> <ul> <li>integer identifiers</li> <li>variant boxed values</li> </ul>
error	If not `NULL`, used to return errors if `FALSE` is returned
loop	If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`

Returns

TRUE on success, FALSE and sets error on error

tp_cli_properties_interface_callback_for_list_properties ()

void
(*tp_cli_properties_interface_callback_for_list_properties)
                               (TpProxy *proxy,
                                const GPtrArray *out_Available_Properties,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a ListProperties method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
out_Available_Properties	Used to return an 'out' argument if `error` is `NULL`: An array of structs containing: <ul> <li>an integer identifier</li> <li>a string property name</li> <li>a string representing the D-Bus signature of this property</li> <li>a bitwise OR of the flags applicable to this property</li> </ul>
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_properties_interface_call_list_properties ()

TpProxyPendingCall *
tp_cli_properties_interface_call_list_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                tp_cli_properties_interface_callback_for_list_properties callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a ListProperties method call.

Returns a dictionary of the properties available on this channel.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`

Returns

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_properties_interface_run_list_properties ()

gboolean
tp_cli_properties_interface_run_list_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                GPtrArray **out_Available_Properties,
                                GError **error,
                                GMainLoop **loop);

tp_cli_properties_interface_run_list_properties is deprecated and should not be used in newly-written code.

Call the method ListProperties and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Returns a dictionary of the properties available on this channel.

Parameters

proxy	A TpProxy or subclass
timeout_ms	Timeout in milliseconds, or -1 for default
out_Available_Properties	Used to return an 'out' argument if `TRUE` is returned: An array of structs containing: <ul> <li>an integer identifier</li> <li>a string property name</li> <li>a string representing the D-Bus signature of this property</li> <li>a bitwise OR of the flags applicable to this property</li> </ul>
error	If not `NULL`, used to return errors if `FALSE` is returned
loop	If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`

Returns

TRUE on success, FALSE and sets error on error

tp_cli_properties_interface_callback_for_set_properties ()

void
(*tp_cli_properties_interface_callback_for_set_properties)
                               (TpProxy *proxy,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a SetProperties method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_properties_interface_call_set_properties ()

TpProxyPendingCall *
tp_cli_properties_interface_call_set_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                const GPtrArray *in_Properties,
                                tp_cli_properties_interface_callback_for_set_properties callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a SetProperties method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Takes an array of (identifier, value) pairs containing desired values to set the given properties. In the case of any errors, no properties will be changed. When the changes have been acknowledged by the server, the PropertiesChanged signal will be emitted.</p> <p>All properties given must have the PROPERTY_FLAG_WRITE flag, or PermissionDenied will be returned. If any variants are of the wrong type, NotAvailable will be returned. If any given property identifiers are invalid, InvalidArgument will be returned.</p>

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Properties	Used to pass an 'in' argument: An array mapping integer property identifiers to boxed values
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`

Returns

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_properties_interface_run_set_properties ()

gboolean
tp_cli_properties_interface_run_set_properties
                               (gpointer proxy,
                                gint timeout_ms,
                                const GPtrArray *in_Properties,
                                GError **error,
                                GMainLoop **loop);

tp_cli_properties_interface_run_set_properties is deprecated and should not be used in newly-written code.

Call the method SetProperties and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Parameters

proxy	A TpProxy or subclass
timeout_ms	Timeout in milliseconds, or -1 for default
in_Properties	Used to pass an 'in' argument: An array mapping integer property identifiers to boxed values
error	If not `NULL`, used to return errors if `FALSE` is returned
loop	If not `NULL`, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with `g_main_loop_quit()`, causing a return of `FALSE` with `error` set to `TP_DBUS_ERROR_CANCELLED`

Returns

TRUE on success, FALSE and sets error on error

tp_cli_properties_interface_signal_callback_properties_changed ()

void
(*tp_cli_properties_interface_signal_callback_properties_changed)
                               (TpProxy *proxy,
                                const GPtrArray *arg_Properties,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal PropertiesChanged.

Parameters

proxy	The proxy on which `tp_cli_properties_interface_connect_to_properties_changed()` was called
arg_Properties	<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> <ul> <li>integer identifiers</li> <li>variant boxed values</li> </ul> <p>The array should contain only properties whose values have actually changed.</p>
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_properties_interface_connect_to_properties_changed ()

TpProxySignalConnection *
tp_cli_properties_interface_connect_to_properties_changed
                               (gpointer proxy,
                                tp_cli_properties_interface_signal_callback_properties_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal PropertiesChanged.

Emitted when the value of readable properties has changed.

Parameters

proxy	A TpProxy or subclass
callback	Callback to be called when the signal is received
user_data	User-supplied data for the callback
destroy	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
weak_object	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_properties_interface_signal_callback_property_flags_changed ()

void
(*tp_cli_properties_interface_signal_callback_property_flags_changed)
                               (TpProxy *proxy,
                                const GPtrArray *arg_Properties,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal PropertyFlagsChanged.

Parameters

proxy	The proxy on which `tp_cli_properties_interface_connect_to_property_flags_changed()` was called
arg_Properties	<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>An array of structs containing:</p> <ul> <li>integer identifiers</li> <li>a bitwise OR of the current flags</li> </ul> <p>The array should contain only properties whose flags have actually changed.</p>
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

tp_cli_properties_interface_connect_to_property_flags_changed ()

TpProxySignalConnection *
tp_cli_properties_interface_connect_to_property_flags_changed
                               (gpointer proxy,
                                tp_cli_properties_interface_signal_callback_property_flags_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal PropertyFlagsChanged.

Emitted when the flags of some room properties have changed.

Parameters

proxy	A TpProxy or subclass
callback	Callback to be called when the signal is received
user_data	User-supplied data for the callback
destroy	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
weak_object	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.