Class
GioDBusProxy
since: 2.26
Description [src]
class Gio.DBusProxy : GObject.Object
implements Gio.AsyncInitable, Gio.DBusInterface, Gio.Initable {
/* No available fields */
}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
GDBusProxy:g-name-owner. Connect to the
GObject::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).
If the proxy is for a stateless D-Bus service, where the name owner may
be started and stopped between calls, the
GDBusProxy:g-name-owner tracking of GDBusProxy will cause the
proxy to drop signal and property changes from the service after it has
restarted for the first time. When interacting with a stateless D-Bus
service, do not use GDBusProxy — use direct D-Bus method calls and signal connections.
The generic GDBusProxy::g-properties-changed and
GDBusProxy::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. GDBusProxy::g-signal,
GDBusProxy::g-properties-changed and
GObject::notify) are emitted in the thread-default main
context (see g_main_context_push_thread_default()) 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.
Available since: 2.26
Constructors
g_dbus_proxy_new_for_bus_sync
Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.
since: 2.26
g_dbus_proxy_new_sync
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.
since: 2.26
Functions
g_dbus_proxy_new
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 GDBusProxy::g-properties-changed signal to get notified about
property changes.
since: 2.26
g_dbus_proxy_new_for_bus
Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.
since: 2.26
Instance methods
g_dbus_proxy_call_with_unix_fd_list
Like g_dbus_proxy_call() but also takes a GUnixFDList object.
since: 2.30
g_dbus_proxy_call_with_unix_fd_list_finish
Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
since: 2.30
g_dbus_proxy_call_with_unix_fd_list_sync
Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.
since: 2.30
g_dbus_proxy_get_cached_property
Looks up the value for a property from the cache. This call does no blocking IO.
since: 2.26
g_dbus_proxy_get_cached_property_names
Gets the names of all cached properties on proxy.
since: 2.26
g_dbus_proxy_get_default_timeout
Gets 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.
since: 2.26
g_dbus_proxy_get_interface_info
Returns the GDBusInterfaceInfo, if any, specifying the interface
that proxy conforms to. See the GDBusProxy:g-interface-info
property for more details.
since: 2.26
g_dbus_proxy_get_name_owner
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
GObject::notify signal to track changes to the
GDBusProxy:g-name-owner property.
since: 2.26
g_dbus_proxy_set_cached_property
If value is not NULL, sets the cached value for the property with
name property_name to the value in value.
since: 2.26
g_dbus_proxy_set_default_timeout
Sets 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.
since: 2.26
g_dbus_proxy_set_interface_info
Ensure that interactions with proxy conform to the given
interface. See the GDBusProxy:g-interface-info property for more details.
since: 2.26
Methods inherited from GAsyncInitable (3)
g_async_initable_init_async
Starts asynchronous initialization of the object implementing the
interface. This must be done before any real use of the object after
initial construction. If the object also implements GInitable you can
optionally call g_initable_init() instead.
since: 2.22
g_async_initable_init_finish
Finishes asynchronous initialization and returns the result. See g_async_initable_init_async().
since: 2.22
g_async_initable_new_finish
Finishes the async construction for the various g_async_initable_new
calls, returning the created object or NULL on error.
since: 2.22
Methods inherited from GDBusInterface (4)
g_dbus_interface_dup_object
Gets the GDBusObject that interface_ belongs to, if any.
since: 2.32
g_dbus_interface_get_info
Gets D-Bus introspection information for the D-Bus interface
implemented by interface_.
since: 2.30
g_dbus_interface_get_object
Gets the GDBusObject that interface_ belongs to, if any.
since: 2.30
g_dbus_interface_set_object
Sets the GDBusObject for interface_ to object.
since: 2.30
Methods inherited from GInitable (1)
Properties
Gio.DBusProxy:g-bus-type
If this property is not G_BUS_TYPE_NONE, then
GDBusProxy:g-connection must be NULL and will be set to the
GDBusConnection obtained by calling g_bus_get() with the value
of this property.
since: 2.26
Gio.DBusProxy:g-default-timeout
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.
since: 2.26
Gio.DBusProxy:g-interface-info
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”.
since: 2.26
Gio.DBusProxy:g-name-owner
The unique name that owns GDBusProxy:g-name or NULL if no-one
currently owns that name. You may connect to GObject::notify signal to
track changes to this property.
since: 2.26
Signals
Gio.DBusProxy::g-properties-changed
Emitted when one or more D-Bus properties on proxy changes. The
local cache has already been updated when this signal fires. Note
that both changed_properties and invalidated_properties are
guaranteed to never be NULL (either may be empty though).
since: 2.26
Gio.DBusProxy::g-signal
Emitted when a signal from the remote object and interface that proxy is for, has been received.
since: 2.26
Signals inherited from GObject (1)
GObject::notify
The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.
Class structure
struct GioDBusProxyClass {
void (* g_properties_changed) (
GDBusProxy* proxy,
GVariant* changed_properties,
const gchar* const* invalidated_properties
);
void (* g_signal) (
GDBusProxy* proxy,
const gchar* sender_name,
const gchar* signal_name,
GVariant* parameters
);
}Class structure for GDBusProxy.
Class members
g_properties_changed: void (* g_properties_changed) ( GDBusProxy* proxy, GVariant* changed_properties, const gchar* const* invalidated_properties )Signal class handler for the
GDBusProxy::g-properties-changedsignal.g_signal: void (* g_signal) ( GDBusProxy* proxy, const gchar* sender_name, const gchar* signal_name, GVariant* parameters )Signal class handler for the
GDBusProxy::g-signalsignal.
Virtual methods
Gio.DBusProxyClass.g_properties_changed
Signal class handler for the GDBusProxy::g-properties-changed signal.