Copyright	Will Thompson and Iñaki García Etxebarria
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	Safe-Inferred
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
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 (Maybe 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 (Maybe 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

Instances details

Eq DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods (==) :: DBusMethodInvocation -> DBusMethodInvocation -> Bool # (/=) :: DBusMethodInvocation -> DBusMethodInvocation -> Bool #
GObject DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation
ManagedPtrNewtype DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods toManagedPtr :: DBusMethodInvocation -> ManagedPtr DBusMethodInvocation #
TypedObject DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods glibType :: IO GType #
HasParentTypes DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation
IsGValue (Maybe DBusMethodInvocation) Source #	Convert `DBusMethodInvocation` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe DBusMethodInvocation -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe DBusMethodInvocation) #
type ParentTypes DBusMethodInvocation Source #
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation type ParentTypes DBusMethodInvocation = '[Object]

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

Instances details

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

Methods

Click to display all available methods, including inherited ones

Expand

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 (Maybe 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 (Maybe 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

Exported types

Instances

Instances

Methods

Click to display all available methods, including inherited ones

Methods

Getters

Setters

getConnection

getInterfaceName

getMessage

getMethodInfo

getMethodName

getObjectPath

getParameters

getPropertyInfo

getSender

returnDbusError

returnErrorLiteral

returnGerror

returnValue

C code

returnValueWithUnixFdList