path: root/gio/src/dbusconnection.hg

// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-

/* 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, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <glibmm/object.h>
#include <giomm/initable.h>
#include <giomm/asyncinitable.h>
#include <giomm/iostream.h>
#include <giomm/asyncresult.h>
#include <giomm/credentials.h>
#include <giomm/dbusmessage.h>

_DEFS(giomm,gio)
_PINCLUDE(glibmm/private/object_p.h)

//TODO: Use a GDbus namespace, and remove the DBus prefixes.
namespace Gio
{

_WRAP_ENUM(BusType, GBusType)
_WRAP_ENUM(DBusCallFlags, GDBusCallFlags, NO_GTYPE)
_WRAP_ENUM(DBusConnectionFlags, GDBusConnectionFlags, NO_GTYPE)
_WRAP_ENUM(DBusSendMessageFlags, GDBusSendMessageFlags, NO_GTYPE)
_WRAP_ENUM(DBusSignalFlags, GDBusSignalFlags, NO_GTYPE)

class DBusAuthObserver;

//TODO: Add example from C API in class docs.
/** DBusConnection - D-Bus Connections.
 * The DBusConnection 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 an
 * D-Bus client, it is often easier to use the Gio::DBus::own_name(),
 * Gio::DBus::watch_name() or DBusProxy::create_for_bus() APIs.
 *
 * @newin{2,28}
 */
class DBusConnection
: public Glib::Object, public Initable, public AsyncInitable
{
protected:
  _CLASS_GOBJECT(DBusConnection, GDBusConnection, G_DBUS_CONNECTION, Glib::Object, GObject)
  _IMPLEMENTS_INTERFACE(Initable)
  _IMPLEMENTS_INTERFACE(AsyncInitable)

protected:

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    DBusConnectionFlags flags);

  DBusConnection(const Glib::ustring& address,
    DBusConnectionFlags flags);

public:

  /** Signature for slot used in signal_subscribe().
   *  For example,
   * @code
   * void on_signal(const Glib::RefPtr<DBusConnection>&, 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::VariantBase& parameters);.
   * @endcode
   */
  typedef sigc::slot<void, const Glib::RefPtr<DBusConnection>&,
    const Glib::ustring&, const Glib::ustring&, const Glib::ustring&,
    const Glib::ustring&, const Glib::VariantBase&>  SlotSignal;

  /** Signature for slot used in add_filter().
   *  For example,
   * @code
   * Glib::RefPtr<DBusMessage> on_message_filter(const
   * Glib::RefPtr<DBusConnection>, const Glib::RefPtr<DBusMessage>& bool
   * incoming);.
   * @endcode
   *
   * A filter function is passed a DBusMessage and expected to return a
   * DBusMessage 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 <tt>0</tt>.  And filter function may
   * modify a message by copying it and return the copy.
   */
  typedef sigc::slot<Glib::RefPtr<DBusMessage>,
    const Glib::RefPtr<DBusConnection>&,
    const Glib::RefPtr<DBusMessage>&, bool> SlotMessageFilter;

  /** 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>& cancellable);
  _IGNORE(g_bus_get)

  /** Non-cancellable version of get().
   */
  static void get(BusType bus_type, const SlotAsyncReady& slot);

  _WRAP_METHOD_DOCS_ONLY( g_bus_get_finish, errthrow)
  /// @throw Glib::Error.
  _WRAP_METHOD(static Glib::RefPtr<DBusConnection> get_finish(const Glib::RefPtr<AsyncResult>& res), g_bus_get_finish, errthrow)

  _WRAP_METHOD(static Glib::RefPtr<DBusConnection> get_sync(BusType bus_type, const Glib::RefPtr<Cancellable>& cancellable), g_bus_get_sync, errthrow)

  /// A Non-cancellable version of get_sync().
  static Glib::RefPtr<DBusConnection> get_sync(BusType bus_type);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new)
  static void create(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new)
  static void create(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create().
  static void create(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create().
  static void create(const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_finish)
  /// @throw Glib::Error.
  _WRAP_METHOD(static Glib::RefPtr<DBusConnection> create_finish(const Glib::RefPtr<AsyncResult>& res), g_dbus_connection_new_finish, errthrow)

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address)
  static void create_for_address(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address)
  static void create_for_address(const Glib::ustring& address,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_for_address().
  static void create_for_address(const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_for_address().
  static void create_for_address(const Glib::ustring& address,
    const SlotAsyncReady& slot,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address_finish)
  /// @throw Glib::Error.
  _WRAP_METHOD(static Glib::RefPtr<DBusConnection> create_for_address_finish(const Glib::RefPtr<AsyncResult>& res), g_dbus_connection_new_for_address_finish, errthrow)

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_sync)
  /// @throw Glib::Error.
  static Glib::RefPtr<DBusConnection> create_sync(
    const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_sync)
  /// @throw Glib::Error.
  static Glib::RefPtr<DBusConnection> create_sync(
    const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_sync().
  static Glib::RefPtr<DBusConnection> create_sync(
    const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_sync().
  static Glib::RefPtr<DBusConnection> create_sync(
    const Glib::RefPtr<IOStream>& stream,
    const Glib::ustring& guid,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address_sync)
  /// @throw Glib::Error.
  static Glib::RefPtr<DBusConnection> create_for_address_sync(
    const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_new_for_address_sync)
  /// @throw Glib::Error.
  static Glib::RefPtr<DBusConnection> create_for_address_sync(
    const Glib::ustring& address,
    const Glib::RefPtr<Cancellable>& cancellable,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_for_address_sync().
  static Glib::RefPtr<DBusConnection> create_for_address_sync(
    const Glib::ustring& address,
    const Glib::RefPtr<DBusAuthObserver>& observer,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_NONE);

  /// Non-cancellable version of create_for_address_sync().
  static Glib::RefPtr<DBusConnection> create_for_address_sync(
    const Glib::ustring& address,
    DBusConnectionFlags flags = Gio::DBUS_CONNECTION_FLAGS_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>& 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<AsyncResult>& result),
               g_dbus_connection_close_finish, errthrow)

  /** Synchronously closees the connection. The calling thread is blocked
   * until this is done. See close() for the asynchronous version of this
   * method and more details about what it does.
   *
   * @newin{2,28}
   *
   * @throw Glib::Error.
   */
  void close_sync();

  _WRAP_METHOD(void close_sync(const Glib::RefPtr<Cancellable>& 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>& 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<AsyncResult>& result),
               g_dbus_connection_flush_finish, errthrow)

  /** Synchronously flushes the connection. The calling thread is blocked
   * until this is done. See flush() for the asynchronous version of this
   * method and more details about what it does.
   *
   * @newin{2,28}
   *
   * @throw Glib::Error.
   */
  void flush_sync();

  _WRAP_METHOD(void flush_sync(const Glib::RefPtr<Cancellable>& 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<DBusMessage>& message, DBusSendMessageFlags flags, guint32* out_serial), g_dbus_connection_send_message, errthrow)

  /** Asynchronously sends message to the peer represented by the connection.
   *
   * Unless flags contain the Gio::DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL
   * flag, the serial number will be assigned by the connection and set on
   * message via Gio::DBusMessage::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_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
   *
   * See the C API docs for examples.
   *
   * @param message A DBusMessage.
   * @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<DBusMessage>& message,
    int timeout_msec,
    const SlotAsyncReady& slot,
    const Glib::RefPtr<Cancellable>& 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<DBusMessage>& message,
    int timeout_msec,
    const SlotAsyncReady& slot);

  _WRAP_METHOD_DOCS_ONLY(g_dbus_connection_send_message_with_reply_finish)
  /// @throw Glib::Error.
  _WRAP_METHOD(Glib::RefPtr<DBusMessage> send_message_with_reply_finish(const Glib::RefPtr<AsyncResult>& result), 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_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL
   * flag, the serial number will be assigned by the connection and set on
   * message via Gio::DBusMessage::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 DBusMessage object may be of type
   * G_DBUS_MESSAGE_TYPE_ERROR. Use Gio::DBusMessage::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_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
   *
   * @param message A DBusMessage.
   * @param cancellable A Cancellable.
   * @param timeout_msec The timeout in milliseconds or -1 to use the default
   * timeout.
   * @return A locked DBusMessage that is the reply to @a message or
   * <tt>0</tt> if a Glib::Error is thrown.
   * @throw Glib::Error.
   * @newin{2,28}
   */
  Glib::RefPtr<DBusMessage> send_message_with_reply_sync(
    const Glib::RefPtr<DBusMessage>& message,
    const Glib::RefPtr<Cancellable>& cancellable,
    gint timeout_msec
  );

  /// A non-cancellable version of send_message_with_reply_sync().
  Glib::RefPtr<DBusMessage> send_message_with_reply_sync(
    const Glib::RefPtr<DBusMessage>& 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<IOStream> get_stream(), g_dbus_connection_get_stream, refreturn)
  _WRAP_METHOD(Glib::RefPtr<const IOStream> get_stream() const, g_dbus_connection_get_stream, refreturn, constversion)

  _WRAP_METHOD(Glib::ustring get_guid() const, g_dbus_connection_get_guid)
  _WRAP_METHOD(Glib::ustring get_unique_name() const, g_dbus_connection_get_unique_name)

  _WRAP_METHOD(DBusCapabilityFlags get_capabilities() const, g_dbus_connection_get_capabilities)

  _WRAP_METHOD(Glib::RefPtr<Credentials> get_peer_credentials(), g_dbus_connection_get_peer_credentials, refreturn)
  _WRAP_METHOD(Glib::RefPtr<const Credentials> get_peer_credentials() const, g_dbus_connection_get_peer_credentials, refreturn, constversion)

  /** 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-<tt>0</tt> 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-<tt>0</tt> 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 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 <tt>0</tt> 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::DBusCallFlags enumeration.
   * @param parameters A Glib::VariantBase tuple with parameters for the
   * method or <tt>0</tt> if not passing parameters.
   * @param reply_type The expected type of the reply, or <tt>0</tt>.
   * @newin{2,28}
   */
  void call(
    const Glib::ustring&                object_path,
    const Glib::ustring&                interface_name,
    const Glib::ustring&                method_name,
    const SlotAsyncReady&               slot,
    const Glib::RefPtr<Cancellable>&    cancellable,
    int                                 timeout_msec = -1,
    const Glib::ustring&                bus_name = Glib::ustring(),
    DBusCallFlags                       flags = Gio::DBUS_CALL_FLAGS_NONE,
    const Glib::VariantBase&            parameters = Glib::VariantBase(),
    const Glib::VariantType&            reply_type = Glib::VariantType()
  );
  _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 SlotAsyncReady&               slot,
    int                                 timeout_msec = -1,
    const Glib::ustring&                bus_name = Glib::ustring(),
    DBusCallFlags                       flags = Gio::DBUS_CALL_FLAGS_NONE,
    const Glib::VariantBase&            parameters = Glib::VariantBase(),
    const Glib::VariantType&            reply_type = Glib::VariantType()
  );

  /** Finishes an operation started with call().
   * @param output A location in which to return a tuple with return values.
   * @param res A AsyncResult obtained from the SlotAsyncReady passed to
   * call().
   * @throw Glib::Error.
   * @newin{2,28}
   */
  void call_finish(
    Glib::VariantBase&                   output,
    const Glib::RefPtr<AsyncResult>&     res
  );
  _IGNORE(g_dbus_connection_call_finish)

  /** 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-<tt>0</tt> 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-<tt>0</tt> 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 output A location in which to return a tuple with return values.
   * @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 cancellable A Cancellable.
   * @param bus_name A unique or well-known bus name or <tt>0</tt> 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::DBusCallFlags enumeration.
   * @param parameters A Glib::VariantBase tuple with parameters for the
   * method or <tt>0</tt> if not passing parameters.
   * @param reply_type The expected type of the reply, or <tt>0</tt>.
   * @throw Glib::Error.
   * @newin{2,28}
   */
  void call_sync(
    Glib::VariantBase&                  output,
    const Glib::ustring&                object_path,
    const Glib::ustring&                interface_name,
    const Glib::ustring&                method_name,
    const Glib::RefPtr<Cancellable>&    cancellable,
    int                                 timeout_msec = -1,
    const Glib::ustring&                bus_name = Glib::ustring(),
    DBusCallFlags                       flags = Gio::DBUS_CALL_FLAGS_NONE,
    const Glib::VariantBase&            parameters = Glib::VariantBase(),
    const Glib::VariantType&            reply_type = Glib::VariantType()
  );
  _IGNORE(g_dbus_connection_call_sync)

  /// A non-cancellable version of call_sync().
  void call_sync(
    Glib::VariantBase&                  output,
    const Glib::ustring&                object_path,
    const Glib::ustring&                interface_name,
    const Glib::ustring&                method_name,
    int                                 timeout_msec = -1,
    const Glib::ustring&                bus_name = Glib::ustring(),
    DBusCallFlags                       flags = Gio::DBUS_CALL_FLAGS_NONE,
    const Glib::VariantBase&            parameters = Glib::VariantBase(),
    const Glib::VariantType&            reply_type = Glib::VariantType()
  );

  /** 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 <tt>0</tt> to emit to all listeners.
   * @param parameters A Glib::VariantBase tuple with parameters for the
   * signal or <tt>0</tt> 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 = Glib::ustring(),
    const Glib::VariantBase&            parameters = Glib::VariantBase()
  );
  _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
   * <tt>0</tt>.
   *
   * 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
   * <tt>0</tt> to listen from all senders.
   * @param interface_name D-Bus interface name to match on or <tt>0</tt> to
   * match on all interfaces.
   * @param member D-Bus signal name to match on or <tt>0</tt> to match on all
   * signals.  
   * @param object_path Object path to match on or <tt>0</tt> to match on all
   * object paths.  
   * @param arg0 Contents of first string argument to match on or <tt>0</tt>
   * 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 = Glib::ustring(),
    const Glib::ustring& interface_name = Glib::ustring(),
    const Glib::ustring& member = Glib::ustring(),
    const Glib::ustring& object_path = Glib::ustring(),
    const Glib::ustring& arg0 = Glib::ustring(),
    DBusSignalFlags flags = Gio::DBUS_SIGNAL_FLAGS_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)
};

} // namespace Gio