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

Contents

- Exported types
- Methods
  - call
  - callFinish
  - callSync
  - callWithUnixFdList
  - callWithUnixFdListFinish
  - callWithUnixFdListSync
  - getCachedProperty
  - getCachedPropertyNames
  - getConnection
  - getDefaultTimeout
  - getFlags
  - getInterfaceInfo
  - getInterfaceName
  - getName
  - getNameOwner
  - getObjectPath
  - new
  - newFinish
  - newForBus
  - newForBusFinish
  - newForBusSync
  - newSync
  - setCachedProperty
  - setDefaultTimeout
  - setInterfaceInfo
- Properties
  - gBusType
  - gConnection
  - gDefaultTimeout
  - gFlags
  - gInterfaceInfo
  - gInterfaceName
  - gName
  - gNameOwner
  - gObjectPath
- Signals
  - gPropertiesChanged
  - gSignal

Description

`GDBusProxy` is a base class used for proxies to access a D-Bus interface on a remote object. A `GDBusProxy` can be constructed for both well-known and unique names.

By default, `GDBusProxy` will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable [flags`gio`.DBusProxyFlags] when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

The unique name owner of the proxy’s name is tracked and can be read from DBusProxy:gNameOwner. Connect to the Object::notify signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless `G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set).

If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the DBusProxy:gNameOwner tracking of `GDBusProxy` will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use `GDBusProxy` — use direct D-Bus method calls and signal connections.

The generic DBusProxy::gPropertiesChanged and DBusProxy::gSignal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass `GDBusProxy`, and have more natural properties and signals in your derived class. This example shows how this can easily be done using the `gdbus-codegen` tool.

A `GDBusProxy` instance can be used from multiple threads but note that all signals (e.g. DBusProxy::gSignal, DBusProxy::gPropertiesChanged and Object::notify) are emitted in the thread-default main context (see `mainContextPushThreadDefault`) of the thread where the instance was constructed.

## A watch proxy example

An example using a proxy for a well-known name can be found in `gdbus-example-watch-proxy.c`.

Since: 2.26

Synopsis

- newtype DBusProxy = DBusProxy (ManagedPtr DBusProxy)
- class (GObject o, IsDescendantOf DBusProxy o) => IsDBusProxy o
- toDBusProxy :: (MonadIO m, IsDBusProxy o) => o -> m DBusProxy
- dBusProxyCall :: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) => a -> Text -> Maybe GVariant -> [DBusCallFlags] -> Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- dBusProxyCallFinish :: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) => a -> b -> m GVariant
- dBusProxyCallSync :: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) => a -> Text -> Maybe GVariant -> [DBusCallFlags] -> Int32 -> Maybe b -> m GVariant
- dBusProxyCallWithUnixFdList :: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) => a -> Text -> Maybe GVariant -> [DBusCallFlags] -> Int32 -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- dBusProxyCallWithUnixFdListFinish :: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) => a -> b -> m (GVariant, Maybe UnixFDList)
- dBusProxyCallWithUnixFdListSync :: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) => a -> Text -> Maybe GVariant -> [DBusCallFlags] -> Int32 -> Maybe b -> Maybe c -> m (GVariant, Maybe UnixFDList)
- dBusProxyGetCachedProperty :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> Text -> m (Maybe GVariant)
- dBusProxyGetCachedPropertyNames :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m (Maybe [Text])
- dBusProxyGetConnection :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m DBusConnection
- dBusProxyGetDefaultTimeout :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m Int32
- dBusProxyGetFlags :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m [DBusProxyFlags]
- dBusProxyGetInterfaceInfo :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m (Maybe DBusInterfaceInfo)
- dBusProxyGetInterfaceName :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m Text
- dBusProxyGetName :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m (Maybe Text)
- dBusProxyGetNameOwner :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m (Maybe Text)
- dBusProxyGetObjectPath :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> m Text
- dBusProxyNew :: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) => a -> [DBusProxyFlags] -> Maybe DBusInterfaceInfo -> Maybe Text -> Text -> Text -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- dBusProxyNewFinish :: (HasCallStack, MonadIO m, IsAsyncResult a) => a -> m DBusProxy
- dBusProxyNewForBus :: (HasCallStack, MonadIO m, IsCancellable a) => BusType -> [DBusProxyFlags] -> Maybe DBusInterfaceInfo -> Text -> Text -> Text -> Maybe a -> Maybe AsyncReadyCallback -> m ()
- dBusProxyNewForBusFinish :: (HasCallStack, MonadIO m, IsAsyncResult a) => a -> m DBusProxy
- dBusProxyNewForBusSync :: (HasCallStack, MonadIO m, IsCancellable a) => BusType -> [DBusProxyFlags] -> Maybe DBusInterfaceInfo -> Text -> Text -> Text -> Maybe a -> m DBusProxy
- dBusProxyNewSync :: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) => a -> [DBusProxyFlags] -> Maybe DBusInterfaceInfo -> Maybe Text -> Text -> Text -> Maybe b -> m DBusProxy
- dBusProxySetCachedProperty :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> Text -> Maybe GVariant -> m ()
- dBusProxySetDefaultTimeout :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> Int32 -> m ()
- dBusProxySetInterfaceInfo :: (HasCallStack, MonadIO m, IsDBusProxy a) => a -> Maybe DBusInterfaceInfo -> m ()
- constructDBusProxyGBusType :: (IsDBusProxy o, MonadIO m) => BusType -> m (GValueConstruct o)
- constructDBusProxyGConnection :: (IsDBusProxy o, MonadIO m, IsDBusConnection a) => a -> m (GValueConstruct o)
- getDBusProxyGConnection :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusConnection)
- constructDBusProxyGDefaultTimeout :: (IsDBusProxy o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> m Int32
- setDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> Int32 -> m ()
- constructDBusProxyGFlags :: (IsDBusProxy o, MonadIO m) => [DBusProxyFlags] -> m (GValueConstruct o)
- getDBusProxyGFlags :: (MonadIO m, IsDBusProxy o) => o -> m [DBusProxyFlags]
- clearDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m ()
- constructDBusProxyGInterfaceInfo :: (IsDBusProxy o, MonadIO m) => DBusInterfaceInfo -> m (GValueConstruct o)
- getDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusInterfaceInfo)
- setDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> DBusInterfaceInfo -> m ()
- constructDBusProxyGInterfaceName :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o)
- getDBusProxyGInterfaceName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- constructDBusProxyGName :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o)
- getDBusProxyGName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- getDBusProxyGNameOwner :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- constructDBusProxyGObjectPath :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o)
- getDBusProxyGObjectPath :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- type DBusProxyGPropertiesChangedCallback = GVariant -> [Text] -> IO ()
- afterDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> ((?self :: a) => DBusProxyGPropertiesChangedCallback) -> m SignalHandlerId
- onDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> ((?self :: a) => DBusProxyGPropertiesChangedCallback) -> m SignalHandlerId
- type DBusProxyGSignalCallback = Maybe Text -> Text -> GVariant -> IO ()
- afterDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => DBusProxyGSignalCallback) -> m SignalHandlerId
- onDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => DBusProxyGSignalCallback) -> m SignalHandlerId

# Exported types

newtype DBusProxy Source #

Memory-managed wrapper type.

Constructors

DBusProxy (ManagedPtr DBusProxy) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf DBusProxy o) => IsDBusProxy o Source #

Type class for types which can be safely cast to `DBusProxy`, for instance with `toDBusProxy`.

#### Instances

Instances details

(GObject o, IsDescendantOf DBusProxy o) => IsDBusProxy o Source # |
Instance details Defined in GI.Gio.Objects.DBusProxy

toDBusProxy :: (MonadIO m, IsDBusProxy o) => o -> m DBusProxy Source #

Cast to `DBusProxy`, 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, call, callFinish, callSync, callWithUnixFdList, callWithUnixFdListFinish, callWithUnixFdListSync, forceFloating, freezeNotify, getv, init, initAsync, initFinish, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getCachedProperty, getCachedPropertyNames, getConnection, getData, getDefaultTimeout, getFlags, getInfo, getInterfaceInfo, getInterfaceName, getName, getNameOwner, getObject, getObjectPath, getProperty, getQdata.

#### Setters

setCachedProperty, setData, setDataFull, setDefaultTimeout, setInterfaceInfo, setObject, setProperty.

## call

dBusProxyCall Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) |
=> a | `proxy`: A `DBusProxy`.
-> Text | `methodName`: Name of method to invoke.
-> Maybe GVariant | `parameters`: A `GVariant` tuple with parameters for the signal or `Nothing` if not passing parameters.
-> [DBusCallFlags] | `flags`: Flags from the `DBusCallFlags` enumeration.
-> Int32 | `timeoutMsec`: The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> Maybe AsyncReadyCallback | `callback`: A `AsyncReadyCallback` to call when the request is satisfied or `Nothing` if you don't care about the result of the method invocation.
-> m () |

Asynchronously invokes the `methodName` method on `proxy`.

If `methodName` contains any dots, then `name` is split into interface and method name parts. This allows using `proxy` for invoking methods on other interfaces.

If the `DBusConnection` associated with `proxy` is closed then the operation will fail with `IOErrorEnumClosed`. If `cancellable` is canceled, the operation will fail with `IOErrorEnumCancelled`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `IOErrorEnumInvalidArgument`.

If the `parameters` `GVariant` is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

### C code

    g_dbus_proxy_call (proxy,
                       "TwoStrings",
                       g_variant_new ("(ss)",
                                      "Thing One",
                                      "Thing Two"),
                       G_DBUS_CALL_FLAGS_NONE,
                       -1,
                       NULL,
                       (GAsyncReadyCallback) two_strings_done,
                       &data);

If `proxy` has an expected interface (see DBusProxy:gInterfaceInfo) and `methodName` is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, `callback` will be invoked in the thread-default main context (see `mainContextPushThreadDefault`) of the thread you are calling this method from. You can then call `dBusProxyCallFinish` to get the result of the operation. See `dBusProxyCallSync` for the synchronous version of this method.

If `callback` is `Nothing` then the D-Bus method call message will be sent with the `DBusMessageFlagsNoReplyExpected` flag set.

Since: 2.26

## callFinish

dBusProxyCallFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) |
=> a | `proxy`: A `DBusProxy`.
-> b | `res`: A `AsyncResult` obtained from the `AsyncReadyCallback` passed to `dBusProxyCall`.
-> m GVariant | Returns: `Nothing` if `error` is set. Otherwise a `GVariant` tuple with return values. Free with `variantUnref`. (Can throw `GError`)

Finishes an operation started with `dBusProxyCall`.

Since: 2.26

## callSync

dBusProxyCallSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) |
=> a | `proxy`: A `DBusProxy`.
-> Text | `methodName`: Name of method to invoke.
-> Maybe GVariant | `parameters`: A `GVariant` tuple with parameters for the signal or `Nothing` if not passing parameters.
-> [DBusCallFlags] | `flags`: Flags from the `DBusCallFlags` enumeration.
-> Int32 | `timeoutMsec`: The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> m GVariant | Returns: `Nothing` if `error` is set. Otherwise a `GVariant` tuple with return values. Free with `variantUnref`. (Can throw `GError`)

Synchronously invokes the `methodName` method on `proxy`.

If `methodName` contains any dots, then `name` is split into interface and method name parts. This allows using `proxy` for invoking methods on other interfaces.

If the `DBusConnection` associated with `proxy` is disconnected then the operation will fail with `IOErrorEnumClosed`. If `cancellable` is canceled, the operation will fail with `IOErrorEnumCancelled`. If `parameters` contains a value not compatible with the D-Bus protocol, the operation fails with `IOErrorEnumInvalidArgument`.

If the `parameters` `GVariant` is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.:

### C code

    g_dbus_proxy_call_sync (proxy,
                            "TwoStrings",
                            g_variant_new ("(ss)",
                                           "Thing One",
                                           "Thing Two"),
                            G_DBUS_CALL_FLAGS_NONE,
                            -1,
                            NULL,
                            &error);

The calling thread is blocked until a reply is received. See `dBusProxyCall` for the asynchronous version of this method.

If `proxy` has an expected interface (see DBusProxy:gInterfaceInfo) and `methodName` is referenced by it, then the return value is checked against the return type.

Since: 2.26

## callWithUnixFdList

dBusProxyCallWithUnixFdList Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) |
=> a | `proxy`: A `DBusProxy`.
-> Text | `methodName`: Name of method to invoke.
-> Maybe GVariant | `parameters`: A `GVariant` tuple with parameters for the signal or `Nothing` if not passing parameters.
-> [DBusCallFlags] | `flags`: Flags from the `DBusCallFlags` enumeration.
-> Int32 | `timeoutMsec`: The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
-> Maybe b | `fdList`: A `UnixFDList` or `Nothing`.
-> Maybe c | `cancellable`: A `Cancellable` or `Nothing`.
-> Maybe AsyncReadyCallback | `callback`: A `AsyncReadyCallback` to call when the request is satisfied or `Nothing` if you don't care about the result of the method invocation.
-> m () |

Like `dBusProxyCall` but also takes a `UnixFDList` object.

This method is only available on UNIX.

Since: 2.30

## callWithUnixFdListFinish

dBusProxyCallWithUnixFdListFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) |
=> a | `proxy`: A `DBusProxy`.
-> b | `res`: A `AsyncResult` obtained from the `AsyncReadyCallback` passed to `dBusProxyCallWithUnixFdList`.
-> m (GVariant, Maybe UnixFDList) | Returns: `Nothing` if `error` is set. Otherwise a `GVariant` tuple with return values. Free with `variantUnref`. (Can throw `GError`)

Finishes an operation started with `dBusProxyCallWithUnixFdList`.

Since: 2.30

## callWithUnixFdListSync

dBusProxyCallWithUnixFdListSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) |
=> a | `proxy`: A `DBusProxy`.
-> Text | `methodName`: Name of method to invoke.
-> Maybe GVariant | `parameters`: A `GVariant` tuple with parameters for the signal or `Nothing` if not passing parameters.
-> [DBusCallFlags] | `flags`: Flags from the `DBusCallFlags` enumeration.
-> Int32 | `timeoutMsec`: The timeout in milliseconds (with `G_MAXINT` meaning "infinite") or -1 to use the proxy default timeout.
-> Maybe b | `fdList`: A `UnixFDList` or `Nothing`.
-> Maybe c | `cancellable`: A `Cancellable` or `Nothing`.
-> m (GVariant, Maybe UnixFDList) | Returns: `Nothing` if `error` is set. Otherwise a `GVariant` tuple with return values. Free with `variantUnref`. (Can throw `GError`)

Like `dBusProxyCallSync` but also takes and returns `UnixFDList` objects.

This method is only available on UNIX.

Since: 2.30

## getCachedProperty

dBusProxyGetCachedProperty Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> Text | `propertyName`: Property name.
-> m (Maybe GVariant) | Returns: A reference to the `GVariant` instance that holds the value for `propertyName` or `Nothing` if the value is not in the cache. The returned reference must be freed with `variantUnref`.

Looks up the value for a property from the cache. This call does no blocking IO.

If `proxy` has an expected interface (see DBusProxy:gInterfaceInfo) and `propertyName` is referenced by it, then `value` is checked against the type of the property.

Since: 2.26

## getCachedPropertyNames

dBusProxyGetCachedPropertyNames Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m (Maybe [Text]) | Returns: A `Nothing`-terminated array of strings or `Nothing` if `proxy` has no cached properties. Free the returned array with `strfreev`.

Gets the names of all cached properties on `proxy`.

Since: 2.26

## getConnection

dBusProxyGetConnection Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m DBusConnection | Returns: A `DBusConnection` owned by `proxy`. Do not free.

Gets the connection `proxy` is for.

Since: 2.26

## getDefaultTimeout

dBusProxyGetDefaultTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m Int32 | Returns: Timeout to use for `proxy`.

Gets the timeout to use if -1 (specifying default timeout) is passed as `timeoutMsec` in the `dBusProxyCall` and `dBusProxyCallSync` functions.

See the DBusProxy:gDefaultTimeout property for more details.

Since: 2.26

## getFlags

dBusProxyGetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m [DBusProxyFlags] | Returns: Flags from the `DBusProxyFlags` enumeration.

Gets the flags that `proxy` was constructed with.

Since: 2.26

## getInterfaceInfo

dBusProxyGetInterfaceInfo Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`
-> m (Maybe DBusInterfaceInfo) | Returns: A `DBusInterfaceInfo` or `Nothing`. Do not unref the returned object, it is owned by `proxy`.

Returns the `DBusInterfaceInfo`, if any, specifying the interface that `proxy` conforms to. See the DBusProxy:gInterfaceInfo property for more details.

Since: 2.26

## getInterfaceName

dBusProxyGetInterfaceName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m Text | Returns: A string owned by `proxy`. Do not free.

Gets the D-Bus interface name `proxy` is for.

Since: 2.26

## getName

dBusProxyGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m (Maybe Text) | Returns: A string owned by `proxy`. Do not free.

Gets the name that `proxy` was constructed for.

When connected to a message bus, this will usually be non-`Nothing`. However, it may be `Nothing` for a proxy that communicates using a peer-to-peer pattern.

Since: 2.26

## getNameOwner

dBusProxyGetNameOwner Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m (Maybe Text) | Returns: The name owner or `Nothing` if no name owner exists. Free with `free`.

The unique name that owns the name that `proxy` is for or `Nothing` if no-one currently owns that name. You may connect to the Object::notify signal to track changes to the DBusProxy:gNameOwner property.

Since: 2.26

## getObjectPath

dBusProxyGetObjectPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> m Text | Returns: A string owned by `proxy`. Do not free.

Gets the object path `proxy` is for.

Since: 2.26

## new

dBusProxyNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) |
=> a | `connection`: A `DBusConnection`.
-> [DBusProxyFlags] | `flags`: Flags used when constructing the proxy.
-> Maybe DBusInterfaceInfo | `info`: A `DBusInterfaceInfo` specifying the minimal interface that `proxy` conforms to or `Nothing`.
-> Maybe Text | `name`: A bus name (well-known or unique) or `Nothing` if `connection` is not a message bus connection.
-> Text | `objectPath`: An object path.
-> Text | `interfaceName`: A D-Bus interface name.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> Maybe AsyncReadyCallback | `callback`: Callback function to invoke when the proxy is ready.
-> m () |

Creates a proxy for accessing `interfaceName` on the remote object at `objectPath` owned by `name` at `connection` and asynchronously loads D-Bus properties unless the `DBusProxyFlagsDoNotLoadProperties` flag is used. Connect to the DBusProxy::gPropertiesChanged signal to get notified about property changes.

If the `DBusProxyFlagsDoNotConnectSignals` flag is not set, also sets up match rules for signals. Connect to the DBusProxy::gSignal signal to handle signals from the remote object.

If both `DBusProxyFlagsDoNotLoadProperties` and `DBusProxyFlagsDoNotConnectSignals` are set, this constructor is guaranteed to complete immediately without blocking.

If `name` is a well-known name and the `DBusProxyFlagsDoNotAutoStart` and `DBusProxyFlagsDoNotAutoStartAtConstruction` flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, `callback` will be invoked and you can use `dBusProxyNewFinish` to get the result.

See `dBusProxyNewSync` and for a synchronous version of this constructor.

`DBusProxy` is used in this [example][class`gio`.DBusProxy`a`-watch-proxy-example].

Since: 2.26

## newFinish

dBusProxyNewFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a) |
=> a | `res`: A `AsyncResult` obtained from the `AsyncReadyCallback` function passed to `dBusProxyNew`.
-> m DBusProxy | Returns: A `DBusProxy` or `Nothing` if `error` is set. Free with `objectUnref`. (Can throw `GError`)

Finishes creating a `DBusProxy`.

Since: 2.26

## newForBus

dBusProxyNewForBus Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a) |
=> BusType | `busType`: A `BusType`.
-> [DBusProxyFlags] | `flags`: Flags used when constructing the proxy.
-> Maybe DBusInterfaceInfo | `info`: A `DBusInterfaceInfo` specifying the minimal interface that `proxy` conforms to or `Nothing`.
-> Text | `name`: A bus name (well-known or unique).
-> Text | `objectPath`: An object path.
-> Text | `interfaceName`: A D-Bus interface name.
-> Maybe a | `cancellable`: A `Cancellable` or `Nothing`.
-> Maybe AsyncReadyCallback | `callback`: Callback function to invoke when the proxy is ready.
-> m () |

Like `dBusProxyNew` but takes a `BusType` instead of a `DBusConnection`.

`DBusProxy` is used in this [example][class`gio`.DBusProxy`a`-watch-proxy-example].

Since: 2.26

## newForBusFinish

dBusProxyNewForBusFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a) |
=> a | `res`: A `AsyncResult` obtained from the `AsyncReadyCallback` function passed to `dBusProxyNewForBus`.
-> m DBusProxy | Returns: A `DBusProxy` or `Nothing` if `error` is set. Free with `objectUnref`. (Can throw `GError`)

Finishes creating a `DBusProxy`.

Since: 2.26

## newForBusSync

dBusProxyNewForBusSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a) |
=> BusType | `busType`: A `BusType`.
-> [DBusProxyFlags] | `flags`: Flags used when constructing the proxy.
-> Maybe DBusInterfaceInfo | `info`: A `DBusInterfaceInfo` specifying the minimal interface that `proxy` conforms to or `Nothing`.
-> Text | `name`: A bus name (well-known or unique).
-> Text | `objectPath`: An object path.
-> Text | `interfaceName`: A D-Bus interface name.
-> Maybe a | `cancellable`: A `Cancellable` or `Nothing`.
-> m DBusProxy | Returns: A `DBusProxy` or `Nothing` if error is set. Free with `objectUnref`. (Can throw `GError`)

Like `dBusProxyNewSync` but takes a `BusType` instead of a `DBusConnection`.

`DBusProxy` is used in this [example][class`gio`.DBusProxy`a`-watch-proxy-example].

Since: 2.26

## newSync

dBusProxyNewSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) |
=> a | `connection`: A `DBusConnection`.
-> [DBusProxyFlags] | `flags`: Flags used when constructing the proxy.
-> Maybe DBusInterfaceInfo | `info`: A `DBusInterfaceInfo` specifying the minimal interface that `proxy` conforms to or `Nothing`.
-> Maybe Text | `name`: A bus name (well-known or unique) or `Nothing` if `connection` is not a message bus connection.
-> Text | `objectPath`: An object path.
-> Text | `interfaceName`: A D-Bus interface name.
-> Maybe b | `cancellable`: A `Cancellable` or `Nothing`.
-> m DBusProxy | Returns: A `DBusProxy` or `Nothing` if error is set. Free with `objectUnref`. (Can throw `GError`)

Creates a proxy for accessing `interfaceName` on the remote object at `objectPath` owned by `name` at `connection` and synchronously loads D-Bus properties unless the `DBusProxyFlagsDoNotLoadProperties` flag is used.

If the `DBusProxyFlagsDoNotConnectSignals` flag is not set, also sets up match rules for signals. Connect to the DBusProxy::gSignal signal to handle signals from the remote object.

If both `DBusProxyFlagsDoNotLoadProperties` and `DBusProxyFlagsDoNotConnectSignals` are set, this constructor is guaranteed to return immediately without blocking.

If `name` is a well-known name and the `DBusProxyFlagsDoNotAutoStart` and `DBusProxyFlagsDoNotAutoStartAtConstruction` flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See `dBusProxyNew` and `dBusProxyNewFinish` for the asynchronous version.

`DBusProxy` is used in this [example][class`gio`.DBusProxy`a`-watch-proxy-example].

Since: 2.26

## setCachedProperty

dBusProxySetCachedProperty Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`
-> Text | `propertyName`: Property name.
-> Maybe GVariant | `value`: Value for the property or `Nothing` to remove it from the cache.
-> m () |

If `value` is not `Nothing`, sets the cached value for the property with name `propertyName` to the value in `value`.

If `value` is `Nothing`, then the cached value is removed from the property cache.

If `proxy` has an expected interface (see DBusProxy:gInterfaceInfo) and `propertyName` is referenced by it, then `value` is checked against the type of the property.

If the `value` `GVariant` is floating, it is consumed. This allows convenient 'inline' use of `g_variant_new()`, e.g.

### C code

    g_dbus_proxy_set_cached_property (proxy,
                                      "SomeProperty",
                                      g_variant_new ("(si)",
                                                    "A String",
                                                    42));

Normally you will not need to use this method since `proxy` is tracking changes using the `org.freedesktop.DBus.Properties.PropertiesChanged` D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property `ChatroomParticipants` which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals `ChatroomParticipantJoined(String name)` and `ChatroomParticipantParted(String name)`.

Since: 2.26

## setDefaultTimeout

dBusProxySetDefaultTimeout Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`.
-> Int32 | `timeoutMsec`: Timeout in milliseconds.
-> m () |

Sets the timeout to use if -1 (specifying default timeout) is passed as `timeoutMsec` in the `dBusProxyCall` and `dBusProxyCallSync` functions.

See the DBusProxy:gDefaultTimeout property for more details.

Since: 2.26

## setInterfaceInfo

dBusProxySetInterfaceInfo Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusProxy a) |
=> a | `proxy`: A `DBusProxy`
-> Maybe DBusInterfaceInfo | `info`: Minimum interface this proxy conforms to or `Nothing` to unset.
-> m () |

Ensure that interactions with `proxy` conform to the given interface. See the DBusProxy:gInterfaceInfo property for more details.

Since: 2.26

# Properties

## gBusType

If this property is not `BusTypeNone`, then DBusProxy:gConnection must be `Nothing` and will be set to the `DBusConnection` obtained by calling `busGet` with the value of this property.

Since: 2.26

constructDBusProxyGBusType :: (IsDBusProxy o, MonadIO m) => BusType -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-bus-type`” property. This is rarely needed directly, but it is used by `new`.

## gConnection

The `DBusConnection` the proxy is for.

Since: 2.26

constructDBusProxyGConnection :: (IsDBusProxy o, MonadIO m, IsDBusConnection a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-connection`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGConnection :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusConnection) Source #

Get the value of the “`g-connection`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gConnection

## gDefaultTimeout

The timeout to use if -1 (specifying default timeout) is passed as `timeoutMsec` in the `dBusProxyCall` and `dBusProxyCallSync` functions.

This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to `G_MAXINT`, then no timeout is used.

Since: 2.26

constructDBusProxyGDefaultTimeout :: (IsDBusProxy o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-default-timeout`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> m Int32 Source #

Get the value of the “`g-default-timeout`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gDefaultTimeout

setDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> Int32 -> m () Source #

Set the value of the “`g-default-timeout`” property. When overloading is enabled, this is equivalent to

    set dBusProxy [ #gDefaultTimeout := value ]

## gFlags

Flags from the `DBusProxyFlags` enumeration.

Since: 2.26

constructDBusProxyGFlags :: (IsDBusProxy o, MonadIO m) => [DBusProxyFlags] -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-flags`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGFlags :: (MonadIO m, IsDBusProxy o) => o -> m [DBusProxyFlags] Source #

Get the value of the “`g-flags`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gFlags

## gInterfaceInfo

Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given `DBusInterfaceInfo` is said to be the "expected interface".

The checks performed are: * When completing a method call, if the type signature of the reply message isn't what's expected, the reply is discarded and the `GError` is set to `IOErrorEnumInvalidArgument`. * Received signals that have a type signature mismatch are dropped and a warning is logged via `g_warning()`. * Properties received via the initial `GetAll()` call or via the `::PropertiesChanged` signal (on the org.freedesktop.DBus.Properties interface) or set using `dBusProxySetCachedProperty` with a type signature mismatch are ignored and a warning is logged via `g_warning()`.

Note that these checks are never done on methods, signals and properties that are not referenced in the given `DBusInterfaceInfo`, since extending a D-Bus interface on the service-side is not considered an ABI break.

Since: 2.26

clearDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m () Source #

Set the value of the “`g-interface-info`” property to `Nothing`. When overloading is enabled, this is equivalent to

    clear #gInterfaceInfo

constructDBusProxyGInterfaceInfo :: (IsDBusProxy o, MonadIO m) => DBusInterfaceInfo -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-interface-info`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusInterfaceInfo) Source #

Get the value of the “`g-interface-info`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gInterfaceInfo

setDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> DBusInterfaceInfo -> m () Source #

Set the value of the “`g-interface-info`” property. When overloading is enabled, this is equivalent to

    set dBusProxy [ #gInterfaceInfo := value ]

## gInterfaceName

The D-Bus interface name the proxy is for.

Since: 2.26

constructDBusProxyGInterfaceName :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-interface-name`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGInterfaceName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text) Source #

Get the value of the “`g-interface-name`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gInterfaceName

## gName

The well-known or unique name that the proxy is for.

Since: 2.26

constructDBusProxyGName :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-name`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text) Source #

Get the value of the “`g-name`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gName

## gNameOwner

The unique name that owns DBusProxy:gName or `Nothing` if no-one currently owns that name. You may connect to Object::notify signal to track changes to this property.

Since: 2.26

getDBusProxyGNameOwner :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text) Source #

Get the value of the “`g-name-owner`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gNameOwner

## gObjectPath

The object path the proxy is for.

Since: 2.26

constructDBusProxyGObjectPath :: (IsDBusProxy o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`g-object-path`” property. This is rarely needed directly, but it is used by `new`.

getDBusProxyGObjectPath :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text) Source #

Get the value of the “`g-object-path`” property. When overloading is enabled, this is equivalent to

    get dBusProxy #gObjectPath

# Signals

## gPropertiesChanged

type DBusProxyGPropertiesChangedCallback Source #

Arguments

= GVariant | `changedProperties`: A `GVariant` containing the properties that changed (type: `a{sv}`)
-> [Text] | `invalidatedProperties`: A `Nothing` terminated array of properties that was invalidated
-> IO () |

Emitted when one or more D-Bus properties on `proxy` changes. The local cache has already been updated when this signal fires. Note that both `changedProperties` and `invalidatedProperties` are guaranteed to never be `Nothing` (either may be empty though).

If the proxy has the flag `DBusProxyFlagsGetInvalidatedProperties` set, then `invalidatedProperties` will always be empty.

This signal corresponds to the `PropertiesChanged` D-Bus signal on the `org.freedesktop.DBus.Properties` interface.

Since: 2.26

afterDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> ((?self :: a) => DBusProxyGPropertiesChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the gPropertiesChanged signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dBusProxy #gPropertiesChanged callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> ((?self :: a) => DBusProxyGPropertiesChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the gPropertiesChanged signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dBusProxy #gPropertiesChanged callback

## gSignal

type DBusProxyGSignalCallback Source #

Arguments

= Maybe Text | `senderName`: The sender of the signal or `Nothing` if the connection is not a bus connection.
-> Text | `signalName`: The name of the signal.
-> GVariant | `parameters`: A `GVariant` tuple with parameters for the signal.
-> IO () |

Emitted when a signal from the remote object and interface that `proxy` is for, has been received.

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal `g-signal::x` in order to receive callbacks only when signal `x` is received from the remote object.

Since: 2.26

afterDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => DBusProxyGSignalCallback) -> m SignalHandlerId Source #

Connect a signal handler for the gSignal signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after dBusProxy #gSignal callback

This signal admits a optional parameter `detail`. If it's not `Nothing`, we will connect to “`g-signal::detail`” instead.

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> Maybe Text -> ((?self :: a) => DBusProxyGSignalCallback) -> m SignalHandlerId Source #

Connect a signal handler for the gSignal signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on dBusProxy #gSignal callback

This signal admits a optional parameter `detail`. If it's not `Nothing`, we will connect to “`g-signal::detail`” instead.