gio/auto/

dbus_server.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

use crate::{ffi, Cancellable, DBusAuthObserver, DBusConnection, DBusServerFlags, Initable};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GDBusServer` is a helper for listening to and accepting D-Bus
    /// connections. This can be used to create a new D-Bus server, allowing two
    /// peers to use the D-Bus protocol for their own specialized communication.
    /// A server instance provided in this way will not perform message routing or
    /// implement the
    /// [`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages).
    ///
    /// To just export an object on a well-known name on a message bus, such as the
    /// session or system bus, you should instead use `bus_own_name()`.
    ///
    /// An example of peer-to-peer communication with GDBus can be found
    /// in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
    ///
    /// Note that a minimal `GDBusServer` will accept connections from any
    /// peer. In many use-cases it will be necessary to add a
    /// [`DBusAuthObserver`][crate::DBusAuthObserver] that only accepts connections that have
    /// successfully authenticated as the same user that is running the
    /// `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing
    /// the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the
    /// server.
    ///
    /// ## Properties
    ///
    ///
    /// #### `active`
    ///  Whether the server is currently active.
    ///
    /// Readable
    ///
    ///
    /// #### `address`
    ///  The D-Bus address to listen on.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `authentication-observer`
    ///  A #GDBusAuthObserver object to assist in the authentication process or [`None`].
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `client-address`
    ///  The D-Bus address that clients can use.
    ///
    /// Readable
    ///
    ///
    /// #### `flags`
    ///  Flags from the #GDBusServerFlags enumeration.
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `guid`
    ///  The GUID of the server.
    ///
    /// See #GDBusConnection:guid for more details.
    ///
    /// Readable | Writeable | Construct Only
    ///
    /// ## Signals
    ///
    ///
    /// #### `new-connection`
    ///  Emitted when a new authenticated connection has been made. Use
    /// g_dbus_connection_get_peer_credentials() to figure out what
    /// identity (if any), was authenticated.
    ///
    /// If you want to accept the connection, take a reference to the
    /// @connection object and return [`true`]. When you are done with the
    /// connection call g_dbus_connection_close() and give up your
    /// reference. Note that the other peer may disconnect at any time -
    /// a typical thing to do when accepting a connection is to listen to
    /// the #GDBusConnection::closed signal.
    ///
    /// If #GDBusServer:flags contains [`DBusServerFlags::RUN_IN_THREAD`][crate::DBusServerFlags::RUN_IN_THREAD]
    /// then the signal is emitted in a new thread dedicated to the
    /// connection. Otherwise the signal is emitted in the
    /// [thread-default main context][g-main-context-push-thread-default]
    /// of the thread that @server was constructed in.
    ///
    /// You are guaranteed that signal handlers for this signal runs
    /// before incoming messages on @connection are processed. This means
    /// that it's suitable to call g_dbus_connection_register_object() or
    /// similar from the signal handler.
    ///
    ///
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`], [`InitableExt`][trait@crate::prelude::InitableExt]
    #[doc(alias = "GDBusServer")]
    pub struct DBusServer(Object<ffi::GDBusServer>) @implements Initable;

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

impl DBusServer {
    /// Creates a new D-Bus server that listens on the first address in
    /// @address that works.
    ///
    /// Once constructed, you can use g_dbus_server_get_client_address() to
    /// get a D-Bus address string that clients can use to connect.
    ///
    /// To have control over the available authentication mechanisms and
    /// the users that are authorized to connect, it is strongly recommended
    /// to provide a non-[`None`] #GDBusAuthObserver.
    ///
    /// Connect to the #GDBusServer::new-connection signal to handle
    /// incoming connections.
    ///
    /// The returned #GDBusServer isn't active - you have to start it with
    /// g_dbus_server_start().
    ///
    /// #GDBusServer is used in this [example][gdbus-peer-to-peer].
    ///
    /// This is a synchronous failable constructor. There is currently no
    /// asynchronous version.
    /// ## `address`
    /// A D-Bus address.
    /// ## `flags`
    /// Flags from the #GDBusServerFlags enumeration.
    /// ## `guid`
    /// A D-Bus GUID.
    /// ## `observer`
    /// A #GDBusAuthObserver or [`None`].
    /// ## `cancellable`
    /// A #GCancellable or [`None`].
    ///
    /// # Returns
    ///
    /// A #GDBusServer or [`None`] if @error is set. Free with
    /// g_object_unref().
    #[doc(alias = "g_dbus_server_new_sync")]
    pub fn new_sync(
        address: &str,
        flags: DBusServerFlags,
        guid: &str,
        observer: Option<&DBusAuthObserver>,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<DBusServer, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_dbus_server_new_sync(
                address.to_glib_none().0,
                flags.into_glib(),
                guid.to_glib_none().0,
                observer.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))
            }
        }
    }

    /// Gets a
    /// [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
    /// string that can be used by clients to connect to @self.
    ///
    /// This is valid and non-empty if initializing the #GDBusServer succeeded.
    ///
    /// # Returns
    ///
    /// A D-Bus address string. Do not free, the string is owned
    /// by @self.
    #[doc(alias = "g_dbus_server_get_client_address")]
    #[doc(alias = "get_client_address")]
    #[doc(alias = "client-address")]
    pub fn client_address(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::g_dbus_server_get_client_address(self.to_glib_none().0)) }
    }

    /// Gets the flags for @self.
    ///
    /// # Returns
    ///
    /// A set of flags from the #GDBusServerFlags enumeration.
    #[doc(alias = "g_dbus_server_get_flags")]
    #[doc(alias = "get_flags")]
    pub fn flags(&self) -> DBusServerFlags {
        unsafe { from_glib(ffi::g_dbus_server_get_flags(self.to_glib_none().0)) }
    }

    /// Gets the GUID for @self, as provided to g_dbus_server_new_sync().
    ///
    /// # Returns
    ///
    /// A D-Bus GUID. Do not free this string, it is owned by @self.
    #[doc(alias = "g_dbus_server_get_guid")]
    #[doc(alias = "get_guid")]
    pub fn guid(&self) -> glib::GString {
        unsafe { from_glib_none(ffi::g_dbus_server_get_guid(self.to_glib_none().0)) }
    }

    /// Gets whether @self is active.
    ///
    /// # Returns
    ///
    /// [`true`] if server is active, [`false`] otherwise.
    #[doc(alias = "g_dbus_server_is_active")]
    #[doc(alias = "active")]
    pub fn is_active(&self) -> bool {
        unsafe { from_glib(ffi::g_dbus_server_is_active(self.to_glib_none().0)) }
    }

    /// Starts @self.
    #[doc(alias = "g_dbus_server_start")]
    pub fn start(&self) {
        unsafe {
            ffi::g_dbus_server_start(self.to_glib_none().0);
        }
    }

    /// Stops @self.
    #[doc(alias = "g_dbus_server_stop")]
    pub fn stop(&self) {
        unsafe {
            ffi::g_dbus_server_stop(self.to_glib_none().0);
        }
    }

    /// The D-Bus address to listen on.
    pub fn address(&self) -> Option<glib::GString> {
        ObjectExt::property(self, "address")
    }

    /// A #GDBusAuthObserver object to assist in the authentication process or [`None`].
    #[doc(alias = "authentication-observer")]
    pub fn authentication_observer(&self) -> Option<DBusAuthObserver> {
        ObjectExt::property(self, "authentication-observer")
    }

    /// Emitted when a new authenticated connection has been made. Use
    /// g_dbus_connection_get_peer_credentials() to figure out what
    /// identity (if any), was authenticated.
    ///
    /// If you want to accept the connection, take a reference to the
    /// @connection object and return [`true`]. When you are done with the
    /// connection call g_dbus_connection_close() and give up your
    /// reference. Note that the other peer may disconnect at any time -
    /// a typical thing to do when accepting a connection is to listen to
    /// the #GDBusConnection::closed signal.
    ///
    /// If #GDBusServer:flags contains [`DBusServerFlags::RUN_IN_THREAD`][crate::DBusServerFlags::RUN_IN_THREAD]
    /// then the signal is emitted in a new thread dedicated to the
    /// connection. Otherwise the signal is emitted in the
    /// [thread-default main context][g-main-context-push-thread-default]
    /// of the thread that @server was constructed in.
    ///
    /// You are guaranteed that signal handlers for this signal runs
    /// before incoming messages on @connection are processed. This means
    /// that it's suitable to call g_dbus_connection_register_object() or
    /// similar from the signal handler.
    /// ## `connection`
    /// A #GDBusConnection for the new connection.
    ///
    /// # Returns
    ///
    /// [`true`] to claim @connection, [`false`] to let other handlers
    /// run.
    #[doc(alias = "new-connection")]
    pub fn connect_new_connection<F: Fn(&Self, &DBusConnection) -> bool + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn new_connection_trampoline<
            F: Fn(&DBusServer, &DBusConnection) -> bool + 'static,
        >(
            this: *mut ffi::GDBusServer,
            connection: *mut ffi::GDBusConnection,
            f: glib::ffi::gpointer,
        ) -> glib::ffi::gboolean {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this), &from_glib_borrow(connection)).into_glib()
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"new-connection".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    new_connection_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "active")]
    pub fn connect_active_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_active_trampoline<F: Fn(&DBusServer) + 'static>(
            this: *mut ffi::GDBusServer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::active".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_active_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }

    #[doc(alias = "client-address")]
    pub fn connect_client_address_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_client_address_trampoline<F: Fn(&DBusServer) + 'static>(
            this: *mut ffi::GDBusServer,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::client-address".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_client_address_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}