dbus-1.2.29: A client library for the D-Bus IPC system.
Safe HaskellSafe-Inferred
LanguageHaskell2010

DBus.Socket

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 a Source #

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

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.

Instances

Instances details
Exception SocketError Source # 
Instance details

Defined in DBus.Socket

Show SocketError Source # 
Instance details

Defined in DBus.Socket

Eq SocketError Source # 
Instance details

Defined in DBus.Socket

Socket options

data SocketOptions t Source #

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

socketAuthenticator :: SocketOptions t -> Authenticator t Source #

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

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

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

Opening and closing sockets

open :: Address -> IO Socket Source #

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

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 SocketListener Source #

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

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

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 -> Address Source #

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 t Source #

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

Defines the client-side half of an authenticator.

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

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