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 (see
  39 *:initialize* below) and client registration (i.e. issuing the dbus
  40 "Hello():s" message as part of its loading. Currently it connects on
  41 the system bus (only). It also installs the funcion _main-loop_ as
  42 _prompt-event_ function for processing any unsolicited messages from
  43 dbus (so called "signals").
  44
  45 ==== The Dbus Context
  46
  47 (*Dbus* _PATH_ [_DESTINATION_])::
  48
  49 The _Dbus_ context is used for identifying remote "objects" with the
  50 given _PATH_ and _DESTINATION_ (aka bus name). The resulting _FOOP_
  51 object provides a proxying channel for invoking methods targeting the
  52 given path on the given bus-name application. When omitted, the
  53 _DESTINATION_ string is obtained from the _PATH_ string following the
  54 convention of chopping the initial "/" and replacing remaining "/"
  55 with ".".
  56 +
  57 ====
  58 Note that a term like _(Dbus "/org/freedesktop/DBus")_ defines an
  59 identifer for, or pointer to, a remote "dbus object", and it is here
  60 referred to as _PROXY_. The _PATH_ part serves as the object
  61 identifier for dbus while the _DESTINATION_ part is an identfier for
  62 the application that we expect holds the actual "dbus object" for the
  63 given _PATH_. This particular term identifies object path
  64 "/org/freedesktop/DBus" held by the application named
  65 "org.freedesktop.DBus", which belongs to the dbus framewok.
  66
  67 There is however no central arbitration for paths in dbus. It all
  68 relies on application developers documenting which paths their
  69 applications service and access, and then client applications rely on
  70 using the destination tags for directing their messages to the
  71 intended applications.
  72 ====
  73
  74 (*:new-path* _PROXY_ _PATH_)::
  75
  76 The _:new-path_ method clones the FOOP object to dentify the given
  77 _PATH_ for the same destination.
  78
  79 (*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_)::
  80
  81 The _:invoke_ method performs a Dbus _METHOD_CALL_ handshake for the
  82 gven _PROXY_ using the given _METHOD_, _ARGUMENTS_ and message
  83 _FLAGS_. The function sends a dbus message and then polls for debus
  84 messages until the reply message has arrived. any and all other
  85 messages recevied meanwhile are added to the _pending_ list.
  86 +
  87 The _METHOD_ is given as a string composed as path, interface, name
  88 and signature
  89 +
  90 ====
  91 _path:interface.name(signature)_
  92 ====
  93 +
  94 The _path:_ component including the colon is optional and taken from
  95 the _PROXY_ by default. The _interface._ component incuding the period
  96 is also optional as per dbus documentation: a method call without
  97 explicit interface results in that the method name is looked up across
  98 all interfaces of the destination path.
  99 +
 100 The _SIGNATURE_ is the dbus style signature as a character sequence,
 101 where y, b, n, q, i, u, x, t, d and h indicate the basic types BYTE,
 102 BOOLEAN, INT16, UINT16, INT32, UINT32, INT64, UINT64, DOUBLE and FD
 103 respectivly (both BOOLEAN and FD are also UINT32); a indicates
 104 "array"; s, o and g indicate strings of various restrictions;
 105 parentheses and curly braces wrap "struct" signatures, and v indicates
 106 a pair of a data item preceded by its signature. Refer to dbus
 107 documentation for further details.
 108 +
 109 The given _ARGUMENTS_ is a list structure that must correspond to the
 110 given signature. All number and string values are mapped naturally
 111 into the indicated signatures while arrays, struct and variant
 112 elements should occur as lists: an array is formed from the list of
 113 elements, as is a struct. A variant typed element must occur as the
 114 list of signature and data. See also the MARSHALLING section below.
 115 +
 116 The optional _FLAGS_ argument is given either a bit mask (number) or a
 117 list of the _Dbus_ context symbols _NO_REPLY_EXPECTED_,
 118 _NO_AUTO_START_ and _ALLOW_INTERACTIVE_AUTHORIZATION_. Each of these
 119 correspond to a bit position in the _FLAGS_ mask and they are combined
 120 with bit-OR. Refer to dbus documentation for further details.
 121 +
 122 .Some :invoke usage examples
 123 ----
 124 (:invoke Dbus:ROOT "RequestName(su)" '("my.client" 0))
 125
 126 (:invoke Dbus:ROOT "GetNameOwner(s)" '("org.bluez" 0))
 127
 128 (setf BT (Dbus "/" "org.bluez"))
 129 (:invoke BT "GetManagedObjects()")
 130 (Dbus:process-pending)
 131 ----
 132 +
 133 Note "org.bluez" here provides the "GetManagedObjects()" method of
 134 interface "org.freedesktop.ObjectManager" unambiguously on the root
 135 path, "/", rather than its bus name path "/org/bluez".
 136 +
 137 While this process is waiting for the _METHOD_CALL_ reply it may
 138 receive signal messsages from _dbus_. These will be added to the list
 139 of "pending callbacks" that is processed via the _process-all-pending_
 140 function, either via an explicit call following the handshake or
 141 "automagically" as part of the _main-loop_ function that gets
 142 installed as as _prompt-event_ function.
 143 +
 144 .Return value:
 145 [caption=""]
 146 ====
 147 The return value of *:invoke* is the METHOD_REPLY message reduced into
 148 an association list of the headers (with the _Dbus_ header symbols as
 149 keys) extended with the method return value as a list wrapped into a
 150 final association that is keyed by the empty string.
 151
 152 In other words, the template for using *:invoke* may look like the
 153 following:
 154 ----
 155 (if (:invoke ...) ($it -1 -1 -1))
 156 ----
 157 ====
 158
 159 (*Dbus:process-all-pending*)::
 160
 161 The _process-all-pending_ function processes all pending signal
 162 messages by invoking their associated handler functions.
 163
 164 (*prompt-event Dbus:main-loop*)::
 165
 166 The _main-loop_ function is set up as _prompt-event_ function for a
 167 combined _net-select_ on both stdin and the dbus socket as well as to
 168 process all pending signal messages. Any input from dbus, which are
 169 signal messages, are added to the pending list, which also is
 170 processed one message at a time until empty.
 171 +
 172 Note that newlisp uses readline for input but that this is not
 173 activated in _main-loop_. Therefore line editing is not available
 174 immediately. However the operator may use ^D to leave the main-loop
 175 and enter the "normal" command line input state for a single line
 176 input (with line editing), or an initial newline for multi-line input
 177 that is "submitted" by means of two newlines.
 178
 179 (*:handler* _OBJ_ _KEY_ _HANDLER_)::
 180
 181 This function registers a handler callback for a key that is a string
 182 composed as "path:interface.member(signature)". The handler function
 183 takes a single argument, which is the list of unmarshalled actual call
 184 arguments.
 185
 186 ==== The DbusConnection Context
 187
 188 (*DbusConnection* _PATH)::
 189
 190 The _DbusConnection_ context is a FOOP implementation intended for the
 191 dbus socket connection. Each _(DbusConnection PATH)_ is intended to be
 192 like a real object that contains state, namely the opened socket file
 193 descriptor, the connection name given to it by DBus on connection and
 194 and the messaging serial.
 195
 196 (*:serial++* _OBJECT_)::
 197
 198 This method increments the serial of the given object.
 199
 200 (*:open-socket* _OBJECT_)::
 201
 202 This method opens the path and assignes the socket file descriptor of
 203 the given object. Before that though, if the socket file descriptor is
 204 non-negative then that file descriptor is closed before opening the
 205 object's path.
 206
 207 (*:read-message* _OBJECT_)::
 208
 209 This method reads the next message by reading data from the socket
 210 successively while there's something to read within a millisecond.
 211
 212 (*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_])::
 213
 214 This method performs a "raw" text-based handshake on the connection,
 215 which means to send the given message and then read and return the
 216 response message. If a _PATTERN_ is given, then the response must
 217 match the pattern (assigning the automatic variables $1 etc according
 218 to the pattern). The method returns nil if the given pattern is not
 219 matched. Note that this method is used only during connection setup
 220 and dbus communication uses its own marshalling subsequently.
 221
 222 (*:initialize* _OBJECT_  [_USER_])::
 223
 224 This method performs the connection set up including the very first
 225 newline and the subsequent AUTH handshake. It ends with the connection
 226 in "BEGIN" mode and returns the received connection name.
 227
 228 === MARSHALLING
 229
 230 dbus documentation uses the terms "marshalling" and "unmarshalling"
 231 for the translations of data from/to program data to/from dbus message
 232 bytes. The data in newlisp mapped straight-forwardly with the special
 233 note that both "struct" and "array" are held as lists in newlisp. To
 234 that end, the data for the variant type signature must be wrapped into
 235 an extra list of the format _(signature value)_ with explcit dbus
 236 signature string. However, such wrapping does not take place upon
 237 unmarshalling.
 238
 239
 240 == SEE ALSO
 241
 242 *newlisp*, *packnl*, *incore.lsp*
 243
 244 == AUTHOR
 245
 246 Ralph Ronnquist <ralph.ronnquist@gmail.com>