expanded documentation

diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc
index 1fe87296cf9052fbbf935c4c6431a3566c6fc32a..92ce4a98fdedaa02f7f0c5bb2d7390499929aeb2 100644 (file)
--- a/lsp-dbus.a.8.adoc
+++ b/lsp-dbus.a.8.adoc
@@ -1,6 +1,7 @@
 = lsp-dbus.a(8)
 :doctype: manpage
 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:BC: *:*
 
 == NAME
 
@@ -21,82 +22,132 @@ packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a*
 == 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+.
+context _DbusConnection_ that implements the connection/authorization
+level and a context _Dbus_ that implements the "object
+modelling"/messaging level.
 
-=== Essential API
+The source software is divided into a couple of different source files
+that are packed together into an _ar_ archive.
 
-On loading::
+Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*.
 
-The main file, +lsp-dbus.lsp+, includes connection setup and client
+=== lsp-dbus API
+
+(*load "lsp-dbus.lsp")::
+
+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
+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_])::
+(*Dbus* _PATH_ [_DESTINATION_])::
+
+The _Dbus_ context is used for identifying remote "objects" with the
+given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_
+object provides a proxying channel for invoking methods targeting the
+given path on the given bus-name application. When omitted, the
+_DESTINATION_ string is obtained from the _PATH_ string following the
+convention of chopping the initial "/" and replacing remaining "/"
+with ".".
++
+Note that a term like _(Dbus "/org/freedesktop/ObjectManager")_ define
+an identifer for, or pointer to, a remote "dbusobject", and it is here
+referred to as _PROXY_.
 
-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* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_)::
 
-(: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 _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the
+gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message
+_FLAGS_. The function sends a dbus message and then polls for debus
+messages until the reply message has arrived. any and all other
+messages recevied meanwhile are added to the _pending_ list.
++
+The _METHOD_ is given as a string composed as path, interface, name
+and signature
++
+====
+_path:interface.name(signature)_
+====
++
+The _path:_ component including the colon is optional and taken from
+the _PROXY_ by default. The _interface._ component incuding the period
+is also optional as per dbus documentation: a method call without
+explicit interface results in that the method name is looked up across
+all interfaces of the destination path.
++
+The _SIGNATURE_ is the dbus style signature as a character sequence,
+where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE,
+BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD
+respectivly (both BOOLEAN and FD are also UINT32); a indicates
+"array"; s, o and g indicate strings of various restrictions;
+parentheses and curly braces wrap "struct" signatures, and v indicates
+a pair of a data item preceded by its signature. Refer to dbus
+documentation for further details.
 +
 The given _ARGUMENTS_ is a list structure that must correspond to the
-given signature. See the MARSHALLING below.
+given signature. All number and string values are mapped naturally
+into the indicated signatures while arrays, struct and variant
+elements should occur as lists: an array is formed from the list of
+elements, as is a struct. A variant typed element must occur as the
+list of signature and data. See also the MARSHALLING section 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.
+The optional _FLAGS_ argument is given either a bit mask (number) or a
+list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_,
+_NO_AUTO_START_ and _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 documentation for further details.
 +
-.invoke usage examples
+.Some :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 "GetManagedObjects()")
+(Dbus:process-pending)
+----
 +
-(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".
+Note "org.bluez" here provides the "GetManagedObjects()" method of
+interface "org.freedesktop.ObjectManager" unambiguously on the root
+path, "/", rather than its bus name 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+
+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.
+"automagically" as part of the _main-loop_ function that gets
+installed as as _prompt-event_ function.
++
+==== Return value:
++
+The return value of *:invoke* is the METHOD_REPLY message reduced into
+an association list of the headers extended with the reoly value
+wrapped into an association keyed by the empty string. The actual
+return value is thus selected with _(-1 -1 -1)_
 
-(Dbus:process-all-pending)::
+(*Dbus:process-all-pending*)::
 
-The +process-all-pending+ function processes all pending signal
+The _process-all-pending_ function processes all pending signal
 messages by invoking their associated handler functions.
 
-(prompt-event Dbus:main-loop)::
+(*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
+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
+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
+(*:handler* _OBJ_ _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
@@ -113,13 +164,6 @@ 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