DBus.Socket

D-Bus sockets are used for communication between two peers. In this model, there is no "bus" or "client", simply two endpoints sending messages.

Most users will want to use the DBus.Client module instead.

Sockets

data Socket

An open socket to another process. Messages can be sent to the remote peer using send, or received using receive.

send :: Message msg => Socket -> msg -> (Serial -> IO a) -> IO a

Send a single message, with a generated Serial. The second parameter exists to prevent race conditions when registering a reply handler; it receives the serial the message will be sent with, before it's actually sent.

Sockets are thread-safe. Only one message may be sent at a time; if multiple threads attempt to send messages concurrently, one will block until after the other has finished.

Throws SocketError on failure.

receive :: Socket -> IO ReceivedMessage

Receive the next message from the socket , blocking until one is available.

Sockets are thread-safe. Only one message may be received at a time; if multiple threads attempt to receive messages concurrently, one will block until after the other has finished.

Throws SocketError on failure.

Socket errors

data SocketError

Stores information about an error encountered while creating or using a Socket.

Instances

Eq SocketError

Methods

(==) :: SocketError -> SocketError -> Bool

(/=) :: SocketError -> SocketError -> Bool

Show SocketError

Methods

showsPrec :: Int -> SocketError -> ShowS

show :: SocketError -> String

showList :: [SocketError] -> ShowS

Exception SocketError

Methods

toException :: SocketError -> SomeException

fromException :: SomeException -> Maybe SocketError

displayException :: SocketError -> String

socketError :: String -> SocketError

socketErrorMessage :: SocketError -> String

socketErrorFatal :: SocketError -> Bool

socketErrorAddress :: SocketError -> Maybe Address

Socket options

data SocketOptions t

Used with openWith and listenWith to provide custom authenticators or transport options.

socketAuthenticator :: SocketOptions t -> Authenticator t

Used to perform authentication with the remote peer. After a transport has been opened, it will be passed to the authenticator. If the authenticator returns true, then the socket was authenticated.

socketTransportOptions :: SocketOptions t -> TransportOptions t

Options for the underlying transport, to be used by custom transports for controlling how to connect to the remote peer.

See DBus.Transport for details on defining custom transports

defaultSocketOptions :: SocketOptions SocketTransport

Default SocketOptions, which uses the default Unix/TCP transport and authenticator.

Opening and closing sockets

open :: Address -> IO Socket

Open a socket to a remote peer listening at the given address.

open = openWith defaultSocketOptions
 

Throws SocketError on failure.

openWith :: TransportOpen t => SocketOptions t -> Address -> IO Socket

Open a socket to a remote peer listening at the given address.

Most users should use open. This function is for users who need to define custom authenticators or transports.

Throws SocketError on failure.

close :: Socket -> IO ()

Close an open Socket. Once closed, the socket is no longer valid and must not be used.

Listening for connections

data SocketListener

listen :: Address -> IO SocketListener

Begin listening at the given address.

Use accept to create sockets from incoming connections.

Use closeListener to stop listening, and to free underlying transport resources such as file descriptors.

Throws SocketError on failure.

listenWith :: TransportListen t => SocketOptions t -> Address -> IO SocketListener

Begin listening at the given address.

Use accept to create sockets from incoming connections.

Use closeListener to stop listening, and to free underlying transport resources such as file descriptors.

This function is for users who need to define custom authenticators or transports.

Throws SocketError on failure.

accept :: SocketListener -> IO Socket

Accept a new connection from a socket listener.

Throws SocketError on failure.

closeListener :: SocketListener -> IO ()

Close an open SocketListener. Once closed, the listener is no longer valid and must not be used.

socketListenerAddress :: SocketListener -> Address

Get the address to use to connect to a listener.

Authentication

data Authenticator t

An Authenticator defines how the local peer (client) authenticates itself to the remote peer (server).

authenticator :: Authenticator t

An empty authenticator. Use authenticatorClient or authenticatorServer to control how the authentication is performed.

myAuthenticator :: Authenticator MyTransport
myAuthenticator = authenticator
    { authenticatorClient = clientMyAuth
    , authenticatorServer = serverMyAuth
    }

clientMyAuth :: MyTransport -> IO Bool
serverMyAuth :: MyTransport -> String -> IO Bool
 

authenticatorClient :: Authenticator t -> t -> IO Bool

Defines the client-side half of an authenticator.

authenticatorServer :: Authenticator t -> t -> UUID -> IO Bool

Defines the server-side half of an authenticator. The UUID is allocated by the socket listener.