= lsp-dbus.a(8)
:doctype: manpage
:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:BC: *:*
== NAME
== 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"
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
projects / rrq / lsp-utils.git / blobdiff