gio/auto/

dbus_proxy.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
use crate::UnixFDList;
use crate::{
    AsyncInitable, AsyncResult, BusType, Cancellable, DBusCallFlags, DBusConnection, DBusInterface,
    DBusInterfaceInfo, DBusProxyFlags, Initable, ffi,
};
use glib::{
    prelude::*,
    signal::{SignalHandlerId, connect_raw},
    translate::*,
};
use std::{boxed::Box as Box_, pin::Pin};

glib::wrapper! {
    /// `GDBusProxy` is a base class used for proxies to access a D-Bus
    /// interface on a remote object. A `GDBusProxy` can be constructed for
    /// both well-known and unique names.
    ///
    /// By default, `GDBusProxy` will cache all properties (and listen to
    /// changes) of the remote object, and proxy all signals that get
    /// emitted. This behaviour can be changed by passing suitable
    /// [`DBusProxyFlags`][crate::DBusProxyFlags] when the proxy is created. If the proxy is for a
    /// well-known name, the property cache is flushed when the name owner
    /// vanishes and reloaded when a name owner appears.
    ///
    /// The unique name owner of the proxy’s name is tracked and can be read from
    /// [`g-name-owner`][struct@crate::DBusProxy#g-name-owner]. Connect to the
    /// [`notify`][struct@crate::glib::Object#notify] signal to get notified of changes.
    /// Additionally, only signals and property changes emitted from the current name
    /// owner are considered and calls are always sent to the current name owner.
    /// This avoids a number of race conditions when the name is lost by one owner
    /// and claimed by another. However, if no name owner currently exists,
    /// then calls will be sent to the well-known name which may result in
    /// the message bus launching an owner (unless
    /// `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set).
    ///
    /// If the proxy is for a stateless D-Bus service, where the name owner may
    /// be started and stopped between calls, the
    /// [`g-name-owner`][struct@crate::DBusProxy#g-name-owner] tracking of `GDBusProxy` will cause the
    /// proxy to drop signal and property changes from the service after it has
    /// restarted for the first time. When interacting with a stateless D-Bus
    /// service, do not use `GDBusProxy` — use direct D-Bus method calls and signal
    /// connections.
    ///
    /// The generic [`g-properties-changed`][struct@crate::DBusProxy#g-properties-changed] and
    /// [`g-signal`][struct@crate::DBusProxy#g-signal] signals are not very convenient to work
    /// with. Therefore, the recommended way of working with proxies is to subclass
    /// `GDBusProxy`, and have more natural properties and signals in your derived
    /// class. This [example](migrating-gdbus.html#using-gdbus-codegen) shows how
    /// this can easily be done using the [`gdbus-codegen`](gdbus-codegen.html) tool.
    ///
    /// A `GDBusProxy` instance can be used from multiple threads but note
    /// that all signals (e.g. [`g-signal`][struct@crate::DBusProxy#g-signal],
    /// [`g-properties-changed`][struct@crate::DBusProxy#g-properties-changed] and
    /// [`notify`][struct@crate::glib::Object#notify]) are emitted in the thread-default main
    /// context (see [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::push_thread_default()]) of the thread
    /// where the instance was constructed.
    ///
    ///
    /// ## A watch proxy example
    /// An example using a proxy for a well-known name can be found in
    /// [`gdbus-example-watch-proxy.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c).
    ///
    /// ## Properties
    ///
    ///
    /// #### `g-bus-type`
    ///  If this property is not [`BusType::None`][crate::BusType::None], then
    /// #GDBusProxy:g-connection must be [`None`] and will be set to the
    /// #GDBusConnection obtained by calling g_bus_get() with the value
    /// of this property.
    ///
    /// Writable | Construct Only
    ///
    ///
    /// #### `g-connection`
    ///  The #GDBusConnection the proxy is for.
    ///
    /// Readable | Writable | Construct Only
    ///
    ///
    /// #### `g-default-timeout`
    ///  The timeout to use if -1 (specifying default timeout) is passed
    /// as @timeout_msec in the g_dbus_proxy_call() and
    /// g_dbus_proxy_call_sync() functions.
    ///
    /// This allows applications to set a proxy-wide timeout for all
    /// remote method invocations on the proxy. If this property is -1,
    /// the default timeout (typically 25 seconds) is used. If set to
    /// `G_MAXINT`, then no timeout is used.
    ///
    /// Readable | Writable | Construct
    ///
    ///
    /// #### `g-flags`
    ///  Flags from the #GDBusProxyFlags enumeration.
    ///
    /// Readable | Writable | Construct Only
    ///
    ///
    /// #### `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 #GDBusInterfaceInfo 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 #GError is set to [`IOErrorEnum::InvalidArgument`][crate::IOErrorEnum::InvalidArgument].
    ///
    /// - Received signals that have a type signature mismatch are dropped and
    ///   a warning is logged via g_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 g_warning().
    ///
    /// Note that these checks are never done on methods, signals and
    /// properties that are not referenced in the given
    /// #GDBusInterfaceInfo, since extending a D-Bus interface on the
    /// service-side is not considered an ABI break.
    ///
    /// Readable | Writable
    ///
    ///
    /// #### `g-interface-name`
    ///  The D-Bus interface name the proxy is for.
    ///
    /// Readable | Writable | Construct Only
    ///
    ///
    /// #### `g-name`
    ///  The well-known or unique name that the proxy is for.
    ///
    /// Readable | Writable | Construct Only
    ///
    ///
    /// #### `g-name-owner`
    ///  The unique name that owns #GDBusProxy:g-name or [`None`] if no-one
    /// currently owns that name. You may connect to #GObject::notify signal to
    /// track changes to this property.
    ///
    /// Readable
    ///
    ///
    /// #### `g-object-path`
    ///  The object path the proxy is for.
    ///
    /// Readable | Writable | Construct Only
    ///
    /// ## Signals
    ///
    ///
    /// #### `g-properties-changed`
    ///  Emitted when one or more D-Bus properties on @proxy changes. The
    /// local cache has already been updated when this signal fires. Note
    /// that both @changed_properties and @invalidated_properties are
    /// guaranteed to never be [`None`] (either may be empty though).
    ///
    /// If the proxy has the flag
    /// [`DBusProxyFlags::GET_INVALIDATED_PROPERTIES`][crate::DBusProxyFlags::GET_INVALIDATED_PROPERTIES] set, then
    /// @invalidated_properties will always be empty.
    ///
    /// This signal corresponds to the
    /// `PropertiesChanged` D-Bus signal on the
    /// `org.freedesktop.DBus.Properties` interface.
    ///
    ///
    ///
    ///
    /// #### `g-signal`
    ///  Emitted when a signal from the remote object and interface that @proxy is for, has been received.
    ///
    /// Since 2.72 this signal supports detailed connections. You can connect to
    /// the detailed signal `g-signal::x` in order to receive callbacks only when
    /// signal `x` is received from the remote object.
    ///
    /// Detailed
    ///
    /// # Implements
    ///
    /// [`DBusProxyExt`][trait@crate::prelude::DBusProxyExt], [`trait@glib::ObjectExt`], [`AsyncInitableExt`][trait@crate::prelude::AsyncInitableExt], [`DBusInterfaceExt`][trait@crate::prelude::DBusInterfaceExt], [`InitableExt`][trait@crate::prelude::InitableExt], [`DBusProxyExtManual`][trait@crate::prelude::DBusProxyExtManual]
    #[doc(alias = "GDBusProxy")]
    pub struct DBusProxy(Object<ffi::GDBusProxy, ffi::GDBusProxyClass>) @implements AsyncInitable, DBusInterface, Initable;

    match fn {
        type_ => || ffi::g_dbus_proxy_get_type(),
    }
}

impl DBusProxy {
    pub const NONE: Option<&'static DBusProxy> = None;

    /// Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
    ///
    /// #GDBusProxy is used in this [example][`DBusProxy`][crate::DBusProxy]#a-watch-proxy-example].
    /// ## `bus_type`
    /// A #GBusType.
    /// ## `flags`
    /// Flags used when constructing the proxy.
    /// ## `info`
    /// A #GDBusInterfaceInfo specifying the minimal interface
    ///        that @proxy conforms to or [`None`].
    /// ## `name`
    /// A bus name (well-known or unique).
    /// ## `object_path`
    /// An object path.
    /// ## `interface_name`
    /// A D-Bus interface name.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    ///
    /// # Returns
    ///
    /// A #GDBusProxy or [`None`] if error is set.
    ///    Free with g_object_unref().
    #[doc(alias = "g_dbus_proxy_new_for_bus_sync")]
    #[doc(alias = "new_for_bus_sync")]
    pub fn for_bus_sync(
        bus_type: BusType,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: &str,
        object_path: &str,
        interface_name: &str,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<DBusProxy, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dbus_proxy_new_for_bus_sync(
                bus_type.into_glib(),
                flags.into_glib(),
                info.to_glib_none().0,
                name.to_glib_none().0,
                object_path.to_glib_none().0,
                interface_name.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a proxy for accessing @interface_name on the remote object
    /// at @object_path owned by @name at @connection and synchronously
    /// loads D-Bus properties unless the
    /// [`DBusProxyFlags::DO_NOT_LOAD_PROPERTIES`][crate::DBusProxyFlags::DO_NOT_LOAD_PROPERTIES] flag is used.
    ///
    /// If the [`DBusProxyFlags::DO_NOT_CONNECT_SIGNALS`][crate::DBusProxyFlags::DO_NOT_CONNECT_SIGNALS] flag is not set, also sets up
    /// match rules for signals. Connect to the #GDBusProxy::g-signal signal
    /// to handle signals from the remote object.
    ///
    /// If both [`DBusProxyFlags::DO_NOT_LOAD_PROPERTIES`][crate::DBusProxyFlags::DO_NOT_LOAD_PROPERTIES] and
    /// [`DBusProxyFlags::DO_NOT_CONNECT_SIGNALS`][crate::DBusProxyFlags::DO_NOT_CONNECT_SIGNALS] are set, this constructor is
    /// guaranteed to return immediately without blocking.
    ///
    /// If @name is a well-known name and the
    /// [`DBusProxyFlags::DO_NOT_AUTO_START`][crate::DBusProxyFlags::DO_NOT_AUTO_START] and [`DBusProxyFlags::DO_NOT_AUTO_START_AT_CONSTRUCTION`][crate::DBusProxyFlags::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.
    ///
    /// #GDBusProxy is used in this [example][`DBusProxy`][crate::DBusProxy]#a-watch-proxy-example].
    /// ## `connection`
    /// A #GDBusConnection.
    /// ## `flags`
    /// Flags used when constructing the proxy.
    /// ## `info`
    /// A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or [`None`].
    /// ## `name`
    /// A bus name (well-known or unique) or [`None`] if @connection is not a message bus connection.
    /// ## `object_path`
    /// An object path.
    /// ## `interface_name`
    /// A D-Bus interface name.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    ///
    /// # Returns
    ///
    /// A #GDBusProxy or [`None`] if error is set.
    ///    Free with g_object_unref().
    #[doc(alias = "g_dbus_proxy_new_sync")]
    pub fn new_sync(
        connection: &DBusConnection,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: Option<&str>,
        object_path: &str,
        interface_name: &str,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<DBusProxy, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dbus_proxy_new_sync(
                connection.to_glib_none().0,
                flags.into_glib(),
                info.to_glib_none().0,
                name.to_glib_none().0,
                object_path.to_glib_none().0,
                interface_name.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Creates a proxy for accessing @interface_name on the remote object
    /// at @object_path owned by @name at @connection and asynchronously
    /// loads D-Bus properties unless the
    /// [`DBusProxyFlags::DO_NOT_LOAD_PROPERTIES`][crate::DBusProxyFlags::DO_NOT_LOAD_PROPERTIES] flag is used. Connect to
    /// the #GDBusProxy::g-properties-changed signal to get notified about
    /// property changes.
    ///
    /// If the [`DBusProxyFlags::DO_NOT_CONNECT_SIGNALS`][crate::DBusProxyFlags::DO_NOT_CONNECT_SIGNALS] flag is not set, also sets up
    /// match rules for signals. Connect to the #GDBusProxy::g-signal signal
    /// to handle signals from the remote object.
    ///
    /// If both [`DBusProxyFlags::DO_NOT_LOAD_PROPERTIES`][crate::DBusProxyFlags::DO_NOT_LOAD_PROPERTIES] and
    /// [`DBusProxyFlags::DO_NOT_CONNECT_SIGNALS`][crate::DBusProxyFlags::DO_NOT_CONNECT_SIGNALS] are set, this constructor is
    /// guaranteed to complete immediately without blocking.
    ///
    /// If @name is a well-known name and the
    /// [`DBusProxyFlags::DO_NOT_AUTO_START`][crate::DBusProxyFlags::DO_NOT_AUTO_START] and [`DBusProxyFlags::DO_NOT_AUTO_START_AT_CONSTRUCTION`][crate::DBusProxyFlags::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, @callback will be invoked and you can use
    /// g_dbus_proxy_new_finish() to get the result.
    ///
    /// See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
    ///
    /// #GDBusProxy is used in this [example][`DBusProxy`][crate::DBusProxy]#a-watch-proxy-example].
    /// ## `connection`
    /// A #GDBusConnection.
    /// ## `flags`
    /// Flags used when constructing the proxy.
    /// ## `info`
    /// A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or [`None`].
    /// ## `name`
    /// A bus name (well-known or unique) or [`None`] if @connection is not a message bus connection.
    /// ## `object_path`
    /// An object path.
    /// ## `interface_name`
    /// A D-Bus interface name.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    /// ## `callback`
    /// Callback function to invoke when the proxy is ready.
    #[doc(alias = "g_dbus_proxy_new")]
    pub fn new<P: FnOnce(Result<DBusProxy, glib::Error>) + 'static>(
        connection: &DBusConnection,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: Option<&str>,
        object_path: &str,
        interface_name: &str,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn new_trampoline<P: FnOnce(Result<DBusProxy, glib::Error>) + 'static>(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            unsafe {
                let mut error = std::ptr::null_mut();
                let ret = ffi::g_dbus_proxy_new_finish(res, &mut error);
                let result = if error.is_null() {
                    Ok(from_glib_full(ret))
                } else {
                    Err(from_glib_full(error))
                };
                let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                    Box_::from_raw(user_data as *mut _);
                let callback: P = callback.into_inner();
                callback(result);
            }
        }
        let callback = new_trampoline::<P>;
        unsafe {
            ffi::g_dbus_proxy_new(
                connection.to_glib_none().0,
                flags.into_glib(),
                info.to_glib_none().0,
                name.to_glib_none().0,
                object_path.to_glib_none().0,
                interface_name.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn new_future(
        connection: &DBusConnection,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: Option<&str>,
        object_path: &str,
        interface_name: &str,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<DBusProxy, glib::Error>> + 'static>> {
        let connection = connection.clone();
        let info = info.map(ToOwned::to_owned);
        let name = name.map(ToOwned::to_owned);
        let object_path = String::from(object_path);
        let interface_name = String::from(interface_name);
        Box_::pin(crate::GioFuture::new(
            &(),
            move |_obj, cancellable, send| {
                Self::new(
                    &connection,
                    flags,
                    info.as_ref().map(::std::borrow::Borrow::borrow),
                    name.as_ref().map(::std::borrow::Borrow::borrow),
                    &object_path,
                    &interface_name,
                    Some(cancellable),
                    move |res| {
                        send.resolve(res);
                    },
                );
            },
        ))
    }

    /// Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
    ///
    /// #GDBusProxy is used in this [example][`DBusProxy`][crate::DBusProxy]#a-watch-proxy-example].
    /// ## `bus_type`
    /// A #GBusType.
    /// ## `flags`
    /// Flags used when constructing the proxy.
    /// ## `info`
    /// A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or [`None`].
    /// ## `name`
    /// A bus name (well-known or unique).
    /// ## `object_path`
    /// An object path.
    /// ## `interface_name`
    /// A D-Bus interface name.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    /// ## `callback`
    /// Callback function to invoke when the proxy is ready.
    #[doc(alias = "g_dbus_proxy_new_for_bus")]
    #[doc(alias = "new_for_bus")]
    pub fn for_bus<P: FnOnce(Result<DBusProxy, glib::Error>) + 'static>(
        bus_type: BusType,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: &str,
        object_path: &str,
        interface_name: &str,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn for_bus_trampoline<
            P: FnOnce(Result<DBusProxy, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            unsafe {
                let mut error = std::ptr::null_mut();
                let ret = ffi::g_dbus_proxy_new_for_bus_finish(res, &mut error);
                let result = if error.is_null() {
                    Ok(from_glib_full(ret))
                } else {
                    Err(from_glib_full(error))
                };
                let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                    Box_::from_raw(user_data as *mut _);
                let callback: P = callback.into_inner();
                callback(result);
            }
        }
        let callback = for_bus_trampoline::<P>;
        unsafe {
            ffi::g_dbus_proxy_new_for_bus(
                bus_type.into_glib(),
                flags.into_glib(),
                info.to_glib_none().0,
                name.to_glib_none().0,
                object_path.to_glib_none().0,
                interface_name.to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    pub fn for_bus_future(
        bus_type: BusType,
        flags: DBusProxyFlags,
        info: Option<&DBusInterfaceInfo>,
        name: &str,
        object_path: &str,
        interface_name: &str,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<DBusProxy, glib::Error>> + 'static>> {
        let info = info.map(ToOwned::to_owned);
        let name = String::from(name);
        let object_path = String::from(object_path);
        let interface_name = String::from(interface_name);
        Box_::pin(crate::GioFuture::new(
            &(),
            move |_obj, cancellable, send| {
                Self::for_bus(
                    bus_type,
                    flags,
                    info.as_ref().map(::std::borrow::Borrow::borrow),
                    &name,
                    &object_path,
                    &interface_name,
                    Some(cancellable),
                    move |res| {
                        send.resolve(res);
                    },
                );
            },
        ))
    }
}

unsafe impl Send for DBusProxy {}
unsafe impl Sync for DBusProxy {}

/// Trait containing all [`struct@DBusProxy`] methods.
///
/// # Implementors
///
/// [`DBusProxy`][struct@crate::DBusProxy]
pub trait DBusProxyExt: IsA<DBusProxy> + 'static {
    /// data);
    /// ]|
    ///
    /// If @self has an expected interface (see
    /// #GDBusProxy:g-interface-info) and @method_name is referenced by it,
    /// then the return value is checked against the return type.
    ///
    /// This is an asynchronous method. When the operation is finished,
    /// @callback will be invoked in the thread-default main context
    /// (see [`glib::MainContext::push_thread_default()`][crate::glib::MainContext::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 @callback is [`None`] then the D-Bus method call message will be sent with
    /// the [`DBusMessageFlags::NO_REPLY_EXPECTED`][crate::DBusMessageFlags::NO_REPLY_EXPECTED] flag set.
    /// ## `method_name`
    /// Name of method to invoke.
    /// ## `parameters`
    /// A #GVariant tuple with parameters for the signal or [`None`] if not passing parameters.
    /// ## `flags`
    /// Flags from the #GDBusCallFlags enumeration.
    /// ## `timeout_msec`
    /// The timeout in milliseconds (with `G_MAXINT` meaning
    ///                "infinite") or -1 to use the proxy default timeout.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    /// ## `callback`
    /// A #GAsyncReadyCallback to call when the request is satisfied or [`None`] if you don't
    /// care about the result of the method invocation.
    #[doc(alias = "g_dbus_proxy_call")]
    fn call<P: FnOnce(Result<glib::Variant, glib::Error>) + 'static>(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn call_trampoline<
            P: FnOnce(Result<glib::Variant, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            unsafe {
                let mut error = std::ptr::null_mut();
                let ret = ffi::g_dbus_proxy_call_finish(_source_object as *mut _, res, &mut error);
                let result = if error.is_null() {
                    Ok(from_glib_full(ret))
                } else {
                    Err(from_glib_full(error))
                };
                let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                    Box_::from_raw(user_data as *mut _);
                let callback: P = callback.into_inner();
                callback(result);
            }
        }
        let callback = call_trampoline::<P>;
        unsafe {
            ffi::g_dbus_proxy_call(
                self.as_ref().to_glib_none().0,
                method_name.to_glib_none().0,
                parameters.to_glib_none().0,
                flags.into_glib(),
                timeout_msec,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    fn call_future(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<glib::Variant, glib::Error>> + 'static>>
    {
        let method_name = String::from(method_name);
        let parameters = parameters.map(ToOwned::to_owned);
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.call(
                    &method_name,
                    parameters.as_ref().map(::std::borrow::Borrow::borrow),
                    flags,
                    timeout_msec,
                    Some(cancellable),
                    move |res| {
                        send.resolve(res);
                    },
                );
            },
        ))
    }

    /// error);
    /// ]|
    ///
    /// The calling thread is blocked until a reply is received. See
    /// g_dbus_proxy_call() for the asynchronous version of this
    /// method.
    ///
    /// If @self has an expected interface (see
    /// #GDBusProxy:g-interface-info) and @method_name is referenced by it,
    /// then the return value is checked against the return type.
    /// ## `method_name`
    /// Name of method to invoke.
    /// ## `parameters`
    /// A #GVariant tuple with parameters for the signal
    ///              or [`None`] if not passing parameters.
    /// ## `flags`
    /// Flags from the #GDBusCallFlags enumeration.
    /// ## `timeout_msec`
    /// The timeout in milliseconds (with `G_MAXINT` meaning
    ///                "infinite") or -1 to use the proxy default timeout.
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    ///
    /// # Returns
    ///
    /// [`None`] if @error is set. Otherwise a #GVariant tuple with
    /// return values. Free with g_variant_unref().
    #[doc(alias = "g_dbus_proxy_call_sync")]
    fn call_sync(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<glib::Variant, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dbus_proxy_call_sync(
                self.as_ref().to_glib_none().0,
                method_name.to_glib_none().0,
                parameters.to_glib_none().0,
                flags.into_glib(),
                timeout_msec,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
    ///
    /// This method is only available on UNIX.
    /// ## `method_name`
    /// Name of method to invoke.
    /// ## `parameters`
    /// A #GVariant tuple with parameters for the signal or [`None`] if not passing parameters.
    /// ## `flags`
    /// Flags from the #GDBusCallFlags enumeration.
    /// ## `timeout_msec`
    /// The timeout in milliseconds (with `G_MAXINT` meaning
    ///                "infinite") or -1 to use the proxy default timeout.
    /// ## `fd_list`
    /// A #GUnixFDList or [`None`].
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    /// ## `callback`
    /// A #GAsyncReadyCallback to call when the request is satisfied or [`None`] if you don't
    /// care about the result of the method invocation.
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_dbus_proxy_call_with_unix_fd_list")]
    fn call_with_unix_fd_list<
        P: FnOnce(Result<(glib::Variant, Option<UnixFDList>), glib::Error>) + 'static,
    >(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&impl IsA<UnixFDList>>,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn call_with_unix_fd_list_trampoline<
            P: FnOnce(Result<(glib::Variant, Option<UnixFDList>), glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            unsafe {
                let mut error = std::ptr::null_mut();
                let mut out_fd_list = std::ptr::null_mut();
                let ret = ffi::g_dbus_proxy_call_with_unix_fd_list_finish(
                    _source_object as *mut _,
                    &mut out_fd_list,
                    res,
                    &mut error,
                );
                let result = if error.is_null() {
                    Ok((from_glib_full(ret), from_glib_full(out_fd_list)))
                } else {
                    Err(from_glib_full(error))
                };
                let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                    Box_::from_raw(user_data as *mut _);
                let callback: P = callback.into_inner();
                callback(result);
            }
        }
        let callback = call_with_unix_fd_list_trampoline::<P>;
        unsafe {
            ffi::g_dbus_proxy_call_with_unix_fd_list(
                self.as_ref().to_glib_none().0,
                method_name.to_glib_none().0,
                parameters.to_glib_none().0,
                flags.into_glib(),
                timeout_msec,
                fd_list.map(|p| p.as_ref()).to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    fn call_with_unix_fd_list_future(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&(impl IsA<UnixFDList> + Clone + 'static)>,
    ) -> Pin<
        Box_<
            dyn std::future::Future<
                    Output = Result<(glib::Variant, Option<UnixFDList>), glib::Error>,
                > + 'static,
        >,
    > {
        let method_name = String::from(method_name);
        let parameters = parameters.map(ToOwned::to_owned);
        let fd_list = fd_list.map(ToOwned::to_owned);
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.call_with_unix_fd_list(
                    &method_name,
                    parameters.as_ref().map(::std::borrow::Borrow::borrow),
                    flags,
                    timeout_msec,
                    fd_list.as_ref().map(::std::borrow::Borrow::borrow),
                    Some(cancellable),
                    move |res| {
                        send.resolve(res);
                    },
                );
            },
        ))
    }

    /// Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
    ///
    /// This method is only available on UNIX.
    /// ## `method_name`
    /// Name of method to invoke.
    /// ## `parameters`
    /// A #GVariant tuple with parameters for the signal
    ///              or [`None`] if not passing parameters.
    /// ## `flags`
    /// Flags from the #GDBusCallFlags enumeration.
    /// ## `timeout_msec`
    /// The timeout in milliseconds (with `G_MAXINT` meaning
    ///                "infinite") or -1 to use the proxy default timeout.
    /// ## `fd_list`
    /// A #GUnixFDList or [`None`].
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    ///
    /// # Returns
    ///
    /// [`None`] if @error is set. Otherwise a #GVariant tuple with
    /// return values. Free with g_variant_unref().
    ///
    /// ## `out_fd_list`
    /// Return location for a #GUnixFDList or [`None`].
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_dbus_proxy_call_with_unix_fd_list_sync")]
    fn call_with_unix_fd_list_sync(
        &self,
        method_name: &str,
        parameters: Option<&glib::Variant>,
        flags: DBusCallFlags,
        timeout_msec: i32,
        fd_list: Option<&impl IsA<UnixFDList>>,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<(glib::Variant, Option<UnixFDList>), glib::Error> {
        unsafe {
            let mut out_fd_list = std::ptr::null_mut();
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dbus_proxy_call_with_unix_fd_list_sync(
                self.as_ref().to_glib_none().0,
                method_name.to_glib_none().0,
                parameters.to_glib_none().0,
                flags.into_glib(),
                timeout_msec,
                fd_list.map(|p| p.as_ref()).to_glib_none().0,
                &mut out_fd_list,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok((from_glib_full(ret), from_glib_full(out_fd_list)))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Looks up the value for a property from the cache. This call does no
    /// blocking IO.
    ///
    /// If @self has an expected interface (see
    /// #GDBusProxy:g-interface-info) and @property_name is referenced by
    /// it, then @value is checked against the type of the property.
    /// ## `property_name`
    /// Property name.
    ///
    /// # Returns
    ///
    /// A reference to the #GVariant instance
    ///    that holds the value for @property_name or [`None`] if the value is not in
    ///    the cache. The returned reference must be freed with g_variant_unref().
    #[doc(alias = "g_dbus_proxy_get_cached_property")]
    #[doc(alias = "get_cached_property")]
    fn cached_property(&self, property_name: &str) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_dbus_proxy_get_cached_property(
                self.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
            ))
        }
    }

    /// Gets the names of all cached properties on @self.
    ///
    /// # Returns
    ///
    /// A
    ///          [`None`]-terminated array of strings or [`None`] if
    ///          @self has no cached properties. Free the returned array with
    ///          g_strfreev().
    #[doc(alias = "g_dbus_proxy_get_cached_property_names")]
    #[doc(alias = "get_cached_property_names")]
    fn cached_property_names(&self) -> Vec<glib::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_dbus_proxy_get_cached_property_names(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the connection @self is for.
    ///
    /// # Returns
    ///
    /// A #GDBusConnection owned by @self. Do not free.
    #[doc(alias = "g_dbus_proxy_get_connection")]
    #[doc(alias = "get_connection")]
    #[doc(alias = "g-connection")]
    fn connection(&self) -> DBusConnection {
        unsafe {
            from_glib_none(ffi::g_dbus_proxy_get_connection(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the timeout to use if -1 (specifying default timeout) is
    /// passed as @timeout_msec in the g_dbus_proxy_call() and
    /// g_dbus_proxy_call_sync() functions.
    ///
    /// See the #GDBusProxy:g-default-timeout property for more details.
    ///
    /// # Returns
    ///
    /// Timeout to use for @self.
    #[doc(alias = "g_dbus_proxy_get_default_timeout")]
    #[doc(alias = "get_default_timeout")]
    #[doc(alias = "g-default-timeout")]
    fn default_timeout(&self) -> i32 {
        unsafe { ffi::g_dbus_proxy_get_default_timeout(self.as_ref().to_glib_none().0) }
    }

    /// Gets the flags that @self was constructed with.
    ///
    /// # Returns
    ///
    /// Flags from the #GDBusProxyFlags enumeration.
    #[doc(alias = "g_dbus_proxy_get_flags")]
    #[doc(alias = "get_flags")]
    #[doc(alias = "g-flags")]
    fn flags(&self) -> DBusProxyFlags {
        unsafe { from_glib(ffi::g_dbus_proxy_get_flags(self.as_ref().to_glib_none().0)) }
    }

    /// Returns the #GDBusInterfaceInfo, if any, specifying the interface
    /// that @self conforms to. See the #GDBusProxy:g-interface-info
    /// property for more details.
    ///
    /// # Returns
    ///
    /// A #GDBusInterfaceInfo or [`None`].
    ///    Do not unref the returned object, it is owned by @self.
    #[doc(alias = "g_dbus_proxy_get_interface_info")]
    #[doc(alias = "get_interface_info")]
    #[doc(alias = "g-interface-info")]
    fn interface_info(&self) -> Option<DBusInterfaceInfo> {
        unsafe {
            from_glib_none(ffi::g_dbus_proxy_get_interface_info(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the D-Bus interface name @self is for.
    ///
    /// # Returns
    ///
    /// A string owned by @self. Do not free.
    #[doc(alias = "g_dbus_proxy_get_interface_name")]
    #[doc(alias = "get_interface_name")]
    #[doc(alias = "g-interface-name")]
    fn interface_name(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_dbus_proxy_get_interface_name(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the name that @self was constructed for.
    ///
    /// When connected to a message bus, this will usually be non-[`None`].
    /// However, it may be [`None`] for a proxy that communicates using a peer-to-peer
    /// pattern.
    ///
    /// # Returns
    ///
    /// A string owned by @self. Do not free.
    #[doc(alias = "g_dbus_proxy_get_name")]
    #[doc(alias = "get_name")]
    #[doc(alias = "g-name")]
    fn name(&self) -> Option<glib::GString> {
        unsafe { from_glib_none(ffi::g_dbus_proxy_get_name(self.as_ref().to_glib_none().0)) }
    }

    /// The unique name that owns the name that @self is for or [`None`] if
    /// no-one currently owns that name. You may connect to the
    /// #GObject::notify signal to track changes to the
    /// #GDBusProxy:g-name-owner property.
    ///
    /// # Returns
    ///
    /// The name owner or [`None`] if no name
    ///    owner exists. Free with g_free().
    #[doc(alias = "g_dbus_proxy_get_name_owner")]
    #[doc(alias = "get_name_owner")]
    #[doc(alias = "g-name-owner")]
    fn name_owner(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::g_dbus_proxy_get_name_owner(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the object path @self is for.
    ///
    /// # Returns
    ///
    /// A string owned by @self. Do not free.
    #[doc(alias = "g_dbus_proxy_get_object_path")]
    #[doc(alias = "get_object_path")]
    #[doc(alias = "g-object-path")]
    fn object_path(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_dbus_proxy_get_object_path(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    ///
    ///  g_dbus_proxy_set_cached_property (proxy,
    ///                                    "SomeProperty",
    ///                                    g_variant_new ("(si)",
    ///                                                  "A String",
    ///                                                  42));
    /// ]|
    ///
    /// Normally you will not need to use this method since @self
    /// 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)`.
    /// ## `property_name`
    /// Property name.
    /// ## `value`
    /// Value for the property or [`None`] to remove it from the cache.
    #[doc(alias = "g_dbus_proxy_set_cached_property")]
    fn set_cached_property(&self, property_name: &str, value: Option<&glib::Variant>) {
        unsafe {
            ffi::g_dbus_proxy_set_cached_property(
                self.as_ref().to_glib_none().0,
                property_name.to_glib_none().0,
                value.to_glib_none().0,
            );
        }
    }

    /// Sets the timeout to use if -1 (specifying default timeout) is
    /// passed as @timeout_msec in the g_dbus_proxy_call() and
    /// g_dbus_proxy_call_sync() functions.
    ///
    /// See the #GDBusProxy:g-default-timeout property for more details.
    /// ## `timeout_msec`
    /// Timeout in milliseconds.
    #[doc(alias = "g_dbus_proxy_set_default_timeout")]
    #[doc(alias = "g-default-timeout")]
    fn set_default_timeout(&self, timeout_msec: i32) {
        unsafe {
            ffi::g_dbus_proxy_set_default_timeout(self.as_ref().to_glib_none().0, timeout_msec);
        }
    }

    /// Ensure that interactions with @self conform to the given
    /// interface. See the #GDBusProxy:g-interface-info property for more
    /// details.
    /// ## `info`
    /// Minimum interface this proxy conforms to
    ///    or [`None`] to unset.
    #[doc(alias = "g_dbus_proxy_set_interface_info")]
    #[doc(alias = "g-interface-info")]
    fn set_interface_info(&self, info: Option<&DBusInterfaceInfo>) {
        unsafe {
            ffi::g_dbus_proxy_set_interface_info(
                self.as_ref().to_glib_none().0,
                info.to_glib_none().0,
            );
        }
    }

    #[doc(alias = "g-default-timeout")]
    fn connect_g_default_timeout_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_g_default_timeout_trampoline<
            P: IsA<DBusProxy>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GDBusProxy,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(DBusProxy::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::g-default-timeout".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_g_default_timeout_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "g-interface-info")]
    fn connect_g_interface_info_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_g_interface_info_trampoline<
            P: IsA<DBusProxy>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GDBusProxy,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(DBusProxy::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::g-interface-info".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_g_interface_info_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "g-name-owner")]
    fn connect_g_name_owner_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_g_name_owner_trampoline<
            P: IsA<DBusProxy>,
            F: Fn(&P) + Send + Sync + 'static,
        >(
            this: *mut ffi::GDBusProxy,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            unsafe {
                let f: &F = &*(f as *const F);
                f(DBusProxy::from_glib_borrow(this).unsafe_cast_ref())
            }
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::g-name-owner".as_ptr(),
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_g_name_owner_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<DBusProxy>> DBusProxyExt for O {}