DBusMethodInvocation#
Added in version 2.26.
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 theVariant
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. Seeget_property_info()
andDBusInterfaceVTable
for more information.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.
- 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
. SeeDBusInterfaceVTable
for more information about the ownership ofinvocation
.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
. SeeDBusInterfaceVTable
for more information about the ownership ofinvocation
.Added in version 2.26.
- Parameters:
domain – A
Quark
for theError
error domain.code – The error code.
message – The error message.
- return_gerror(error: GError) None #
Like
return_error()
but takes aError
instead of the error domain, error code and message.This method will take ownership of
invocation
. SeeDBusInterfaceVTable
for more information about the ownership ofinvocation
.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 theparameters
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 beNone
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
. SeeDBusInterfaceVTable
for more information about the ownership ofinvocation
.Since 2.48, if the method call requested for a reply not to be sent then this call will sink
parameters
and freeinvocation
, 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 orNone
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 aUnixFDList
.This method is only available on UNIX.
This method will take ownership of
invocation
. SeeDBusInterfaceVTable
for more information about the ownership ofinvocation
.Added in version 2.30.
- Parameters:
parameters – A
Variant
tuple with out parameters for the method orNone
if not passing any parameters.fd_list – A
UnixFDList
orNone
.