Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
- 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
- Signals
DBusProxy
is a base class used for proxies to access a D-Bus
interface on a remote object. A DBusProxy
can be constructed for
both well-known and unique names.
By default, DBusProxy
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
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.
If a DBusProxy
is used for a well-known name, the owner of the
name is tracked and can be read from
DBusProxy
:g-name-owner
. 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
DBusProxyFlagsDoNotAutoStart
is set).
The generic DBusProxy
::g-properties-changed
and
DBusProxy
::g-signal
signals are not very convenient to work with.
Therefore, the recommended way of working with proxies is to subclass
DBusProxy
, and have more natural properties and signals in your derived
class. This [example][gdbus-example-gdbus-codegen] shows how this can
easily be done using the [gdbus-codegen][gdbus-codegen] tool.
A DBusProxy
instance can be used from multiple threads but note
that all signals (e.g. DBusProxy
::g-signal
, DBusProxy
::g-properties-changed
and Object
::notify
) are emitted in the
[thread-default main context][g-main-context-push-thread-default]
of the thread where the instance was constructed.
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 => IsDBusProxy o
- toDBusProxy :: (MonadIO m, IsDBusProxy o) => o -> m DBusProxy
- noDBusProxy :: Maybe 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, UnixFDList)
- dBusProxyCallWithUnixFdListSync :: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) => a -> Text -> Maybe GVariant -> [DBusCallFlags] -> Int32 -> Maybe b -> Maybe c -> m (GVariant, 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 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 => BusType -> IO (GValueConstruct o)
- constructDBusProxyGConnection :: (IsDBusProxy o, IsDBusConnection a) => a -> IO (GValueConstruct o)
- getDBusProxyGConnection :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusConnection)
- constructDBusProxyGDefaultTimeout :: IsDBusProxy o => Int32 -> IO (GValueConstruct o)
- getDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> m Int32
- setDBusProxyGDefaultTimeout :: (MonadIO m, IsDBusProxy o) => o -> Int32 -> m ()
- constructDBusProxyGFlags :: IsDBusProxy o => [DBusProxyFlags] -> IO (GValueConstruct o)
- getDBusProxyGFlags :: (MonadIO m, IsDBusProxy o) => o -> m [DBusProxyFlags]
- clearDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m ()
- constructDBusProxyGInterfaceInfo :: IsDBusProxy o => DBusInterfaceInfo -> IO (GValueConstruct o)
- getDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe DBusInterfaceInfo)
- setDBusProxyGInterfaceInfo :: (MonadIO m, IsDBusProxy o) => o -> DBusInterfaceInfo -> m ()
- constructDBusProxyGInterfaceName :: IsDBusProxy o => Text -> IO (GValueConstruct o)
- getDBusProxyGInterfaceName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- constructDBusProxyGName :: IsDBusProxy o => Text -> IO (GValueConstruct o)
- getDBusProxyGName :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- getDBusProxyGNameOwner :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- constructDBusProxyGObjectPath :: IsDBusProxy o => Text -> IO (GValueConstruct o)
- getDBusProxyGObjectPath :: (MonadIO m, IsDBusProxy o) => o -> m (Maybe Text)
- type C_DBusProxyGPropertiesChangedCallback = Ptr () -> Ptr GVariant -> Ptr CString -> Ptr () -> IO ()
- type DBusProxyGPropertiesChangedCallback = GVariant -> [Text] -> IO ()
- afterDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGPropertiesChangedCallback -> m SignalHandlerId
- genClosure_DBusProxyGPropertiesChanged :: DBusProxyGPropertiesChangedCallback -> IO Closure
- mk_DBusProxyGPropertiesChangedCallback :: C_DBusProxyGPropertiesChangedCallback -> IO (FunPtr C_DBusProxyGPropertiesChangedCallback)
- noDBusProxyGPropertiesChangedCallback :: Maybe DBusProxyGPropertiesChangedCallback
- onDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGPropertiesChangedCallback -> m SignalHandlerId
- wrap_DBusProxyGPropertiesChangedCallback :: DBusProxyGPropertiesChangedCallback -> C_DBusProxyGPropertiesChangedCallback
- type C_DBusProxyGSignalCallback = Ptr () -> CString -> CString -> Ptr GVariant -> Ptr () -> IO ()
- type DBusProxyGSignalCallback = Maybe Text -> Text -> GVariant -> IO ()
- afterDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGSignalCallback -> m SignalHandlerId
- genClosure_DBusProxyGSignal :: DBusProxyGSignalCallback -> IO Closure
- mk_DBusProxyGSignalCallback :: C_DBusProxyGSignalCallback -> IO (FunPtr C_DBusProxyGSignalCallback)
- noDBusProxyGSignalCallback :: Maybe DBusProxyGSignalCallback
- onDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGSignalCallback -> m SignalHandlerId
- wrap_DBusProxyGSignalCallback :: DBusProxyGSignalCallback -> C_DBusProxyGSignalCallback
Exported types
Memory-managed wrapper type.
Instances
GObject DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy gobjectType :: DBusProxy -> IO GType # | |
IsObject DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy | |
IsAsyncInitable DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy | |
IsDBusInterface DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy | |
IsInitable DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy | |
IsDBusProxy DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy |
class GObject o => IsDBusProxy o Source #
Type class for types which can be safely cast to DBusProxy
, for instance with toDBusProxy
.
Instances
(GObject a, (UnknownAncestorError DBusProxy a :: Constraint)) => IsDBusProxy a Source # | |
Defined in GI.Gio.Objects.DBusProxy | |
IsDBusProxy DBusProxy Source # | |
Defined in GI.Gio.Objects.DBusProxy |
toDBusProxy :: (MonadIO m, IsDBusProxy o) => o -> m DBusProxy Source #
Methods
call
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Maybe GVariant |
|
-> [DBusCallFlags] |
|
-> Int32 |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> 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
:g-interface-info
) 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][g-main-context-push-thread-default]
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
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m GVariant | Returns: |
Finishes an operation started with dBusProxyCall
.
Since: 2.26
callSync
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsCancellable b) | |
=> a |
|
-> Text |
|
-> Maybe GVariant |
|
-> [DBusCallFlags] |
|
-> Int32 |
|
-> Maybe b |
|
-> m GVariant | Returns: |
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
:g-interface-info
) and methodName
is referenced by it,
then the return value is checked against the return type.
Since: 2.26
callWithUnixFdList
dBusProxyCallWithUnixFdList Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) | |
=> a |
|
-> Text |
|
-> Maybe GVariant |
|
-> [DBusCallFlags] |
|
-> Int32 |
|
-> Maybe b |
|
-> Maybe c |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Like dBusProxyCall
but also takes a UnixFDList
object.
This method is only available on UNIX.
Since: 2.30
callWithUnixFdListFinish
dBusProxyCallWithUnixFdListFinish Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m (GVariant, UnixFDList) | Returns: |
Finishes an operation started with dBusProxyCallWithUnixFdList
.
Since: 2.30
callWithUnixFdListSync
dBusProxyCallWithUnixFdListSync Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a, IsUnixFDList b, IsCancellable c) | |
=> a |
|
-> Text |
|
-> Maybe GVariant |
|
-> [DBusCallFlags] |
|
-> Int32 |
|
-> Maybe b |
|
-> Maybe c |
|
-> m (GVariant, UnixFDList) | Returns: |
Like dBusProxyCallSync
but also takes and returns UnixFDList
objects.
This method is only available on UNIX.
Since: 2.30
getCachedProperty
dBusProxyGetCachedProperty Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> Text |
|
-> m (Maybe GVariant) | Returns: A reference to the |
Looks up the value for a property from the cache. This call does no blocking IO.
If proxy
has an expected interface (see
DBusProxy
:g-interface-info
) and propertyName
is referenced by
it, then value
is checked against the type of the property.
Since: 2.26
getCachedPropertyNames
dBusProxyGetCachedPropertyNames Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m (Maybe [Text]) | Returns: A
|
Gets the names of all cached properties on proxy
.
Since: 2.26
getConnection
dBusProxyGetConnection Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m DBusConnection | Returns: A |
Gets the connection proxy
is for.
Since: 2.26
getDefaultTimeout
dBusProxyGetDefaultTimeout Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m Int32 | Returns: Timeout to use for |
Gets the timeout to use if -1 (specifying default timeout) is
passed as timeoutMsec
in the dBusProxyCall
and
dBusProxyCallSync
functions.
See the DBusProxy
:g-default-timeout
property for more details.
Since: 2.26
getFlags
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m [DBusProxyFlags] | Returns: Flags from the |
Gets the flags that proxy
was constructed with.
Since: 2.26
getInterfaceInfo
dBusProxyGetInterfaceInfo Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m (Maybe DBusInterfaceInfo) | Returns: A |
Returns the DBusInterfaceInfo
, if any, specifying the interface
that proxy
conforms to. See the DBusProxy
:g-interface-info
property for more details.
Since: 2.26
getInterfaceName
dBusProxyGetInterfaceName Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m Text | Returns: A string owned by |
Gets the D-Bus interface name proxy
is for.
Since: 2.26
getName
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m Text | Returns: A string owned by |
Gets the name that proxy
was constructed for.
Since: 2.26
getNameOwner
dBusProxyGetNameOwner Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m (Maybe Text) | Returns: The name owner or |
getObjectPath
dBusProxyGetObjectPath Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> m Text | Returns: A string owned by |
Gets the object path proxy
is for.
Since: 2.26
new
:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) | |
=> a |
|
-> [DBusProxyFlags] |
|
-> Maybe DBusInterfaceInfo |
|
-> Maybe Text |
|
-> Text |
|
-> Text |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> 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
::g-properties-changed
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
::g-signal
signal
to handle signals from the remote object.
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][gdbus-wellknown-proxy].
Since: 2.26
newFinish
:: (HasCallStack, MonadIO m, IsAsyncResult a) | |
=> a |
|
-> m DBusProxy | Returns: A |
Finishes creating a DBusProxy
.
Since: 2.26
newForBus
:: (HasCallStack, MonadIO m, IsCancellable a) | |
=> BusType |
|
-> [DBusProxyFlags] |
|
-> Maybe DBusInterfaceInfo |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Maybe a |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Like dBusProxyNew
but takes a BusType
instead of a DBusConnection
.
DBusProxy
is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
newForBusFinish
dBusProxyNewForBusFinish Source #
:: (HasCallStack, MonadIO m, IsAsyncResult a) | |
=> a |
|
-> m DBusProxy | Returns: A |
Finishes creating a DBusProxy
.
Since: 2.26
newForBusSync
dBusProxyNewForBusSync Source #
:: (HasCallStack, MonadIO m, IsCancellable a) | |
=> BusType |
|
-> [DBusProxyFlags] |
|
-> Maybe DBusInterfaceInfo |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Maybe a |
|
-> m DBusProxy | Returns: A |
Like dBusProxyNewSync
but takes a BusType
instead of a DBusConnection
.
DBusProxy
is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
newSync
:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) | |
=> a |
|
-> [DBusProxyFlags] |
|
-> Maybe DBusInterfaceInfo |
|
-> Maybe Text |
|
-> Text |
|
-> Text |
|
-> Maybe b |
|
-> m DBusProxy | Returns: A |
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
::g-signal
signal
to handle signals from the remote object.
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][gdbus-wellknown-proxy].
Since: 2.26
setCachedProperty
dBusProxySetCachedProperty Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> Text |
|
-> Maybe GVariant |
|
-> 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
:g-interface-info
) 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 #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> Int32 |
|
-> m () |
Sets the timeout to use if -1 (specifying default timeout) is
passed as timeoutMsec
in the dBusProxyCall
and
dBusProxyCallSync
functions.
See the DBusProxy
:g-default-timeout
property for more details.
Since: 2.26
setInterfaceInfo
dBusProxySetInterfaceInfo Source #
:: (HasCallStack, MonadIO m, IsDBusProxy a) | |
=> a |
|
-> Maybe DBusInterfaceInfo |
|
-> m () |
Ensure that interactions with proxy
conform to the given
interface. See the DBusProxy
:g-interface-info
property for more
details.
Since: 2.26
Properties
gBusType
If this property is not BusTypeNone
, then
DBusProxy
:g-connection
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 => BusType -> IO (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, IsDBusConnection a) => a -> IO (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 => Int32 -> IO (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 => [DBusProxyFlags] -> IO (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 toIOErrorEnumInvalidArgument
. - 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 usingdBusProxySetCachedProperty
with a type signature mismatch are ignored and a warning is logged viag_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 => DBusInterfaceInfo -> IO (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 => Text -> IO (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 => Text -> IO (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
:g-name
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 => Text -> IO (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 C_DBusProxyGPropertiesChangedCallback = Ptr () -> Ptr GVariant -> Ptr CString -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type DBusProxyGPropertiesChangedCallback Source #
= GVariant |
|
-> [Text] |
|
-> 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 -> DBusProxyGPropertiesChangedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “g-properties-changed
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
dBusProxy #gPropertiesChanged callback
genClosure_DBusProxyGPropertiesChanged :: DBusProxyGPropertiesChangedCallback -> IO Closure Source #
Wrap the callback into a Closure
.
mk_DBusProxyGPropertiesChangedCallback :: C_DBusProxyGPropertiesChangedCallback -> IO (FunPtr C_DBusProxyGPropertiesChangedCallback) Source #
Generate a function pointer callable from C code, from a C_DBusProxyGPropertiesChangedCallback
.
noDBusProxyGPropertiesChangedCallback :: Maybe DBusProxyGPropertiesChangedCallback Source #
A convenience synonym for
.Nothing
:: Maybe
DBusProxyGPropertiesChangedCallback
onDBusProxyGPropertiesChanged :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGPropertiesChangedCallback -> m SignalHandlerId Source #
Connect a signal handler for the “g-properties-changed
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
dBusProxy #gPropertiesChanged callback
wrap_DBusProxyGPropertiesChangedCallback :: DBusProxyGPropertiesChangedCallback -> C_DBusProxyGPropertiesChangedCallback Source #
gSignal
type C_DBusProxyGSignalCallback = Ptr () -> CString -> CString -> Ptr GVariant -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type DBusProxyGSignalCallback Source #
= Maybe Text |
|
-> Text |
|
-> GVariant |
|
-> IO () |
Emitted when a signal from the remote object and interface that proxy
is for, has been received.
Since: 2.26
afterDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGSignalCallback -> m SignalHandlerId Source #
Connect a signal handler for the “g-signal
” signal, to be run after the default handler.
When overloading is enabled, this is equivalent to
after
dBusProxy #gSignal callback
genClosure_DBusProxyGSignal :: DBusProxyGSignalCallback -> IO Closure Source #
Wrap the callback into a Closure
.
mk_DBusProxyGSignalCallback :: C_DBusProxyGSignalCallback -> IO (FunPtr C_DBusProxyGSignalCallback) Source #
Generate a function pointer callable from C code, from a C_DBusProxyGSignalCallback
.
noDBusProxyGSignalCallback :: Maybe DBusProxyGSignalCallback Source #
A convenience synonym for
.Nothing
:: Maybe
DBusProxyGSignalCallback
onDBusProxyGSignal :: (IsDBusProxy a, MonadIO m) => a -> DBusProxyGSignalCallback -> m SignalHandlerId Source #
Connect a signal handler for the “g-signal
” signal, to be run before the default handler.
When overloading is enabled, this is equivalent to
on
dBusProxy #gSignal callback