gi-gio-2.0.29: Gio bindings
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellSafe-Inferred
LanguageHaskell2010

GI.Gio.Objects.DBusMethodInvocation

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

Exported types

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

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 #

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