DBus.Client

Documentation

module DBus.Bus

module DBus.Types

module DBus.Message

Clients

data Client

Clients are opaque handles to an open connection and other internal state.

data Connection

Instances

Show Connection

clientName :: Client -> BusName

newClient :: (Connection, BusName) -> IO Client

Create a new Client from an open connection and bus name. The weird signature allows newClient to use the computations in DBus.Bus directly, without unpacking:

 client <- newClient =<< getSessionBus

Only one client should be created for any given connection. Otherwise, they will compete to receive messages.

data DBus a

Instances

Monad DBus

Functor DBus

Applicative DBus

MonadIO DBus

MonadError DBus

data DBusException

Instances

Eq DBusException

Show DBusException

Typeable DBusException

Exception DBusException

runDBus :: Client -> DBus a -> IO a

Run a DBus computation with the given client callbacks. Errors encountered while running will be thrown as exceptions, using the DBusException type.

Use the MonadError instance for DBus to handle errors inside the computation.

getClient :: DBus Client

processMessage :: ReceivedMessage -> DBus ()

Run message handlers with the received message. If any method reply callbacks or signal handlers are found, they will be run in the current thread.

send :: Message msg => (Serial -> DBus a) -> msg -> DBus a

A wrapper around send.

send_ :: Message msg => msg -> DBus ()

A wrapper around send, which does not allow the message serial to be recorded. This is a useful shortcut when sending messages which are not expected to receive a reply.

receive :: DBus ReceivedMessage

A wrapper around receive.

mainLoop :: DBus ()

Run in a loop forever, processing messages.

This is commonly run in a separate thread, ie

 client <- newClient =<< getSessionBus
 forkIO $ runDBus client mainLoop

call :: MethodCall -> (Error -> DBus ()) -> (MethodReturn -> DBus ()) -> DBus ()

Perform an asynchronous method call. One of the provided computations will be performed depending on what message type the destination sends back.

callBlocking :: MethodCall -> DBus (Either Error MethodReturn)

Sends a method call, and then blocks until a reply is received. Use this when the receive/process loop is running in a separate thread.

callBlocking_ :: MethodCall -> DBus MethodReturn

A variant of callBlocking, which throws an exception if the remote client returns Error.

Handling signals

onSignal :: MatchRule -> (BusName -> Signal -> DBus ()) -> DBus ()

Perform some computation every time this client receives a matching signal.

Name reservation

data RequestNameFlag

Constructors

AllowReplacement

ReplaceExisting

DoNotQueue

Instances

Show RequestNameFlag

data RequestNameReply

Constructors

PrimaryOwner

InQueue

Exists

AlreadyOwner

Instances

Show RequestNameReply

data ReleaseNameReply

Constructors

Released

NonExistent

NotOwner

Instances

Show ReleaseNameReply

requestName :: BusName -> [RequestNameFlag] -> (Error -> DBus ()) -> (RequestNameReply -> DBus ()) -> DBus ()

releaseName :: BusName -> (Error -> DBus ()) -> (ReleaseNameReply -> DBus ()) -> DBus ()

requestName_ :: BusName -> [RequestNameFlag] -> DBus RequestNameReply

releaseName_ :: BusName -> DBus ReleaseNameReply

Exporting local objects

newtype Object

Constructors

Object (Map InterfaceName Interface)

newtype Interface

Constructors

Interface (Map MemberName Member)

data Member

Constructors

MemberMethod Method

MemberSignal Signature

data Method

Constructors

Method Signature Signature (MethodCtx -> DBus ())

export :: ObjectPath -> Object -> DBus ()

Export a set of interfaces on the bus. Whenever a method call is received which matches the object's path, interface, and member name, one of its members will be called.

Exported objects automatically implement the org.freedesktop.DBus.Introspectable interface.

object :: [(InterfaceName, Interface)] -> Object

interface :: [(MemberName, Member)] -> Interface

method

Arguments

:: Signature

Input signature

-> Signature

Output signature

-> (MethodCtx -> DBus ())

Implementation

-> Member

Responding to method calls

data MethodCtx

Constructors

MethodCtx

Fields

methodCtxObject :: Object

methodCtxMethod :: Method

methodCtxSerial :: Serial

methodCtxSender :: Maybe BusName

methodCtxFlags :: Set Flag

methodCtxBody :: [Variant]

replyReturn :: MethodCtx -> [Variant] -> DBus ()

Send a successful return reply for a method call.

replyError :: MethodCtx -> ErrorName -> [Variant] -> DBus ()

data Proxy

Constructors

Proxy

Fields

proxyName :: BusName

proxyObjectPath :: ObjectPath

proxyInterface :: InterfaceName

Instances

Eq Proxy

Show Proxy

callProxy :: Proxy -> MemberName -> [Flag] -> [Variant] -> (Error -> DBus ()) -> (MethodReturn -> DBus ()) -> DBus ()

As call, except that the proxy's information is used to build the message.

callProxyBlocking :: Proxy -> MemberName -> [Flag] -> [Variant] -> DBus (Either Error MethodReturn)

As callBlocking, except that the proxy's information is used to build the message.

callProxyBlocking_ :: Proxy -> MemberName -> [Flag] -> [Variant] -> DBus MethodReturn

As callBlocking_, except that the proxy's information is used to build the message.

onProxySignal :: Proxy -> MemberName -> (Signal -> DBus ()) -> DBus ()

As onSIgnal, except that the proxy's information is used to build the match rule.