lsp-dbus.a.8.adoc

   1 = lsp-dbus.a(8)
   2 :doctype: manpage
   3 :revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
   4 :BC: *:*
   5
   6 == NAME
   7
   8 lsp-dbus.a - Dbus API for newlisp.
   9
  10 == SYNOPSIS
  11
  12 .With packnl
  13 packnl _main.lsp_ *-A lsp-misc.a* *-A lsp-dbus.a*
  14
  15
  16 .With incore.lsp
  17 (load "incore.lsp") +
  18 (archive "lsp-misc.a") +
  19 (archive "lsp-utils.a") +
  20 (load "lsp-dbus.lsp")
  21
  22 == DESCRIPTION
  23
  24 *lsp-dbus.a* implements a newlisp API for Dbus. The module includes a
  25 context _DbusConnection_ that implements the connection/authorization
  26 level and a context _Dbus_ that implements the "object
  27 modelling"/messaging level.
  28
  29 The source software is divided into a couple of different source files
  30 that are packed together into an _ar_ archive.
  31
  32 Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*.
  33
  34 === lsp-dbus API
  35
  36 (*load "lsp-dbus.lsp")::
  37
  38 The main file, *lsp-dbus.lsp*, includes connection setup and client
  39 registration as part of its loading. Currently it connects on the
  40 system bus (only). It also installs the funcion _main-loop_ as
  41 _prompt-event_ function for processing any unsolicited messages from
  42 dbus (so called "signals").
  43
  44 (*Dbus* _PATH_ [_DESTINATION_])::
  45
  46 The _Dbus_ context is used for identifying remote "objects" with the
  47 given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_
  48 object provides a proxying channel for invoking methods targeting the
  49 given path on the given bus-name application. When omitted, the
  50 _DESTINATION_ string is obtained from the _PATH_ string following the
  51 convention of chopping the initial "/" and replacing remaining "/"
  52 with ".".
  53 +
  54 Note that a term like _(Dbus "/org/freedesktop/ObjectManager")_ define
  55 an identifer for, or pointer to, a remote "dbusobject", and it is here
  56 referred to as _PROXY_.
  57
  58 (*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_)::
  59
  60 The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the
  61 gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message
  62 _FLAGS_. The function sends a dbus message and then polls for debus
  63 messages until the reply message has arrived. any and all other
  64 messages recevied meanwhile are added to the _pending_ list.
  65 +
  66 The _METHOD_ is given as a string composed as path, interface, name
  67 and signature
  68 +
  69 ====
  70 _path:interface.name(signature)_
  71 ====
  72 +
  73 The _path:_ component including the colon is optional and taken from
  74 the _PROXY_ by default. The _interface._ component incuding the period
  75 is also optional as per dbus documentation: a method call without
  76 explicit interface results in that the method name is looked up across
  77 all interfaces of the destination path.
  78 +
  79 The _SIGNATURE_ is the dbus style signature as a character sequence,
  80 where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE,
  81 BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD
  82 respectivly (both BOOLEAN and FD are also UINT32); a indicates
  83 "array"; s, o and g indicate strings of various restrictions;
  84 parentheses and curly braces wrap "struct" signatures, and v indicates
  85 a pair of a data item preceded by its signature. Refer to dbus
  86 documentation for further details.
  87 +
  88 The given _ARGUMENTS_ is a list structure that must correspond to the
  89 given signature. All number and string values are mapped naturally
  90 into the indicated signatures while arrays, struct and variant
  91 elements should occur as lists: an array is formed from the list of
  92 elements, as is a struct. A variant typed element must occur as the
  93 list of signature and data. See also the MARSHALLING section below.
  94 +
  95 The optional _FLAGS_ argument is given either a bit mask (number) or a
  96 list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_,
  97 _NO_AUTO_START_ and _ALLOW_INTERACTIVE_AUTHORIZATION_. Each of these
  98 correspond to a bit position in the _FLAGS_ mask and they are combined
  99 with bit-OR. Refer to dbus documentation for further details.
 100 +
 101 .Some :invoke usage examples
 102 ----
 103 (:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0))
 104
 105 (:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0))
 106
 107 (setf BT (Dbus "/" "org.bluez"))
 108 (:invoke BT "GetManagedObjects()")
 109 (Dbus:process-pending)
 110 ----
 111 +
 112 Note "org.bluez" here provides the "GetManagedObjects()" method of
 113 interface "org.freedesktop.ObjectManager" unambiguously on the root
 114 path, "/", rather than its bus name path "/org/bluez".
 115 +
 116 While this process is waiting for the _METHOD_CALL_ reply it may
 117 receive signal messsages from _dbus_. These will be added to the list
 118 of "pending callbacks" that is processed via the _process-all-pending_
 119 function, either via an explicit call following the handshake or
 120 "automagically" as part of the _main-loop_ function that gets
 121 installed as as _prompt-event_ function.
 122 +
 123 ==== Return value:
 124 +
 125 The return value of *:invoke* is the METHOD_REPLY message reduced into
 126 an association list of the headers extended with the reoly value
 127 wrapped into an association keyed by the empty string. The actual
 128 return value is thus selected with _(-1 -1 -1)_
 129
 130 (*Dbus:process-all-pending*)::
 131
 132 The _process-all-pending_ function processes all pending signal
 133 messages by invoking their associated handler functions.
 134
 135 (*prompt-event Dbus:main-loop*)::
 136
 137 The _main-loop_ function is set up as _prompt-event_ function for a
 138 _net-select_ on both stdin and the dbus socket as well as to process
 139 all pending signal messages. Any input from dbus, which are signal
 140 messages, are added to the pending list, which also is processed one
 141 message at a time until empty.
 142 +
 143 Note that newlisp uses readline for input but that this is not
 144 activated in _main-loop_. Therefore line editing is not available
 145 immediately. However the operator may use ^D to leave the main-loop
 146 and enter the "normal" command line input state for a single line
 147 input (with line editing), or an initial newline for multi-line input
 148 that is "submitted" by means of two newlines.
 149
 150 (*:handler* _OBJ_ _KEY_ _HANDLER_):: This function registers a handler
 151 callback for a key that is a string composed as
 152 "path:interface.member(signature)". The handler function takes a
 153 single argument, which is the list of unmarshalled actual call
 154 arguments.
 155
 156 === MARSHALLING
 157
 158 dbus documentation uses the terms "marshalling" and "unmarshalling"
 159 for the translations of data from/to program data to/from dbus message
 160 bytes. The data in newlisp mapped straight-forwardly with the special
 161 note that both "struct" and "array" are held as lists in newlisp. To
 162 that end, the data for the variant type signature must be wrapped into
 163 an extra list of the format _(signature value)_ with explcit dbus
 164 signature string. However, such wrapping does not take place upon
 165 unmarshalling.
 166
 167
 168 == SEE ALSO
 169
 170 *newlisp*, *packnl*, *incore.lsp*
 171
 172 == AUTHOR
 173
 174 Ralph Ronnquist <ralph.ronnquist@gmail.com>