A client-side proxy. More...
#include <giomm/dbusproxy.h>
Public Types | |
| using | MapChangedProperties = std::map< Glib::ustring, Glib::VariantBase > |
 Public Types inherited from Glib::Object | |
| using | DestroyNotify = void(*)(gpointer data) |
Related Symbols | |
(Note that these are not member symbols.) | |
| Glib::RefPtr< Gio::DBus::Proxy > | wrap (GDBusProxy *object, bool take_copy=false) |
| A Glib::wrap() method for this object. | |
| Related Symbols inherited from Glib::Object | |
| Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false) |
| Related Symbols inherited from Gio::Initable | |
| Glib::RefPtr< Gio::Initable > | wrap (GInitable *object, bool take_copy=false) |
| A Glib::wrap() method for this object. | |
| Related Symbols inherited from Gio::AsyncInitable | |
| Glib::RefPtr< Gio::AsyncInitable > | wrap (GAsyncInitable *object, bool take_copy=false) |
| A Glib::wrap() method for this object. | |
| Related Symbols inherited from Gio::DBus::Interface | |
| Glib::RefPtr< Gio::DBus::Interface > | wrap (GDBusInterface *object, bool take_copy=false) |
| A Glib::wrap() method for this object. | |
Detailed Description
A client-side proxy.
This is a base class used for proxies to access a D-Bus interface on a remote object. It can be constructed for both well-known and unique names.
By default, Proxy 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 ProxyFlags 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 Proxy is used for a well-known name, the owner of the name is tracked and can be read from property_g_name_owner().
The generic signal_properties_changed() and signal_signal() signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass Proxy, and have more natural properties and signals in your derived class.
This documentation was adapted from the C API documentation. The C API docs has more information and an example.
Member Typedef Documentation
◆ MapChangedProperties
Constructor & Destructor Documentation
◆ Proxy() [1/9]
|
noexcept |
◆ ~Proxy()
|
overridenoexcept |
◆ Proxy() [2/9]
|
protected |
◆ Proxy() [3/9]
|
protected |
◆ Proxy() [4/9]
|
protected |
◆ Proxy() [5/9]
|
protected |
◆ Proxy() [6/9]
|
protected |
◆ Proxy() [7/9]
|
protected |
◆ Proxy() [8/9]
|
protected |
◆ Proxy() [9/9]
|
protected |
Member Function Documentation
◆ call() [1/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call() [2/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call() [3/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call() [4/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const SlotAsyncReady & | slot, | ||
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
Like g_dbus_proxy_call() but also takes a UnixFDList object.
This method is only available on UNIX.
- Parameters
-
method_name Name of method to invoke. parameters A Variant tuple with parameters for the signal or nullptrif not passing parameters.flags Flags from the Gio::DBus::CallFlags enumeration. timeout_msec The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. fd_list A UnixFDList or nullptr.cancellable A Cancellable or nullptr.slot A SlotAsyncReady to call when the request is satisfied. Use another overload without this parameter if your don't care about the result of the method invocation.
◆ call() [5/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const SlotAsyncReady & | slot, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call() [6/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call() [7/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const SlotAsyncReady & | slot, | ||
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
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 Gio::DBus::Connection associated with proxy is closed then the operation will fail with Gio::Error::CLOSED. If cancellable is canceled, the operation will fail with Gio::Error::CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with Gio::Error::INVALID_ARGUMENT.
If the parameters Variant is floating, it is consumed. This allows convenient 'inline' use of Glib::variant_new(), e.g.:
[C example ellipted]
If proxy has an expected interface (see Gio::DBus::Proxy::property_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, slot will be invoked in the [thread-default main context][g-main-context-push-thread-default] 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 slot is nullptr then the D-Bus method call message will be sent with the Gio::DBus::MessageFlags::NO_REPLY_EXPECTED flag set.
- Parameters
-
method_name Name of method to invoke. parameters A Variant tuple with parameters for the signal or nullptrif not passing parameters.flags Flags from the Gio::DBus::CallFlags enumeration. timeout_msec The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. cancellable A Cancellable or nullptr.slot A SlotAsyncReady to call when the request is satisfied. Use another overload without this parameter if your don't care about the result of the method invocation.
◆ call() [8/8]
| void Gio::DBus::Proxy::call | ( | const Glib::ustring & | method_name, |
| const SlotAsyncReady & | slot, | ||
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call() convenience overload.
◆ call_finish() [1/2]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_finish | ( | const Glib::RefPtr< AsyncResult > & | res | ) |
Finishes an operation started with call().
- Parameters
-
res An AsyncResult obtained from the SlotAsyncReady passed to call().
- Returns
- A Variant tuple with return values.
- Exceptions
-
Glib::Error.
◆ call_finish() [2/2]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_finish | ( | const Glib::RefPtr< AsyncResult > & | res, |
| Glib::RefPtr< UnixFDList > & | out_fd_list | ||
| ) |
Finishes an operation started with call() (with a UnixFDList).
- Parameters
-
res A AsyncResult obtained from the SlotAsyncReady passed to call(). out_fd_list Return location for a UnixFDList.
- Returns
- A Variant tuple with return values.
- Exceptions
-
Glib::Error.
◆ call_sync() [1/4]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_sync | ( | const Glib::ustring & | method_name, |
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
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 Gio::DBus::Connection associated with proxy is disconnected then the operation will fail with Gio::Error::CLOSED. If cancellable is canceled, the operation will fail with Gio::Error::CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with Gio::Error::INVALID_ARGUMENT.
If the parameters Variant is floating, it is consumed. This allows convenient 'inline' use of Glib::variant_new(), e.g.:
[C example ellipted]
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 Gio::DBus::Proxy::property_g_interface_info()) and method_name is referenced by it, then the return value is checked against the return type.
- Parameters
-
method_name Name of method to invoke. parameters A Variant tuple with parameters for the signal or nullptrif not passing parameters.flags Flags from the Gio::DBus::CallFlags enumeration. timeout_msec The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. cancellable A Cancellable or nullptr.
- Returns
nullptrif error is set. Otherwise a Variant tuple with return values. Free with Glib::variant_unref().
- Exceptions
-
Glib::Error
◆ call_sync() [2/4]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_sync | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const Glib::RefPtr< Cancellable > & | cancellable, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| Glib::RefPtr< UnixFDList > & | out_fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
Like g_dbus_proxy_call_sync() but also takes and returns UnixFDList objects.
This method is only available on UNIX.
- Parameters
-
method_name Name of method to invoke. parameters A Variant tuple with parameters for the signal or nullptrif not passing parameters.flags Flags from the Gio::DBus::CallFlags enumeration. timeout_msec The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. fd_list A UnixFDList or nullptr.out_fd_list Return location for a UnixFDList or nullptr.cancellable A Cancellable or nullptr.
- Returns
nullptrif error is set. Otherwise a Variant tuple with return values. Free with Glib::variant_unref().
- Exceptions
-
Glib::Error
◆ call_sync() [3/4]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_sync | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters, | ||
| const Glib::RefPtr< UnixFDList > & | fd_list, | ||
| Glib::RefPtr< UnixFDList > & | out_fd_list, | ||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call_sync() convenience overload.
◆ call_sync() [4/4]
| Glib::VariantContainerBase Gio::DBus::Proxy::call_sync | ( | const Glib::ustring & | method_name, |
| const Glib::VariantContainerBase & | parameters = {}, |
||
| int | timeout_msec = -1, |
||
| CallFlags | flags = Gio::DBus::CallFlags::NONE |
||
| ) |
A call_sync() convenience overload.
◆ create() [1/2]
|
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 Gio::DBus::ProxyFlags::DO_NOT_LOAD_PROPERTIES flag is used.
Connect to the Gio::DBus::Proxy::signal_g_properties_changed() signal to get notified about property changes.
If the Gio::DBus::ProxyFlags::DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the Gio::DBus::Proxy::signal_g_signal() signal to handle signals from the remote object.
If both Gio::DBus::ProxyFlags::DO_NOT_LOAD_PROPERTIES and Gio::DBus::ProxyFlags::DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.
If name is a well-known name and the Gio::DBus::ProxyFlags::DO_NOT_AUTO_START and Gio::DBus::ProxyFlags::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, slot 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.
Gio::DBus::Proxy is used in this [example][gdbus-wellknown-proxy].
- Parameters
-
connection A Gio::DBus::Connection. flags Flags used when constructing the proxy. info A Gio::DBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nullptr.name A bus name (well-known or unique) or nullptrif connection is not a message bus connection.object_path An object path. interface_name A D-Bus interface name. cancellable A Cancellable or nullptr.slot Callback function to invoke when the proxy is ready. user_data User data to pass to slot.
◆ create() [2/2]
|
static |
Non-cancellable version of create().
◆ create_finish()
|
static |
Finishes creating a Gio::DBus::Proxy.
- Parameters
-
res A AsyncResult obtained from the SlotAsyncReady function passed to g_dbus_proxy_new().
- Returns
- A Gio::DBus::Proxy or
nullptrif error is set. Free with Glib::object_unref().
- Exceptions
-
Glib::Error.
◆ create_for_bus() [1/2]
|
static |
Like g_dbus_proxy_new() but takes a BusType instead of a Gio::DBus::Connection.
Gio::DBus::Proxy is used in this [example][gdbus-wellknown-proxy].
- Parameters
-
bus_type A BusType. flags Flags used when constructing the proxy. info A Gio::DBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nullptr.name A bus name (well-known or unique). object_path An object path. interface_name A D-Bus interface name. cancellable A Cancellable or nullptr.slot Callback function to invoke when the proxy is ready. user_data User data to pass to slot.
◆ create_for_bus() [2/2]
|
static |
Non-cancellable version of create_for_bus().
◆ create_for_bus_finish()
|
static |
Finishes creating a Gio::DBus::Proxy.
- Parameters
-
res A AsyncResult obtained from the SlotAsyncReady function passed to g_dbus_proxy_new_for_bus().
- Returns
- A Gio::DBus::Proxy or
nullptrif error is set. Free with Glib::object_unref().
- Exceptions
-
Glib::Error.
◆ create_for_bus_sync() [1/2]
|
static |
Like g_dbus_proxy_new_sync() but takes a BusType instead of a Gio::DBus::Connection.
Gio::DBus::Proxy is used in this [example][gdbus-wellknown-proxy].
- Parameters
-
bus_type A BusType. flags Flags used when constructing the proxy. info A Gio::DBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nullptr.name A bus name (well-known or unique). object_path An object path. interface_name A D-Bus interface name. cancellable A Cancellable or nullptr.
- Returns
- A Gio::DBus::Proxy or
nullptrif error is set. Free with Glib::object_unref().
◆ create_for_bus_sync() [2/2]
|
static |
Non-cancellable version of create_for_bus_sync().
◆ create_sync() [1/2]
|
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 Gio::DBus::ProxyFlags::DO_NOT_LOAD_PROPERTIES flag is used.
If the Gio::DBus::ProxyFlags::DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the Gio::DBus::Proxy::signal_g_signal() signal to handle signals from the remote object.
If both Gio::DBus::ProxyFlags::DO_NOT_LOAD_PROPERTIES and Gio::DBus::ProxyFlags::DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.
If name is a well-known name and the Gio::DBus::ProxyFlags::DO_NOT_AUTO_START and Gio::DBus::ProxyFlags::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.
Gio::DBus::Proxy is used in this [example][gdbus-wellknown-proxy].
- Parameters
-
connection A Gio::DBus::Connection. flags Flags used when constructing the proxy. info A Gio::DBus::InterfaceInfo specifying the minimal interface that proxy conforms to or nullptr.name A bus name (well-known or unique) or nullptrif connection is not a message bus connection.object_path An object path. interface_name A D-Bus interface name. cancellable A Cancellable or nullptr.
- Returns
- A Gio::DBus::Proxy or
nullptrif error is set. Free with Glib::object_unref().
◆ create_sync() [2/2]
|
static |
Non-cancellable version of create_sync().
◆ get_cached_property()
| void Gio::DBus::Proxy::get_cached_property | ( | Glib::VariantBase & | property, |
| const Glib::ustring & | property_name | ||
| ) | const |
Looks up the value for a property from the cache.
This call does no blocking IO.
If proxy has an expected interface (see property_g_interface_info()), then property_name (for existence) is checked against it.
- Parameters
-
property An output parameter in which to hold to the variant instance that holds the value for property_name. property_name Property name.
◆ get_cached_property_names()
| std::vector< Glib::ustring > Gio::DBus::Proxy::get_cached_property_names | ( | ) | const |
Gets the names of all cached properties on proxy.
- Returns
- A
nullptr-terminated array of strings ornullptrif proxy has no cached properties.
◆ get_connection() [1/2]
| Glib::RefPtr< Connection > Gio::DBus::Proxy::get_connection | ( | ) |
Gets the connection proxy is for.
- Returns
- A Gio::DBus::Connection owned by proxy. Do not free.
◆ get_connection() [2/2]
| Glib::RefPtr< const Connection > Gio::DBus::Proxy::get_connection | ( | ) | const |
Gets the connection proxy is for.
- Returns
- A Gio::DBus::Connection owned by proxy. Do not free.
◆ get_default_timeout()
| int Gio::DBus::Proxy::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 Gio::DBus::Proxy::property_g_default_timeout() property for more details.
- Returns
- Timeout to use for proxy.
◆ get_flags()
| ProxyFlags Gio::DBus::Proxy::get_flags | ( | ) | const |
Gets the flags that proxy was constructed with.
- Returns
- Flags from the Gio::DBus::ProxyFlags enumeration.
◆ get_interface_info() [1/2]
| Glib::RefPtr< InterfaceInfo > Gio::DBus::Proxy::get_interface_info | ( | ) |
Returns the Gio::DBus::InterfaceInfo, if any, specifying the interface that proxy conforms to.
See the Gio::DBus::Proxy::property_g_interface_info() property for more details.
- Returns
- A Gio::DBus::InterfaceInfo or
nullptr. Do not unref the returned object, it is owned by proxy.
◆ get_interface_info() [2/2]
| Glib::RefPtr< const InterfaceInfo > Gio::DBus::Proxy::get_interface_info | ( | ) | const |
Returns the Gio::DBus::InterfaceInfo, if any, specifying the interface that proxy conforms to.
See the Gio::DBus::Proxy::property_g_interface_info() property for more details.
- Returns
- A Gio::DBus::InterfaceInfo or
nullptr. Do not unref the returned object, it is owned by proxy.
◆ get_interface_name()
| Glib::ustring Gio::DBus::Proxy::get_interface_name | ( | ) | const |
Gets the D-Bus interface name proxy is for.
- Returns
- A string owned by proxy. Do not free.
◆ get_name()
| Glib::ustring Gio::DBus::Proxy::get_name | ( | ) | const |
Gets the name that proxy was constructed for.
When connected to a message bus, this will usually be non-nullptr. However, it may be nullptr for a proxy that communicates using a peer-to-peer pattern.
- Returns
- A string owned by proxy. Do not free.
◆ get_name_owner()
| Glib::ustring Gio::DBus::Proxy::get_name_owner | ( | ) | const |
The unique name that owns the name that proxy is for or nullptr if no-one currently owns that name.
You may connect to the Object::signal_notify() signal to track changes to the Gio::DBus::Proxy::property_g_name_owner() property.
- Returns
- The name owner or
nullptrif no name owner exists.
◆ get_object_path()
| Glib::ustring Gio::DBus::Proxy::get_object_path | ( | ) | const |
◆ get_type()
Get the GType for this class, for use with the underlying GObject type system.
◆ gobj() [1/2]
|
inline |
Provides access to the underlying C GObject.
◆ gobj() [2/2]
|
inline |
Provides access to the underlying C GObject.
◆ gobj_copy()
| GDBusProxy * Gio::DBus::Proxy::gobj_copy | ( | ) |
Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
◆ on_properties_changed()
|
protectedvirtual |
This is a default handler for the signal signal_properties_changed().
◆ on_signal()
|
protectedvirtual |
This is a default handler for the signal signal_signal().
◆ operator=()
◆ property_g_connection()
| Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Connection > > Gio::DBus::Proxy::property_g_connection | ( | ) | const |
The Gio::DBus::Connection the proxy is for.
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_default_timeout() [1/2]
| Glib::PropertyProxy< int > Gio::DBus::Proxy::property_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.
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.
Default value: -1
- Returns
- A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
◆ property_g_default_timeout() [2/2]
| Glib::PropertyProxy_ReadOnly< int > Gio::DBus::Proxy::property_g_default_timeout | ( | ) | const |
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.
Default value: -1
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_flags()
| Glib::PropertyProxy_ReadOnly< ProxyFlags > Gio::DBus::Proxy::property_g_flags | ( | ) | const |
Flags from the Gio::DBus::ProxyFlags enumeration.
Default value: Gio::DBus::ProxyFlags::NONE
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_interface_info() [1/2]
| Glib::PropertyProxy< Glib::RefPtr< InterfaceInfo > > Gio::DBus::Proxy::property_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 Gio::DBus::InterfaceInfo 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 Error is set to Gio::Error::INVALID_ARGUMENT.
- Received signals that have a type signature mismatch are dropped and a warning is logged via Glib::warning().
- Properties received via the initial
GetAll()call or via thePropertiesChangedsignal (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 Glib::warning().
Note that these checks are never done on methods, signals and properties that are not referenced in the given Gio::DBus::InterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.
- Returns
- A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
◆ property_g_interface_info() [2/2]
| Glib::PropertyProxy_ReadOnly< Glib::RefPtr< InterfaceInfo > > Gio::DBus::Proxy::property_g_interface_info | ( | ) | const |
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 Gio::DBus::InterfaceInfo 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 Error is set to Gio::Error::INVALID_ARGUMENT.
- Received signals that have a type signature mismatch are dropped and a warning is logged via Glib::warning().
- Properties received via the initial
GetAll()call or via thePropertiesChangedsignal (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 Glib::warning().
Note that these checks are never done on methods, signals and properties that are not referenced in the given Gio::DBus::InterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_interface_name()
| Glib::PropertyProxy_ReadOnly< Glib::ustring > Gio::DBus::Proxy::property_g_interface_name | ( | ) | const |
The D-Bus interface name the proxy is for.
Default value: ""
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_name()
| Glib::PropertyProxy_ReadOnly< Glib::ustring > Gio::DBus::Proxy::property_g_name | ( | ) | const |
The well-known or unique name that the proxy is for.
Default value: ""
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_name_owner()
| Glib::PropertyProxy_ReadOnly< Glib::ustring > Gio::DBus::Proxy::property_g_name_owner | ( | ) | const |
The unique name that owns Gio::DBus::Proxy::property_g_name() or nullptr if no-one currently owns that name.
You may connect to Object::signal_notify() signal to track changes to this property.
Default value: ""
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ property_g_object_path()
| Glib::PropertyProxy_ReadOnly< Glib::ustring > Gio::DBus::Proxy::property_g_object_path | ( | ) | const |
The object path the proxy is for.
Default value: ""
- Returns
- A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
◆ set_cached_property()
| void Gio::DBus::Proxy::set_cached_property | ( | const Glib::ustring & | property_name, |
| const Glib::VariantBase & | value | ||
| ) |
If value is not nullptr, sets the cached value for the property with name property_name to the value in value.
If value is nullptr, then the cached value is removed from the property cache.
If proxy has an expected interface (see Gio::DBus::Proxy::property_g_interface_info()) and property_name is referenced by it, then value is checked against the type of the property.
If the value Variant is floating, it is consumed. This allows convenient 'inline' use of Glib::variant_new(), e.g.
[C example ellipted]
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).
- Parameters
-
property_name Property name. value Value for the property or nullptrto remove it from the cache.
◆ 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.
See the Gio::DBus::Proxy::property_g_default_timeout() property for more details.
- Parameters
-
timeout_msec Timeout in milliseconds.
◆ set_interface_info()
| void Gio::DBus::Proxy::set_interface_info | ( | const Glib::RefPtr< InterfaceInfo > & | info | ) |
Ensure that interactions with proxy conform to the given interface.
See the Gio::DBus::Proxy::property_g_interface_info() property for more details.
- Parameters
-
info Minimum interface this proxy conforms to or nullptrto unset.
◆ signal_properties_changed()
| Glib::SignalProxy< void(const MapChangedProperties &, const std::vector< Glib::ustring > &)> Gio::DBus::Proxy::signal_properties_changed | ( | ) |
- Slot Prototype:
void on_my_properties_changed(const MapChangedProperties& changed_properties, const std::vector<Glib::ustring>& invalidated_properties)
Flags: Run Last, Must Collect
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 nullptr (either may be empty though).
If the proxy has the flag Gio::DBus::ProxyFlags::GET_INVALIDATED_PROPERTIES set, then invalidated_properties will always be empty.
This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.
- Parameters
-
changed_properties A Variant containing the properties that changed (type: a{sv}).invalidated_properties A nullptrterminated array of properties that was invalidated.
◆ signal_signal() [1/2]
| Glib::SignalProxy< void(const Glib::ustring &, const Glib::ustring &, const Glib::VariantContainerBase &)> Gio::DBus::Proxy::signal_signal | ( | ) |
- Slot Prototype:
void on_my_signal(const Glib::ustring& sender_name, const Glib::ustring& signal_name, const Glib::VariantContainerBase& parameters)
Flags: Run Last, Must Collect
Emitted when a signal from the remote object and interface that proxy is for, has been received.
Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signalx in order to receive callbacks only when signal x is received from the remote object.
- Parameters
-
sender_name The sender of the signal or nullptrif the connection is not a bus connection.signal_name The name of the signal. parameters A Variant tuple with parameters for the signal.
◆ signal_signal() [2/2]
| Glib::SignalProxyDetailed< void(const Glib::ustring &, const Glib::ustring &, const Glib::VariantContainerBase &)> Gio::DBus::Proxy::signal_signal | ( | const Glib::ustring & | signal_name | ) |
- Slot Prototype:
void on_my_signal(const Glib::ustring& sender_name, const Glib::ustring& signal_name, const Glib::VariantContainerBase& parameters)
Flags: Run Last, Must Collect
Emitted when a signal from the remote object and interface that proxy is for, has been received.
Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signalx in order to receive callbacks only when signal x is received from the remote object.
- Parameters
-
sender_name The sender of the signal or nullptrif the connection is not a bus connection.signal_name The name of the signal. parameters A Variant tuple with parameters for the signal.
Friends And Related Symbol Documentation
◆ wrap()
|
related |
A Glib::wrap() method for this object.
- Parameters
-
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.
- Returns
- A C++ instance that wraps this C instance.
