= lsp-dbus.a(8)
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}

== NAME

lsp-dbus.a - Dbus API for newlisp.

== SYNOPSIS

.With packnl
packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a*


.With incore.lsp
(load "incore.lsp") +
(archive "lsp-misc.a") +
(archive "lsp-utils.a") +
(load "lsp-dbus.lsp")

== DESCRIPTION

*lsp-dbus.a* implements a newlisp API for Dbus. The module includes a
context *DbusConnection* implementing the connection/authorization
level and a context *Dbus* that implements the "object modelling"
level. The software is divided into a couple of different source files
that are packed together int a _ar_ archive. It also depends on +foop+
and +prog1+ from +lsp-misc.a+.

=== Essential API

On loading::

The main file, +lsp-dbus.lsp+, includes connection setup and client
registration as part of its loading. Currently it connects on the
system bus only. It also installs the funcion +main-loop+ as
+prompt-event+ function for processing any unsolicited messages from
dbus (so called "signals").

(Dbus _PATH_ [_DESTINATION_])::

The context +Dbus+ is used for identifying remote services which by
default have coinsiding path _PATH_ and _DESTINATION_ (aka bus name).
The resulting FOOP object provides a channel for invoking methods.

(:invoke _OBJECT_ _METHOD_ _ARGUMENTS_ _FLAGS_):: The +:invoke+ method
performs a Dbus +METHOD_CALL+ handshake for the gven _OBJECT_ using
the given _METHOD_, _ARGUMENTS_and message _FLAGS_, while also polling
s.c. signal messages from Dbus. The _METHOD_ is given as a string
composed as "_path_:_interface_._name_(_signature_)", although the
_path_ and _interface_ parts are optional. If without explicit _path_,
the _OBJECT_ path is used. If without explicit interface, the method
will be looked up across all interfaces of the destination path.
+
The given _ARGUMENTS_ is a list structure that must correspond to the
given signature. See the MARSHALLING below.
+
The optional _FLAGS_ is either a bit mask or a list of applicable
method call flags as Dbus symbols. See METHOD_CALL flags below.
+
.invoke usage examples
(:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0))
+
(:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0))
+
(setf BT (Dbus "/org/bluez")) +
(:invoke BT "/:org.freedesktop.ObjectManager.GetManagedObjects()") +
; Note that "org.bluez" here provides the "GetManagedObjects()" +
; method on the root path, "/", rather than its own path +
; "/org/bluez".
+
While this process is waiting for the +METHOD_CALL+ reply it may
receive signal messsages from +dbus+. These will be added to the list
of "pending callbacks" that is processed via the +process-all-pending+
function, either via an explicit call following the handshake or
"automagically" as part of the +main-loop+ function that gets
installed as as +prompt-event+ function.

(Dbus:process-all-pending)::

The +process-all-pending+ function processes all pending signal
messages by invoking their associated handler functions.

(prompt-event Dbus:main-loop)::

The +main-loop+ function is set up as +prompt-event+ function for a
+net-select+ on both stdin and the dbus socket as well as to process
all pending signal messages. Any input from dbus, which are signal
messages, are added to the pending list, which also is processed one
message at a time until empty.
+
Note that newlisp uses readline for input but that this is not
activated in +main-loop+. Therefore line editing is not available
immediately. However the operator may use ^D to leave the main-loop
and enter the "normal" command line input state for a single line
input (with line editing), or an initial newline for multi-line input
that is "submitted" by means of two newlines.

(Dbus:handler _KEY_ _HANDLER_):: This function registers a handler
callback for a key that is a string composed as
"path:interface.member(signature)". The handler function takes a
single argument, which is the list of unmarshalled actual call
arguments.

=== MARSHALLING

dbus documentation uses the terms "marshalling" and "unmarshalling"
for the translations of data from/to program data to/from dbus message
bytes. The data in newlisp mapped straight-forwardly with the special
note that both "struct" and "array" are held as lists in newlisp. To
that end, the data for the variant type signature must be wrapped into
an extra list of the format _(signature value)_ with explcit dbus
signature string. However, such wrapping does not take place upon
unmarshalling.

=== METHOD_CALL FLAGS

As per dbus documentation, there are three +METHOD_call+ flags:
+Dbus:NO_REPLY_EXPECTED+, +Dbus:NO_AUTO_START+ and
+Dbus:ALLOW_INTERACTIVE_AUTHORIZATION. Each of these correspond to a
bit position in the _FLAGS_ mask and they are combined with bit-OR.
Refer to dbus docuemntation for further details.

== SEE ALSO

*newlisp*, *packnl*, *incore.lsp*

== AUTHOR

Ralph Ronnquist <ralph.ronnquist@gmail.com>