DBus.Socket

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

Safe Haskell | None
Language | Haskell98

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
- 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

Eq SocketError |
Show SocketError |
Exception SocketError |

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.