Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (inaki@blueleaf.cc)
Safe Haskell	None
Language	Haskell2010

GI.Gio.Objects.DBusMethodInvocation

Contents

Exported types
Methods

Description

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

Synopsis

newtype DBusMethodInvocation = DBusMethodInvocation (ManagedPtr DBusMethodInvocation)
class (GObject o, IsDescendantOf DBusMethodInvocation o) => IsDBusMethodInvocation o
toDBusMethodInvocation :: (MonadIO m, IsDBusMethodInvocation o) => o -> m DBusMethodInvocation
noDBusMethodInvocation :: Maybe DBusMethodInvocation
dBusMethodInvocationGetConnection :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m DBusConnection
dBusMethodInvocationGetInterfaceName :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m Text
dBusMethodInvocationGetMessage :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m DBusMessage
dBusMethodInvocationGetMethodInfo :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m DBusMethodInfo
dBusMethodInvocationGetMethodName :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m Text
dBusMethodInvocationGetObjectPath :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m Text
dBusMethodInvocationGetParameters :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m GVariant
dBusMethodInvocationGetPropertyInfo :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m DBusPropertyInfo
dBusMethodInvocationGetSender :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> m Text
dBusMethodInvocationReturnDbusError :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> Text -> Text -> m ()
dBusMethodInvocationReturnErrorLiteral :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> Word32 -> Int32 -> Text -> m ()
dBusMethodInvocationReturnGerror :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> GError -> m ()
dBusMethodInvocationReturnValue :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a) => a -> Maybe GVariant -> m ()
dBusMethodInvocationReturnValueWithUnixFdList :: (HasCallStack, MonadIO m, IsDBusMethodInvocation a, IsUnixFDList b) => a -> Maybe GVariant -> Maybe b -> m ()

Exported types

newtype DBusMethodInvocation Source #

Memory-managed wrapper type.

Constructors

DBusMethodInvocation (ManagedPtr DBusMethodInvocation)

Instances

GObject DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods gobjectType :: IO GType #
HasParentTypes DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation
type ParentTypes DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation type ParentTypes DBusMethodInvocation = Object ': ([] :: [Type])

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

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

Instances

(GObject o, IsDescendantOf DBusMethodInvocation o) => IsDBusMethodInvocation o Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation

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

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

noDBusMethodInvocation :: Maybe DBusMethodInvocation Source #

A convenience alias for Nothing :: Maybe DBusMethodInvocation.

Methods

getConnection

dBusMethodInvocationGetConnection Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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