GI.Gio.Objects.DBusMethodInvocation

Instances of the 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 object is to receive it as an argument to the handle_method_call() function in a DBusInterfaceVTable that was passed to g_dbus_connection_register_object().

Since: 2.26

Exported types

newtype DBusMethodInvocation

Memory-managed wrapper type.

Constructors

DBusMethodInvocation (ManagedPtr DBusMethodInvocation)

Instances

Eq DBusMethodInvocation

Defined in GI.Gio.Objects.DBusMethodInvocation

Methods

(==) :: DBusMethodInvocation -> DBusMethodInvocation -> Bool

(/=) :: DBusMethodInvocation -> DBusMethodInvocation -> Bool

GObject DBusMethodInvocation

Defined in GI.Gio.Objects.DBusMethodInvocation

Methods

gobjectType :: IO GType

IsGValue DBusMethodInvocation

Convert DBusMethodInvocation to and from GValue with toGValue and fromGValue.

Defined in GI.Gio.Objects.DBusMethodInvocation

Methods

toGValue :: DBusMethodInvocation -> IO GValue

fromGValue :: GValue -> IO DBusMethodInvocation

HasParentTypes DBusMethodInvocation

Defined in GI.Gio.Objects.DBusMethodInvocation

type ParentTypes DBusMethodInvocation

Defined in GI.Gio.Objects.DBusMethodInvocation

type ParentTypes DBusMethodInvocation = '[Object]

class (GObject o, IsDescendantOf DBusMethodInvocation o) => IsDBusMethodInvocation o

Type class for types which can be safely cast to DBusMethodInvocation, for instance with toDBusMethodInvocation.

Instances

(GObject o, IsDescendantOf DBusMethodInvocation o) => IsDBusMethodInvocation o

Defined in GI.Gio.Objects.DBusMethodInvocation

toDBusMethodInvocation :: (MonadIO m, IsDBusMethodInvocation o) => o -> m DBusMethodInvocation

Cast to DBusMethodInvocation, for types for which this is known to be safe. For general casts, use castTo.

noDBusMethodInvocation :: Maybe DBusMethodInvocation

A convenience alias for Nothing :: Maybe DBusMethodInvocation.

Methods

Overloaded methods

getConnection

dBusMethodInvocationGetConnection

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m DBusConnection

Returns: A DBusConnection. Do not free, it is owned by invocation.

Gets the DBusConnection the method was invoked on.

Since: 2.26

getInterfaceName

dBusMethodInvocationGetInterfaceName

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m Text

Returns: A string. Do not free, it is owned by invocation.

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.

Since: 2.26

getMessage

dBusMethodInvocationGetMessage

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m DBusMessage

Returns: DBusMessage. Do not free, it is owned by invocation.

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

Since: 2.26

getMethodInfo

dBusMethodInvocationGetMethodInfo

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m DBusMethodInfo

Returns: A DBusMethodInfo or Nothing. Do not free, it is owned by invocation.

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 Nothing will be returned. See dBusMethodInvocationGetPropertyInfo and DBusInterfaceVTable for more information.

Since: 2.26

getMethodName

dBusMethodInvocationGetMethodName

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m Text

Returns: A string. Do not free, it is owned by invocation.

Gets the name of the method that was invoked.

Since: 2.26

getObjectPath

dBusMethodInvocationGetObjectPath

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m Text

Returns: A string. Do not free, it is owned by invocation.

Gets the object path the method was invoked on.

Since: 2.26

getParameters

dBusMethodInvocationGetParameters

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m GVariant

Returns: A GVariant tuple. Do not unref this because it is owned by invocation.

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.

Since: 2.26

getPropertyInfo

dBusMethodInvocationGetPropertyInfo

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation

-> m DBusPropertyInfo

Returns: a DBusPropertyInfo or Nothing

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, Nothing will be returned.

Since: 2.38

getSender

dBusMethodInvocationGetSender

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> m Text

Returns: A string. Do not free, it is owned by invocation.

Gets the bus name that invoked the method.

Since: 2.26

returnDbusError

dBusMethodInvocationReturnDbusError

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> Text

errorName: A valid D-Bus error name.

-> Text

errorMessage: A valid D-Bus error message.

-> m ()

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.

Since: 2.26

returnErrorLiteral

dBusMethodInvocationReturnErrorLiteral

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> Word32

domain: A GQuark for the GError error domain.

-> Int32

code: The error code.

-> Text

message: The error message.

-> m ()

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.

Since: 2.26

returnGerror

dBusMethodInvocationReturnGerror

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> GError

error: A GError.

-> m ()

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

Since: 2.26

returnValue

dBusMethodInvocationReturnValue

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a)

=> a

invocation: A DBusMethodInvocation.

-> Maybe GVariant

parameters: A GVariant tuple with out parameters for the method or Nothing if not passing any parameters.

-> m ()

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 Nothing or an empty tuple.

C code

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

Since: 2.26

returnValueWithUnixFdList

dBusMethodInvocationReturnValueWithUnixFdList

Arguments

:: (HasCallStack, MonadIO m, IsDBusMethodInvocation a, IsUnixFDList b)

=> a

invocation: A DBusMethodInvocation.

-> Maybe GVariant

parameters: A GVariant tuple with out parameters for the method or Nothing if not passing any parameters.

-> Maybe b

fdList: A UnixFDList or Nothing.

-> m ()

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

Since: 2.30