gi-gio-2.0.11: Gio bindings

CopyrightWill Thompson, Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gio.Objects.DBusObjectManagerClient

Contents

Description

DBusObjectManagerClient is used to create, monitor and delete object proxies for remote objects exported by a DBusObjectManagerServer (or any code implementing the org.freedesktop.DBus.ObjectManager interface).

Once an instance of this type has been created, you can connect to the DBusObjectManager::object-added and DBusObjectManager::object-removed signals and inspect the DBusObjectProxy objects returned by dBusObjectManagerGetObjects.

If the name for a DBusObjectManagerClient is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be disabled using the DBusObjectManagerClientFlagsDoNotAutoStart flag. It's also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this case, DBusObjectManagerClient object construction still succeeds but there will be no object proxies (e.g. dBusObjectManagerGetObjects returns the empty list) and the DBusObjectManagerClient:name-owner property is Nothing.

The owner of the requested name can come and go (for example consider a system service being restarted) – DBusObjectManagerClient handles this case too; simply connect to the Object::notify signal to watch for changes on the DBusObjectManagerClient:name-owner property. When the name owner vanishes, the behavior is that DBusObjectManagerClient:name-owner is set to Nothing (this includes emission of the Object::notify signal) and then DBusObjectManager::object-removed signals are synthesized for all currently existing object proxies. Since DBusObjectManagerClient:name-owner is Nothing when this happens, you can use this information to disambiguate a synthesized signal from a genuine signal caused by object removal on the remote DBusObjectManager. Similarly, when a new name owner appears, DBusObjectManager::object-added signals are synthesized while DBusObjectManagerClient:name-owner is still Nothing. Only when all object proxies have been added, the DBusObjectManagerClient:name-owner is set to the new name owner (this includes emission of the Object::notify signal). Furthermore, you are guaranteed that DBusObjectManagerClient:name-owner will alternate between a name owner (e.g. :1.42) and Nothing even in the case where the name of interest is atomically replaced

Ultimately, DBusObjectManagerClient is used to obtain DBusProxy instances. All signals (including the org.freedesktop.DBus.Properties::PropertiesChanged signal) delivered to DBusProxy instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the "half the proxy is from the old owner and the other half is from the new owner" problem cannot happen.

To avoid having the application connect to signals on the returned DBusObjectProxy and DBusProxy objects, the DBusObject::interface-added, DBusObject::interface-removed, DBusProxy::g-properties-changed and DBusProxy::g-signal signals are also emitted on the DBusObjectManagerClient instance managing these objects. The signals emitted are DBusObjectManager::interface-added, DBusObjectManager::interface-removed, DBusObjectManagerClient::interface-proxy-properties-changed and DBusObjectManagerClient::interface-proxy-signal.

Note that all callbacks and signals are emitted in the [thread-default main context][g-main-context-push-thread-default] that the DBusObjectManagerClient object was constructed in. Additionally, the DBusObjectProxy and DBusProxy objects originating from the DBusObjectManagerClient object will be created in the same context and, consequently, will deliver signals in the same main loop.

Synopsis

Exported types

Methods

getConnection

dBusObjectManagerClientGetConnection Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusObjectManagerClient a) 
=> a

manager: A DBusObjectManagerClient

-> m DBusConnection

Returns: A DBusConnection object. Do not free, the object belongs to manager.

Gets the DBusConnection used by manager.

Since: 2.30

getFlags

dBusObjectManagerClientGetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusObjectManagerClient a) 
=> a

manager: A DBusObjectManagerClient

-> m [DBusObjectManagerClientFlags]

Returns: Zero of more flags from the DBusObjectManagerClientFlags enumeration.

Gets the flags that manager was constructed with.

Since: 2.30

getName

dBusObjectManagerClientGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusObjectManagerClient a) 
=> a

manager: A DBusObjectManagerClient

-> m Text

Returns: A unique or well-known name. Do not free, the string belongs to manager.

Gets the name that manager is for, or Nothing if not a message bus connection.

Since: 2.30

getNameOwner

dBusObjectManagerClientGetNameOwner Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusObjectManagerClient a) 
=> a

manager: A DBusObjectManagerClient.

-> 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 manager is for or Nothing if no-one currently owns that name. You can connect to the Object::notify signal to track changes to the DBusObjectManagerClient:name-owner property.

Since: 2.30

new

dBusObjectManagerClientNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) 
=> a

connection: A DBusConnection.

-> [DBusObjectManagerClientFlags]

flags: Zero or more flags from the DBusObjectManagerClientFlags enumeration.

-> Text

name: The owner of the control object (unique or well-known name).

-> Text

objectPath: The object path of the control object.

-> Maybe DBusProxyTypeFunc

getProxyTypeFunc: A DBusProxyTypeFunc function or Nothing to always construct DBusProxy proxies.

-> Maybe b

cancellable: A Cancellable or Nothing

-> Maybe AsyncReadyCallback

callback: A AsyncReadyCallback to call when the request is satisfied.

-> m () 

Asynchronously creates a new DBusObjectManagerClient object.

This is an asynchronous failable constructor. When the result is ready, 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 dBusObjectManagerClientNewFinish to get the result. See dBusObjectManagerClientNewSync for the synchronous version.

Since: 2.30

newFinish

dBusObjectManagerClientNewFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a) 
=> a

res: A AsyncResult obtained from the AsyncReadyCallback passed to dBusObjectManagerClientNew.

-> m DBusObjectManagerClient

Returns: A DBusObjectManagerClient object or Nothing if error is set. Free with objectUnref. (Can throw GError)

Finishes an operation started with dBusObjectManagerClientNew.

Since: 2.30

newForBus

dBusObjectManagerClientNewForBus Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a) 
=> BusType

busType: A BusType.

-> [DBusObjectManagerClientFlags]

flags: Zero or more flags from the DBusObjectManagerClientFlags enumeration.

-> Text

name: The owner of the control object (unique or well-known name).

-> Text

objectPath: The object path of the control object.

-> Maybe DBusProxyTypeFunc

getProxyTypeFunc: A DBusProxyTypeFunc function or Nothing to always construct DBusProxy proxies.

-> Maybe a

cancellable: A Cancellable or Nothing

-> Maybe AsyncReadyCallback

callback: A AsyncReadyCallback to call when the request is satisfied.

-> m () 

Like dBusObjectManagerClientNew but takes a BusType instead of a DBusConnection.

This is an asynchronous failable constructor. When the result is ready, callback will be invoked in the [thread-default main loop][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call dBusObjectManagerClientNewForBusFinish to get the result. See dBusObjectManagerClientNewForBusSync for the synchronous version.

Since: 2.30

newForBusFinish

dBusObjectManagerClientNewForBusFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a) 
=> a

res: A AsyncResult obtained from the AsyncReadyCallback passed to dBusObjectManagerClientNewForBus.

-> m DBusObjectManagerClient

Returns: A DBusObjectManagerClient object or Nothing if error is set. Free with objectUnref. (Can throw GError)

Finishes an operation started with dBusObjectManagerClientNewForBus.

Since: 2.30

newForBusSync

dBusObjectManagerClientNewForBusSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a) 
=> BusType

busType: A BusType.

-> [DBusObjectManagerClientFlags]

flags: Zero or more flags from the DBusObjectManagerClientFlags enumeration.

-> Text

name: The owner of the control object (unique or well-known name).

-> Text

objectPath: The object path of the control object.

-> Maybe DBusProxyTypeFunc

getProxyTypeFunc: A DBusProxyTypeFunc function or Nothing to always construct DBusProxy proxies.

-> Maybe a

cancellable: A Cancellable or Nothing

-> m DBusObjectManagerClient

Returns: A DBusObjectManagerClient object or Nothing if error is set. Free with objectUnref. (Can throw GError)

Like dBusObjectManagerClientNewSync but takes a BusType instead of a DBusConnection.

This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See dBusObjectManagerClientNewForBus for the asynchronous version.

Since: 2.30

newSync

dBusObjectManagerClientNewSync Source #

Arguments

:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) 
=> a

connection: A DBusConnection.

-> [DBusObjectManagerClientFlags]

flags: Zero or more flags from the DBusObjectManagerClientFlags enumeration.

-> Maybe Text

name: The owner of the control object (unique or well-known name), or Nothing when not using a message bus connection.

-> Text

objectPath: The object path of the control object.

-> Maybe DBusProxyTypeFunc

getProxyTypeFunc: A DBusProxyTypeFunc function or Nothing to always construct DBusProxy proxies.

-> Maybe b

cancellable: A Cancellable or Nothing

-> m DBusObjectManagerClient

Returns: A DBusObjectManagerClient object or Nothing if error is set. Free with objectUnref. (Can throw GError)

Creates a new DBusObjectManagerClient object.

This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See dBusObjectManagerClientNew for the asynchronous version.

Since: 2.30

Properties

busType

data DBusObjectManagerClientBusTypePropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrLabel DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrGetType DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientBusTypePropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientBusTypePropertyInfo Source # 

connection

data DBusObjectManagerClientConnectionPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientConnectionPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientConnectionPropertyInfo Source # 

flags

data DBusObjectManagerClientFlagsPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientFlagsPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientFlagsPropertyInfo Source # 

getProxyTypeDestroyNotify

data DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientGetProxyTypeDestroyNotifyPropertyInfo Source # 

getProxyTypeFunc

data DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientGetProxyTypeFuncPropertyInfo Source # 

getProxyTypeUserData

data DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientGetProxyTypeUserDataPropertyInfo Source # 

name

data DBusObjectManagerClientNamePropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientNamePropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientNamePropertyInfo Source # 
type AttrLabel DBusObjectManagerClientNamePropertyInfo Source # 
type AttrGetType DBusObjectManagerClientNamePropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientNamePropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientNamePropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientNamePropertyInfo Source # 

nameOwner

data DBusObjectManagerClientNameOwnerPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientNameOwnerPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientNameOwnerPropertyInfo Source # 

objectPath

data DBusObjectManagerClientObjectPathPropertyInfo Source #

Instances

AttrInfo DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrOrigin DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrLabel DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrGetType DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrBaseTypeConstraint DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrSetTypeConstraint DBusObjectManagerClientObjectPathPropertyInfo Source # 
type AttrAllowedOps DBusObjectManagerClientObjectPathPropertyInfo Source # 

Signals

interfaceProxyPropertiesChanged

interfaceProxySignal