// Generated by gmmproc 2.54.1 -- DO NOT MODIFY!
#ifndef _GIOMM_DBUSPROXY_H
#define _GIOMM_DBUSPROXY_H
#include <glibmm/ustring.h>
#include <sigc++/sigc++.h>
/* Copyright (C) 2010 The giomm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*/
#include <glibmm/object.h>
#include <giomm/asyncresult.h>
#include <giomm/dbusintrospection.h>
#include <giomm/initable.h>
#include <giomm/asyncinitable.h>
#include <giomm/dbusconnection.h>
#ifndef DOXYGEN_SHOULD_SKIP_THIS
using GDBusProxy = struct _GDBusProxy;
using GDBusProxyClass = struct _GDBusProxyClass;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
namespace Gio
{
namespace DBus
{ class Proxy_Class; } // namespace DBus
} // namespace Gio
#endif //DOXYGEN_SHOULD_SKIP_THIS
namespace Gio
{
namespace DBus
{
//The GMMPROC_EXTRA_NAMESPACE() macro is a hint to generate_wrap_init.pl to put it in the DBus sub-namespace
/** @addtogroup giommEnums giomm Enums and Flags */
/**
* @var ProxyFlags PROXY_FLAGS_NONE
* No flags set.
*
* @var ProxyFlags PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES
* Don't load properties.
*
* @var ProxyFlags PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS
* Don't connect to signals on the remote object.
*
* @var ProxyFlags PROXY_FLAGS_DO_NOT_AUTO_START
* If the proxy is for a well-known name,
* do not ask the bus to launch an owner during proxy initialization or a method call.
* This flag is only meaningful in proxies for well-known names.
*
* @var ProxyFlags PROXY_FLAGS_GET_INVALIDATED_PROPERTIES
* If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the DBusProxy::signal_g_properties_changed() signal. When the value is received the DBusProxy::signal_g_properties_changed() signal is emitted for the property along with the retrieved value. @newin{2,32}
*
* @var ProxyFlags PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
* If the proxy is for a well-known name,
* do not ask the bus to launch an owner during proxy initialization, but allow it to be
* autostarted by a method call. This flag is only meaningful in proxies for well-known names,
* and only if DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified.
*
* @enum ProxyFlags
*
* Flags used when constructing an instance of a DBusProxy derived class.
*
* @newin{2,26}
*
* @ingroup giommEnums
* @par Bitwise operators:
* <tt>%ProxyFlags operator|(ProxyFlags, ProxyFlags)</tt><br>
* <tt>%ProxyFlags operator&(ProxyFlags, ProxyFlags)</tt><br>
* <tt>%ProxyFlags operator^(ProxyFlags, ProxyFlags)</tt><br>
* <tt>%ProxyFlags operator~(ProxyFlags)</tt><br>
* <tt>%ProxyFlags& operator|=(ProxyFlags&, ProxyFlags)</tt><br>
* <tt>%ProxyFlags& operator&=(ProxyFlags&, ProxyFlags)</tt><br>
* <tt>%ProxyFlags& operator^=(ProxyFlags&, ProxyFlags)</tt><br>
*/
enum ProxyFlags
{
PROXY_FLAGS_NONE = 0x0,
PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES = (1<<0),
PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS = (1<<1),
PROXY_FLAGS_DO_NOT_AUTO_START = (1<<2),
PROXY_FLAGS_GET_INVALIDATED_PROPERTIES = (1<<3),
PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION = (1<<4)
};
/** @ingroup giommEnums */
inline ProxyFlags operator|(ProxyFlags lhs, ProxyFlags rhs)
{ return static_cast<ProxyFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
/** @ingroup giommEnums */
inline ProxyFlags operator&(ProxyFlags lhs, ProxyFlags rhs)
{ return static_cast<ProxyFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
/** @ingroup giommEnums */
inline ProxyFlags operator^(ProxyFlags lhs, ProxyFlags rhs)
{ return static_cast<ProxyFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
/** @ingroup giommEnums */
inline ProxyFlags operator~(ProxyFlags flags)
{ return static_cast<ProxyFlags>(~static_cast<unsigned>(flags)); }
/** @ingroup giommEnums */
inline ProxyFlags& operator|=(ProxyFlags& lhs, ProxyFlags rhs)
{ return (lhs = static_cast<ProxyFlags>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
/** @ingroup giommEnums */
inline ProxyFlags& operator&=(ProxyFlags& lhs, ProxyFlags rhs)
{ return (lhs = static_cast<ProxyFlags>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
/** @ingroup giommEnums */
inline ProxyFlags& operator^=(ProxyFlags& lhs, ProxyFlags rhs)
{ return (lhs = static_cast<ProxyFlags>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
/** 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_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 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.
*
* @newin{2,28}
* @ingroup DBus
*/
class Proxy
: public Glib::Object,
public Initable,
public AsyncInitable
{
#ifndef DOXYGEN_SHOULD_SKIP_THIS
public:
using CppObjectType = Proxy;
using CppClassType = Proxy_Class;
using BaseObjectType = GDBusProxy;
using BaseClassType = GDBusProxyClass;
// noncopyable
Proxy(const Proxy&) = delete;
Proxy& operator=(const Proxy&) = delete;
private: friend class Proxy_Class;
static CppClassType proxy_class_;
protected:
explicit Proxy(const Glib::ConstructParams& construct_params);
explicit Proxy(GDBusProxy* castitem);
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
public:
Proxy(Proxy&& src) noexcept;
Proxy& operator=(Proxy&& src) noexcept;
~Proxy() noexcept override;
/** Get the GType for this class, for use with the underlying GObject type system.
*/
static GType get_type() G_GNUC_CONST;
#ifndef DOXYGEN_SHOULD_SKIP_THIS
static GType get_base_type() G_GNUC_CONST;
#endif
///Provides access to the underlying C GObject.
GDBusProxy* gobj() { return reinterpret_cast<GDBusProxy*>(gobject_); }
///Provides access to the underlying C GObject.
const GDBusProxy* gobj() const { return reinterpret_cast<GDBusProxy*>(gobject_); }
///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
GDBusProxy* gobj_copy();
private:
protected:
Proxy(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
Proxy(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
public:
/** Creates a proxy for accessing @a interface_name on the remote object
* at @a object_path owned by @a name at @a connection and asynchronously
* loads D-Bus properties unless the
* DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
* the DBusProxy::signal_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::signal_g_signal() signal
* to handle signals from the remote object.
*
* If @a name is a well-known name and the
* DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and 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, @a 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.
*
* DBusProxy is used in this [example][gdbus-wellknown-proxy].
*
* @newin{2,26}
*
* @param connection A DBusConnection.
* @param flags Flags used when constructing the proxy.
* @param info A DBusInterfaceInfo specifying the minimal interface that @a proxy conforms to or <tt>nullptr</tt>.
* @param name A bus name (well-known or unique) or <tt>nullptr</tt> if @a connection is not a message bus connection.
* @param object_path An object path.
* @param interface_name A D-Bus interface name.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @param slot Callback function to invoke when the proxy is ready.
* @param user_data User data to pass to @a slot.
*/
static void create(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/// Non-cancellable version of create().
static void create(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/** Finishes creating a DBusProxy.
*
* @newin{2,26}
*
* @param res A AsyncResult obtained from the SlotAsyncReady function passed to g_dbus_proxy_new().
* @return A DBusProxy or <tt>nullptr</tt> if @a error is set.
* Free with Glib::object_unref().
*/
/** @throw Glib::Error.
*/
static Glib::RefPtr<Gio::DBus::Proxy> create_finish(const Glib::RefPtr<AsyncResult>& res);
/** Creates a proxy for accessing @a interface_name on the remote object
* at @a object_path owned by @a name at @a 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::signal_g_signal() signal
* to handle signals from the remote object.
*
* If @a name is a well-known name and the
* DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and 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.
*
* DBusProxy is used in this [example][gdbus-wellknown-proxy].
*
* @newin{2,26}
*
* @param connection A DBusConnection.
* @param flags Flags used when constructing the proxy.
* @param info A DBusInterfaceInfo specifying the minimal interface that @a proxy conforms to or <tt>nullptr</tt>.
* @param name A bus name (well-known or unique) or <tt>nullptr</tt> if @a connection is not a message bus connection.
* @param object_path An object path.
* @param interface_name A D-Bus interface name.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @return A DBusProxy or <tt>nullptr</tt> if error is set.
* Free with Glib::object_unref().
*/
static Glib::RefPtr<Proxy>
create_sync(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/// Non-cancellable version of create_sync().
static Glib::RefPtr<Proxy>
create_sync(const Glib::RefPtr<Connection>& connection,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/** Like g_dbus_proxy_new() but takes a BusType instead of a DBusConnection.
*
* DBusProxy is used in this [example][gdbus-wellknown-proxy].
*
* @newin{2,26}
*
* @param bus_type A BusType.
* @param flags Flags used when constructing the proxy.
* @param info A DBusInterfaceInfo specifying the minimal interface that @a proxy conforms to or <tt>nullptr</tt>.
* @param name A bus name (well-known or unique).
* @param object_path An object path.
* @param interface_name A D-Bus interface name.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @param slot Callback function to invoke when the proxy is ready.
* @param user_data User data to pass to @a slot.
*/
static void create_for_bus(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/// Non-cancellable version of create_for_bus().
static void create_for_bus(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const SlotAsyncReady& slot,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/** Finishes creating a DBusProxy.
*
* @newin{2,26}
*
* @param res A AsyncResult obtained from the SlotAsyncReady function passed to g_dbus_proxy_new_for_bus().
* @return A DBusProxy or <tt>nullptr</tt> if @a error is set.
* Free with Glib::object_unref().
*/
/** @throw Glib::Error.
*/
static Glib::RefPtr<Gio::DBus::Proxy> create_for_bus_finish(const Glib::RefPtr<AsyncResult>& res);
/** Like g_dbus_proxy_new_sync() but takes a BusType instead of a DBusConnection.
*
* DBusProxy is used in this [example][gdbus-wellknown-proxy].
*
* @newin{2,26}
*
* @param bus_type A BusType.
* @param flags Flags used when constructing the proxy.
* @param info A DBusInterfaceInfo specifying the minimal interface
* that @a proxy conforms to or <tt>nullptr</tt>.
* @param name A bus name (well-known or unique).
* @param object_path An object path.
* @param interface_name A D-Bus interface name.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @return A DBusProxy or <tt>nullptr</tt> if error is set.
* Free with Glib::object_unref().
*/
static Glib::RefPtr<Proxy>
create_for_bus_sync(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<Cancellable>& cancellable,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/// Non-cancellable version of create_for_bus_sync().
static Glib::RefPtr<Proxy>
create_for_bus_sync(BusType bus_type,
const Glib::ustring& name,
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::RefPtr<InterfaceInfo>& info = Glib::RefPtr<InterfaceInfo>(),
ProxyFlags flags = PROXY_FLAGS_NONE);
/** Gets the flags that @a proxy was constructed with.
*
* @newin{2,26}
*
* @return Flags from the DBusProxyFlags enumeration.
*/
ProxyFlags get_flags() const;
/** Gets the connection @a proxy is for.
*
* @newin{2,26}
*
* @return A DBusConnection owned by @a proxy. Do not free.
*/
Glib::RefPtr<Connection> get_connection();
/** Gets the connection @a proxy is for.
*
* @newin{2,26}
*
* @return A DBusConnection owned by @a proxy. Do not free.
*/
Glib::RefPtr<const Connection> get_connection() const;
/** Gets the name that @a proxy was constructed for.
*
* @newin{2,26}
*
* @return A string owned by @a proxy. Do not free.
*/
Glib::ustring get_name() const;
/** The unique name that owns the name that @a proxy is for or <tt>nullptr</tt> if
* no-one currently owns that name. You may connect to the
* Object::signal_notify() signal to track changes to the
* DBusProxy::property_g_name_owner() property.
*
* @newin{2,26}
*
* @return The name owner or <tt>nullptr</tt> if no name
* owner exists.
*/
Glib::ustring get_name_owner() const;
/** Gets the object path @a proxy is for.
*
* @newin{2,26}
*
* @return A string owned by @a proxy. Do not free.
*/
Glib::ustring get_object_path() const;
/** Gets the D-Bus interface name @a proxy is for.
*
* @newin{2,26}
*
* @return A string owned by @a proxy. Do not free.
*/
Glib::ustring get_interface_name() const;
/** Gets the timeout to use if -1 (specifying default timeout) is
* passed as @a timeout_msec in the g_dbus_proxy_call() and
* g_dbus_proxy_call_sync() functions.
*
* See the DBusProxy::property_g_default_timeout() property for more details.
*
* @newin{2,26}
*
* @return Timeout to use for @a proxy.
*/
int get_default_timeout() const;
/** Sets the timeout to use if -1 (specifying default timeout) is
* passed as @a timeout_msec in the g_dbus_proxy_call() and
* g_dbus_proxy_call_sync() functions.
*
* See the DBusProxy::property_g_default_timeout() property for more details.
*
* @newin{2,26}
*
* @param timeout_msec Timeout in milliseconds.
*/
void set_default_timeout(int timeout_msec = -1);
/** 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 @a property_name (for existence) is checked against it.
*
* @param property An output parameter in which to hold to the variant
* instance that holds the value for @a property_name.
* @param property_name Property name.
*
* @newin{2,28}
*/
void get_cached_property(Glib::VariantBase& property,
const Glib::ustring& property_name) const;
/** If @a value is not <tt>nullptr</tt>, sets the cached value for the property with
* name @a property_name to the value in @a value.
*
* If @a value is <tt>nullptr</tt>, then the cached value is removed from the
* property cache.
*
* If @a proxy has an expected interface (see
* DBusProxy::property_g_interface_info()) and @a property_name is referenced by
* it, then @a value is checked against the type of the property.
*
* If the @a 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 @a 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)`.
*
* @newin{2,26}
*
* @param property_name Property name.
* @param value Value for the property or <tt>nullptr</tt> to remove it from the cache.
*/
void set_cached_property(const Glib::ustring& property_name, const Glib::VariantBase& value);
/** Gets the names of all cached properties on @a proxy.
*
* @newin{2,26}
*
* @return A
* <tt>nullptr</tt>-terminated array of strings or <tt>nullptr</tt> if
* @a proxy has no cached properties.
*/
Glib::StringArrayHandle get_cached_property_names() const;
/** Ensure that interactions with @a proxy conform to the given
* interface. See the DBusProxy::property_g_interface_info() property for more
* details.
*
* @newin{2,26}
*
* @param info Minimum interface this proxy conforms to
* or <tt>nullptr</tt> to unset.
*/
void set_interface_info(const Glib::RefPtr<InterfaceInfo>& info);
/** Returns the DBusInterfaceInfo, if any, specifying the interface
* that @a proxy conforms to. See the DBusProxy::property_g_interface_info()
* property for more details.
*
* @newin{2,26}
*
* @return A DBusInterfaceInfo or <tt>nullptr</tt>.
* Do not unref the returned object, it is owned by @a proxy.
*/
Glib::RefPtr<InterfaceInfo> get_interface_info();
/** Returns the DBusInterfaceInfo, if any, specifying the interface
* that @a proxy conforms to. See the DBusProxy::property_g_interface_info()
* property for more details.
*
* @newin{2,26}
*
* @return A DBusInterfaceInfo or <tt>nullptr</tt>.
* Do not unref the returned object, it is owned by @a proxy.
*/
Glib::RefPtr<const InterfaceInfo> get_interface_info() const;
/** Asynchronously invokes the @a method_name method on @a proxy.
*
* If @a method_name contains any dots, then @a name is split into interface and
* method name parts. This allows using @a proxy for invoking methods on
* other interfaces.
*
* If the DBusConnection associated with @a proxy is closed then
* the operation will fail with IO_ERROR_CLOSED. If
* @a cancellable is canceled, the operation will fail with
* IO_ERROR_CANCELLED. If @a parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* IO_ERROR_INVALID_ARGUMENT.
*
* If the @a parameters Variant is floating, it is consumed. This allows
* convenient 'inline' use of Glib::variant_new(), e.g.:
*
* [C example ellipted]
*
* If @a proxy has an expected interface (see
* DBusProxy::property_g_interface_info()) and @a 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,
* @a 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 @a slot is <tt>nullptr</tt> then the D-Bus method call message will be sent with
* the DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
*
* @newin{2,26}
*
* @param method_name Name of method to invoke.
* @param parameters A Variant tuple with parameters for the signal or <tt>nullptr</tt> if not passing parameters.
* @param flags Flags from the DBusCallFlags enumeration.
* @param timeout_msec The timeout in milliseconds (with G_MAXINT meaning
* "infinite") or -1 to use the proxy default timeout.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @param 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.
*/
void call(const Glib::ustring& method_name, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
/// A call() convenience overload.
void call(const Glib::ustring& method_name, const SlotAsyncReady& slot, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
/// A call() convenience overload.
void call(const Glib::ustring& method_name, const Glib::RefPtr<Cancellable>& cancellable, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
/// A call() convenience overload.
void call(const Glib::ustring& method_name, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
/** Finishes an operation started with call().
*
* @param res An AsyncResult obtained from the SlotAsyncReady passed to
* call().
* @result A Variant tuple with return values.
*
* @throw Glib::Error.
*/
Glib::VariantContainerBase call_finish(const Glib::RefPtr<AsyncResult>& res);
/** Synchronously invokes the @a method_name method on @a proxy.
*
* If @a method_name contains any dots, then @a name is split into interface and
* method name parts. This allows using @a proxy for invoking methods on
* other interfaces.
*
* If the DBusConnection associated with @a proxy is disconnected then
* the operation will fail with IO_ERROR_CLOSED. If
* @a cancellable is canceled, the operation will fail with
* IO_ERROR_CANCELLED. If @a parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* IO_ERROR_INVALID_ARGUMENT.
*
* If the @a 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 @a proxy has an expected interface (see
* DBusProxy::property_g_interface_info()) and @a method_name is referenced by it,
* then the return value is checked against the return type.
*
* @newin{2,26}
*
* @param method_name Name of method to invoke.
* @param parameters A Variant tuple with parameters for the signal
* or <tt>nullptr</tt> if not passing parameters.
* @param flags Flags from the DBusCallFlags enumeration.
* @param timeout_msec The timeout in milliseconds (with G_MAXINT meaning
* "infinite") or -1 to use the proxy default timeout.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @return <tt>nullptr</tt> if @a error is set. Otherwise a Variant tuple with
* return values. Free with Glib::variant_unref().
*
* @throws Glib::Error
*/
Glib::VariantContainerBase call_sync(const Glib::ustring& method_name, const Glib::RefPtr<Cancellable>& cancellable, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
/// A call_sync() convenience overload.
Glib::VariantContainerBase call_sync(const Glib::ustring& method_name, const Glib::VariantContainerBase& parameters = Glib::VariantContainerBase(), int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
#ifdef G_OS_UNIX
/** Like g_dbus_proxy_call() but also takes a UnixFDList object.
*
* This method is only available on UNIX.
*
* @newin{2,30}
*
* @param method_name Name of method to invoke.
* @param parameters A Variant tuple with parameters for the signal or <tt>nullptr</tt> if not passing parameters.
* @param flags Flags from the DBusCallFlags enumeration.
* @param timeout_msec The timeout in milliseconds (with G_MAXINT meaning
* "infinite") or -1 to use the proxy default timeout.
* @param fd_list A UnixFDList or <tt>nullptr</tt>.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @param 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.
*/
void 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::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/// A call() convenience overload.
void 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::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/// A call() convenience overload.
void 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::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/// A call() convenience overload.
void call(const Glib::ustring& method_name, const Glib::VariantContainerBase& parameters, const Glib::RefPtr<UnixFDList>& fd_list, int timeout_msec = -1, CallFlags flags = Gio::DBus::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/** Finishes an operation started with call() (with a UnixFDList).
* @param res A AsyncResult obtained from the SlotAsyncReady passed to
* call().
* @param out_fd_list Return location for a UnixFDList.
* @result A Variant tuple with return values.
* @throw Glib::Error.
* @newin{2,34}
*/
Glib::VariantContainerBase call_finish(const Glib::RefPtr<AsyncResult>& res, Glib::RefPtr<UnixFDList>& out_fd_list);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/** Like g_dbus_proxy_call_sync() but also takes and returns UnixFDList objects.
*
* This method is only available on UNIX.
*
* @newin{2,30}
*
* @param method_name Name of method to invoke.
* @param parameters A Variant tuple with parameters for the signal
* or <tt>nullptr</tt> if not passing parameters.
* @param flags Flags from the DBusCallFlags enumeration.
* @param timeout_msec The timeout in milliseconds (with G_MAXINT meaning
* "infinite") or -1 to use the proxy default timeout.
* @param fd_list A UnixFDList or <tt>nullptr</tt>.
* @param out_fd_list Return location for a UnixFDList or <tt>nullptr</tt>.
* @param cancellable A Cancellable or <tt>nullptr</tt>.
* @return <tt>nullptr</tt> if @a error is set. Otherwise a Variant tuple with
* return values. Free with Glib::variant_unref().
*
* @throws Glib::Error
*/
Glib::VariantContainerBase 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::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
#ifdef G_OS_UNIX
/// A call_sync() convenience overload.
Glib::VariantContainerBase 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::CALL_FLAGS_NONE);
#endif // G_OS_UNIX
//_WRAP_PROPERTY("g-bus-type", BusType) // write-only construct-only
/** The DBusConnection the proxy is for.
*
* @newin{2,26}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Connection> > property_g_connection() const;
/** The timeout to use if -1 (specifying default timeout) is passed
* as @a 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.
*
* @newin{2,26}
*
* Default value: -1
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< int > property_g_default_timeout() ;
/** The timeout to use if -1 (specifying default timeout) is passed
* as @a 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.
*
* @newin{2,26}
*
* Default value: -1
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< int > property_g_default_timeout() const;
/** Flags from the DBusProxyFlags enumeration.
*
* @newin{2,26}
*
* Default value: DBUS_PROXY_FLAGS_NONE
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< ProxyFlags > property_g_flags() 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 DBusInterfaceInfo 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 IO_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 the
* `::PropertiesChanged` signal (on the
* [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-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
* DBusInterfaceInfo, since extending a D-Bus interface on the
* service-side is not considered an ABI break.
*
* @newin{2,26}
*
* @return A PropertyProxy that allows you to get or set the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy< Glib::RefPtr<InterfaceInfo> > 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 DBusInterfaceInfo 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 IO_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 the
* `::PropertiesChanged` signal (on the
* [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-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
* DBusInterfaceInfo, since extending a D-Bus interface on the
* service-side is not considered an ABI break.
*
* @newin{2,26}
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<InterfaceInfo> > property_g_interface_info() const;
/** The D-Bus interface name the proxy is for.
*
* @newin{2,26}
*
* Default value: ""
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_g_interface_name() const;
/** The well-known or unique name that the proxy is for.
*
* @newin{2,26}
*
* Default value: ""
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_g_name() const;
/** The unique name that owns DBusProxy::property_g_name() or <tt>nullptr</tt> if no-one
* currently owns that name. You may connect to Object::signal_notify() signal to
* track changes to this property.
*
* @newin{2,26}
*
* Default value: ""
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_g_name_owner() const;
/** The object path the proxy is for.
*
* @newin{2,26}
*
* Default value: ""
*
* @return A PropertyProxy_ReadOnly that allows you to get the value of the property,
* or receive notification when the value of the property changes.
*/
Glib::PropertyProxy_ReadOnly< Glib::ustring > property_g_object_path() const;
using MapChangedProperties = std::map<Glib::ustring, Glib::VariantBase>;
// TODO: Should the signal names match the C API names (ie. the C API names
// are g_signal_name while these are just signal_name).
// The DBus API ensures that the variant changed_properties is of type "DICT<STRING,VARIANT>"
/**
* @par Slot Prototype:
* <tt>void on_my_%properties_changed(const MapChangedProperties& changed_properties, const std::vector<Glib::ustring>& invalidated_properties)</tt>
*
* Flags: Run Last, Must Collect
*
* Emitted when one or more D-Bus properties on @a proxy changes. The
* local cache has already been updated when this signal fires. Note
* that both @a changed_properties and @a invalidated_properties are
* guaranteed to never be <tt>nullptr</tt> (either may be empty though).
*
* If the proxy has the flag
* DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
* @a invalidated_properties will always be empty.
*
* This signal corresponds to the
* `PropertiesChanged` D-Bus signal on the
* `org.freedesktop.DBus.Properties` interface.
*
* @newin{2,26}
*
* @param changed_properties A Variant containing the properties that changed.
* @param invalidated_properties A <tt>nullptr</tt> terminated array of properties that was invalidated.
*/
Glib::SignalProxy< void,const MapChangedProperties&,const std::vector<Glib::ustring>& > signal_properties_changed();
/**
* @par Slot Prototype:
* <tt>void on_my_%signal(const Glib::ustring& sender_name, const Glib::ustring& signal_name, const Glib::VariantContainerBase& parameters)</tt>
*
* Flags: Run Last, Must Collect
*
* Emitted when a signal from the remote object and interface that @a proxy is for, has been received.
*
* @newin{2,26}
*
* @param sender_name The sender of the signal or <tt>nullptr</tt> if the connection is not a bus connection.
* @param signal_name The name of the signal.
* @param parameters A Variant tuple with parameters for the signal.
*/
Glib::SignalProxy< void,const Glib::ustring&,const Glib::ustring&,const Glib::VariantContainerBase& > signal_signal();
public:
public:
//C++ methods used to invoke GTK+ virtual functions:
protected:
//GTK+ Virtual Functions (override these to change behaviour):
//Default Signal Handlers::
/// This is a default handler for the signal signal_properties_changed().
virtual void on_properties_changed(const MapChangedProperties& changed_properties, const std::vector<Glib::ustring>& invalidated_properties);
/// This is a default handler for the signal signal_signal().
virtual void on_signal(const Glib::ustring& sender_name, const Glib::ustring& signal_name, const Glib::VariantContainerBase& parameters);
};
} //namespace
} // namespace Gio
namespace Glib
{
/** A Glib::wrap() method for this object.
*
* @param object The C instance.
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
* @result A C++ instance that wraps this C instance.
*
* @relates Gio::DBus::Proxy
*/
Glib::RefPtr<Gio::DBus::Proxy> wrap(GDBusProxy* object, bool take_copy = false);
}
#endif /* _GIOMM_DBUSPROXY_H */