DBusMethodInvocation

Added in version 2.26.

class DBusMethodInvocation(**properties: Any)

Superclasses: 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 register_object.

Methods

class DBusMethodInvocation

get_connection() → DBusConnection: Gets the DBusConnection the method was invoked on.

Added in version 2.26.

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 DBusInterfaceVTable for more information.

Added in version 2.26.

get_message() → 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 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.

Added in version 2.26.

get_method_info() → 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 get_property_info() and DBusInterfaceVTable for more information.

Added in version 2.26.

get_method_name() → str: Gets the name of the method that was invoked.

Added in version 2.26.

get_object_path() → str: Gets the object path the method was invoked on.

Added in version 2.26.

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

Added in version 2.26.

get_property_info() → 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.

Added in version 2.38.

get_sender() → str: Gets the bus name that invoked the method.

Added in version 2.26.

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 DBusInterfaceVTable for more information about the ownership of invocation.

Added in version 2.26.

Parameters:

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

return_error_literal(domain: int, code: int, message: str) → None

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

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

Added in version 2.26.

Parameters:

domain – A Quark for the Error error domain.
code – The error code.
message – The error message.

return_gerror(error: GError) → None

Like return_error() but takes a 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.

Added in version 2.26.

Parameters:: error – A Error.

return_value(parameters: 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 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).

Added in version 2.26.

Parameters:: parameters – A Variant tuple with out parameters for the method or None if not passing any parameters.

return_value_with_unix_fd_list(parameters: Variant | None = None, fd_list: UnixFDList | None = None) → None

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

Added in version 2.30.

Parameters:

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