gio/

dbus.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use std::num::NonZeroU32;

use glib::translate::*;

use crate::{ffi, BusNameOwnerFlags, BusNameWatcherFlags, BusType, DBusConnection};

#[derive(Debug, Eq, PartialEq)]
pub struct OwnerId(NonZeroU32);
#[derive(Debug, Eq, PartialEq)]
pub struct WatcherId(NonZeroU32);

fn own_closure<F>(f: F) -> glib::Closure
where
    F: Fn(DBusConnection, &str) + 'static,
{
    glib::Closure::new_local(move |args| {
        let conn = args[0].get::<DBusConnection>().unwrap();
        let name = args[1].get::<&str>().unwrap();
        f(conn, name);
        None
    })
}

fn appeared_closure<F>(f: F) -> glib::Closure
where
    F: Fn(DBusConnection, &str, &str) + 'static,
{
    glib::Closure::new_local(move |args| {
        let conn = args[0].get::<DBusConnection>().unwrap();
        let name = args[1].get::<&str>().unwrap();
        let name_owner = args[2].get::<&str>().unwrap();
        f(conn, name, name_owner);
        None
    })
}

fn vanished_closure<F>(f: F) -> glib::Closure
where
    F: Fn(DBusConnection, &str) + 'static,
{
    glib::Closure::new_local(move |args| {
        let conn = args[0].get::<DBusConnection>().unwrap();
        let name = args[1].get::<&str>().unwrap();
        f(conn, name);
        None
    })
}

/// Like `bus_own_name()` but takes a [`DBusConnection`][crate::DBusConnection] instead
/// of a [`BusType`][crate::BusType].
/// ## `connection`
/// a bus connection
/// ## `name`
/// the well-known name to own
/// ## `flags`
/// a set of flags with ownership options
/// ## `name_acquired_handler`
/// handler to invoke when
///   @name is acquired, or `NULL` to ignore
/// ## `name_lost_handler`
/// handler to invoke when @name
///   is lost, or `NULL` to ignore
///
/// # Returns
///
/// an identifier (never 0) that can be used with
///   `bus_unown_name()` to stop owning the name
#[doc(alias = "g_bus_own_name_on_connection_with_closures")]
pub fn bus_own_name_on_connection<NameAcquired, NameLost>(
    connection: &DBusConnection,
    name: &str,
    flags: BusNameOwnerFlags,
    name_acquired: NameAcquired,
    name_lost: NameLost,
) -> OwnerId
where
    NameAcquired: Fn(DBusConnection, &str) + 'static,
    NameLost: Fn(DBusConnection, &str) + 'static,
{
    unsafe {
        let id = ffi::g_bus_own_name_on_connection_with_closures(
            connection.to_glib_none().0,
            name.to_glib_none().0,
            flags.into_glib(),
            own_closure(name_acquired).to_glib_none().0,
            own_closure(name_lost).to_glib_none().0,
        );
        OwnerId(NonZeroU32::new_unchecked(id))
    }
}

/// Requests ownership of @name on the bus specified by @bus_type.
///
/// It asynchronously calls @name_acquired_handler and @name_lost_handler when
/// the name is acquired and lost, respectively.
///
/// Callbacks 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 function from.
///
/// You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
/// callbacks will be invoked after calling this function — there are three
/// possible cases:
///
/// - @name_lost_handler with a `NULL` connection (if a connection to the bus
///   can’t be made).
/// - @bus_acquired_handler then @name_lost_handler (if the name can’t be
///   obtained).
/// - @bus_acquired_handler then @name_acquired_handler (if the name was
///   obtained).
///
/// When you are done owning the name, call `bus_unown_name()` with the
/// owner ID this function returns.
///
/// If the name is acquired or lost (for example another application
/// could acquire the name if you allow replacement or the application
/// currently owning the name exits), the handlers are also invoked.
/// If the [`DBusConnection`][crate::DBusConnection] that is used for attempting to own the name
/// closes, then @name_lost_handler is invoked since it is no longer
/// possible for other processes to access the process.
///
/// You cannot use `bus_own_name()` several times for the same name (unless
/// interleaved with calls to `bus_unown_name()`) — only the first call
/// will work.
///
/// Another guarantee is that invocations of @name_acquired_handler
/// and @name_lost_handler are guaranteed to alternate; that
/// is, if @name_acquired_handler is invoked then you are
/// guaranteed that the next time one of the handlers is invoked, it
/// will be @name_lost_handler. The reverse is also true.
///
/// If you plan on exporting objects (using, for example,
/// [`DBusConnection::register_object()`][crate::DBusConnection::register_object()]), note that it is generally too late
/// to export the objects in @name_acquired_handler. Instead, you can do this
/// in @bus_acquired_handler since you are guaranteed that this will run
/// before @name is requested from the bus.
///
/// This behavior makes it very simple to write applications that want
/// to [own names](dbus-name-owning.html#d-bus-name-owning) and export objects.
/// Simply register objects to be exported in @bus_acquired_handler and
/// unregister the objects (if any) in @name_lost_handler.
/// ## `bus_type`
/// the type of bus to own a name on
/// ## `name`
/// the well-known name to own
/// ## `flags`
/// a set of flags with ownership options
/// ## `bus_acquired_handler`
/// handler to invoke when
///   connected to the bus of type @bus_type, or `NULL` to ignore
/// ## `name_acquired_handler`
/// handler to invoke when
///   @name is acquired, or `NULL` to ignore
/// ## `name_lost_handler`
/// handler to invoke when @name
///   is lost, or `NULL` to ignore
///
/// # Returns
///
/// an identifier (never 0) that can be used with
///   `bus_unown_name()` to stop owning the name
#[doc(alias = "g_bus_own_name_with_closures")]
pub fn bus_own_name<BusAcquired, NameAcquired, NameLost>(
    bus_type: BusType,
    name: &str,
    flags: BusNameOwnerFlags,
    bus_acquired: BusAcquired,
    name_acquired: NameAcquired,
    name_lost: NameLost,
) -> OwnerId
where
    BusAcquired: Fn(DBusConnection, &str) + 'static,
    NameAcquired: Fn(DBusConnection, &str) + 'static,
    NameLost: Fn(Option<DBusConnection>, &str) + 'static,
{
    unsafe {
        let id = ffi::g_bus_own_name_with_closures(
            bus_type.into_glib(),
            name.to_glib_none().0,
            flags.into_glib(),
            own_closure(bus_acquired).to_glib_none().0,
            own_closure(name_acquired).to_glib_none().0,
            glib::Closure::new_local(move |args| {
                let conn = args[0].get::<Option<DBusConnection>>().unwrap();
                let name = args[1].get::<&str>().unwrap();
                name_lost(conn, name);
                None
            })
            .to_glib_none()
            .0,
        );
        OwnerId(NonZeroU32::new_unchecked(id))
    }
}

#[doc(alias = "g_bus_unown_name")]
pub fn bus_unown_name(owner_id: OwnerId) {
    unsafe {
        ffi::g_bus_unown_name(owner_id.0.into());
    }
}

/// Like g_bus_watch_name() but takes a #GDBusConnection instead of a
/// #GBusType.
/// ## `connection`
/// A #GDBusConnection.
/// ## `name`
/// The name (well-known or unique) to watch.
/// ## `flags`
/// Flags from the #GBusNameWatcherFlags enumeration.
/// ## `name_appeared_handler`
/// Handler to invoke when
///   @name is known to exist or [`None`].
/// ## `name_vanished_handler`
/// Handler to invoke when
///   @name is known to not exist or [`None`].
///
/// # Returns
///
/// An identifier (never 0) that can be used with
/// g_bus_unwatch_name() to stop watching the name.
#[doc(alias = "g_bus_watch_name_on_connection_with_closures")]
pub fn bus_watch_name_on_connection<NameAppeared, NameVanished>(
    connection: &DBusConnection,
    name: &str,
    flags: BusNameWatcherFlags,
    name_appeared: NameAppeared,
    name_vanished: NameVanished,
) -> WatcherId
where
    NameAppeared: Fn(DBusConnection, &str, &str) + 'static,
    NameVanished: Fn(DBusConnection, &str) + 'static,
{
    unsafe {
        let id = ffi::g_bus_watch_name_on_connection_with_closures(
            connection.to_glib_none().0,
            name.to_glib_none().0,
            flags.into_glib(),
            appeared_closure(name_appeared).to_glib_none().0,
            vanished_closure(name_vanished).to_glib_none().0,
        );
        WatcherId(NonZeroU32::new_unchecked(id))
    }
}

/// Starts watching @name on the bus specified by @bus_type and calls
/// @name_appeared_handler and @name_vanished_handler when the name is
/// known to have an owner respectively known to lose its
/// owner. Callbacks 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 function from.
///
/// You are guaranteed that one of the handlers will be invoked after
/// calling this function. When you are done watching the name, just
/// call g_bus_unwatch_name() with the watcher id this function
/// returns.
///
/// If the name vanishes or appears (for example the application owning
/// the name could restart), the handlers are also invoked. If the
/// #GDBusConnection that is used for watching the name disconnects, then
/// @name_vanished_handler is invoked since it is no longer
/// possible to access the name.
///
/// Another guarantee is that invocations of @name_appeared_handler
/// and @name_vanished_handler are guaranteed to alternate; that
/// is, if @name_appeared_handler is invoked then you are
/// guaranteed that the next time one of the handlers is invoked, it
/// will be @name_vanished_handler. The reverse is also true.
///
/// This behavior makes it very simple to write applications that want
/// to take action when a certain [name exists](dbus-name-watching.html#d-bus-name-watching).
/// Basically, the application should create object proxies in
/// @name_appeared_handler and destroy them again (if any) in
/// @name_vanished_handler.
/// ## `bus_type`
/// The type of bus to watch a name on.
/// ## `name`
/// The name (well-known or unique) to watch.
/// ## `flags`
/// Flags from the #GBusNameWatcherFlags enumeration.
/// ## `name_appeared_handler`
/// Handler to invoke when
///   @name is known to exist or [`None`].
/// ## `name_vanished_handler`
/// Handler to invoke when
///   @name is known to not exist or [`None`].
///
/// # Returns
///
/// An identifier (never 0) that can be used with
/// g_bus_unwatch_name() to stop watching the name.
#[doc(alias = "g_bus_watch_name_with_closures")]
pub fn bus_watch_name<NameAppeared, NameVanished>(
    bus_type: BusType,
    name: &str,
    flags: BusNameWatcherFlags,
    name_appeared: NameAppeared,
    name_vanished: NameVanished,
) -> WatcherId
where
    NameAppeared: Fn(DBusConnection, &str, &str) + 'static,
    NameVanished: Fn(DBusConnection, &str) + 'static,
{
    unsafe {
        let id = ffi::g_bus_watch_name_with_closures(
            bus_type.into_glib(),
            name.to_glib_none().0,
            flags.into_glib(),
            appeared_closure(name_appeared).to_glib_none().0,
            vanished_closure(name_vanished).to_glib_none().0,
        );
        WatcherId(NonZeroU32::new_unchecked(id))
    }
}

#[doc(alias = "g_bus_unwatch_name")]
pub fn bus_unwatch_name(watcher_id: WatcherId) {
    unsafe {
        ffi::g_bus_unwatch_name(watcher_id.0.into());
    }
}