DBus.Socket

dbus-1.3.11: A client library for the D-Bus IPC system.

Safe Haskell | None
Language | Haskell2010

DBus.Socket

Contents

- Sockets
- Socket errors
- Socket options
- Opening and closing sockets
- Listening for connections
- Authentication

Description

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.

Synopsis

- data Socket
- send :: Message msg => Socket -> msg -> (Serial -> IO a) -> IO a
- receive :: Socket -> IO ReceivedMessage
- data SocketError
- socketError :: String -> SocketError
- socketErrorMessage :: SocketError -> String
- socketErrorFatal :: SocketError -> Bool
- socketErrorAddress :: SocketError -> Maybe Address
- data SocketOptions t
- socketAuthenticator :: SocketOptions t -> Authenticator t
- socketTransportOptions :: SocketOptions t -> TransportOptions t
- defaultSocketOptions :: SocketOptions SocketTransport
- open :: Address -> IO Socket
- openWith :: TransportOpen t => SocketOptions t -> Address -> IO Socket
- close :: Socket -> IO ()
- data SocketListener
- listen :: Address -> IO SocketListener
- listenWith :: TransportListen t => SocketOptions t -> Address -> IO SocketListener
- accept :: SocketListener -> IO Socket
- closeListener :: SocketListener -> IO ()
- socketListenerAddress :: SocketListener -> Address
- data Authenticator t
- authenticator :: Authenticator t
- authenticatorWithUnixFds :: Authenticator SocketTransport
- authenticatorClient :: Authenticator t -> t -> IO Bool
- authenticatorServer :: Authenticator t -> t -> UUID -> IO Bool

# 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

Instances details

Exception SocketError # |
Instance details Defined in DBus.Socket Methods toException :: SocketError -> SomeException # fromException :: SomeException -> Maybe SocketError # displayException :: SocketError -> String # backtraceDesired :: SocketError -> Bool #
Show SocketError # |
Instance details Defined in DBus.Socket Methods showsPrec :: Int -> SocketError -> ShowS # show :: SocketError -> String # showList :: [SocketError] -> ShowS #
Eq SocketError # |
Instance details Defined in DBus.Socket Methods (==) :: SocketError -> SocketError -> Bool # (/=) :: SocketError -> SocketError -> Bool #

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 (without support for Unix file descriptor passing).

# 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

authenticatorWithUnixFds :: Authenticator SocketTransport #

An authenticator that implements the D-Bus `EXTERNAL` mechanism, which uses credential passing over a Unix socket, with support for Unix file descriptor passing.

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.