gi-gio-2.0.38: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.DBusMethodInvocation

Contents

- Exported types
- Methods
  - getConnection
  - getInterfaceName
  - getMessage
  - getMethodInfo
  - getMethodName
  - getObjectPath
  - getParameters
  - getPropertyInfo
  - getSender
  - returnDbusError
  - returnErrorLiteral
  - returnGerror
  - returnValue
  - returnValueWithUnixFdList

Description

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 [type`gio`.DBusInterfaceVTable] that was passed to `dBusConnectionRegisterObject`.

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 (Maybe 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 (Maybe 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 Source # (/=) :: DBusMethodInvocation -> DBusMethodInvocation -> Bool Source #
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 Source #
TypedObject DBusMethodInvocation Source # |
Instance details Defined in GI.Gio.Objects.DBusMethodInvocation Methods glibType :: IO GType Source #
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 Source # gvalueSet_ :: Ptr GValue -> Maybe DBusMethodInvocation -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe DBusMethodInvocation) Source #
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

#### Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, returnDbusError, returnErrorLiteral, returnGerror, returnValue, returnValueWithUnixFdList, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getConnection, getData, getInterfaceName, getMessage, getMethodInfo, getMethodName, getObjectPath, getParameters, getProperty, getPropertyInfo, getQdata, getSender.

#### Setters

setData, setDataFull, setProperty.

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

This can be `NULL` if it was not specified by the sender. See [callback`gio`.DBusInterfaceMethodCallFunc] or the D-Bus Specification for details on when this can happen and how it should be handled.

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][class`gio`.DBusConnection`an`-example-d-bus-server] and [client][class`gio`.DBusConnection`an`-example-for-file-descriptor-passing] 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 (Maybe Text) | Returns: A string. Do not free, it is owned by `invocation`.

Gets the bus name that invoked the method.

This can return `Nothing` if not specified by the caller, e.g. on peer-to-peer connections.

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