:right-sidebar: True DBusMethodInvocation =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.26 .. class:: DBusMethodInvocation(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` 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 :obj:`~gi.repository.Gio.DBusInterfaceVTable` that was passed to :obj:`~gi.repository.Gio.DBusConnection.register_object`\. Methods ------- .. rst-class:: interim-class .. class:: DBusMethodInvocation :no-index: .. method:: get_connection() -> ~gi.repository.Gio.DBusConnection Gets the :obj:`~gi.repository.Gio.DBusConnection` the method was invoked on. .. versionadded:: 2.26 .. method:: get_interface_name() -> str 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 :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information. .. versionadded:: 2.26 .. method:: get_message() -> ~gi.repository.Gio.DBusMessage Gets the :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.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. .. versionadded:: 2.26 .. method:: get_method_info() -> ~gi.repository.Gio.DBusMethodInfo | None 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 :const:`None` will be returned. See :func:`~gi.repository.Gio.DBusMethodInvocation.get_property_info` and :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information. .. versionadded:: 2.26 .. method:: get_method_name() -> str Gets the name of the method that was invoked. .. versionadded:: 2.26 .. method:: get_object_path() -> str Gets the object path the method was invoked on. .. versionadded:: 2.26 .. method:: get_parameters() -> ~gi.repository.GLib.Variant 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. .. versionadded:: 2.26 .. method:: get_property_info() -> ~gi.repository.Gio.DBusPropertyInfo | None 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 :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information. If the call was GetAll, :const:`None` will be returned. .. versionadded:: 2.38 .. method:: get_sender() -> str Gets the bus name that invoked the method. .. versionadded:: 2.26 .. method:: return_dbus_error(error_name: str, error_message: str) -> None Finishes handling a D-Bus method call by returning an error. This method will take ownership of ``invocation``\. See :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information about the ownership of ``invocation``\. .. versionadded:: 2.26 :param error_name: A valid D-Bus error name. :param error_message: A valid D-Bus error message. .. method:: return_error_literal(domain: int, code: int, message: str) -> None Like :func:`~gi.repository.Gio.DBusMethodInvocation.return_error` but without printf()-style formatting. This method will take ownership of ``invocation``\. See :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information about the ownership of ``invocation``\. .. versionadded:: 2.26 :param domain: A :obj:`~gi.repository.GLib.Quark` for the :obj:`~gi.repository.GLib.Error` error domain. :param code: The error code. :param message: The error message. .. method:: return_gerror(error: ~gi.repository.GLib.GError) -> None Like :func:`~gi.repository.Gio.DBusMethodInvocation.return_error` but takes a :obj:`~gi.repository.GLib.Error` instead of the error domain, error code and message. This method will take ownership of ``invocation``\. See :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information about the ownership of ``invocation``\. .. versionadded:: 2.26 :param error: A :obj:`~gi.repository.GLib.Error`\. .. method:: return_value(parameters: ~gi.repository.GLib.Variant | None = None) -> None 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 :const:`None` or an empty tuple. .. code-block:: C :dedent: 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 @invocation here; returning a value does that This method will take ownership of ``invocation``\. See :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information about the ownership of ``invocation``\. Since 2.48, if the method call requested for a reply not to be sent then this call will sink ``parameters`` and free ``invocation``\, but otherwise do nothing (as per the recommendations of the D-Bus specification). .. versionadded:: 2.26 :param parameters: A :obj:`~gi.repository.GLib.Variant` tuple with out parameters for the method or :const:`None` if not passing any parameters. .. method:: return_value_with_unix_fd_list(parameters: ~gi.repository.GLib.Variant | None = None, fd_list: ~gi.repository.Gio.UnixFDList | None = None) -> None Like :func:`~gi.repository.Gio.DBusMethodInvocation.return_value` but also takes a :obj:`~gi.repository.Gio.UnixFDList`\. This method is only available on UNIX. This method will take ownership of ``invocation``\. See :obj:`~gi.repository.Gio.DBusInterfaceVTable` for more information about the ownership of ``invocation``\. .. versionadded:: 2.30 :param parameters: A :obj:`~gi.repository.GLib.Variant` tuple with out parameters for the method or :const:`None` if not passing any parameters. :param fd_list: A :obj:`~gi.repository.Gio.UnixFDList` or :const:`None`.