Gio.DBusMethodInvocation¶

class — extends 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 DBusInterfaceVTable that was passed to DBusConnection.register_object.

Methods¶

get_connection¶

def get_connection(self) -> DBusConnection

Gets the DBusConnection the method was invoked on.

get_interface_name¶

def get_interface_name(self) -> str | None

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 DBusInterfaceMethodCallFunc or the D-Bus Specification 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 DBusInterfaceVTable for more information.

get_message¶

def get_message(self) -> DBusMessage

Gets the 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 API.

See this [server][classGio.DBusConnection#an-example-d-bus-server] and [client][classGio.DBusConnection#an-example-for-file-descriptor-passing] for an example of how to use this low-level API to send and receive UNIX file descriptors.

get_method_info¶

def get_method_info(self) -> 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 None will be returned. See DBusMethodInvocation.get_property_info and DBusInterfaceVTable for more information.

get_method_name¶

def get_method_name(self) -> str

Gets the name of the method that was invoked.

get_object_path¶

def get_object_path(self) -> str

Gets the object path the method was invoked on.

get_parameters¶

def get_parameters(self) -> 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.

get_property_info¶

def get_property_info(self) -> 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 DBusInterfaceVTable for more information.

If the call was GetAll, None will be returned.

get_sender¶

def get_sender(self) -> str | None

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.

return_dbus_error¶

def return_dbus_error(self, 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 DBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

error_name — A valid D-Bus error name.
error_message — A valid D-Bus error message.

return_error_literal¶

def return_error_literal(self, domain: GLib.Quark, code: int, message: str) -> None

Like g_dbus_method_invocation_return_error() but without printf()-style formatting.

This method will take ownership of invocation. See DBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

domain — A GQuark for the GLib.Error error domain.
code — The error code.
message — The error message.

return_gerror¶

def return_gerror(self, error: GLib.Error) -> None

Like g_dbus_method_invocation_return_error() but takes a GLib.Error instead of the error domain, error code and message.

This method will take ownership of invocation. See DBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

error — A GLib.Error.

return_value¶

def return_value(self, parameters: GLib.Variant | 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 None or an empty tuple.

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

Parameters:

parameters — A GLib.Variant tuple with out parameters for the method or None if not passing any parameters.

return_value_with_unix_fd_list¶

def return_value_with_unix_fd_list(self, parameters: GLib.Variant | None = ..., fd_list: UnixFDList | None = ...) -> None

Like DBusMethodInvocation.return_value but also takes a UnixFDList.

This method is only available on UNIX.

This method will take ownership of invocation. See DBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

parameters — A GLib.Variant tuple with out parameters for the method or None if not passing any parameters.
fd_list — A UnixFDList or None.