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

Safe Haskell | None
Language | Haskell2010

DBus.Transport

Contents

- Transports
- Transport errors
- Socket transport

Description

Support for defining custom transport mechanisms. Most users will not need to care about the types defined in this module.

Synopsis

- class Transport t where
  - data TransportOptions t
  - transportDefaultOptions :: TransportOptions t
  - transportPut :: t -> ByteString -> IO ()
  - transportPutWithFds :: t -> ByteString -> [Fd] -> IO ()
  - transportGet :: t -> Int -> IO ByteString
  - transportGetWithFds :: t -> Int -> IO (ByteString, [Fd])
  - transportClose :: t -> IO ()
- class Transport t => TransportOpen t where
  - transportOpen :: TransportOptions t -> Address -> IO t
- class Transport t => TransportListen t where
  - data TransportListener t
  - transportListen :: TransportOptions t -> Address -> IO (TransportListener t)
  - transportAccept :: TransportListener t -> IO t
  - transportListenerClose :: TransportListener t -> IO ()
  - transportListenerAddress :: TransportListener t -> Address
  - transportListenerUUID :: TransportListener t -> UUID
- data TransportError
- transportError :: String -> TransportError
- transportErrorMessage :: TransportError -> String
- transportErrorAddress :: TransportError -> Maybe Address
- data SocketTransport
- socketTransportOptionBacklog :: TransportOptions SocketTransport -> Int
- socketTransportCredentials :: SocketTransport -> IO (Maybe CUInt, Maybe CUInt, Maybe CUInt)

# Transports

class Transport t where #

A `Transport` can exchange bytes with a remote peer.

Minimal complete definition

transportDefaultOptions, transportPut, transportGet, transportClose

Associated Types

data TransportOptions t #

Additional options that this transport type may use when establishing a connection.

Methods

transportDefaultOptions :: TransportOptions t #

Default values for this transport's options.

transportPut :: t -> ByteString -> IO () #

Send a `ByteString` over the transport.

Throws a `TransportError` if an error occurs.

transportPutWithFds :: t -> ByteString -> [Fd] -> IO () #

Send a `ByteString` and Unix file descriptors over the transport.

Throws a `TransportError` if an error occurs.

transportGet :: t -> Int -> IO ByteString #

Receive a `ByteString` of the given size from the transport. The transport should block until sufficient bytes are available, and only return fewer than the requested amount if there will not be any more data.

Throws a `TransportError` if an error occurs.

transportGetWithFds :: t -> Int -> IO (ByteString, [Fd]) #

Receive a `ByteString` of the given size from the transport, plus any Unix file descriptors that arrive with the byte data. The transport should block until sufficient bytes are available, and only return fewer than the requested amount if there will not be any more data.

Throws a `TransportError` if an error occurs.

transportClose :: t -> IO () #

Close an open transport, and release any associated resources or handles.

#### Instances

Instances details

Transport SocketTransport # |
Instance details Defined in DBus.Transport Associated Types
data TransportOptions SocketTransport |
Instance details Defined in DBus.Transport data TransportOptions SocketTransport = SocketTransportOptions { socketTransportOptionBacklog :: Int }
Methods transportDefaultOptions :: TransportOptions SocketTransport # transportPut :: SocketTransport -> ByteString -> IO () # transportPutWithFds :: SocketTransport -> ByteString -> [Fd] -> IO () # transportGet :: SocketTransport -> Int -> IO ByteString # transportGetWithFds :: SocketTransport -> Int -> IO (ByteString, [Fd]) # transportClose :: SocketTransport -> IO () #

class Transport t => TransportOpen t where #

A `Transport` which can open a connection to a remote peer.

Methods

transportOpen :: TransportOptions t -> Address -> IO t #

Open a connection to the given address, using the given options.

Throws a `TransportError` if the connection could not be established.

#### Instances

Instances details

TransportOpen SocketTransport # |
Instance details Defined in DBus.Transport Methods transportOpen :: TransportOptions SocketTransport -> Address -> IO SocketTransport #

class Transport t => TransportListen t where #

A `Transport` which can listen for and accept connections from remote peers.

Associated Types

data TransportListener t #

Used for transports that listen on a port or address.

Methods

transportListen :: TransportOptions t -> Address -> IO (TransportListener t) #

Begin listening for connections on the given address, using the given options.

Throws a `TransportError` if it's not possible to listen at that address (for example, if the port is already in use).

transportAccept :: TransportListener t -> IO t #

Accept a new connection.

Throws a `TransportError` if some error happens before the transport is ready to exchange bytes.

transportListenerClose :: TransportListener t -> IO () #

Close an open listener.

transportListenerAddress :: TransportListener t -> Address #

Get the address to use to connect to a listener.

transportListenerUUID :: TransportListener t -> UUID #

Get the UUID allocated to this transport listener.

See `randomUUID`.

#### Instances

Instances details

TransportListen SocketTransport # |
Instance details Defined in DBus.Transport Associated Types
data TransportListener SocketTransport |
Instance details Defined in DBus.Transport data TransportListener SocketTransport = SocketTransportListener Address UUID Socket
Methods transportListen :: TransportOptions SocketTransport -> Address -> IO (TransportListener SocketTransport) # transportAccept :: TransportListener SocketTransport -> IO SocketTransport # transportListenerClose :: TransportListener SocketTransport -> IO () # transportListenerAddress :: TransportListener SocketTransport -> Address # transportListenerUUID :: TransportListener SocketTransport -> UUID #

# Transport errors

data TransportError #

Thrown from transport methods when an error occurs.

#### Instances

Instances details

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

transportError :: String -> TransportError #

transportErrorMessage :: TransportError -> String #

transportErrorAddress :: TransportError -> Maybe Address #

# Socket transport

data SocketTransport #

Supports connecting over Unix or TCP sockets.

Unix sockets are similar to pipes, but exist as special files in the filesystem. On Linux, abstract sockets have a path-like address, but do not actually have entries in the filesystem.

TCP sockets may use either IPv4 or IPv6.

#### Instances

Instances details

Transport SocketTransport # |
Instance details Defined in DBus.Transport Associated Types
data TransportOptions SocketTransport |
Instance details Defined in DBus.Transport data TransportOptions SocketTransport = SocketTransportOptions { socketTransportOptionBacklog :: Int }
Methods transportDefaultOptions :: TransportOptions SocketTransport # transportPut :: SocketTransport -> ByteString -> IO () # transportPutWithFds :: SocketTransport -> ByteString -> [Fd] -> IO () # transportGet :: SocketTransport -> Int -> IO ByteString # transportGetWithFds :: SocketTransport -> Int -> IO (ByteString, [Fd]) # transportClose :: SocketTransport -> IO () #
TransportListen SocketTransport # |
Instance details Defined in DBus.Transport Associated Types
data TransportListener SocketTransport |
Instance details Defined in DBus.Transport data TransportListener SocketTransport = SocketTransportListener Address UUID Socket
Methods transportListen :: TransportOptions SocketTransport -> Address -> IO (TransportListener SocketTransport) # transportAccept :: TransportListener SocketTransport -> IO SocketTransport # transportListenerClose :: TransportListener SocketTransport -> IO () # transportListenerAddress :: TransportListener SocketTransport -> Address # transportListenerUUID :: TransportListener SocketTransport -> UUID #
TransportOpen SocketTransport # |
Instance details Defined in DBus.Transport Methods transportOpen :: TransportOptions SocketTransport -> Address -> IO SocketTransport #
data TransportListener SocketTransport # |
Instance details Defined in DBus.Transport data TransportListener SocketTransport = SocketTransportListener Address UUID Socket
data TransportOptions SocketTransport # |
Instance details Defined in DBus.Transport data TransportOptions SocketTransport = SocketTransportOptions { socketTransportOptionBacklog :: Int }

socketTransportOptionBacklog :: TransportOptions SocketTransport -> Int #

socketTransportCredentials :: SocketTransport -> IO (Maybe CUInt, Maybe CUInt, Maybe CUInt) #

Returns the processID, userID, and groupID of the socket's peer.

See `getPeerCredential`.