Safe Haskell | Safe-Infered |
---|
Basic types, useful to every D-Bus application.
Authors of client applications should import DBus.Client, which provides an easy RPC-oriented interface to D-Bus methods and signals.
- class Message a
- data MethodCall
- methodCall :: ObjectPath -> InterfaceName -> MemberName -> MethodCall
- methodCallPath :: MethodCall -> ObjectPath
- methodCallInterface :: MethodCall -> Maybe InterfaceName
- methodCallMember :: MethodCall -> MemberName
- methodCallSender :: MethodCall -> Maybe BusName
- methodCallDestination :: MethodCall -> Maybe BusName
- methodCallAutoStart :: MethodCall -> Bool
- methodCallReplyExpected :: MethodCall -> Bool
- methodCallBody :: MethodCall -> [Variant]
- data MethodReturn
- methodReturn :: Serial -> MethodReturn
- methodReturnSerial :: MethodReturn -> Serial
- methodReturnSender :: MethodReturn -> Maybe BusName
- methodReturnDestination :: MethodReturn -> Maybe BusName
- methodReturnBody :: MethodReturn -> [Variant]
- data MethodError
- methodError :: Serial -> ErrorName -> MethodError
- methodErrorName :: MethodError -> ErrorName
- methodErrorSerial :: MethodError -> Serial
- methodErrorSender :: MethodError -> Maybe BusName
- methodErrorDestination :: MethodError -> Maybe BusName
- methodErrorBody :: MethodError -> [Variant]
- methodErrorMessage :: MethodError -> String
- data Signal
- signal :: ObjectPath -> InterfaceName -> MemberName -> Signal
- signalPath :: Signal -> ObjectPath
- signalMember :: Signal -> MemberName
- signalInterface :: Signal -> InterfaceName
- signalSender :: Signal -> Maybe BusName
- signalDestination :: Signal -> Maybe BusName
- signalBody :: Signal -> [Variant]
- data ReceivedMessage
- receivedMessageSerial :: ReceivedMessage -> Serial
- receivedMessageSender :: ReceivedMessage -> Maybe BusName
- receivedMessageBody :: ReceivedMessage -> [Variant]
- data Variant
- class IsVariant a where
- toVariant :: a -> Variant
- fromVariant :: Variant -> Maybe a
- variantType :: Variant -> Type
- class IsValue a => IsAtom a
- class IsVariant a => IsValue a
- typeOf :: IsValue a => a -> Type
- data Signature
- data Type
- = TypeBoolean
- | TypeWord8
- | TypeWord16
- | TypeWord32
- | TypeWord64
- | TypeInt16
- | TypeInt32
- | TypeInt64
- | TypeDouble
- | TypeString
- | TypeSignature
- | TypeObjectPath
- | TypeVariant
- | TypeArray Type
- | TypeDictionary Type Type
- | TypeStructure [Type]
- signature :: [Type] -> Maybe Signature
- signature_ :: [Type] -> Signature
- signatureTypes :: Signature -> [Type]
- formatSignature :: Signature -> String
- parseSignature :: String -> Maybe Signature
- data ObjectPath
- objectPath_ :: String -> ObjectPath
- formatObjectPath :: ObjectPath -> String
- parseObjectPath :: String -> Maybe ObjectPath
- data InterfaceName
- interfaceName_ :: String -> InterfaceName
- formatInterfaceName :: InterfaceName -> String
- parseInterfaceName :: String -> Maybe InterfaceName
- data MemberName
- memberName_ :: String -> MemberName
- formatMemberName :: MemberName -> String
- parseMemberName :: String -> Maybe MemberName
- data ErrorName
- errorName_ :: String -> ErrorName
- formatErrorName :: ErrorName -> String
- parseErrorName :: String -> Maybe ErrorName
- data BusName
- busName_ :: String -> BusName
- formatBusName :: BusName -> String
- parseBusName :: String -> Maybe BusName
- data Structure
- structureItems :: Structure -> [Variant]
- data Array
- arrayItems :: Array -> [Variant]
- data Dictionary
- dictionaryItems :: Dictionary -> [(Variant, Variant)]
- data Address
- addressMethod :: Address -> String
- addressParameters :: Address -> Map String String
- address :: String -> Map String String -> Maybe Address
- formatAddress :: Address -> String
- formatAddresses :: [Address] -> String
- parseAddress :: String -> Maybe Address
- parseAddresses :: String -> Maybe [Address]
- getSystemAddress :: IO (Maybe Address)
- getSessionAddress :: IO (Maybe Address)
- getStarterAddress :: IO (Maybe Address)
- data Endianness
- marshal :: Message msg => Endianness -> Serial -> msg -> Either MarshalError ByteString
- data MarshalError
- marshalErrorMessage :: MarshalError -> String
- unmarshal :: ByteString -> Either UnmarshalError ReceivedMessage
- data UnmarshalError
- unmarshalErrorMessage :: UnmarshalError -> String
- data Serial
- serialValue :: Serial -> Word32
- firstSerial :: Serial
- nextSerial :: Serial -> Serial
- data UUID
- formatUUID :: UUID -> String
- randomUUID :: IO UUID
Messages
Method calls
data MethodCall Source
A method call is a request to run some procedure exported by the remote process. Procedures are identified by an (object_path, interface_name, method_name) tuple.
methodCall :: ObjectPath -> InterfaceName -> MemberName -> MethodCallSource
Construct a new MethodCall
for the given object, interface, and method.
Use fields such as methodCallDestination
and methodCallBody
to populate
a MethodCall
.
{-# LANGUAGE OverloadedStrings #-} methodCall "/" "org.example.Math" "Add" {methodCallDestination
= Just "org.example.Calculator" ,methodCallBody
= [toVariant
(1 :: Int32),toVariant
(2 :: Int32)] }
methodCallPath :: MethodCall -> ObjectPathSource
The object path of the method call. Conceptually, object paths act like a procedural language's pointers. Each object referenced by a path is a collection of procedures.
methodCallInterface :: MethodCall -> Maybe InterfaceNameSource
The interface of the method call. Each object may implement any number of interfaces. Each method is part of at least one interface.
In certain cases, this may be Nothing
, but most users should set
it to a value.
methodCallMember :: MethodCall -> MemberNameSource
The method name of the method call. Method names are unique within an interface, but might not be unique within an object.
methodCallSender :: MethodCall -> Maybe BusNameSource
The name of the application that sent this call.
Most users will just leave this empty, because the bus overwrites the sender for security reasons. Setting the sender manually is used for peer-peer connections.
Defaults to Nothing
.
methodCallDestination :: MethodCall -> Maybe BusNameSource
The name of the application to send the call to.
Most users should set this. If a message with no destination is
sent to the bus, the bus will behave as if the destination was
set to org.freedesktop.DBus
. For peer-peer connections, the
destination can be empty because there is only one peer.
Defaults to Nothing
.
methodCallAutoStart :: MethodCall -> BoolSource
Set whether the bus should auto-start the remote
Defaults to True
.
methodCallReplyExpected :: MethodCall -> BoolSource
Set whether a reply is expected. This can save network and cpu resources by inhibiting unnecessary replies.
Defaults to True
.
methodCallBody :: MethodCall -> [Variant]Source
The arguments to the method call. See toVariant
.
Defaults to []
.
Method returns
data MethodReturn Source
A method return is a reply to a method call, indicating that the call succeeded.
methodReturn :: Serial -> MethodReturnSource
Construct a new MethodReturn
, in reply to a method call with the given
serial.
Use fields such as methodReturnBody
to populate a MethodReturn
.
methodReturnSerial :: MethodReturn -> SerialSource
The serial of the original method call. This lets the original caller match up this reply to the pending call.
methodReturnSender :: MethodReturn -> Maybe BusNameSource
The name of the application that is returning from a call.
Most users will just leave this empty, because the bus overwrites the sender for security reasons. Setting the sender manually is used for peer-peer connections.
Defaults to Nothing
.
methodReturnDestination :: MethodReturn -> Maybe BusNameSource
The name of the application that initiated the call.
Most users should set this. If a message with no destination is
sent to the bus, the bus will behave as if the destination was
set to org.freedesktop.DBus
. For peer-peer connections, the
destination can be empty because there is only one peer.
Defaults to Nothing
.
methodReturnBody :: MethodReturn -> [Variant]Source
Values returned from the method call. See toVariant
.
Defaults to []
.
Method errors
data MethodError Source
A method error is a reply to a method call, indicating that the call received an error and did not succeed.
methodError :: Serial -> ErrorName -> MethodErrorSource
Construct a new MethodError
, in reply to a method call with the given
serial.
Use fields such as methodErrorBody
to populate a MethodError
.
methodErrorName :: MethodError -> ErrorNameSource
The name of the error type. Names are used so clients can handle certain classes of error differently from others.
methodErrorSerial :: MethodError -> SerialSource
The serial of the original method call. This lets the original caller match up this reply to the pending call.
methodErrorSender :: MethodError -> Maybe BusNameSource
The name of the application that is returning from a call.
Most users will just leave this empty, because the bus overwrites the sender for security reasons. Setting the sender manually is used for peer-peer connections.
Defaults to Nothing
.
methodErrorDestination :: MethodError -> Maybe BusNameSource
The name of the application that initiated the call.
Most users should set this. If a message with no destination is
sent to the bus, the bus will behave as if the destination was
set to org.freedesktop.DBus
. For peer-peer connections, the
destination can be empty because there is only one peer.
Defaults to Nothing
.
methodErrorBody :: MethodError -> [Variant]Source
Additional information about the error. By convention, if the error body contains any items, the first item should be a string describing the error.
methodErrorMessage :: MethodError -> StringSource
Get a human-readable description of the error, by returning the first item in the error body if it's a string.
Signals
Signals are broadcast by applications to notify other clients of some event.
signal :: ObjectPath -> InterfaceName -> MemberName -> SignalSource
Construct a new Signal
for the given object, interface, and signal name.
Use fields such as signalBody
to populate a Signal
.
signalPath :: Signal -> ObjectPathSource
The path of the object that emitted this signal.
signalMember :: Signal -> MemberNameSource
The name of this signal.
signalInterface :: Signal -> InterfaceNameSource
The interface that this signal belongs to.
signalSender :: Signal -> Maybe BusNameSource
The name of the application that emitted this signal.
Most users will just leave this empty, because the bus overwrites the sender for security reasons. Setting the sender manually is used for peer-peer connections.
Defaults to Nothing
.
signalDestination :: Signal -> Maybe BusNameSource
The name of the application to emit the signal to. If Nothing
,
the signal is sent to any application that has registered an
appropriate match rule.
Defaults to Nothing
.
signalBody :: Signal -> [Variant]Source
Additional information about the signal, such as the new value or the time.
Defaults to []
.
Received messages
data ReceivedMessage Source
Not an actual message type, but a wrapper around messages received from
the bus. Each value contains the message's Serial
.
If casing against these constructors, always include a default case to handle messages of an unknown type. New message types may be added to the D-Bus specification, and applications should handle them gracefully by either ignoring or logging them.
receivedMessageSerial :: ReceivedMessage -> SerialSource
No matter what sort of message was received, get its serial.
receivedMessageSender :: ReceivedMessage -> Maybe BusNameSource
No matter what sort of message was received, get its sender (if provided).
receivedMessageBody :: ReceivedMessage -> [Variant]Source
No matter what sort of message was received, get its body (if provided).
Variants
Variants may contain any other built-in D-Bus value. Besides
representing native VARIANT
values, they allow type-safe storage and
inspection of D-Bus collections.
variantType :: Variant -> TypeSource
Every variant is strongly-typed; that is, the type of its contained value is known at all times. This function retrieves that type, so that the correct cast can be used to retrieve the value.
class IsValue a => IsAtom a Source
Atomic types can be used as keys to dictionaries.
Users may not provide new instances of IsAtom
because this could allow
dictionaries to be created with invalid keys.
class IsVariant a => IsValue a Source
Value types can be used as items in containers, such as lists or dictionaries.
Users may not provide new instances of IsValue
because this could allow
containers to be created with items of heterogenous types.
IsValue Bool | |
IsValue Double | |
IsValue Int16 | |
IsValue Int32 | |
IsValue Int64 | |
IsValue Word8 | |
IsValue Word16 | |
IsValue Word32 | |
IsValue Word64 | |
IsValue String | |
IsValue ByteString | |
IsValue ByteString | |
IsValue Text | |
IsValue Text | |
IsValue ObjectPath | |
IsValue Variant | |
IsValue Signature | |
IsValue a => IsValue [a] | |
IsValue a => IsValue (Vector a) | |
(IsValue a1, IsValue a2) => IsValue (a1, a2) | |
(Ord k, IsAtom k, IsValue v) => IsValue (Map k v) | |
(IsValue a1, IsValue a2, IsValue a3) => IsValue (a1, a2, a3) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4) => IsValue (a1, a2, a3, a4) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5) => IsValue (a1, a2, a3, a4, a5) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6) => IsValue (a1, a2, a3, a4, a5, a6) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7) => IsValue (a1, a2, a3, a4, a5, a6, a7) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10, IsValue a11) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10, IsValue a11, IsValue a12) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10, IsValue a11, IsValue a12, IsValue a13) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10, IsValue a11, IsValue a12, IsValue a13, IsValue a14) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14) | |
(IsValue a1, IsValue a2, IsValue a3, IsValue a4, IsValue a5, IsValue a6, IsValue a7, IsValue a8, IsValue a9, IsValue a10, IsValue a11, IsValue a12, IsValue a13, IsValue a14, IsValue a15) => IsValue (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15) |
typeOf :: IsValue a => a -> TypeSource
Get the D-Bus type corresponding to the given Haskell value. The value
may be undefined
.
Signatures
A signature is a list of D-Bus types, obeying some basic rules of validity.
The rules of signature validity are complex: see http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures for details.
signature :: [Type] -> Maybe SignatureSource
Convert a list of types into a valid signature.
Returns Nothing
if the given types are not a valid signature.
signature_ :: [Type] -> SignatureSource
Convert a list of types into a valid signature.
Throws an exception if the given types are not a valid signature.
signatureTypes :: Signature -> [Type]Source
Get the list of types in a signature. The inverse of signature
.
formatSignature :: Signature -> StringSource
Convert a signature into a signature string. The inverse of
parseSignature
.
parseSignature :: String -> Maybe SignatureSource
Parse a signature string into a valid signature.
Returns Nothing
if the given string is not a valid signature.
Object paths
data ObjectPath Source
Object paths are special strings, used to identify a particular object exported from a D-Bus application.
Object paths must begin with a slash, and consist of alphanumeric characters separated by slashes.
See http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path for details.
Names
Interface names
data InterfaceName Source
Interfaces are used to group a set of methods and signals within an exported object. Interface names consist of alphanumeric characters separated by periods.
See http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface for details.
Member names
data MemberName Source
Member names are used to identify a single method or signal within an interface. Method names consist of alphanumeric characters.
See http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-member for details.
Error names
Error names are used to identify which type of error was returned from a method call. Error names consist of alphanumeric characters separated by periods.
See http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-error for details.
errorName_ :: String -> ErrorNameSource
Bus names
Bus names are used to identify particular clients on the message bus. A bus name may be either unique or well-known, where unique names start with a colon. Bus names consist of alphanumeric characters separated by periods.
See http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus for details.
formatBusName :: BusName -> StringSource
parseBusName :: String -> Maybe BusNameSource
Non-native containers
Structures
A D-Bus Structure is a container type similar to Haskell tuples, storing
values of any type that is convertable to IsVariant
. A Structure may
contain up to 255 values.
Most users can use the IsVariant
instance for tuples to extract the
values of a structure. This type is for very large structures, which may
be awkward to work with as tuples.
structureItems :: Structure -> [Variant]Source
Arrays
A D-Bus Array is a container type similar to Haskell lists, storing zero or more values of a single D-Bus type.
Most users can use the IsVariant
instance for lists or vectors to extract
the values of an array. This type is for advanced use cases, where the user
wants to convert array values to Haskell types that are not instances of
IsValue
.
arrayItems :: Array -> [Variant]Source
Dictionaries
data Dictionary Source
A D-Bus Dictionary is a container type similar to Haskell maps, storing zero or more associations between keys and values.
Most users can use the IsVariant
instance for maps to extract the values
of a dictionary. This type is for advanced use cases, where the user
wants to convert dictionary items to Haskell types that are not instances
of IsValue
.
dictionaryItems :: Dictionary -> [(Variant, Variant)]Source
Addresses
When a D-Bus server must listen for connections, or a client must connect to a server, the listening socket's configuration is specified with an address. An address contains the method, which determines the protocol and transport mechanism, and parameters, which provide additional method-specific information about the address.
addressMethod :: Address -> StringSource
formatAddress :: Address -> StringSource
Convert an address to a string in the format expected by parseAddress
.
formatAddresses :: [Address] -> StringSource
Convert a list of addresses to a string in the format expected by
parseAddresses
.
parseAddress :: String -> Maybe AddressSource
Try to parse a string containing one valid address.
An address string is in the format method:key1=val1,key2=val2
. There
are some limitations on the characters allowed within methods and
parameters; see the D-Bus specification for full details.
parseAddresses :: String -> Maybe [Address]Source
Try to parse a string containing one or more valid addresses.
Addresses are separated by semicolons. See parseAddress
for the format
of addresses.
getSystemAddress :: IO (Maybe Address)Source
Returns the address in the environment variable
DBUS_SYSTEM_BUS_ADDRESS
, or
unix:path=/var/run/dbus/system_bus_socket
if DBUS_SYSTEM_BUS_ADDRESS
is not set.
Returns Nothing
if DBUS_SYSTEM_BUS_ADDRESS
contains an invalid address.
getSessionAddress :: IO (Maybe Address)Source
Returns the address in the environment variable
DBUS_SESSION_BUS_ADDRESS
, which must be set.
Returns Nothing
if DBUS_SYSTEM_BUS_ADDRESS
is unset or contains an
invalid address.
getStarterAddress :: IO (Maybe Address)Source
Returns the address in the environment variable
DBUS_STARTER_ADDRESS
, which must be set.
Returns Nothing
if DBUS_STARTER_ADDRESS
is unset or contains an
invalid address.
Message marshaling
Marshal
marshal :: Message msg => Endianness -> Serial -> msg -> Either MarshalError ByteStringSource
Convert a Message
into a ByteString
. Although unusual, it is
possible for marshaling to fail; if this occurs, an error will be
returned instead.
Unmarshal
unmarshal :: ByteString -> Either UnmarshalError ReceivedMessageSource
Parse a ByteString
into a ReceivedMessage
. The result can be
inspected to see what type of message was parsed. Unknown message types
can still be parsed successfully, as long as they otherwise conform to
the D-Bus standard.
Message serials
A value used to uniquely identify a particular message within a session. Serials are 32-bit unsigned integers, and eventually wrap.
serialValue :: Serial -> Word32Source
Get the first serial in the sequence.
nextSerial :: Serial -> SerialSource
Get the next serial in the sequence. This may wrap around to
firstSerial
.
D-Bus UUIDs
A D-Bus UUID is 128 bits of data, usually randomly generated. They are used for identifying unique server instances to clients.
Older versions of the D-Bus spec also called these values GUIDs.
D-Bus UUIDs are not the same as the RFC-standardized UUIDs or GUIDs.
formatUUID :: UUID -> StringSource
Format a D-Bus UUID as hex-encoded ASCII.
Generate a random D-Bus UUID. This value is suitable for use in a
randomly-allocated address, or as a listener's socket address
"guid"
parameter.