DBusProxy - Client-side proxies. More...
#include <giomm/dbusproxy.h>
Public Member Functions | |
virtual | ~DBusProxy () |
GDBusProxy* | gobj () |
Provides access to the underlying C GObject. | |
const GDBusProxy* | gobj () const |
Provides access to the underlying C GObject. | |
GDBusProxy* | gobj_copy () |
Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. | |
DBusProxyFlags | get_flags () const |
Gets the flags that proxy was constructed with. | |
Glib::RefPtr< DBusConnection > | get_connection () |
Gets the connection proxy is for. | |
Glib::RefPtr< const DBusConnection > | get_connection () const |
Gets the connection proxy is for. | |
Glib::ustring | get_name () const |
Gets the name that proxy was constructed for. | |
Glib::ustring | get_name_owner () const |
The unique name that owns the name that proxy is for or 0 if no-one currently owns that name. | |
Glib::ustring | get_object_path () const |
Gets the object path proxy is for. | |
Glib::ustring | get_interface_name () const |
Gets the D-Bus interface name proxy is for. | |
int | get_default_timeout () const |
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. | |
void | set_default_timeout (int timeout_msec) |
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. | |
void | set_cached_property (const Glib::ustring& property_name, const Glib::VariantBase&value) |
If value is not 0 , sets the cached value for the property with name property_name to the value in value. | |
Glib::StringArrayHandle | get_cached_property_names () const |
Gets the names of all cached properties on proxy. | |
void | set_interface_info (const Glib::RefPtr< DBusInterfaceInfo >& info) |
Ensure that interactions with proxy conform to the given interface. | |
Glib::RefPtr< DBusInterfaceInfo > | get_interface_info () |
Returns the DBusInterfaceInfo, if any, specifying the minimal interface that proxy conforms to. | |
Glib::RefPtr< const DBusInterfaceInfo > | get_interface_info () const |
Returns the DBusInterfaceInfo, if any, specifying the minimal interface that proxy conforms to. | |
Static Public Member Functions | |
static void | create (const Glib::RefPtr< DBusConnection >& connection, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >()) |
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 DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. | |
static Glib::RefPtr< DBusProxy > | create_finish (const Glib::RefPtr< AsyncResult >& result) |
static Glib::RefPtr< DBusProxy > | create (const Glib::RefPtr< DBusConnection >& connection, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >()) |
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 DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. | |
static void | create_for_bus (BusType bus_type, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >()) |
Like g_dbus_proxy_new() but takes a BusType instead of a DBusConnection. | |
static Glib::RefPtr< DBusProxy > | create_for_bus_finish (const Glib::RefPtr< AsyncResult >& result) |
static Glib::RefPtr< DBusProxy > | create_for_bus (BusType bus_type, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >()) |
Protected Member Functions | |
DBusProxy (const Glib::RefPtr< DBusConnection >& connection, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable) | |
DBusProxy (const Glib::RefPtr< DBusConnection >& connection, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const Glib::RefPtr< Cancellable >& cancellable) | |
DBusProxy (BusType bus_type, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable) | |
DBusProxy (BusType bus_type, DBusProxyFlags flags, const Glib::RefPtr< DBusInterfaceInfo >& info, const Glib::ustring& name, const Glib::ustring& object_path, const Glib::ustring& interface_name, const Glib::RefPtr< Cancellable >& cancellable) | |
Related Functions | |
(Note that these are not member functions.) | |
Glib::RefPtr< Gio::DBusProxy > | wrap (GDBusProxy* object, bool take_copy=false) |
A Glib::wrap() method for this object. |
DBusProxy - Client-side proxies.
DBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A DBusProxy can be constructed for both well-known and unique names.
By default, DBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that gets emitted. This behaviour can be changed by passing suitable DBusProxyFlags 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.
If a DBusProxy is used for a well-known name, the owner of the name is tracked and can be read from property_g_name_owner(). Connect to the signal_notify() signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered. This avoids a number of race conditions when the name is lost by one owner and claimed by another.
The generic signal_g_properties_changed() and signal_g_signal() signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass DBusProxy, and have more natural properties and signals in your derived class.
The C API docs has more information and an example.
virtual Gio::DBusProxy::~DBusProxy | ( | ) | [virtual] |
Gio::DBusProxy::DBusProxy | ( | const Glib::RefPtr< DBusConnection >& | connection, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const SlotAsyncReady& | slot, | |||
const Glib::RefPtr< Cancellable >& | cancellable | |||
) | [protected] |
Gio::DBusProxy::DBusProxy | ( | const Glib::RefPtr< DBusConnection >& | connection, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const Glib::RefPtr< Cancellable >& | cancellable | |||
) | [protected] |
Gio::DBusProxy::DBusProxy | ( | BusType | bus_type, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const SlotAsyncReady& | slot, | |||
const Glib::RefPtr< Cancellable >& | cancellable | |||
) | [protected] |
Gio::DBusProxy::DBusProxy | ( | BusType | bus_type, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const Glib::RefPtr< Cancellable >& | cancellable | |||
) | [protected] |
static Glib::RefPtr<DBusProxy> Gio::DBusProxy::create | ( | const Glib::RefPtr< DBusConnection >& | connection, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const Glib::RefPtr< Cancellable >& | cancellable = Glib::RefPtr< Cancellable >() | |||
) | [static] |
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 DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
If the DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the DBusProxy::g-signal signal to handle signals from the remote object.
If name is a well-known name and the DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn'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.
See <xref linkend="gdbus-wellknown-proxy"> for an example of how DBusProxy can be used.
connection | A DBusConnection. | |
flags | Flags used when constructing the proxy. | |
info | A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or 0 . | |
name | A bus name (well-known or unique) or 0 if connection is not a message bus connection. | |
object_path | An object path. | |
interface_name | A D-Bus interface name. | |
cancellable | A Cancellable or 0 . |
0
if error is set. Free with Glib::object_unref(). static void Gio::DBusProxy::create | ( | const Glib::RefPtr< DBusConnection >& | connection, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const SlotAsyncReady& | slot, | |||
const Glib::RefPtr< Cancellable >& | cancellable = Glib::RefPtr< Cancellable >() | |||
) | [static] |
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 DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
Connect to the DBusProxy::g-properties-changed signal to get notified about property changes.
If the DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the DBusProxy::g-signal signal to handle signals from the remote object.
If name is a well-known name and the DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn'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.
See <xref linkend="gdbus-wellknown-proxy"> for an example of how DBusProxy can be used.
connection | A DBusConnection. | |
flags | Flags used when constructing the proxy. | |
info | A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or 0 . | |
name | A bus name (well-known or unique) or 0 if connection is not a message bus connection. | |
object_path | An object path. | |
interface_name | A D-Bus interface name. | |
cancellable | A Cancellable or 0 . | |
callback | Callback function to invoke when the proxy is ready. | |
user_data | User data to pass to callback. |
static Glib::RefPtr<DBusProxy> Gio::DBusProxy::create_finish | ( | const Glib::RefPtr< AsyncResult >& | result | ) | [static] |
Glib::Error. |
static Glib::RefPtr<DBusProxy> Gio::DBusProxy::create_for_bus | ( | BusType | bus_type, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const Glib::RefPtr< Cancellable >& | cancellable = Glib::RefPtr< Cancellable >() | |||
) | [static] |
static void Gio::DBusProxy::create_for_bus | ( | BusType | bus_type, | |
DBusProxyFlags | flags, | |||
const Glib::RefPtr< DBusInterfaceInfo >& | info, | |||
const Glib::ustring& | name, | |||
const Glib::ustring& | object_path, | |||
const Glib::ustring& | interface_name, | |||
const SlotAsyncReady& | slot, | |||
const Glib::RefPtr< Cancellable >& | cancellable = Glib::RefPtr< Cancellable >() | |||
) | [static] |
Like g_dbus_proxy_new() but takes a BusType instead of a DBusConnection.
See <xref linkend="gdbus-wellknown-proxy"> for an example of how DBusProxy can be used.
bus_type | A BusType. | |
flags | Flags used when constructing the proxy. | |
info | A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or 0 . | |
name | A bus name (well-known or unique). | |
object_path | An object path. | |
interface_name | A D-Bus interface name. | |
cancellable | A Cancellable or 0 . | |
callback | Callback function to invoke when the proxy is ready. | |
user_data | User data to pass to callback. |
static Glib::RefPtr<DBusProxy> Gio::DBusProxy::create_for_bus_finish | ( | const Glib::RefPtr< AsyncResult >& | result | ) | [static] |
Glib::Error. |
Glib::StringArrayHandle Gio::DBusProxy::get_cached_property_names | ( | ) | const |
Gets the names of all cached properties on proxy.
0
-terminated array of strings or 0
if proxy has no cached properties. Free the returned array with Glib::strfreev(). Glib::RefPtr<const DBusConnection> Gio::DBusProxy::get_connection | ( | ) | const |
Gets the connection proxy is for.
Glib::RefPtr<DBusConnection> Gio::DBusProxy::get_connection | ( | ) |
Gets the connection proxy is for.
int Gio::DBusProxy::get_default_timeout | ( | ) | const |
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.
See the DBusProxy:g-default-timeout property for more details.
DBusProxyFlags Gio::DBusProxy::get_flags | ( | ) | const |
Gets the flags that proxy was constructed with.
Glib::RefPtr<const DBusInterfaceInfo> Gio::DBusProxy::get_interface_info | ( | ) | const |
Returns the DBusInterfaceInfo, if any, specifying the minimal interface that proxy conforms to.
See the DBusProxy:g-interface-info property for more details.
0
. Do not unref the returned object, it is owned by proxy. Glib::RefPtr<DBusInterfaceInfo> Gio::DBusProxy::get_interface_info | ( | ) |
Returns the DBusInterfaceInfo, if any, specifying the minimal interface that proxy conforms to.
See the DBusProxy:g-interface-info property for more details.
0
. Do not unref the returned object, it is owned by proxy. Glib::ustring Gio::DBusProxy::get_interface_name | ( | ) | const |
Gets the D-Bus interface name proxy is for.
Glib::ustring Gio::DBusProxy::get_name | ( | ) | const |
Gets the name that proxy was constructed for.
Glib::ustring Gio::DBusProxy::get_name_owner | ( | ) | const |
The unique name that owns the name that proxy is for or 0
if no-one currently owns that name.
You may connect to the Object::notify signal to track changes to the DBusProxy:g-name-owner property.
0
if no name owner exists. Free with Glib::free(). Glib::ustring Gio::DBusProxy::get_object_path | ( | ) | const |
const GDBusProxy* Gio::DBusProxy::gobj | ( | ) | const [inline] |
Provides access to the underlying C GObject.
Reimplemented from Gio::AsyncInitable.
GDBusProxy* Gio::DBusProxy::gobj | ( | ) | [inline] |
Provides access to the underlying C GObject.
Reimplemented from Gio::AsyncInitable.
GDBusProxy* Gio::DBusProxy::gobj_copy | ( | ) |
Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void Gio::DBusProxy::set_cached_property | ( | const Glib::ustring& | property_name, | |
const Glib::VariantBase& | value | |||
) |
If value is not 0
, sets the cached value for the property with name property_name to the value in value.
If value is 0
, then the cached value is removed from the property cache.
If proxy has an expected interface (see DBusProxy:g-interface-info), then property_name (for existence) and value (for the type) is checked against it.
If the value Variant is floating, it is consumed. This allows convenient 'inline' use of Glib::variant_new(), e.g. |[ g_dbus_proxy_set_cached_property (proxy, "SomeProperty", g_variant_new ("(si)", "A String", 42)); ]|
Normally you will not need to use this method since proxy is tracking changes using the <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> 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 <literal>ChatroomParticipants</literal> 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 <literal>ChatroomParticipantJoined(String name)</literal> and <literal>ChatroomParticipantParted(String name)</literal>.
property_name | Property name. | |
value | Value for the property or 0 to remove it from the cache. |
void Gio::DBusProxy::set_default_timeout | ( | int | timeout_msec | ) |
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.
See the DBusProxy:g-default-timeout property for more details.
timeout_msec | Timeout in milliseconds. |
void Gio::DBusProxy::set_interface_info | ( | const Glib::RefPtr< DBusInterfaceInfo >& | info | ) |
Ensure that interactions with proxy conform to the given interface.
For example, when completing a method call, if the type signature of the message isn't what's expected, the given Error is set. Signals that have a type signature mismatch are simply dropped.
See the DBusProxy:g-interface-info property for more details.
info | Minimum interface this proxy conforms to or 0 to unset. |
Glib::RefPtr< Gio::DBusProxy > wrap | ( | GDBusProxy * | object, | |
bool | take_copy = false | |||
) | [related] |
A Glib::wrap() method for this object.
object | The C instance. | |
take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref. |