-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A client library for the D-Bus IPC system.
--   
--   D-Bus is a simple, message-based protocol for inter-process
--   communication, which allows applications to interact with other parts
--   of the machine and the user's session using remote procedure calls.
--   
--   D-Bus is a essential part of the modern Linux desktop, where it
--   replaces earlier protocols such as CORBA and DCOP.
--   
--   This library is an implementation of the D-Bus protocol in Haskell. It
--   can be used to add D-Bus support to Haskell applications, without the
--   awkward interfaces common to foreign bindings.
--   
--   Example: connect to the session bus, and get a list of active names.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.List (sort)
--   import DBus
--   import DBus.Client
--   
--   main = do
--       client &lt;- connectSession
--       //
--       -- Request a list of connected clients from the bus
--       reply &lt;- call_ client (methodCall "/org/freedesktop/DBus" "org.freedesktop.DBus" "ListNames")
--           { methodCallDestination = Just "org.freedesktop.DBus"
--           }
--       //
--       -- org.freedesktop.DBus.ListNames() returns a single value, which is
--       -- a list of names (here represented as [String])
--       let Just names = fromVariant (methodReturnBody reply !! 0)
--       //
--       -- Print each name on a line, sorted so reserved names are below
--       -- temporary names.
--       mapM_ putStrLn (sort names)
--   </pre>
--   
--   <pre>
--   $ ghc --make list-names.hs
--   $ ./list-names
--   :1.0
--   :1.1
--   :1.10
--   :1.106
--   :1.109
--   :1.110
--   ca.desrt.dconf
--   org.freedesktop.DBus
--   org.freedesktop.Notifications
--   org.freedesktop.secrets
--   org.gnome.ScreenSaver
--   </pre>
@package dbus
@version 0.10.12


-- | Basic types, useful to every D-Bus application.
--   
--   Authors of client applications should import <a>DBus.Client</a>, which
--   provides an easy RPC-oriented interface to D-Bus methods and signals.
module DBus
class Message a where messageFlags _ = 0

-- | 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.
data MethodCall

-- | Construct a new <a>MethodCall</a> for the given object, interface, and
--   method.
--   
--   Use fields such as <a>methodCallDestination</a> and
--   <a>methodCallBody</a> to populate a <a>MethodCall</a>.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   methodCall "/" "org.example.Math" "Add"
--       { <a>methodCallDestination</a> = Just "org.example.Calculator"
--       , <a>methodCallBody</a> = [<a>toVariant</a> (1 :: Int32), <a>toVariant</a> (2 :: Int32)]
--       }
--    
--   </pre>
methodCall :: ObjectPath -> InterfaceName -> MemberName -> MethodCall

-- | 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.
methodCallPath :: MethodCall -> ObjectPath

-- | 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 <tt>Nothing</tt>, but most users should
--   set it to a value.
methodCallInterface :: MethodCall -> Maybe InterfaceName

-- | The method name of the method call. Method names are unique within an
--   interface, but might not be unique within an object.
methodCallMember :: MethodCall -> MemberName

-- | 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 <tt>Nothing</tt>.
methodCallSender :: MethodCall -> Maybe BusName

-- | 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
--   <tt>org.freedesktop.DBus</tt>. For peer-peer connections, the
--   destination can be empty because there is only one peer.
--   
--   Defaults to <tt>Nothing</tt>.
methodCallDestination :: MethodCall -> Maybe BusName

-- | Set whether the bus should auto-start the remote
--   
--   Defaults to <tt>True</tt>.
methodCallAutoStart :: MethodCall -> Bool

-- | Set whether a reply is expected. This can save network and cpu
--   resources by inhibiting unnecessary replies.
--   
--   Defaults to <tt>True</tt>.
methodCallReplyExpected :: MethodCall -> Bool

-- | The arguments to the method call. See <a>toVariant</a>.
--   
--   Defaults to <tt>[]</tt>.
methodCallBody :: MethodCall -> [Variant]

-- | A method return is a reply to a method call, indicating that the call
--   succeeded.
data MethodReturn

-- | Construct a new <a>MethodReturn</a>, in reply to a method call with
--   the given serial.
--   
--   Use fields such as <a>methodReturnBody</a> to populate a
--   <a>MethodReturn</a>.
methodReturn :: Serial -> MethodReturn

-- | The serial of the original method call. This lets the original caller
--   match up this reply to the pending call.
methodReturnSerial :: MethodReturn -> Serial

-- | 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 <tt>Nothing</tt>.
methodReturnSender :: MethodReturn -> Maybe BusName

-- | 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
--   <tt>org.freedesktop.DBus</tt>. For peer-peer connections, the
--   destination can be empty because there is only one peer.
--   
--   Defaults to <tt>Nothing</tt>.
methodReturnDestination :: MethodReturn -> Maybe BusName

-- | Values returned from the method call. See <a>toVariant</a>.
--   
--   Defaults to <tt>[]</tt>.
methodReturnBody :: MethodReturn -> [Variant]

-- | A method error is a reply to a method call, indicating that the call
--   received an error and did not succeed.
data MethodError

-- | Construct a new <a>MethodError</a>, in reply to a method call with the
--   given serial.
--   
--   Use fields such as <a>methodErrorBody</a> to populate a
--   <a>MethodError</a>.
methodError :: Serial -> ErrorName -> MethodError

-- | The name of the error type. Names are used so clients can handle
--   certain classes of error differently from others.
methodErrorName :: MethodError -> ErrorName

-- | The serial of the original method call. This lets the original caller
--   match up this reply to the pending call.
methodErrorSerial :: MethodError -> Serial

-- | 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 <tt>Nothing</tt>.
methodErrorSender :: MethodError -> Maybe BusName

-- | 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
--   <tt>org.freedesktop.DBus</tt>. For peer-peer connections, the
--   destination can be empty because there is only one peer.
--   
--   Defaults to <tt>Nothing</tt>.
methodErrorDestination :: MethodError -> Maybe BusName

-- | Additional information about the error. By convention, if the error
--   body contains any items, the first item should be a string describing
--   the error.
methodErrorBody :: MethodError -> [Variant]

-- | Get a human-readable description of the error, by returning the first
--   item in the error body if it's a string.
methodErrorMessage :: MethodError -> String

-- | Signals are broadcast by applications to notify other clients of some
--   event.
data Signal

-- | Construct a new <a>Signal</a> for the given object, interface, and
--   signal name.
--   
--   Use fields such as <a>signalBody</a> to populate a <a>Signal</a>.
signal :: ObjectPath -> InterfaceName -> MemberName -> Signal

-- | The path of the object that emitted this signal.
signalPath :: Signal -> ObjectPath

-- | The name of this signal.
signalMember :: Signal -> MemberName

-- | The interface that this signal belongs to.
signalInterface :: Signal -> InterfaceName

-- | 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 <tt>Nothing</tt>.
signalSender :: Signal -> Maybe BusName

-- | The name of the application to emit the signal to. If
--   <tt>Nothing</tt>, the signal is sent to any application that has
--   registered an appropriate match rule.
--   
--   Defaults to <tt>Nothing</tt>.
signalDestination :: Signal -> Maybe BusName

-- | Additional information about the signal, such as the new value or the
--   time.
--   
--   Defaults to <tt>[]</tt>.
signalBody :: Signal -> [Variant]

-- | Not an actual message type, but a wrapper around messages received
--   from the bus. Each value contains the message's <a>Serial</a>.
--   
--   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.
data ReceivedMessage
ReceivedMethodCall :: Serial -> MethodCall -> ReceivedMessage
ReceivedMethodReturn :: Serial -> MethodReturn -> ReceivedMessage
ReceivedMethodError :: Serial -> MethodError -> ReceivedMessage
ReceivedSignal :: Serial -> Signal -> ReceivedMessage

-- | No matter what sort of message was received, get its serial.
receivedMessageSerial :: ReceivedMessage -> Serial

-- | No matter what sort of message was received, get its sender (if
--   provided).
receivedMessageSender :: ReceivedMessage -> Maybe BusName

-- | No matter what sort of message was received, get its body (if
--   provided).
receivedMessageBody :: ReceivedMessage -> [Variant]

-- | Variants may contain any other built-in D-Bus value. Besides
--   representing native <tt>VARIANT</tt> values, they allow type-safe
--   storage and inspection of D-Bus collections.
data Variant
class IsVariant a
toVariant :: IsVariant a => a -> Variant
fromVariant :: IsVariant a => Variant -> Maybe a

-- | 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.
variantType :: Variant -> Type

-- | Atomic types can be used as keys to dictionaries.
--   
--   Users may not provide new instances of <a>IsAtom</a> because this
--   could allow dictionaries to be created with invalid keys.
class IsValue a => IsAtom a

-- | Value types can be used as items in containers, such as lists or
--   dictionaries.
--   
--   Users may not provide new instances of <a>IsValue</a> because this
--   could allow containers to be created with items of heterogenous types.
class IsVariant a => IsValue a

-- | Get the D-Bus type corresponding to the given Haskell value. The value
--   may be <tt>undefined</tt>.
typeOf :: IsValue a => a -> Type

-- | A signature is a list of D-Bus types, obeying some basic rules of
--   validity.
--   
--   The rules of signature validity are complex: see
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures</a>
--   for details.
data Signature
data Type
TypeBoolean :: Type
TypeWord8 :: Type
TypeWord16 :: Type
TypeWord32 :: Type
TypeWord64 :: Type
TypeInt16 :: Type
TypeInt32 :: Type
TypeInt64 :: Type
TypeDouble :: Type
TypeUnixFd :: Type
TypeString :: Type
TypeSignature :: Type
TypeObjectPath :: Type
TypeVariant :: Type
TypeArray :: Type -> Type
TypeDictionary :: Type -> Type -> Type
TypeStructure :: [Type] -> Type

-- | Convert a list of types into a valid signature.
--   
--   Returns <tt>Nothing</tt> if the given types are not a valid signature.
signature :: [Type] -> Maybe Signature

-- | Convert a list of types into a valid signature.
--   
--   Throws an exception if the given types are not a valid signature.
signature_ :: [Type] -> Signature

-- | Get the list of types in a signature. The inverse of <a>signature</a>.
signatureTypes :: Signature -> [Type]

-- | Convert a signature into a signature string. The inverse of
--   <a>parseSignature</a>.
formatSignature :: Signature -> String

-- | Parse a signature string into a valid signature.
--   
--   Returns <tt>Nothing</tt> if the given string is not a valid signature.
parseSignature :: String -> Maybe Signature

-- | 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
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path</a>
--   for details.
data ObjectPath
objectPath_ :: String -> ObjectPath
formatObjectPath :: ObjectPath -> String
parseObjectPath :: String -> Maybe ObjectPath

-- | 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
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface</a>
--   for details.
data InterfaceName
interfaceName_ :: String -> InterfaceName
formatInterfaceName :: InterfaceName -> String
parseInterfaceName :: String -> Maybe InterfaceName

-- | Member names are used to identify a single method or signal within an
--   interface. Method names consist of alphanumeric characters.
--   
--   See
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-member</a>
--   for details.
data MemberName
memberName_ :: String -> MemberName
formatMemberName :: MemberName -> String
parseMemberName :: String -> Maybe MemberName

-- | 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
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-error</a>
--   for details.
data ErrorName
errorName_ :: String -> ErrorName
formatErrorName :: ErrorName -> String
parseErrorName :: String -> Maybe ErrorName

-- | Bus names are used to identify particular clients on the message bus.
--   A bus name may be either <i>unique</i> or <i>well-known</i>, where
--   unique names start with a colon. Bus names consist of alphanumeric
--   characters separated by periods.
--   
--   See
--   <a>http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus</a>
--   for details.
data BusName
busName_ :: String -> BusName
formatBusName :: BusName -> String
parseBusName :: String -> Maybe BusName

-- | A D-Bus Structure is a container type similar to Haskell tuples,
--   storing values of any type that is convertable to <a>IsVariant</a>. A
--   Structure may contain up to 255 values.
--   
--   Most users can use the <a>IsVariant</a> 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.
data Structure
structureItems :: Structure -> [Variant]

-- | 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 <a>IsVariant</a> 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 <a>IsValue</a>.
data Array
arrayItems :: Array -> [Variant]

-- | 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 <a>IsVariant</a> 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 <a>IsValue</a>.
data Dictionary
dictionaryItems :: Dictionary -> [(Variant, Variant)]

-- | 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 <i>address</i>. An address contains the <i>method</i>, which
--   determines the protocol and transport mechanism, and
--   <i>parameters</i>, which provide additional method-specific
--   information about the address.
data Address
addressMethod :: Address -> String
addressParameters :: Address -> Map String String

-- | Try to convert a method string and parameter map to an <a>Address</a>.
--   
--   Returns <a>Nothing</a> if the method or parameters are invalid.
address :: String -> Map String String -> Maybe Address

-- | Convert an address to a string in the format expected by
--   <a>parseAddress</a>.
formatAddress :: Address -> String

-- | Convert a list of addresses to a string in the format expected by
--   <a>parseAddresses</a>.
formatAddresses :: [Address] -> String

-- | Try to parse a string containing one valid address.
--   
--   An address string is in the format
--   <tt>method:key1=val1,key2=val2</tt>. There are some limitations on the
--   characters allowed within methods and parameters; see the D-Bus
--   specification for full details.
parseAddress :: String -> Maybe Address

-- | Try to parse a string containing one or more valid addresses.
--   
--   Addresses are separated by semicolons. See <a>parseAddress</a> for the
--   format of addresses.
parseAddresses :: String -> Maybe [Address]

-- | Returns the address in the environment variable
--   <tt>DBUS_SYSTEM_BUS_ADDRESS</tt>, or
--   <tt>unix:path=/var/run/dbus/system_bus_socket</tt> if
--   <tt>DBUS_SYSTEM_BUS_ADDRESS</tt> is not set.
--   
--   Returns <a>Nothing</a> if <tt>DBUS_SYSTEM_BUS_ADDRESS</tt> contains an
--   invalid address.
getSystemAddress :: IO (Maybe Address)

-- | Returns the address in the environment variable
--   <tt>DBUS_SESSION_BUS_ADDRESS</tt>, which must be set.
--   
--   Returns <a>Nothing</a> if <tt>DBUS_SYSTEM_BUS_ADDRESS</tt> is unset or
--   contains an invalid address.
getSessionAddress :: IO (Maybe Address)

-- | Returns the address in the environment variable
--   <tt>DBUS_STARTER_ADDRESS</tt>, which must be set.
--   
--   Returns <a>Nothing</a> if <tt>DBUS_STARTER_ADDRESS</tt> is unset or
--   contains an invalid address.
getStarterAddress :: IO (Maybe Address)
data Endianness
LittleEndian :: Endianness
BigEndian :: Endianness

-- | Convert a <a>Message</a> into a <a>ByteString</a>. Although unusual,
--   it is possible for marshaling to fail; if this occurs, an error will
--   be returned instead.
marshal :: Message msg => Endianness -> Serial -> msg -> Either MarshalError ByteString
data MarshalError
marshalErrorMessage :: MarshalError -> String

-- | Parse a <a>ByteString</a> into a <a>ReceivedMessage</a>. 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.
unmarshal :: ByteString -> Either UnmarshalError ReceivedMessage
data UnmarshalError
unmarshalErrorMessage :: UnmarshalError -> String

-- | A value used to uniquely identify a particular message within a
--   session. Serials are 32-bit unsigned integers, and eventually wrap.
data Serial
serialValue :: Serial -> Word32

-- | Get the first serial in the sequence.
firstSerial :: Serial

-- | Get the next serial in the sequence. This may wrap around to
--   <a>firstSerial</a>.
nextSerial :: Serial -> Serial

-- | 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
--   <i>GUIDs</i>.
--   
--   D-Bus UUIDs are not the same as the RFC-standardized UUIDs or GUIDs.
data UUID

-- | Format a D-Bus UUID as hex-encoded ASCII.
formatUUID :: UUID -> String

-- | Generate a random D-Bus UUID. This value is suitable for use in a
--   randomly-allocated address, or as a listener's socket address
--   <tt>"guid"</tt> parameter.
randomUUID :: IO UUID
instance GHC.Show.Show DBus.UUID
instance GHC.Classes.Ord DBus.UUID
instance GHC.Classes.Eq DBus.UUID

module DBus.Introspection
parseXML :: ObjectPath -> String -> Maybe Object
formatXML :: Object -> Maybe String
data Object
object :: ObjectPath -> Object
objectPath :: Object -> ObjectPath
objectInterfaces :: Object -> [Interface]
objectChildren :: Object -> [Object]
data Interface
interface :: InterfaceName -> Interface
interfaceName :: Interface -> InterfaceName
interfaceMethods :: Interface -> [Method]
interfaceSignals :: Interface -> [Signal]
interfaceProperties :: Interface -> [Property]
data Method
method :: MemberName -> Method
methodName :: Method -> MemberName
methodArgs :: Method -> [MethodArg]
data MethodArg
methodArg :: String -> Type -> Direction -> MethodArg
methodArgName :: MethodArg -> String
methodArgType :: MethodArg -> Type
methodArgDirection :: MethodArg -> Direction
data Direction
directionIn :: Direction
directionOut :: Direction
data Signal
signal :: MemberName -> Signal
signalName :: Signal -> MemberName
signalArgs :: Signal -> [SignalArg]
data SignalArg
signalArg :: String -> Type -> SignalArg
signalArgName :: SignalArg -> String
signalArgType :: SignalArg -> Type
data Property
property :: String -> Type -> Property
propertyName :: Property -> String
propertyType :: Property -> Type
propertyRead :: Property -> Bool
propertyWrite :: Property -> Bool
instance GHC.Classes.Eq DBus.Introspection.Object
instance GHC.Show.Show DBus.Introspection.Object
instance GHC.Classes.Eq DBus.Introspection.Interface
instance GHC.Show.Show DBus.Introspection.Interface
instance GHC.Classes.Eq DBus.Introspection.Property
instance GHC.Show.Show DBus.Introspection.Property
instance GHC.Classes.Eq DBus.Introspection.Signal
instance GHC.Show.Show DBus.Introspection.Signal
instance GHC.Classes.Eq DBus.Introspection.SignalArg
instance GHC.Show.Show DBus.Introspection.SignalArg
instance GHC.Classes.Eq DBus.Introspection.Method
instance GHC.Show.Show DBus.Introspection.Method
instance GHC.Classes.Eq DBus.Introspection.MethodArg
instance GHC.Show.Show DBus.Introspection.MethodArg
instance GHC.Classes.Eq DBus.Introspection.Direction
instance GHC.Show.Show DBus.Introspection.Direction
instance GHC.Base.Functor DBus.Introspection.XmlWriter
instance GHC.Base.Applicative DBus.Introspection.XmlWriter
instance GHC.Base.Monad DBus.Introspection.XmlWriter


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

-- | A <a>Transport</a> can exchange bytes with a remote peer.
class Transport t where data TransportOptions t :: * where {
    data family TransportOptions t :: *;
}

-- | Default values for this transport's options.
transportDefaultOptions :: Transport t => TransportOptions t

-- | Send a <a>ByteString</a> over the transport.
--   
--   Throws a <a>TransportError</a> if an error occurs.
transportPut :: Transport t => t -> ByteString -> IO ()

-- | Receive a <a>ByteString</a> 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 <a>TransportError</a> if an error occurs.
transportGet :: Transport t => t -> Int -> IO ByteString

-- | Close an open transport, and release any associated resources or
--   handles.
transportClose :: Transport t => t -> IO ()

-- | A <a>Transport</a> which can open a connection to a remote peer.
class Transport t => TransportOpen t

-- | Open a connection to the given address, using the given options.
--   
--   Throws a <a>TransportError</a> if the connection could not be
--   established.
transportOpen :: TransportOpen t => TransportOptions t -> Address -> IO t

-- | A <a>Transport</a> which can listen for and accept connections from
--   remote peers.
class Transport t => TransportListen t where data TransportListener t :: * where {
    data family TransportListener t :: *;
}

-- | Begin listening for connections on the given address, using the given
--   options.
--   
--   Throws a <a>TransportError</a> if it's not possible to listen at that
--   address (for example, if the port is already in use).
transportListen :: TransportListen t => TransportOptions t -> Address -> IO (TransportListener t)

-- | Accept a new connection.
--   
--   Throws a <a>TransportError</a> if some error happens before the
--   transport is ready to exchange bytes.
transportAccept :: TransportListen t => TransportListener t -> IO t

-- | Close an open listener.
transportListenerClose :: TransportListen t => TransportListener t -> IO ()

-- | Get the address to use to connect to a listener.
transportListenerAddress :: TransportListen t => TransportListener t -> Address

-- | Get the UUID allocated to this transport listener.
--   
--   See <a>randomUUID</a>.
transportListenerUUID :: TransportListen t => TransportListener t -> UUID

-- | Thrown from transport methods when an error occurs.
data TransportError
transportError :: String -> TransportError
transportErrorMessage :: TransportError -> String
transportErrorAddress :: TransportError -> Maybe Address

-- | Supports connecting over Unix or TCP sockets.
--   
--   Unix sockets are similar to pipes, but exist as special files in the
--   filesystem. On Linux, <i>abstract sockets</i> have a path-like
--   address, but do not actually have entries in the filesystem.
--   
--   TCP sockets may use either IPv4 or IPv6.
data SocketTransport

-- | The maximum size of the connection queue for a listening socket.
socketTransportOptionBacklog :: TransportOptions SocketTransport -> Int

-- | Returns the processID, userID, and groupID of the socket's peer.
--   
--   See <a>getPeerCred</a>.
socketTransportCredentials :: SocketTransport -> IO (CUInt, CUInt, CUInt)
instance GHC.Show.Show DBus.Transport.TransportError
instance GHC.Classes.Eq DBus.Transport.TransportError
instance GHC.Exception.Exception DBus.Transport.TransportError
instance DBus.Transport.Transport DBus.Transport.SocketTransport
instance DBus.Transport.TransportOpen DBus.Transport.SocketTransport
instance DBus.Transport.TransportListen DBus.Transport.SocketTransport


-- | 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 <a>DBus.Client</a> module instead.
module DBus.Socket

-- | An open socket to another process. Messages can be sent to the remote
--   peer using <a>send</a>, or received using <a>receive</a>.
data Socket

-- | Send a single message, with a generated <a>Serial</a>. The second
--   parameter exists to prevent race conditions when registering a reply
--   handler; it receives the serial the message <i>will</i> 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 <a>SocketError</a> on failure.
send :: Message msg => Socket -> msg -> (Serial -> IO a) -> IO a

-- | 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 <a>SocketError</a> on failure.
receive :: Socket -> IO ReceivedMessage

-- | Stores information about an error encountered while creating or using
--   a <a>Socket</a>.
data SocketError
socketError :: String -> SocketError
socketErrorMessage :: SocketError -> String
socketErrorFatal :: SocketError -> Bool
socketErrorAddress :: SocketError -> Maybe Address

-- | Used with <a>openWith</a> and <a>listenWith</a> to provide custom
--   authenticators or transport options.
data SocketOptions 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.
socketAuthenticator :: SocketOptions t -> Authenticator t

-- | Options for the underlying transport, to be used by custom transports
--   for controlling how to connect to the remote peer.
--   
--   See <a>DBus.Transport</a> for details on defining custom transports
socketTransportOptions :: SocketOptions t -> TransportOptions t

-- | Default <a>SocketOptions</a>, which uses the default Unix/TCP
--   transport and authenticator.
defaultSocketOptions :: SocketOptions SocketTransport

-- | Open a socket to a remote peer listening at the given address.
--   
--   <pre>
--   open = <a>openWith</a> <a>defaultSocketOptions</a>
--    
--   </pre>
--   
--   Throws <a>SocketError</a> on failure.
open :: Address -> IO Socket

-- | Open a socket to a remote peer listening at the given address.
--   
--   Most users should use <a>open</a>. This function is for users who need
--   to define custom authenticators or transports.
--   
--   Throws <a>SocketError</a> on failure.
openWith :: TransportOpen t => SocketOptions t -> Address -> IO Socket

-- | Close an open <a>Socket</a>. Once closed, the socket is no longer
--   valid and must not be used.
close :: Socket -> IO ()
data SocketListener

-- | Begin listening at the given address.
--   
--   Use <a>accept</a> to create sockets from incoming connections.
--   
--   Use <a>closeListener</a> to stop listening, and to free underlying
--   transport resources such as file descriptors.
--   
--   Throws <a>SocketError</a> on failure.
listen :: Address -> IO SocketListener

-- | Begin listening at the given address.
--   
--   Use <a>accept</a> to create sockets from incoming connections.
--   
--   Use <a>closeListener</a> 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 <a>SocketError</a> on failure.
listenWith :: TransportListen t => SocketOptions t -> Address -> IO SocketListener

-- | Accept a new connection from a socket listener.
--   
--   Throws <a>SocketError</a> on failure.
accept :: SocketListener -> IO Socket

-- | Close an open <a>SocketListener</a>. Once closed, the listener is no
--   longer valid and must not be used.
closeListener :: SocketListener -> IO ()

-- | Get the address to use to connect to a listener.
socketListenerAddress :: SocketListener -> Address

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

-- | An empty authenticator. Use <a>authenticatorClient</a> or
--   <a>authenticatorServer</a> to control how the authentication is
--   performed.
--   
--   <pre>
--   myAuthenticator :: Authenticator MyTransport
--   myAuthenticator = authenticator
--       { <a>authenticatorClient</a> = clientMyAuth
--       , <a>authenticatorServer</a> = serverMyAuth
--       }
--   
--   clientMyAuth :: MyTransport -&gt; IO Bool
--   serverMyAuth :: MyTransport -&gt; String -&gt; IO Bool
--    
--   </pre>
authenticator :: Authenticator t

-- | Defines the client-side half of an authenticator.
authenticatorClient :: Authenticator t -> t -> IO Bool

-- | Defines the server-side half of an authenticator. The UUID is
--   allocated by the socket listener.
authenticatorServer :: Authenticator t -> t -> UUID -> IO Bool
instance GHC.Show.Show DBus.Socket.SocketError
instance GHC.Classes.Eq DBus.Socket.SocketError
instance GHC.Exception.Exception DBus.Socket.SocketError
instance DBus.Transport.Transport DBus.Socket.SomeTransport


-- | D-Bus clients are an abstraction over the lower-level messaging
--   system. When combined with an external daemon called the "bus",
--   clients can perform remote procedure calls to other clients on the
--   bus.
--   
--   Clients may also listen for or emit <i>signals</i>, which are
--   asynchronous broadcast notifications.
--   
--   Example: connect to the session bus, and get a list of active names.
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.List (sort)
--   import DBus
--   import DBus.Client
--   
--   main = do
--       client &lt;- <a>connectSession</a>
--       //
--       -- Request a list of connected clients from the bus
--       reply &lt;- <a>call_</a> client (<a>methodCall</a> "/org/freedesktop/DBus" "org.freedesktop.DBus" "ListNames")
--           { <a>methodCallDestination</a> = Just "org.freedesktop.DBus"
--           }
--       //
--       -- org.freedesktop.DBus.ListNames() returns a single value, which is
--       -- a list of names (here represented as [String])
--       let Just names = <a>fromVariant</a> (<a>methodReturnBody</a> reply !! 0)
--       //
--       -- Print each name on a line, sorted so reserved names are below
--       -- temporary names.
--       mapM_ putStrLn (sort names)
--    
--   </pre>
module DBus.Client

-- | An active client session to a message bus. Clients may send or receive
--   method calls, and listen for or emit signals.
data Client

-- | Connect to the bus at the specified address.
--   
--   Throws a <a>ClientError</a> on failure.
connect :: Address -> IO Client

-- | Connect to the bus specified in the environment variable
--   <tt>DBUS_SYSTEM_BUS_ADDRESS</tt>, or to
--   <tt>unix:path=/var/run/dbus/system_bus_socket</tt> if
--   <tt>DBUS_SYSTEM_BUS_ADDRESS</tt> is not set.
--   
--   Throws a <a>ClientError</a> if <tt>DBUS_SYSTEM_BUS_ADDRESS</tt>
--   contains an invalid address, or if connecting to the bus failed.
connectSystem :: IO Client

-- | Connect to the bus specified in the environment variable
--   <tt>DBUS_SESSION_BUS_ADDRESS</tt>, which must be set.
--   
--   Throws a <a>ClientError</a> if <tt>DBUS_SESSION_BUS_ADDRESS</tt> is
--   unset, contains an invalid address, or if connecting to the bus
--   failed.
connectSession :: IO Client

-- | Connect to the bus specified in the environment variable
--   <tt>DBUS_STARTER_ADDRESS</tt>, which must be set.
--   
--   Throws a <a>ClientError</a> if <tt>DBUS_STARTER_ADDRESS</tt> is unset,
--   contains an invalid address, or if connecting to the bus failed.
connectStarter :: IO Client

-- | Stop a <tt>Client'</tt>s callback thread and close its underlying
--   socket.
disconnect :: Client -> IO ()

-- | Send a method call to the bus, and wait for the response.
--   
--   Throws a <a>ClientError</a> if the method call couldn't be sent, or if
--   the reply couldn't be parsed.
call :: Client -> MethodCall -> IO (Either MethodError MethodReturn)

-- | Send a method call to the bus, and wait for the response.
--   
--   Unsets the <tt>noReplyExpected</tt> message flag before sending.
--   
--   Throws a <a>ClientError</a> if the method call couldn't sent, if the
--   reply couldn't be parsed, or if the reply was a <a>MethodError</a>.
call_ :: Client -> MethodCall -> IO MethodReturn

-- | Send a method call to the bus, and do not wait for a response.
--   
--   Sets the <tt>noReplyExpected</tt> message flag before sending.
--   
--   Throws a <a>ClientError</a> if the method call couldn't be sent.
callNoReply :: Client -> MethodCall -> IO ()

-- | Export the given functions under the given <a>ObjectPath</a> and
--   <a>InterfaceName</a>.
--   
--   Use <a>autoMethod</a> to construct a <a>Method</a> from a function
--   that accepts and returns simple types.
--   
--   Use <a>method</a> to construct a <a>Method</a> from a function that
--   handles parameter conversion manually.
--   
--   <pre>
--   ping :: MethodCall -&gt; IO <a>Reply</a>
--   ping _ = replyReturn []
--   
--   sayHello :: String -&gt; IO String
--   sayHello name = return ("Hello " ++ name ++ "!")
--   
--   export client "/hello_world"
--       [ <a>method</a> "com.example.HelloWorld" "Ping" ping
--       , <a>autoMethod</a> "com.example.HelloWorld" "Hello" sayHello
--       ]
--    
--   </pre>
export :: Client -> ObjectPath -> [Method] -> IO ()

-- | Revokes the export of the given <a>ObjectPath</a>. This will remove
--   all interfaces and methods associated with the path.
unexport :: Client -> ObjectPath -> IO ()
data Method

-- | Define a method handler, which will accept method calls with the given
--   interface and member name.
--   
--   Note that the input and output parameter signatures are used for
--   introspection, but are not checked when executing a method.
--   
--   See <a>autoMethod</a> for an easier way to export functions with
--   simple parameter and return types.
method :: InterfaceName -> MemberName -> Signature -> Signature -> (MethodCall -> IO Reply) -> Method
data Reply

-- | Reply to a method call with a successful return, containing the given
--   body.
replyReturn :: [Variant] -> Reply

-- | Reply to a method call with an error, containing the given error name
--   and body.
--   
--   Typically, the first item of the error body is a string with a message
--   describing the error.
replyError :: ErrorName -> [Variant] -> Reply

-- | Normally, any exceptions raised while executing a method will be given
--   the generic <tt>"org.freedesktop.DBus.Error.Failed"</tt> name.
--   <a>throwError</a> allows the programmer to specify an error name, and
--   provide additional information to the remote application. You may use
--   this instead of <a>throwIO</a> to abort a method call.
throwError :: ErrorName -> String -> [Variant] -> IO a

-- | Used to automatically generate method signatures for introspection
--   documents. To support automatic signatures, a method's parameters and
--   return value must all be instances of <a>IsValue</a>.
--   
--   This class maps Haskell idioms to D-Bus; it is therefore unable to
--   generate some signatures. In particular, it does not support methods
--   which accept/return a single structure, or single-element structures.
--   It also cannot generate signatures for methods with parameters or
--   return values which are only instances of <a>IsVariant</a>. For these
--   cases, please use <a>method</a>.
--   
--   To match common Haskell use, if the return value is a tuple, it will
--   be converted to a list of return values.
class AutoMethod a

-- | Prepare a Haskell function for export, automatically detecting the
--   function's type signature.
--   
--   See <a>AutoMethod</a> for details on the limitations of this function.
--   
--   See <a>method</a> for exporting functions with user-defined types.
autoMethod :: (AutoMethod fn) => InterfaceName -> MemberName -> fn -> Method
data SignalHandler

-- | Request that the bus forward signals matching the given rule to this
--   client, and process them in a callback.
--   
--   A received signal might be processed by more than one callback at a
--   time. Callbacks each run in their own thread.
--   
--   The returned <a>SignalHandler</a> can be passed to <a>removeMatch</a>
--   to stop handling this signal.
--   
--   Throws a <a>ClientError</a> if the match rule couldn't be added to the
--   bus.
addMatch :: Client -> MatchRule -> (Signal -> IO ()) -> IO SignalHandler

-- | Request that the bus stop forwarding signals for the given handler.
--   
--   Throws a <a>ClientError</a> if the match rule couldn't be removed from
--   the bus.
removeMatch :: Client -> SignalHandler -> IO ()

-- | Emit the signal on the bus.
--   
--   Throws a <a>ClientError</a> if the signal message couldn't be sent.
emit :: Client -> Signal -> IO ()

-- | Equivalent to <a>addMatch</a>, but does not return the added
--   <a>SignalHandler</a>.

-- | <i>Deprecated: Prefer DBus.Client.addMatch in new code.</i>
listen :: Client -> MatchRule -> (Signal -> IO ()) -> IO ()

-- | A match rule describes which signals a particular callback is
--   interested in. Use <a>matchAny</a> to construct match rules.
--   
--   Example: a match rule which matches signals sent by the root object.
--   
--   <pre>
--   matchFromRoot :: MatchRule
--   matchFromRoot = <a>matchAny</a> { <a>matchPath</a> = Just "/" }
--    
--   </pre>
data MatchRule

-- | Convert a match rule into the textual format accepted by the bus.
formatMatchRule :: MatchRule -> String

-- | Match any signal.
matchAny :: MatchRule

-- | If set, only receives signals sent from the given bus name.
--   
--   The standard D-Bus implementation from
--   <a>http://dbus.freedesktop.org/</a> almost always sets signal senders
--   to the unique name of the sending client. If <a>matchSender</a> is a
--   requested name like <tt>"com.example.Foo"</tt>, it will not match any
--   signals.
--   
--   The exception is for signals sent by the bus itself, which always have
--   a sender of <tt>"org.freedesktop.DBus"</tt>.
matchSender :: MatchRule -> Maybe BusName

-- | If set, only receives signals sent to the given bus name.
matchDestination :: MatchRule -> Maybe BusName

-- | If set, only receives signals sent with the given path.
matchPath :: MatchRule -> Maybe ObjectPath

-- | If set, only receives signals sent with the given interface name.
matchInterface :: MatchRule -> Maybe InterfaceName

-- | If set, only receives signals sent with the given member name.
matchMember :: MatchRule -> Maybe MemberName

-- | Asks the message bus to assign the given name to this client. The bus
--   maintains a queue of possible owners, where the head of the queue is
--   the current ("primary") owner.
--   
--   There are several uses for name reservation:
--   
--   <ul>
--   <li>Clients which export methods reserve a name so users and
--   applications can send them messages. For example, the GNOME Keyring
--   reserves the name <tt>"org.gnome.keyring"</tt> on the user's session
--   bus, and NetworkManager reserves
--   <tt>"org.freedesktop.NetworkManager"</tt> on the system bus.</li>
--   <li>When there are multiple implementations of a particular service,
--   the service standard will ususally include a generic bus name for the
--   service. This allows other clients to avoid depending on any
--   particular implementation's name. For example, both the GNOME Keyring
--   and KDE KWallet services request the
--   <tt>"org.freedesktop.secrets"</tt> name on the user's session
--   bus.</li>
--   <li>A process with "single instance" behavior can use name assignment
--   to check whether the instance is already running, and invoke some
--   method on it (e.g. opening a new window).</li>
--   </ul>
--   
--   Throws a <a>ClientError</a> if the call failed.
requestName :: Client -> BusName -> [RequestNameFlag] -> IO RequestNameReply

-- | Release a name that this client previously requested. See
--   <a>requestName</a> for an explanation of name reservation.
--   
--   Throws a <a>ClientError</a> if the call failed.
releaseName :: Client -> BusName -> IO ReleaseNameReply
data RequestNameFlag

-- | Allow this client's reservation to be replaced, if another client
--   requests it with the <a>nameReplaceExisting</a> flag.
--   
--   If this client's reservation is replaced, this client will be added to
--   the wait queue unless the request also included the
--   <a>nameDoNotQueue</a> flag.
nameAllowReplacement :: RequestNameFlag

-- | If the name being requested is already reserved, attempt to replace
--   it. This only works if the current owner provided the
--   <a>nameAllowReplacement</a> flag.
nameReplaceExisting :: RequestNameFlag

-- | If the name is already in use, do not add this client to the queue,
--   just return an error.
nameDoNotQueue :: RequestNameFlag
data RequestNameReply

-- | This client is now the primary owner of the requested name.
NamePrimaryOwner :: RequestNameReply

-- | The name was already reserved by another client, and replacement was
--   either not attempted or not successful.
NameInQueue :: RequestNameReply

-- | The name was already reserved by another client, <a>DoNotQueue</a> was
--   set, and replacement was either not attempted or not successful.
NameExists :: RequestNameReply

-- | This client is already the primary owner of the requested name.
NameAlreadyOwner :: RequestNameReply
data ReleaseNameReply

-- | This client has released the provided name.
NameReleased :: ReleaseNameReply

-- | The provided name is not assigned to any client on the bus.
NameNonExistent :: ReleaseNameReply

-- | The provided name is not assigned to this client.
NameNotOwner :: ReleaseNameReply
data ClientError
clientError :: String -> ClientError
clientErrorMessage :: ClientError -> String
clientErrorFatal :: ClientError -> Bool
data ClientOptions t

-- | Options for the underlying socket, for advanced use cases. See the
--   <a>DBus.Socket</a> module.
clientSocketOptions :: ClientOptions t -> SocketOptions t

-- | A function to run the client thread. The provided IO computation
--   should be called repeatedly; each time it is called, it will process
--   one incoming message.
--   
--   The provided computation will throw a <a>ClientError</a> if it fails
--   to process an incoming message, or if the connection is lost.
--   
--   The default implementation is <a>forever</a>.
clientThreadRunner :: ClientOptions t -> IO () -> IO ()

-- | Default client options. Uses the built-in Socket-based transport,
--   which supports the <tt>tcp:</tt> and <tt>unix:</tt> methods.
defaultClientOptions :: ClientOptions SocketTransport

-- | Connect to the bus at the specified address, with the given connection
--   options. Most users should use <a>connect</a> instead.
--   
--   Throws a <a>ClientError</a> on failure.
connectWith :: TransportOpen t => ClientOptions t -> Address -> IO Client
instance GHC.Classes.Eq DBus.Client.MethodExc
instance GHC.Show.Show DBus.Client.MethodExc
instance GHC.Show.Show DBus.Client.ReleaseNameReply
instance GHC.Classes.Eq DBus.Client.ReleaseNameReply
instance GHC.Show.Show DBus.Client.RequestNameReply
instance GHC.Classes.Eq DBus.Client.RequestNameReply
instance GHC.Show.Show DBus.Client.RequestNameFlag
instance GHC.Classes.Eq DBus.Client.RequestNameFlag
instance GHC.Show.Show DBus.Client.ClientError
instance GHC.Classes.Eq DBus.Client.ClientError
instance GHC.Exception.Exception DBus.Client.ClientError
instance GHC.Show.Show DBus.Client.MatchRule
instance GHC.Exception.Exception DBus.Client.MethodExc
instance DBus.Client.AutoMethod (GHC.Types.IO ())
instance DBus.Types.IsValue a => DBus.Client.AutoMethod (GHC.Types.IO a)
instance (DBus.Types.IsValue a, DBus.Client.AutoMethod fn) => DBus.Client.AutoMethod (a -> fn)
