:# Copyright (C) 2009-2010 John Millikin :# :# This program is free software: you can redistribute it and/or modify :# it under the terms of the GNU General Public License as published by :# the Free Software Foundation, either version 3 of the License, or :# any later version. :# :# This program is distributed in the hope that it will be useful, :# but WITHOUT ANY WARRANTY; without even the implied warranty of :# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the :# GNU General Public License for more details. :# :# You should have received a copy of the GNU General Public License :# along with this program. If not, see . \section{Haddock API documentation} The \LaTeX{} documentation is great for somebody reading the source code or trying to fix an error, but it's not useful for people who just want to add D-Bus support to their applications. These documentation sections will be included in Haddock output for public functions. There's no real order to this section; it exists only because Haddock can't merge documentation from external files. :d apidoc DBus.Client.disconnect -- | Stop a 'Client'’s callback thread and close its underlying socket. : :d apidoc DBus.Client.throwError -- | Normally, any exceptions raised while executing a method will be -- given the generic @\"org.freedesktop.DBus.Error.Failed\"@ name. -- 'throwError' allows the programmer to specify an error name, and provide -- additional information to the remote application. You may use this instead -- of 'Control.Exception.throwIO' to abort a method call. : :d apidoc DBus.Client.Simple.AutoSignature -- | Used to automatically generate method signatures for introspection -- documents. To support automatic signatures, a method#8217;s parameters and -- return value must all be instances of 'IsValue'. -- -- 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 'IsVariant'. For these cases, please -- use 'DBus.Client.method'. -- -- To match common Haskell use, if the return value is a tuple, it will be -- converted to a list of return values. : :d apidoc DBus.Client.Simple.AutoReply -- | Used to automatically generate a 'Reply' from a return value. See -- 'AutoSignature' for some caveats about supported signatures. -- -- To match common Haskell use, if the return value is a tuple, it will be -- converted to a list of return values. : :d apidoc DBus.Client.Simple.connectSession -- | Connect to the bus specified in the environment variable -- @DBUS_SESSION_BUS_ADDRESS@, which must be set. : :d apidoc DBus.Client.Simple.connectStarter -- | Connect to the bus specified in the environment variable -- @DBUS_STARTER_ADDRESS@, which must be set. : :d apidoc DBus.Client.Simple.connectSystem -- | Connect to the bus specified in the environment variable -- @DBUS_SYSTEM_BUS_ADDRESS@, or to -- @unix:path=\/var\/run\/dbus\/system_bus_socket@ if @DBUS_SYSTEM_BUS_ADDRESS@ -- is not set. : :d apidoc DBus.Client.Simple.export -- | Export the given functions under the given 'ObjectPath' and -- 'InterfaceName'. The functions may accept/return any types that are -- instances of 'IsValue'; see 'AutoSignature'. -- -- @ --sayHello :: Text -> IO Text --sayHello name = return ('Data.Text.concat' [\"Hello \", name, \"!\"]) -- --export client \"/hello_world\" -- [ 'method' \"com.example.HelloWorld\" \"Hello\" sayHello -- ] -- @ : :d apidoc DBus.Client.Simple.method -- | Prepare a Haskell function for export. This automatically detects the -- function#8217;s type signature; see 'AutoSignature' and 'AutoReply'. -- -- To manage the type signature and marshaling yourself, use -- 'DBus.Client.method' instead. : :d apidoc DBus.Connection.Connection -- | A 'Connection' is an opaque handle to an open D‐Bus channel, with -- an internal state for maintaining the current message serial. : :d apidoc DBus.Connection.Transport -- | A 'Transport' is anything which can send and receive bytestrings, -- typically via a socket. : :d apidoc DBus.Connection.connect -- | Open a connection to some address, using a given authentication -- mechanism. If the connection fails, a 'ConnectionError' will be thrown. : :d apidoc DBus.Connection.disconnect -- | Close an open connection. Once closed, the 'Connection' is no longer -- valid and must not be used. : :d apidoc DBus.Connection.receive -- | Receive the next message from the connection, blocking until one is -- available. -- -- Only one message may be received at a time; if multiple threads attempt -- to receive messages in parallel, one will block until after the other has -- finished. : :d apidoc DBus.Connection.send -- | 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. -- -- Only one message may be sent at a time; if multiple threads attempt to -- send messages in parallel, one will block until after the other has -- finished. : :d apidoc DBus.Message.ReceivedMessage -- | Not an actual message type, but a wrapper around messages received from -- the bus. Each value contains the message’s 'Serial' and possibly the -- origin’s 'BusName' : :d apidoc DBus.Message.Serial -- | A value used to uniquely identify a particular message within a session. -- 'Serial's are 32‐bit unsigned integers, and eventually wrap. : :d apidoc DBus.Types.Variant -- | 'Variant's may contain any other built‐in D‐Bus value. Besides -- representing native @VARIANT@ values, they allow type‐safe storage and -- deconstruction of heterogeneous collections. : :d apidoc DBus.Types.variantType -- | 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. : :d apidoc DBus.Wire.marshalMessage -- | Convert a 'Message' into a 'ByteString'. Although unusual, it is -- possible for marshaling to fail; if this occurs, an error will be -- returned instead. : :d apidoc DBus.Wire.unmarshalMessage -- | 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. :