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

Safe HaskellNone

DBus.Socket

Contents

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

Sockets

data Socket Source

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 aSource

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 ReceivedMessageSource

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 Source

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

Socket options

data SocketOptions t Source

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

socketAuthenticator :: SocketOptions t -> Authenticator tSource

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 tSource

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 SocketTransportSource

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

Opening and closing sockets

open :: Address -> IO SocketSource

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 SocketSource

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 ()Source

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

Listening for connections

listen :: Address -> IO SocketListenerSource

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 SocketListenerSource

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 SocketSource

Accept a new connection from a socket listener.

Throws SocketError on failure.

closeListener :: SocketListener -> IO ()Source

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

socketListenerAddress :: SocketListener -> AddressSource

Get the address to use to connect to a listener.

Authentication

data Authenticator t Source

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

authenticator :: Authenticator tSource

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 BoolSource

Defines the client-side half of an authenticator.

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

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