dbus-core-0.9.3: src/api-docs.anansi
:# Copyright (C) 2009-2010 John Millikin <jmillikin@gmail.com>
:#
:# 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 <http://www.gnu.org/licenses/>.
\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.
: