gio/auto/

dbus_method_invocation.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::{ffi, DBusConnection, DBusMessage, DBusMethodInfo, DBusPropertyInfo};
#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
use glib::prelude::*;
use glib::translate::*;

glib::wrapper! {
    /// Instances of the `GDBusMethodInvocation` class are used when
    /// handling D-Bus method calls. It provides a way to asynchronously
    /// return results and errors.
    ///
    /// The normal way to obtain a `GDBusMethodInvocation` object is to receive
    /// it as an argument to the `handle_method_call()` function in a
    /// [type@Gio.DBusInterfaceVTable] that was passed to
    /// [`DBusConnection::register_object()`][crate::DBusConnection::register_object()].
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GDBusMethodInvocation")]
    pub struct DBusMethodInvocation(Object<ffi::GDBusMethodInvocation>);

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

impl DBusMethodInvocation {
    /// Gets the #GDBusConnection the method was invoked on.
    ///
    /// # Returns
    ///
    /// A #GDBusConnection. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_connection")]
    #[doc(alias = "get_connection")]
    pub fn connection(&self) -> DBusConnection {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_connection(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the name of the D-Bus interface the method was invoked on.
    ///
    /// This can be `NULL` if it was not specified by the sender. See
    /// `callback::Gio::DBusInterfaceMethodCallFunc or the
    /// [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method)
    /// for details on when this can happen and how it should be handled.
    ///
    /// If this method call is a property Get, Set or GetAll call that has
    /// been redirected to the method call handler then
    /// "org.freedesktop.DBus.Properties" will be returned.  See
    /// #GDBusInterfaceVTable for more information.
    ///
    /// # Returns
    ///
    /// A string. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_interface_name")]
    #[doc(alias = "get_interface_name")]
    pub fn interface_name(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_interface_name(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the #GDBusMessage for the method invocation. This is useful if
    /// you need to use low-level protocol features, such as UNIX file
    /// descriptor passing, that cannot be properly expressed in the
    /// #GVariant API.
    ///
    /// See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
    /// for an example of how to use this low-level API to send and receive
    /// UNIX file descriptors.
    ///
    /// # Returns
    ///
    /// #GDBusMessage. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_message")]
    #[doc(alias = "get_message")]
    pub fn message(&self) -> DBusMessage {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_message(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets information about the method call, if any.
    ///
    /// If this method invocation is a property Get, Set or GetAll call that
    /// has been redirected to the method call handler then [`None`] will be
    /// returned.  See g_dbus_method_invocation_get_property_info() and
    /// #GDBusInterfaceVTable for more information.
    ///
    /// # Returns
    ///
    /// A #GDBusMethodInfo or [`None`]. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_method_info")]
    #[doc(alias = "get_method_info")]
    pub fn method_info(&self) -> Option<DBusMethodInfo> {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_method_info(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the name of the method that was invoked.
    ///
    /// # Returns
    ///
    /// A string. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_method_name")]
    #[doc(alias = "get_method_name")]
    pub fn method_name(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_method_name(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the object path the method was invoked on.
    ///
    /// # Returns
    ///
    /// A string. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_object_path")]
    #[doc(alias = "get_object_path")]
    pub fn object_path(&self) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_object_path(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the parameters of the method invocation. If there are no input
    /// parameters then this will return a GVariant with 0 children rather than NULL.
    ///
    /// # Returns
    ///
    /// A #GVariant tuple. Do not unref this because it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_parameters")]
    #[doc(alias = "get_parameters")]
    pub fn parameters(&self) -> glib::Variant {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_parameters(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets information about the property that this method call is for, if
    /// any.
    ///
    /// This will only be set in the case of an invocation in response to a
    /// property Get or Set call that has been directed to the method call
    /// handler for an object on account of its property_get() or
    /// property_set() vtable pointers being unset.
    ///
    /// See #GDBusInterfaceVTable for more information.
    ///
    /// If the call was GetAll, [`None`] will be returned.
    ///
    /// # Returns
    ///
    /// a #GDBusPropertyInfo or [`None`]
    #[doc(alias = "g_dbus_method_invocation_get_property_info")]
    #[doc(alias = "get_property_info")]
    pub fn property_info(&self) -> Option<DBusPropertyInfo> {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_property_info(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the bus name that invoked the method.
    ///
    /// This can return [`None`] if not specified by the caller, e.g. on peer-to-peer
    /// connections.
    ///
    /// # Returns
    ///
    /// A string. Do not free, it is owned by @self.
    #[doc(alias = "g_dbus_method_invocation_get_sender")]
    #[doc(alias = "get_sender")]
    pub fn sender(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_sender(
                self.to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "g_dbus_method_invocation_get_user_data")]
    //#[doc(alias = "get_user_data")]
    //pub fn user_data(&self) -> /*Unimplemented*/Option<Basic: Pointer> {
    //    unsafe { TODO: call ffi:g_dbus_method_invocation_get_user_data() }
    //}

    /// Finishes handling a D-Bus method call by returning an error.
    ///
    /// This method will take ownership of @self. See
    /// #GDBusInterfaceVTable for more information about the ownership of
    /// @self.
    /// ## `error_name`
    /// A valid D-Bus error name.
    /// ## `error_message`
    /// A valid D-Bus error message.
    #[doc(alias = "g_dbus_method_invocation_return_dbus_error")]
    pub fn return_dbus_error(self, error_name: &str, error_message: &str) {
        unsafe {
            ffi::g_dbus_method_invocation_return_dbus_error(
                self.into_glib_ptr(),
                error_name.to_glib_none().0,
                error_message.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_dbus_method_invocation_return_error")]
    //pub fn return_error(self, domain: glib::Quark, code: i32, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_dbus_method_invocation_return_error() }
    //}

    //#[doc(alias = "g_dbus_method_invocation_return_error_valist")]
    //pub fn return_error_valist(self, domain: glib::Quark, code: i32, format: &str, var_args: /*Unknown conversion*//*Unimplemented*/Unsupported) {
    //    unsafe { TODO: call ffi:g_dbus_method_invocation_return_error_valist() }
    //}

    /// Finishes handling a D-Bus method call by returning @parameters.
    /// If the @parameters GVariant is floating, it is consumed.
    ///
    /// It is an error if @parameters is not of the right format: it must be a tuple
    /// containing the out-parameters of the D-Bus method. Even if the method has a
    /// single out-parameter, it must be contained in a tuple. If the method has no
    /// out-parameters, @parameters may be [`None`] or an empty tuple.
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// GDBusMethodInvocation *invocation = some_invocation;
    /// g_autofree gchar *result_string = NULL;
    /// g_autoptr (GError) error = NULL;
    ///
    /// result_string = calculate_result (&error);
    ///
    /// if (error != NULL)
    ///   g_dbus_method_invocation_return_gerror (invocation, error);
    /// else
    ///   g_dbus_method_invocation_return_value (invocation,
    ///                                          g_variant_new ("(s)", result_string));
    ///
    /// // Do not free @self here; returning a value does that
    /// ```
    ///
    /// This method will take ownership of @self. See
    /// #GDBusInterfaceVTable for more information about the ownership of
    /// @self.
    ///
    /// Since 2.48, if the method call requested for a reply not to be sent
    /// then this call will sink @parameters and free @self, but
    /// otherwise do nothing (as per the recommendations of the D-Bus
    /// specification).
    /// ## `parameters`
    /// A #GVariant tuple with out parameters for the method or [`None`] if not passing any parameters.
    #[doc(alias = "g_dbus_method_invocation_return_value")]
    pub fn return_value(self, parameters: Option<&glib::Variant>) {
        unsafe {
            ffi::g_dbus_method_invocation_return_value(
                self.into_glib_ptr(),
                parameters.to_glib_none().0,
            );
        }
    }

    /// Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
    ///
    /// This method is only available on UNIX.
    ///
    /// This method will take ownership of @self. See
    /// #GDBusInterfaceVTable for more information about the ownership of
    /// @self.
    /// ## `parameters`
    /// A #GVariant tuple with out parameters for the method or [`None`] if not passing any parameters.
    /// ## `fd_list`
    /// A #GUnixFDList or [`None`].
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_dbus_method_invocation_return_value_with_unix_fd_list")]
    pub fn return_value_with_unix_fd_list(
        self,
        parameters: Option<&glib::Variant>,
        fd_list: Option<&impl IsA<UnixFDList>>,
    ) {
        unsafe {
            ffi::g_dbus_method_invocation_return_value_with_unix_fd_list(
                self.into_glib_ptr(),
                parameters.to_glib_none().0,
                fd_list.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }
}