/* 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 .
*/
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
_DEFS(giomm,gio)
_PINCLUDE(glibmm/private/object_p.h)
namespace Gio
{
class GIOMM_API ActionGroup;
class GIOMM_API MenuModel;
class GIOMM_API UnixFDList;
namespace DBus
{
_WRAP_ENUM(BusType, GBusType, decl_prefix GIOMM_API)
_WRAP_ENUM(CallFlags, GDBusCallFlags, NO_GTYPE, decl_prefix GIOMM_API)
_WRAP_ENUM(ConnectionFlags, GDBusConnectionFlags, gtype_func g_dbus_connection_flags_get_type, decl_prefix GIOMM_API)
_WRAP_ENUM(SendMessageFlags, GDBusSendMessageFlags, NO_GTYPE, decl_prefix GIOMM_API)
_WRAP_ENUM(SignalFlags, GDBusSignalFlags, NO_GTYPE, decl_prefix GIOMM_API)
_WRAP_ENUM(SubtreeFlags, GDBusSubtreeFlags, NO_GTYPE, decl_prefix GIOMM_API)
_GMMPROC_EXTRA_NAMESPACE(DBus)
/** @defgroup DBus D-Bus API
*
* API to use D-Bus services as a client or to implement a D-Bus service.
* To write client code, see Gio::DBus::Proxy.
* To export objects on the bus for other clients, see Gio::DBus::own_name(), for instance.
*/
//TODO: Add example from C API in class docs.
/** A D-Bus Connection.
* The Connection type is used for D-Bus connections to remote peers such
* as a message buses. It is a low-level API that offers a lot of flexibility.
* For instance, it lets you establish a connection over any transport that
* can by represented as an IOStream.
*
* This class is rarely used directly in D-Bus clients. If you are writing a
* D-Bus client, it is often easier to use the Gio::DBus::own_name(),
* Gio::DBus::watch_name() or Gio::DBus::Proxy::create_for_bus() APIs.
*
* @newin{2,28}
* @ingroup DBus
*/
class GIOMM_API Connection
: public Glib::Object, public Initable, public AsyncInitable
{
protected:
_CLASS_GOBJECT(Connection, GDBusConnection, G_DBUS_CONNECTION, Glib::Object, GObject, , , GIOMM_API)
_IMPLEMENTS_INTERFACE(Initable)
_IMPLEMENTS_INTERFACE(AsyncInitable)
_CUSTOM_WRAP_FUNCTION
protected:
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const SlotAsyncReady& slot,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
ConnectionFlags flags);
Connection(const Glib::RefPtr& stream,
const std::string& guid,
ConnectionFlags flags);
Connection(const std::string& address,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const std::string& address,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const std::string& address,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
ConnectionFlags flags);
Connection(const std::string& address,
const SlotAsyncReady& slot,
ConnectionFlags flags);
Connection(const std::string& address,
const Glib::RefPtr& observer,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const std::string& address,
const Glib::RefPtr& cancellable,
ConnectionFlags flags);
Connection(const std::string& address,
const Glib::RefPtr& observer,
ConnectionFlags flags);
Connection(const std::string& address,
ConnectionFlags flags);
public:
/** Signature for slot used in signal_subscribe().
* For example,
* @code
* void on_signal(const Glib::RefPtr& connection, const
* Glib::ustring& sender_name, const Glib::ustring& object_path, const
* Glib::ustring& object_path, const Glib::ustring& interface_name, const
* Glib::ustring& signal_name, const Glib::VariantContainerBase& parameters);.
* @endcode
*/
using SlotSignal = sigc::slot&,
const Glib::ustring&, const Glib::ustring&, const Glib::ustring&,
const Glib::ustring&, const Glib::VariantContainerBase&)>;
/** Signature for slot used in add_filter().
* For example,
* @code
* Glib::RefPtr on_message_filter(const
* Glib::RefPtr connection, const Glib::RefPtr&
* message, bool incoming);.
* @endcode
*
* A filter function is passed a Message and expected to return a
* Message too. Passive filter functions that don't modify the message
* can simply return the message object. Filter functions that wants to
* drop a message can simply return 0. And filter function may
* modify a message by copying it and return the copy.
*/
using SlotMessageFilter = sigc::slot(
const Glib::RefPtr&,
const Glib::RefPtr&, bool)>;
/** Asynchronously connects to the message bus specified by @a bus_type.
*
* When the operation is finished, @a slot will be invoked. You can then
* call get_finish() to get the result of the operation.
*
* This is a asynchronous failable function. See get_sync() for the
* synchronous version.
*
* @param bus_type A BusType.
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
*
* @newin{2,28}
*/
static void get(BusType bus_type, const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable);
_IGNORE(g_bus_get)
/** Non-cancellable version of get().
*/
static void get(BusType bus_type, const SlotAsyncReady& slot);
_WRAP_METHOD(static Glib::RefPtr get_finish(const Glib::RefPtr& res), g_bus_get_finish, errthrow)
_WRAP_METHOD(static Glib::RefPtr get_sync(BusType bus_type, const Glib::RefPtr& cancellable{?}), g_bus_get_sync, errthrow)
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new)
static void create(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new)
static void create(const Glib::RefPtr& stream,
const std::string& guid,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create().
static void create(const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create().
static void create(const Glib::RefPtr& stream,
const std::string& guid,
const SlotAsyncReady& slot,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD(static Glib::RefPtr create_finish(const Glib::RefPtr& res), g_dbus_connection_new_finish, errthrow)
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address)
static void create_for_address(const std::string& address,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address)
static void create_for_address(const std::string& address,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_for_address().
static void create_for_address(const std::string& address,
const Glib::RefPtr& observer,
const SlotAsyncReady& slot,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_for_address().
static void create_for_address(const std::string& address,
const SlotAsyncReady& slot,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD(static Glib::RefPtr create_for_address_finish(const Glib::RefPtr& res), g_dbus_connection_new_for_address_finish, errthrow)
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_sync, errthrow)
static Glib::RefPtr create_sync(
const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_sync, errthrow)
static Glib::RefPtr create_sync(
const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_sync().
static Glib::RefPtr create_sync(
const Glib::RefPtr& stream,
const std::string& guid,
const Glib::RefPtr& observer,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_sync().
static Glib::RefPtr create_sync(
const Glib::RefPtr& stream,
const std::string& guid,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address_sync, errthrow)
static Glib::RefPtr create_for_address_sync(
const std::string& address,
const Glib::RefPtr& observer,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
_WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address_sync, errthrow)
static Glib::RefPtr create_for_address_sync(
const std::string& address,
const Glib::RefPtr& cancellable,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_for_address_sync().
static Glib::RefPtr create_for_address_sync(
const std::string& address,
const Glib::RefPtr& observer,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/// Non-cancellable version of create_for_address_sync().
static Glib::RefPtr create_for_address_sync(
const std::string& address,
ConnectionFlags flags = Gio::DBus::ConnectionFlags::NONE);
/** Closes the connection. Note that this never causes the process to exit
* (this might only happen if the other end of a shared message bus
* connection disconnects, see property_exit_on_close()).
*
* Once the connection is closed, operations such as sending a message will
* return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
* automatically flush the connection so queued messages may be lost. Use
* flush() if you need such guarantees.
*
* If the connection is already closed, this method fails with
* Gio::IO_ERROR_CLOSED.
*
* When the connection has been closed, the "closed" signal is emitted in
* the thread-default main loop of the thread that connection was
* constructed in.
*
* This is an asynchronous method. See close_sync() for the synchronous
* version.
*
* @newin{2,28}
*/
void close();
/** Closes the connection. Note that this never causes the process to exit
* (this might only happen if the other end of a shared message bus
* connection disconnects, see property_exit_on_close()).
*
* Once the connection is closed, operations such as sending a message will
* return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
* automatically flush the connection so queued messages may be lost. Use
* flush() if you need such guarantees.
*
* If the connection is already closed, this method fails with
* Gio::IO_ERROR_CLOSED.
*
* When the connection has been closed, the "closed" signal is emitted in
* the thread-default main loop of the thread that connection was
* constructed in.
*
* This is an asynchronous method. When the operation is finished, @a slot
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call close_finish() to get the
* result of the operation. See close_sync() for the synchronous version.
*
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
*
* @newin{2,28}
*/
void close(const SlotAsyncReady& slot, const Glib::RefPtr& cancellable);
/** Closes the connection. Note that this never causes the process to exit
* (this might only happen if the other end of a shared message bus
* connection disconnects, see property_exit_on_close()).
*
* Once the connection is closed, operations such as sending a message will
* return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
* automatically flush the connection so queued messages may be lost. Use
* flush() if you need such guarantees.
*
* If the connection is already closed, this method fails with
* Gio::IO_ERROR_CLOSED.
*
* When the connection has been closed, the "closed" signal is emitted in
* the thread-default main loop of the thread that connection was
* constructed in.
*
* This is an asynchronous method. When the operation is finished, @a slot
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call close_finish() to get the
* result of the operation. See close_sync() for the synchronous version.
*
* @param slot A SlotAsyncReady to call when the request is satisfied.
*
* @newin{2,28}
*/
void close(const SlotAsyncReady& slot);
_IGNORE(g_dbus_connection_close)
_WRAP_METHOD(bool close_finish(const Glib::RefPtr& res),
g_dbus_connection_close_finish, errthrow)
_WRAP_METHOD(void close_sync(const Glib::RefPtr& cancellable{?}), g_dbus_connection_close_sync, errthrow)
/** Asynchronously flushes the connection, that is, writes all queued
* outgoing message to the transport and then flushes the transport (using
* Gio::OutputStream::flush_async()). This is useful in programs that wants
* to emit a D-Bus signal and then exit immediately. Without flushing the
* connection, there is no guarantee that the message has been sent to the
* networking buffers in the OS kernel.
*
* This is an asynchronous method. See flush_sync() for the synchronous
* version.
*
* @newin{2,28}
*/
void flush();
/** Asynchronously flushes the connection, that is, writes all queued
* outgoing message to the transport and then flushes the transport (using
* Gio::OutputStream::flush_async()). This is useful in programs that wants
* to emit a D-Bus signal and then exit immediately. Without flushing the
* connection, there is no guarantee that the message has been sent to the
* networking buffers in the OS kernel.
*
* This is an asynchronous method. When the operation is finished, @a slot
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call flush_finish() to get the
* result of the operation. See flush_sync() for the synchronous version.
*
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
*
* @newin{2,28}
*/
void flush(const SlotAsyncReady& slot, const Glib::RefPtr& cancellable);
/** Asynchronously flushes the connection, that is, writes all queued
* outgoing message to the transport and then flushes the transport (using
* Gio::OutputStream::flush_async()). This is useful in programs that wants
* to emit a D-Bus signal and then exit immediately. Without flushing the
* connection, there is no guarantee that the message has been sent to the
* networking buffers in the OS kernel.
*
* This is an asynchronous method. When the operation is finished, @a slot
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call flush_finish() to get the
* result of the operation. See flush_sync() for the synchronous version.
*
* @param slot A SlotAsyncReady to call when the request is satisfied.
*
* @newin{2,28}
*/
void flush(const SlotAsyncReady& slot);
_IGNORE(g_dbus_connection_flush)
_WRAP_METHOD(bool flush_finish(const Glib::RefPtr& res),
g_dbus_connection_flush_finish, errthrow)
_WRAP_METHOD(void flush_sync(const Glib::RefPtr& cancellable{?}), g_dbus_connection_flush_sync, errthrow)
_WRAP_METHOD(bool get_exit_on_close() const, g_dbus_connection_get_exit_on_close)
_WRAP_METHOD(void set_exit_on_close(bool exit_on_close = true), g_dbus_connection_set_exit_on_close)
//TODO: In the C API, out_serial is volatile, but gmmproc can't parse that.
#m4 _CONVERSION(`guint32&',`volatile guint32*',`&($3)')
_WRAP_METHOD(bool send_message(const Glib::RefPtr& message, SendMessageFlags flags, guint32& out_serial), g_dbus_connection_send_message, errthrow)
/// A send_message() without an "out_serial" parameter.
bool send_message(const Glib::RefPtr& message,
SendMessageFlags flags = Gio::DBus::SendMessageFlags::NONE);
/** Asynchronously sends message to the peer represented by the connection.
*
* Unless flags contain the Gio::DBus::SendMessageFlags::PRESERVE_SERIAL
* flag, the serial number will be assigned by the connection and set on
* message via Gio::DBus::Message::set_serial().
*
* If the connection is closed then the operation will fail with
* Gio::IO_ERROR_CLOSED. If @a cancellable is canceled, the operation will
* fail with Gio::IO_ERROR_CANCELLED. If @a message is not well-formed, the
* operation fails with Gio::IO_ERROR_INVALID_ARGUMENT.
*
* This is an asynchronous method. When the operation is finished, @a slot
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call
* send_message_with_reply_finish() to get the result of the operation. See
* send_message_with_reply_sync() for the synchronous version.
*
* Note that message must be unlocked, unless flags contain the
* Gio::DBus::SendMessageFlags::PRESERVE_SERIAL flag.
*
* See the C API docs for examples.
*
* @param message A Message.
* @param timeout_msec The timeout in milliseconds or -1 to use the default
* timeout.
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
*
* @newin{2,28}
*/
void send_message_with_reply(const Glib::RefPtr& message,
int timeout_msec,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable);
_IGNORE(g_dbus_connection_send_message_with_reply)
/** Non-cancellable version of send_message_with_reply().
*/
void send_message_with_reply(const Glib::RefPtr& message,
int timeout_msec,
const SlotAsyncReady& slot);
_WRAP_METHOD(Glib::RefPtr send_message_with_reply_finish(const Glib::RefPtr& res), g_dbus_connection_send_message_with_reply_finish, errthrow)
/** Synchronously sends @a message to the peer represented by the connection
* and blocks the calling thread until a reply is received or the timeout is
* reached. See send_message_with_reply() for the asynchronous version of
* this method.
*
* Unless flags contain the Gio::DBus::SendMessageFlags::PRESERVE_SERIAL
* flag, the serial number will be assigned by the connection and set on
* message via Gio::DBus::Message::set_serial().
*
* If the connection is closed then the operation will fail with
* Gio::IO_ERROR_CLOSED. If @a cancellable is canceled, the operation will
* fail with Gio::IO_ERROR_CANCELLED. If @a message is not well-formed, the
* operation fails with Gio::IO_ERROR_INVALID_ARGUMENT.
*
* Note that a Glib::Error is thrown if a local in-process error occured.
* That is to say that the returned Message object may be of type
* G_DBUS_MESSAGE_TYPE_ERROR. Use Gio::DBus::Message::to_exception() to
* transcode this to a Glib::Error.
*
* See the C API docs for examples.
*
* Note that message must be unlocked, unless flags contain the
* Gio::DBus::SendMessageFlags::PRESERVE_SERIAL flag.
*
* @param message A Message.
* @param cancellable A Cancellable.
* @param timeout_msec The timeout in milliseconds or -1 to use the default
* timeout.
* @return A locked Message that is the reply to @a message or
* 0 if a Glib::Error is thrown.
* @throw Glib::Error.
* @newin{2,28}
*/
Glib::RefPtr send_message_with_reply_sync(
const Glib::RefPtr& message,
const Glib::RefPtr& cancellable,
gint timeout_msec);
_IGNORE(g_dbus_connection_send_message_with_reply_sync)
/// A non-cancellable version of send_message_with_reply_sync().
Glib::RefPtr send_message_with_reply_sync(
const Glib::RefPtr& message,
gint timeout_msec);
_WRAP_METHOD(void start_message_processing(), g_dbus_connection_start_message_processing)
_WRAP_METHOD(bool is_closed() const, g_dbus_connection_is_closed)
_WRAP_METHOD(Glib::RefPtr get_stream(), g_dbus_connection_get_stream, refreturn)
_WRAP_METHOD(Glib::RefPtr get_stream() const, g_dbus_connection_get_stream, refreturn, constversion)
_WRAP_METHOD(std::string get_guid() const, g_dbus_connection_get_guid)
_WRAP_METHOD(Glib::ustring get_unique_name() const, g_dbus_connection_get_unique_name)
_WRAP_METHOD(CapabilityFlags get_capabilities() const, g_dbus_connection_get_capabilities)
_WRAP_METHOD(ConnectionFlags get_flags() const, g_dbus_connection_get_flags, newin "2,60")
_WRAP_METHOD(Glib::RefPtr get_peer_credentials(), g_dbus_connection_get_peer_credentials, refreturn)
_WRAP_METHOD(Glib::RefPtr get_peer_credentials() const, g_dbus_connection_get_peer_credentials, refreturn, constversion)
_WRAP_METHOD(guint32 get_last_serial() const, g_dbus_connection_get_last_serial)
/** Asynchronously invokes the @a method_name method on the @a
* interface_name D-Bus interface on the remote object at @a object_path
* owned by @a bus_name.
*
* If the connection is closed then the operation will fail with
* Gio::IO_ERROR_CLOSED. If @a cancellable is cancelled, the operation will
* fail with Gio::IO_ERROR_CANCELLED. If @a parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* Gio::IO_ERROR_INVALID_ARGUMENT.
*
* If @a reply_type is non-0 then the reply will be checked for
* having this type and an error will be raised if it does not match. Said
* another way, if you give a @a reply_type then any non-0 return
* value will be of this type.
*
* This is an asynchronous method. When the operation is finished, callback
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call call_finish() to get the
* result of the operation. See call_sync() for the synchronous version of
* this function.
*
* @param object_path Path of remote object.
* @param interface_name D-Bus interface to invoke method on.
* @param method_name The name of the method to invoke.
* @param parameters A Glib::VariantContainerBase tuple with parameters for the
* method or 0 if not passing parameters.
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
* @param bus_name A unique or well-known bus name or an empty string if the
* connection is not a message bus connection.
* @param timeout_msec The timeout in milliseconds, -1 to use the default
* timeout or G_MAXINT for no timeout.
* @param flags Flags from the Gio::DBus::CallFlags enumeration.
* @param reply_type The expected type of the reply, or 0.
* @newin{2,28}
*/
void call(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
_IGNORE(g_dbus_connection_call)
/// A non-cancellable version of call().
void call(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const SlotAsyncReady& slot,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
/** Finishes an operation started with call().
* @param res A AsyncResult obtained from the SlotAsyncReady passed to
* call().
* @result A Variant tuple with return values.
* @throw Glib::Error.
* @newin{2,28}
*/
_WRAP_METHOD(Glib::VariantContainerBase call_finish(const Glib::RefPtr& res), g_dbus_connection_call_finish, errthrow)
/** Synchronously invokes the @a method_name method on the @a interface_name
* D-Bus interface on the remote object at @a object_path owned by @a
* bus_name.
*
* If the connection is closed then the operation will fail with
* Gio::IO_ERROR_CLOSED. If @a cancellable is cancelled, the operation will
* fail with Gio::IO_ERROR_CANCELLED. If @a parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* Gio::IO_ERROR_INVALID_ARGUMENT.
*
* If @a reply_type is non-0 then the reply will be checked for
* having this type and an error will be raised if it does not match. Said
* another way, if you give a @a reply_type then any non-0 return
* value will be of this type.
*
* The calling thread is blocked until a reply is received. See call() for
* the asynchronous version of this method.
*
* @param object_path Path of remote object.
* @param interface_name D-Bus interface to invoke method on.
* @param method_name The name of the method to invoke.
* @param parameters A Glib::VariantContainerBase tuple with parameters for the
* method or 0 if not passing parameters.
* @param cancellable A Cancellable.
* @param bus_name A unique or well-known bus name or an empty string if the
* connection is not a message bus connection.
* @param timeout_msec The timeout in milliseconds, -1 to use the default
* timeout or G_MAXINT for no timeout.
* @param flags Flags from the Gio::DBus::CallFlags enumeration.
* @param reply_type The expected type of the reply, or 0.
* @result A Variant tuple with return values.
* @throw Glib::Error.
* @newin{2,28}
*/
Glib::VariantContainerBase call_sync(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const Glib::RefPtr& cancellable,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
_IGNORE(g_dbus_connection_call_sync)
/// A non-cancellable version of call_sync().
Glib::VariantContainerBase call_sync(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
#ifdef G_OS_UNIX
/** Like call() but also takes a GUnixFDList object.
* This method is only available on UNIX.
*
* This is an asynchronous method. When the operation is finished, callback
* will be invoked in the thread-default main loop of the thread you are
* calling this method from. You can then call call_with_unix_fd_finish() to
* get the result of the operation. See call_sync() for the synchronous
* version of this function.
*
* @param object_path Path of remote object.
* @param interface_name D-Bus interface to invoke method on.
* @param method_name The name of the method to invoke.
* @param parameters A Glib::VariantContainerBase tuple with parameters for the
* method or 0 if not passing parameters.
* @param slot A SlotAsyncReady to call when the request is satisfied.
* @param cancellable A Cancellable.
* @param fd_list A UnixFDList.
* @param bus_name A unique or well-known bus name or an empty string if the
* connection is not a message bus connection.
* @param timeout_msec The timeout in milliseconds, -1 to use the default
* timeout or G_MAXINT for no timeout.
* @param flags Flags from the Gio::DBus::CallFlags enumeration.
* @param reply_type The expected type of the reply, or 0.
* @newin{2,34}
*/
void call(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const SlotAsyncReady& slot,
const Glib::RefPtr& cancellable,
const Glib::RefPtr& fd_list,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
_IGNORE(g_dbus_connection_call_with_unix_fd_list)
/** A non-cancellable version of call() (with a UnixFDList).
* @newin{2,34}
*/
void call(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& method_name,
const Glib::VariantContainerBase& parameters,
const SlotAsyncReady& slot,
const Glib::RefPtr& fd_list,
const Glib::ustring& bus_name = {},
int timeout_msec = -1,
CallFlags flags = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type = {});
#endif // 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}
*/
_WRAP_METHOD(Glib::VariantContainerBase call_finish(const Glib::RefPtr& res{.}, Glib::RefPtr& out_fd_list{.>>}), g_dbus_connection_call_with_unix_fd_list_finish, errthrow, ifdef G_OS_UNIX)
_WRAP_METHOD(
Glib::VariantContainerBase call_sync(
const Glib::ustring& object_path{.},
const Glib::ustring& interface_name{.},
const Glib::ustring& method_name{.},
const Glib::VariantContainerBase& parameters{.},
const Glib::RefPtr& cancellable{.?},
const Glib::RefPtr& fd_list{.},
Glib::RefPtr& out_fd_list{.>>},
const Glib::ustring& bus_name{.NULL} = {},
int timeout_msec{.} = -1,
CallFlags flags{.} = Gio::DBus::CallFlags::NONE,
const Glib::VariantType& reply_type{.} = {}
),
g_dbus_connection_call_with_unix_fd_list_sync, errthrow, ifdef G_OS_UNIX
)
/** Emits a signal.
*
* This can only fail if @a parameters is not compatible with the D-Bus
* protocol.
*
* @param object_path Path of remote object.
* @param interface_name D-Bus interface to emit a signal on.
* @param signal_name The name of the signal to emit.
* @param destination_bus_name The unique bus name for the destination for
* the signal or an empty string to emit to all listeners.
* @param parameters A Glib::VariantContainerBase tuple with parameters for the
* signal or 0 if not passing parameters.
* @throw Glib::Error.
* @newin{2,28}
*/
void emit_signal(
const Glib::ustring& object_path,
const Glib::ustring& interface_name,
const Glib::ustring& signal_name,
const Glib::ustring& destination_bus_name = {},
const Glib::VariantContainerBase& parameters = {});
_IGNORE(g_dbus_connection_emit_signal)
/** Subscribes to signals on the connection and invokes @a slot with a
* whenever the signal is received. Note that @a slot will be invoked in the
* thread-default main loop of the thread you are calling this method from.
*
* If the connection is not a message bus connection, @a sender must be
* 0.
*
* If @a sender is a well-known name note that @a slot is invoked with the
* unique name for the owner of @a sender, not the well-known name as one
* would expect. This is because the message bus rewrites the name. As such,
* to avoid certain race conditions, users should be tracking the name owner
* of the well-known name and use that when processing the received signal.
*
* @param slot Slot to invoke when there is a signal matching the requested
* data.
* @param sender Sender name to match on (unique or well-known name) or
* 0 to listen from all senders.
* @param interface_name D-Bus interface name to match on or 0 to
* match on all interfaces.
* @param member D-Bus signal name to match on or 0 to match on all
* signals.
* @param object_path Object path to match on or 0 to match on all
* object paths.
* @param arg0 Contents of first string argument to match on or 0
* to match on all kinds of arguments.
* @param flags Flags describing how to subscribe to the signal (currently
* unused).
* @return A subscription identifier that can be used with
* signal_unsubscribe().
* @newin{2,28}
*/
guint signal_subscribe(
const SlotSignal& slot,
const Glib::ustring& sender = {},
const Glib::ustring& interface_name = {},
const Glib::ustring& member = {},
const Glib::ustring& object_path = {},
const Glib::ustring& arg0 = {},
SignalFlags flags = Gio::DBus::SignalFlags::NONE);
_IGNORE(g_dbus_connection_signal_subscribe)
_WRAP_METHOD(void signal_unsubscribe(guint subscription_id), g_dbus_connection_signal_unsubscribe)
/** Adds a message filter. Filters are handlers that are run on all incoming
* and outgoing messages, prior to standard dispatch. Filters are run in the
* order that they were added. The same handler can be added as a filter
* more than once, in which case it will be run more than once. Filters
* added during a filter slot won't be run on the message being processed.
* Filter slots are allowed to modify and even drop messages.
*
* Note that filters are run in a dedicated message handling thread so they
* can't block and, generally, can't do anything but signal a worker thread.
* Also note that filters are rarely needed - use API such as
* send_message_with_reply(), signal_subscribe() or call() instead.
*
* If a filter consumes an incoming message the message is not dispatched
* anywhere else - not even the standard dispatch machinery (that API such
* as signal_subscribe() and send_message_with_reply() relies on) will see
* the message. Similary, if a filter consumes an outgoing message, the
* message will not be sent to the other peer.
*
* @param slot A filter slot.
* @return A filter identifier that can be used with remove_filter().
* @newin{2,28}
*/
guint add_filter(const SlotMessageFilter& slot);
_IGNORE(g_dbus_connection_add_filter)
_WRAP_METHOD(void remove_filter(guint filter_id), g_dbus_connection_remove_filter)
/** Registers slots for exported objects at @a object_path with the D-Bus
* interface that is described in @a interface_info.
*
* Calls to slots in @a vtable will happen in the thread-default main loop
* of the thread you are calling this method from.
*
* Note that all Glib::VariantBase values passed to functions in @a vtable
* will match the signature given in @a interface_info - if a remote caller
* passes incorrect values, the @c org.freedesktop.DBus.Error.InvalidArgs is
* returned to the remote caller.
*
* Additionally, if the remote caller attempts to invoke methods or access
* properties not mentioned in @a interface_info the
* @c org.freedesktop.DBus.Error.UnknownMethod resp.
* @c org.freedesktop.DBus.Error.InvalidArgs errors are returned to the
* caller.
*
* It is considered a programming error if the SlotDBusInterfaceGetProperty
* slot in @a vtable returns a Glib::VariantBase of incorrect type.
*
* If an existing slot is already registered at @a object_path and @a
* interface_name, then a Glib::Error is thrown.
*
* GDBus automatically implements the standard D-Bus interfaces
* org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and
* org.freedesktop.Peer, so you don't have to implement those for the
* objects you export. You can implement org.freedesktop.DBus.Properties
* yourself, e.g. to handle getting and setting of properties
* asynchronously.
*
* @param object_path The object path to register at.
* @param interface_info Introspection data for the interface.
* @param vtable An InterfaceVTable to call into.
* @return A registration id (never 0) that can be used with
* unregister_object() if no Glib::Error is thrown.
* @throw Glib::Error.
* @newin{2,28}
*/
guint register_object(const Glib::ustring& object_path,
const Glib::RefPtr& interface_info,
const InterfaceVTable& vtable);
_IGNORE(g_dbus_connection_register_object)
/** Registers exported objects at @a object_path with the D-Bus
* interface that is described in @a interface_info. This method overload,
* which does not take a VTable, is useful for
* marker
* interfaces.
*
* If an existing slot is already registered at @a object_path and @a
* interface_name, then a Glib::Error is thrown.
*
* GDBus automatically implements the standard D-Bus interfaces
* org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable and
* org.freedesktop.Peer, so you don't have to implement those for the
* objects you export.
*
* @param object_path The object path to register at.
* @param interface_info Introspection data for the interface.
* @return A registration id (never 0) that can be used with
* unregister_object() if no Glib::Error is thrown.
* @throw Glib::Error.
* @newin{2,28}
*/
guint register_object(const Glib::ustring& object_path,
const Glib::RefPtr& interface_info);
_WRAP_METHOD(bool unregister_object(guint registration_id), g_dbus_connection_unregister_object)
/** Registers a whole subtree of “dynamic” objects.
*
* Copies of the enumerate and introspection slots usted to create @a vtable
* are used to convey, to remote callers, what nodes exist in the subtree
* rooted by @a object_path.
*
* When handling remote calls into any node in the subtree, first the
* enumerate slot is used to check if the node exists. If the node
* exists or the Gio::DBus::SubtreeFlags::DISPATCH_TO_UNENUMERATED_NODES flag
* is set the introspection slot is used to check if the node supports the
* requested method. If so, the dispatch function is used to determine where
* to dispatch the call. The collected InterfaceVTable will be used to
* call into the interface vtable for processing the request.
*
* All calls into user-provided code will be invoked in the thread-default
* main loop of the thread you are calling this method from.
*
* If an existing subtree is already registered at @a object_path or then
* a Glib::Error is thrown.
*
* Note that it is valid to register regular objects (using
* register_object()) in a subtree registered with register_subtree() - if
* so, the subtree handler is tried as the last resort. One way to think
* about a subtree handler is to consider it a “fallback handler” for object
* paths not registered via register_object().
*
*
* @param object_path The object path to register the subtree at.
* @param vtable A SubtreeVTable to enumerate, introspect and dispatch
* nodes in the subtree.
* @param flags Flags used to fine tune the behavior of the subtree.
* @return A subtree registration id (never 0) that can be used with
* unregister_subtree() if no Glib::Error is thrown.
*
* @newin{2,28}
*/
guint register_subtree(const Glib::ustring& object_path,
const SubtreeVTable& vtable,
SubtreeFlags flags = Gio::DBus::SubtreeFlags::NONE);
_IGNORE(g_dbus_connection_register_subtree)
_WRAP_METHOD(bool unregister_subtree(guint registration_id), g_dbus_connection_unregister_subtree)
_WRAP_METHOD(guint export_action_group(const Glib::ustring& object_path, const Glib::RefPtr& action_group), g_dbus_connection_export_action_group, errthrow)
_WRAP_METHOD(void unexport_action_group(guint export_id), g_dbus_connection_unexport_action_group)
_WRAP_METHOD(guint export_menu_model(const Glib::ustring& object_path, const Glib::RefPtr& menu), g_dbus_connection_export_menu_model, errthrow)
_WRAP_METHOD(void unexport_menu_model(guint export_id), g_dbus_connection_unexport_menu_model)
//_WRAP_PROPERTY("address", std::string) // write-only construct-only
//_WRAP_PROPERTY("authentication-observer", Glib::RefPtr) // write-only construct-only
_WRAP_PROPERTY("capabilities", CapabilityFlags)
_WRAP_PROPERTY("closed", bool)
_WRAP_PROPERTY("exit-on-close", bool)
_WRAP_PROPERTY("flags", ConnectionFlags, newin "2,60")
_WRAP_PROPERTY("guid", std::string)
_WRAP_PROPERTY("stream", Glib::RefPtr)
_WRAP_PROPERTY("unique-name", Glib::ustring)
#m4 _CONVERSION(`GError*', `const Glib::Error&', `Glib::Error($3, true)')
_WRAP_SIGNAL(void closed(bool remote_peer_vanished, const Glib::Error& error), "closed", no_default_handler)
};
} //namespace DBus
} // namespace Gio