From: Ralph Ronnquist Date: Tue, 18 Apr 2023 08:07:23 +0000 (+1000) Subject: More documentation. X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=c64b0953bf1d151c97e9382fe8c825155f22fbd6;p=rrq%2Flsp-utils.git More documentation. --- diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc index 92ce4a9..a5cc14f 100644 --- a/lsp-dbus.a.8.adoc +++ b/lsp-dbus.a.8.adoc @@ -35,9 +35,10 @@ Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*. (*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 +The main file, *lsp-dbus.lsp*, includes connection setup (see +*:initialize* below) and client registration (i.e. issuing the dbus +"Hello():s" message 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"). @@ -120,12 +121,20 @@ 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. + -==== Return value: -+ +.Return value: +[caption=""] +==== 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)_ +an association list of the headers (with the _Dbus_ header symbols as +keys) extended with the method return value as a list wrapped into a +final association that is keyed by the empty string. + +In other words, the template for using *:invoke* may look like the +following: +---- +(if (:invoke ...) ($it -1 -1 -1)) +---- +==== (*Dbus:process-all-pending*):: @@ -135,10 +144,10 @@ 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. +combined _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 @@ -147,12 +156,53 @@ 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. -(*: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 +(*: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 arguments. +(*DbusConnection* _PATH):: + +The _DbusConnection_ context is a FOOP implementation intended for the +dbus socket connection. Each _(DbusConnection PATH)_ is intended to be +like a real object that contains state, namely the opened socket file +descriptor, the connection name given to it by DBus on connection and +and the messaging serial. + +(*:serial++* _OBJECT_):: + +This method increments the serial of the given object. + +(*:open-socket* _OBJECT_):: + +This method opens the path and assignes the socket file descriptor of +the given object. Before that though, if the socket file descriptor is +non-negative then that file descriptor is closed before opening the +object's path. + +(*:read-message* _OBJECT_) + +This method reads the next message by reading data from the socket +successively while there's something to read within a millisecond. + +(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_]) + +This method performs a "raw" text-based handshake on the connection, +which means to send the given message and then read and return the +response message. If a _PATTERN_ is given, then the response must +match the pattern (assigning the automatic variables $1 etc according +to the pattern). The method returns nil if the given pattern is not +matched. Note that this method is used only during connection setup +and dbus communication uses its own marshalling subsequently. + +(*:initialize* _OBJECT_ [_USER_]) + +This method performs the connection set up including the very first +newline and the subsequent AUTH handshake. It ends with the connection +in "BEGIN" mode and returns the received connection name. + === MARSHALLING dbus documentation uses the terms "marshalling" and "unmarshalling"