X-Git-Url: https://git.rrq.au/?a=blobdiff_plain;f=lsp-dbus.a.8.adoc;h=c840c5d2c66553a849d48bd607459c0724d86360;hb=138f6efc39783f261ee63fdf9aaa92d77e28c975;hp=1fe87296cf9052fbbf935c4c6431a3566c6fc32a;hpb=a86cabca62bd753e6d6eb66fbb1473b8d2099dec;p=rrq%2Flsp-utils.git diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc index 1fe8729..c840c5d 100644 --- 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,87 +22,209 @@ 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 -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 +=== lsp-dbus API + +(*load* "lsp-dbus.lsp"):: + +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"). -(Dbus _PATH_ [_DESTINATION_]):: +==== The Dbus Context -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. +(*Dbus* _PATH_ [_DESTINATION_]):: -(: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 _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/DBus")_ defines an +identifer for, or pointer to, a remote "dbus object", and it is here +referred to as _PROXY_. The _PATH_ part serves as the object +identifier for dbus while the _DESTINATION_ part is an identfier for +the application that we expect holds the actual "dbus object" for the +given _PATH_. This particular term identifies object path +"/org/freedesktop/DBus" held by the application named +"org.freedesktop.DBus", which belongs to the dbus framewok. + +There is however no central arbitration for paths in dbus. It all +relies on application developers documenting which paths their +applications service and access, and then client applications rely on +using the destination tags for directing their messages to the +intended applications. +==== + +(*:new-path* _PROXY_ _PATH_):: + +The _:new-path_ method clones the FOOP object to dentify the given +_PATH_ for the same destination. + +(*:invoke* _PROXY_ _METHOD_ _ARGUMENTS_ _FLAGS_):: + +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. - -(Dbus:process-all-pending):: - -The +process-all-pending+ function processes all pending signal +"automagically" as part of the _main-loop_ function that gets +installed as as _prompt-event_ function. ++ +.Return value: +[caption=""] +==== +The return value of *:invoke* is the METHOD_REPLY message reduced into +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*):: + +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 -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. +The _main-loop_ function is set up as _prompt-event_ function for a +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 +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 -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. +==== The DbusConnection Context + +(*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" @@ -113,13 +236,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