lsp-dbus.a.8.adoc

   1 = lsp-dbus.a(8)
   2 :doctype: manpage
   3 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   4
   5 == NAME
   6
   7 lsp-dbus.a - Dbus API for newlisp.
   8
   9 == SYNOPSIS
  10
  11 .With packnl
  12 packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a*
  13
  14
  15 .With incore.lsp
  16 (load "incore.lsp") +
  17 (archive "lsp-misc.a") +
  18 (archive "lsp-utils.a") +
  19 (load "lsp-dbus.lsp")
  20
  21 == DESCRIPTION
  22
  23 *lsp-dbus.a* implements a newlisp API for Dbus. The module includes a
  24 context *DbusConnection* implementing the connection/authorization
  25 level and a context *Dbus* that implements the "object modelling"
  26 level. The software is divided into a couple of different source files
  27 that are packed together int a _ar_ archive. It also depends on +foop+
  28 and +prog1+ from +lsp-misc.a+.
  29
  30 === Essential API
  31
  32 On loading::
  33
  34 The main file, +lsp-dbus.lsp+, includes connection setup and client
  35 registration as part of its loading. Currently it connects on the
  36 system bus only. It also installs the funcion +main-loop+ as
  37 +prompt-event+ function for processing any unsolicited messages from
  38 dbus (so called "signals").
  39
  40 (Dbus _PATH_ [_DESTINATION_])::
  41
  42 The context +Dbus+ is used for identifying remote services which by
  43 default have coinsiding path _PATH_ and _DESTINATION_ (aka bus name).
  44 The resulting FOOP object provides a channel for invoking methods.
  45
  46 (:invoke _OBJECT_ _METHOD_ _ARGUMENTS_ _FLAGS_):: The +:invoke+ method
  47 performs a Dbus +METHOD_CALL+ handshake for the gven _OBJECT_ using
  48 the given _METHOD_, _ARGUMENTS_and message _FLAGS_, while also polling
  49 s.c. signal messages from Dbus. The _METHOD_ is given as a string
  50 composed as "_path_:_interface_._name_(_signature_)", although the
  51 _path_ and _interface_ parts are optional. If without explicit _path_,
  52 the _OBJECT_ path is used. If without explicit interface, the method
  53 will be looked up across all interfaces of the destination path.
  54 +
  55 The given _ARGUMENTS_ is a list structure that must correspond to the
  56 given signature. See the MARSHALLING below.
  57 +
  58 The optional _FLAGS_ is either a bit mask or a list of applicable
  59 method call flags as Dbus symbols. See METHOD_CALL flags below.
  60 +
  61 .invoke usage examples
  62 (:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0))
  63 +
  64 (:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0))
  65 +
  66 (setf BT (Dbus "/org/bluez")) +
  67 (:invoke BT "/:org.freedesktop.ObjectManager.GetManagedObjects()") +
  68 ; Note that "org.bluez" here provides the "GetManagedObjects()" +
  69 ; method on the root path, "/", rather than its own path +
  70 ; "/org/bluez".
  71 +
  72 While this process is waiting for the +METHOD_CALL+ reply it may
  73 receive signal messsages from +dbus+. These will be added to the list
  74 of "pending callbacks" that is processed via the +process-all-pending+
  75 function, either via an explicit call following the handshake or
  76 "automagically" as part of the +main-loop+ function that gets
  77 installed as as +prompt-event+ function.
  78
  79 (Dbus:process-all-pending)::
  80
  81 The +process-all-pending+ function processes all pending signal
  82 messages by invoking their associated handler functions.
  83
  84 (prompt-event Dbus:main-loop)::
  85
  86 The +main-loop+ function is set up as +prompt-event+ function for a
  87 +net-select+ on both stdin and the dbus socket as well as to process
  88 all pending signal messages. Any input from dbus, which are signal
  89 messages, are added to the pending list, which also is processed one
  90 message at a time until empty.
  91 +
  92 Note that newlisp uses readline for input but that this is not
  93 activated in +main-loop+. Therefore line editing is not available
  94 immediately. However the operator may use ^D to leave the main-loop
  95 and enter the "normal" command line input state for a single line
  96 input (with line editing), or an initial newline for multi-line input
  97 that is "submitted" by means of two newlines.
  98
  99 (Dbus:handler _KEY_ _HANDLER_):: This function registers a handler
 100 callback for a key that is a string composed as
 101 "path:interface.member(signature)". The handler function takes a
 102 single argument, which is the list of unmarshalled actual call
 103 arguments.
 104
 105 === MARSHALLING
 106
 107 dbus documentation uses the terms "marshalling" and "unmarshalling"
 108 for the translations of data from/to program data to/from dbus message
 109 bytes. The data in newlisp mapped straight-forwardly with the special
 110 note that both "struct" and "array" are held as lists in newlisp. To
 111 that end, the data for the variant type signature must be wrapped into
 112 an extra list of the format _(signature value)_ with explcit dbus
 113 signature string. However, such wrapping does not take place upon
 114 unmarshalling.
 115
 116 === METHOD_CALL FLAGS
 117
 118 As per dbus documentation, there are three +METHOD_call+ flags:
 119 +Dbus:NO_REPLY_EXPECTED+, +Dbus:NO_AUTO_START+ and
 120 +Dbus:ALLOW_INTERACTIVE_AUTHORIZATION. Each of these correspond to a
 121 bit position in the _FLAGS_ mask and they are combined with bit-OR.
 122 Refer to dbus docuemntation for further details.
 123
 124 == SEE ALSO
 125
 126 *newlisp*, *packnl*, *incore.lsp*
 127
 128 == AUTHOR
 129
 130 Ralph Ronnquist <ralph.ronnquist@gmail.com>