// 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::DBusConnection;
use crate::DBusMessage;
use crate::DBusMethodInfo;
use crate::DBusPropertyInfo;
#[cfg(any(unix, feature = "dox"))]
#[cfg_attr(feature = "dox", doc(cfg(unix)))]
use crate::UnixFDList;
#[cfg(any(unix, feature = "dox"))]
#[cfg_attr(feature = "dox", doc(cfg(unix)))]
use glib::object::IsA;
use glib::translate::*;
use std::fmt;

glib::wrapper! {
    /// Instances of the [`DBusMethodInvocation`][crate::DBusMethodInvocation] 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 [`DBusMethodInvocation`][crate::DBusMethodInvocation] object is to receive
    /// it as an argument to the `handle_method_call()` function in a
    /// `GDBusInterfaceVTable` that was passed to `g_dbus_connection_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 [`DBusConnection`][crate::DBusConnection] the method was invoked on.
    ///
    /// # Returns
    ///
    /// A [`DBusConnection`][crate::DBusConnection]. 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.
    ///
    /// 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) -> glib::GString {
        unsafe {
            from_glib_none(ffi::g_dbus_method_invocation_get_interface_name(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the [`DBusMessage`][crate::DBusMessage] 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
    /// [`glib::Variant`][struct@crate::glib::Variant] 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
    ///
    /// [`DBusMessage`][crate::DBusMessage]. 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 [`property_info()`][Self::property_info()] and
    /// `GDBusInterfaceVTable` for more information.
    ///
    /// # Returns
    ///
    /// A [`DBusMethodInfo`][crate::DBusMethodInfo] 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 [`glib::Variant`][struct@crate::glib::Variant] 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 [`DBusPropertyInfo`][crate::DBusPropertyInfo] 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.
    ///
    /// # 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) -> 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.to_glib_full(),
                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 [`glib::Variant`][struct@crate::glib::Variant] 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.to_glib_full(),
                parameters.to_glib_none().0,
            );
        }
    }

    /// Like [`return_value()`][Self::return_value()] but also takes a [`UnixFDList`][crate::UnixFDList].
    ///
    /// 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 [`glib::Variant`][struct@crate::glib::Variant] tuple with out parameters for the method or [`None`] if not passing any parameters.
    /// ## `fd_list`
    /// A [`UnixFDList`][crate::UnixFDList] or [`None`].
    #[cfg(any(unix, feature = "dox"))]
    #[cfg_attr(feature = "dox", 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.to_glib_full(),
                parameters.to_glib_none().0,
                fd_list.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }
}

impl fmt::Display for DBusMethodInvocation {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("DBusMethodInvocation")
    }
}