Description
GDBusProxy is a base class used for proxies to access a D-Bus
interface on a remote object. A GDBusProxy can be constructed for
both well-known and unique names.
By default, GDBusProxy will cache all properties (and listen to
changes) of the remote object, and proxy all signals that get
emitted. This behaviour can be changed by passing suitable
GDBusProxyFlags when the proxy is created. If the proxy is for a
well-known name, the property cache is flushed when the name owner
vanishes and reloaded when a name owner appears.
The unique name owner of the proxy's name is tracked and can be read from
“g-name-owner”. Connect to the “notify” signal to
get notified of changes. Additionally, only signals and property
changes emitted from the current name owner are considered and
calls are always sent to the current name owner. This avoids a
number of race conditions when the name is lost by one owner and
claimed by another. However, if no name owner currently exists,
then calls will be sent to the well-known name which may result in
the message bus launching an owner (unless
G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
The generic “g-properties-changed” and
“g-signal” signals are not very convenient to work with.
Therefore, the recommended way of working with proxies is to subclass
GDBusProxy, and have more natural properties and signals in your derived
class. This example shows how this can
easily be done using the gdbus-codegen tool.
A GDBusProxy instance can be used from multiple threads but note
that all signals (e.g. “g-signal”, “g-properties-changed”
and “notify”) are emitted in the
thread-default main context
of the thread where the instance was constructed.
An example using a proxy for a well-known name can be found in
gdbus-example-watch-proxy.c
Functions
g_dbus_proxy_new ()
void
g_dbus_proxy_new (GDBusConnection *connection,
GDBusProxyFlags flags,
GDBusInterfaceInfo *info,
const gchar *name,
const gchar *object_path,
const gchar *interface_name,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Creates a proxy for accessing interface_name
on the remote object
at object_path
owned by name
at connection
and asynchronously
loads D-Bus properties unless the
G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
the “g-properties-changed” signal to get notified about
property changes.
If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
match rules for signals. Connect to the “g-signal” signal
to handle signals from the remote object.
If both G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
guaranteed to complete immediately without blocking.
If name
is a well-known name and the
G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
flags aren't set and no name owner currently exists, the message bus
will be requested to launch a name owner for the name.
This is a failable asynchronous constructor - when the proxy is
ready, callback
will be invoked and you can use
g_dbus_proxy_new_finish() to get the result.
See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
GDBusProxy is used in this example.
Since: 2.26
g_dbus_proxy_new_finish ()
GDBusProxy *
g_dbus_proxy_new_finish (GAsyncResult *res,
GError **error);
Finishes creating a GDBusProxy.
Returns
A GDBusProxy or NULL if error
is set.
Free with g_object_unref().
[transfer full]
Since: 2.26
g_dbus_proxy_new_sync ()
GDBusProxy *
g_dbus_proxy_new_sync (GDBusConnection *connection,
GDBusProxyFlags flags,
GDBusInterfaceInfo *info,
const gchar *name,
const gchar *object_path,
const gchar *interface_name,
GCancellable *cancellable,
GError **error);
Creates a proxy for accessing interface_name
on the remote object
at object_path
owned by name
at connection
and synchronously
loads D-Bus properties unless the
G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
match rules for signals. Connect to the “g-signal” signal
to handle signals from the remote object.
If both G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
guaranteed to return immediately without blocking.
If name
is a well-known name and the
G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
flags aren't set and no name owner currently exists, the message bus
will be requested to launch a name owner for the name.
This is a synchronous failable constructor. See g_dbus_proxy_new()
and g_dbus_proxy_new_finish() for the asynchronous version.
GDBusProxy is used in this example.
Returns
A GDBusProxy or NULL if error is set.
Free with g_object_unref().
[transfer full]
Since: 2.26
g_dbus_proxy_new_for_bus_finish ()
GDBusProxy *
g_dbus_proxy_new_for_bus_finish (GAsyncResult *res,
GError **error);
Finishes creating a GDBusProxy.
Returns
A GDBusProxy or NULL if error
is set.
Free with g_object_unref().
[transfer full]
Since: 2.26
g_dbus_proxy_get_flags ()
GDBusProxyFlags
g_dbus_proxy_get_flags (GDBusProxy *proxy);
Gets the flags that proxy
was constructed with.
Since: 2.26
g_dbus_proxy_get_name ()
const gchar *
g_dbus_proxy_get_name (GDBusProxy *proxy);
Gets the name that proxy
was constructed for.
Returns
A string owned by proxy
. Do not free.
Since: 2.26
g_dbus_proxy_get_name_owner ()
gchar *
g_dbus_proxy_get_name_owner (GDBusProxy *proxy);
The unique name that owns the name that proxy
is for or NULL if
no-one currently owns that name. You may connect to the
“notify” signal to track changes to the
“g-name-owner” property.
Returns
The name owner or NULL if no name
owner exists. Free with g_free().
[transfer full][nullable]
Since: 2.26
g_dbus_proxy_get_object_path ()
const gchar *
g_dbus_proxy_get_object_path (GDBusProxy *proxy);
Gets the object path proxy
is for.
Returns
A string owned by proxy
. Do not free.
Since: 2.26
g_dbus_proxy_get_interface_name ()
const gchar *
g_dbus_proxy_get_interface_name (GDBusProxy *proxy);
Gets the D-Bus interface name proxy
is for.
Returns
A string owned by proxy
. Do not free.
Since: 2.26
g_dbus_proxy_get_cached_property ()
GVariant *
g_dbus_proxy_get_cached_property (GDBusProxy *proxy,
const gchar *property_name);
Looks up the value for a property from the cache. This call does no
blocking IO.
If proxy
has an expected interface (see
“g-interface-info”) and property_name
is referenced by
it, then value
is checked against the type of the property.
Returns
A reference to the GVariant instance
that holds the value for property_name
or NULL if the value is not in
the cache. The returned reference must be freed with g_variant_unref().
[transfer full][nullable]
Since: 2.26
g_dbus_proxy_set_cached_property ()
void
g_dbus_proxy_set_cached_property (GDBusProxy *proxy,
const gchar *property_name,
GVariant *value);
If value
is not NULL, sets the cached value for the property with
name property_name
to the value in value
.
If value
is NULL, then the cached value is removed from the
property cache.
If proxy
has an expected interface (see
“g-interface-info”) and property_name
is referenced by
it, then value
is checked against the type of the property.
If the value
GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.
Normally you will not need to use this method since proxy
is tracking changes using the
org.freedesktop.DBus.Properties.PropertiesChanged
D-Bus signal. However, for performance reasons an object may
decide to not use this signal for some properties and instead
use a proprietary out-of-band mechanism to transmit changes.
As a concrete example, consider an object with a property
ChatroomParticipants which is an array of strings. Instead of
transmitting the same (long) array every time the property changes,
it is more efficient to only transmit the delta using e.g. signals
ChatroomParticipantJoined(String name) and
ChatroomParticipantParted(String name).
Since: 2.26
g_dbus_proxy_get_cached_property_names ()
gchar **
g_dbus_proxy_get_cached_property_names
(GDBusProxy *proxy);
Gets the names of all cached properties on proxy
.
Returns
A
NULL-terminated array of strings or NULL if
proxy
has no cached properties. Free the returned array with
g_strfreev().
[transfer full][nullable][array zero-terminated=1]
Since: 2.26
g_dbus_proxy_set_interface_info ()
void
g_dbus_proxy_set_interface_info (GDBusProxy *proxy,
GDBusInterfaceInfo *info);
Ensure that interactions with proxy
conform to the given
interface. See the “g-interface-info” property for more
details.
Since: 2.26
g_dbus_proxy_call ()
void
g_dbus_proxy_call (GDBusProxy *proxy,
const gchar *method_name,
GVariant *parameters,
GDBusCallFlags flags,
gint timeout_msec,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously invokes the method_name
method on proxy
.
If method_name
contains any dots, then name
is split into interface and
method name parts. This allows using proxy
for invoking methods on
other interfaces.
If the GDBusConnection associated with proxy
is closed then
the operation will fail with G_IO_ERROR_CLOSED. If
cancellable
is canceled, the operation will fail with
G_IO_ERROR_CANCELLED. If parameters
contains a value not
compatible with the D-Bus protocol, the operation fails with
G_IO_ERROR_INVALID_ARGUMENT.
If the parameters
GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
If proxy
has an expected interface (see
“g-interface-info”) and method_name
is referenced by it,
then the return value is checked against the return type.
This is an asynchronous method. When the operation is finished,
callback
will be invoked in the
thread-default main context
of the thread you are calling this method from.
You can then call g_dbus_proxy_call_finish() to get the result of
the operation. See g_dbus_proxy_call_sync() for the synchronous
version of this method.
If callback
is NULL then the D-Bus method call message will be sent with
the G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
Since: 2.26
g_dbus_proxy_call_finish ()
GVariant *
g_dbus_proxy_call_finish (GDBusProxy *proxy,
GAsyncResult *res,
GError **error);
Finishes an operation started with g_dbus_proxy_call().
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.26
g_dbus_proxy_call_sync ()
GVariant *
g_dbus_proxy_call_sync (GDBusProxy *proxy,
const gchar *method_name,
GVariant *parameters,
GDBusCallFlags flags,
gint timeout_msec,
GCancellable *cancellable,
GError **error);
Synchronously invokes the method_name
method on proxy
.
If method_name
contains any dots, then name
is split into interface and
method name parts. This allows using proxy
for invoking methods on
other interfaces.
If the GDBusConnection associated with proxy
is disconnected then
the operation will fail with G_IO_ERROR_CLOSED. If
cancellable
is canceled, the operation will fail with
G_IO_ERROR_CANCELLED. If parameters
contains a value not
compatible with the D-Bus protocol, the operation fails with
G_IO_ERROR_INVALID_ARGUMENT.
If the parameters
GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
The calling thread is blocked until a reply is received. See
g_dbus_proxy_call() for the asynchronous version of this
method.
If proxy
has an expected interface (see
“g-interface-info”) and method_name
is referenced by it,
then the return value is checked against the return type.
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.26
g_dbus_proxy_call_with_unix_fd_list_finish ()
GVariant *
g_dbus_proxy_call_with_unix_fd_list_finish
(GDBusProxy *proxy,
GUnixFDList **out_fd_list,
GAsyncResult *res,
GError **error);
Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.30
g_dbus_proxy_call_with_unix_fd_list_sync ()
GVariant *
g_dbus_proxy_call_with_unix_fd_list_sync
(GDBusProxy *proxy,
const gchar *method_name,
GVariant *parameters,
GDBusCallFlags flags,
gint timeout_msec,
GUnixFDList *fd_list,
GUnixFDList **out_fd_list,
GCancellable *cancellable,
GError **error);
Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.
This method is only available on UNIX.
Returns
NULL if error
is set. Otherwise a GVariant tuple with
return values. Free with g_variant_unref().
Since: 2.30
Property Details
The “g-default-timeout” property
“g-default-timeout” gint
The timeout to use if -1 (specifying default timeout) is passed
as timeout_msec
in the g_dbus_proxy_call() and
g_dbus_proxy_call_sync() functions.
This allows applications to set a proxy-wide timeout for all
remote method invocations on the proxy. If this property is -1,
the default timeout (typically 25 seconds) is used. If set to
G_MAXINT, then no timeout is used.
Owner: GDBusProxy
Flags: Read / Write / Construct
Allowed values: >= -1
Default value: -1
Since: 2.26
The “g-interface-info” property
“g-interface-info” GDBusInterfaceInfo *
Ensure that interactions with this proxy conform to the given
interface. This is mainly to ensure that malformed data received
from the other peer is ignored. The given GDBusInterfaceInfo is
said to be the "expected interface".
The checks performed are:
When completing a method call, if the type signature of
the reply message isn't what's expected, the reply is
discarded and the GError is set to G_IO_ERROR_INVALID_ARGUMENT.
Received signals that have a type signature mismatch are dropped and
a warning is logged via g_warning().
Properties received via the initial GetAll() call or via the
::PropertiesChanged signal (on the
org.freedesktop.DBus.Properties
interface) or set using g_dbus_proxy_set_cached_property()
with a type signature mismatch are ignored and a warning is
logged via g_warning().
Note that these checks are never done on methods, signals and
properties that are not referenced in the given
GDBusInterfaceInfo, since extending a D-Bus interface on the
service-side is not considered an ABI break.
Owner: GDBusProxy
Flags: Read / Write
Since: 2.26
The “g-interface-name” property
“g-interface-name” gchar *
The D-Bus interface name the proxy is for.
Owner: GDBusProxy
Flags: Read / Write / Construct Only
Default value: NULL
Since: 2.26
The “g-name” property
“g-name” gchar *
The well-known or unique name that the proxy is for.
Owner: GDBusProxy
Flags: Read / Write / Construct Only
Default value: NULL
Since: 2.26
The “g-name-owner” property
“g-name-owner” gchar *
The unique name that owns “g-name” or NULL if no-one
currently owns that name. You may connect to “notify” signal to
track changes to this property.
Owner: GDBusProxy
Flags: Read
Default value: NULL
Since: 2.26
The “g-object-path” property
“g-object-path” gchar *
The object path the proxy is for.
Owner: GDBusProxy
Flags: Read / Write / Construct Only
Default value: NULL
Since: 2.26