From: Ralph Ronnquist Date: Sat, 22 Apr 2023 23:16:19 +0000 (+1000) Subject: added new-path method X-Git-Url: https://git.rrq.au/?a=commitdiff_plain;h=138f6efc39783f261ee63fdf9aaa92d77e28c975;p=rrq%2Flsp-utils.git added new-path method --- diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc index a5cc14f..c840c5d 100644 --- a/lsp-dbus.a.8.adoc +++ b/lsp-dbus.a.8.adoc @@ -33,7 +33,7 @@ Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*. === lsp-dbus API -(*load "lsp-dbus.lsp"):: +(*load* "lsp-dbus.lsp"):: The main file, *lsp-dbus.lsp*, includes connection setup (see *:initialize* below) and client registration (i.e. issuing the dbus @@ -42,6 +42,8 @@ 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"). +==== The Dbus Context + (*Dbus* _PATH_ [_DESTINATION_]):: The _Dbus_ context is used for identifying remote "objects" with the @@ -52,9 +54,27 @@ _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/ObjectManager")_ define -an identifer for, or pointer to, a remote "dbusobject", and it is here -referred to as _PROXY_. +==== +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_):: @@ -163,6 +183,8 @@ 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 @@ -182,12 +204,12 @@ 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_) +(*: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_]) +(*: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 @@ -197,7 +219,7 @@ 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_]) +(*: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 diff --git a/lsp-dbus/lsp-dbus.lsp b/lsp-dbus/lsp-dbus.lsp index 8a4f7c4..a810998 100644 --- a/lsp-dbus/lsp-dbus.lsp +++ b/lsp-dbus/lsp-dbus.lsp @@ -69,6 +69,10 @@ (define (Dbus:Dbus PATH (NAME (replace "/" (1 PATH) ".")) (BUS 'SYSTEM-BUS)) (list (context) PATH NAME BUS)) +;; Method to clone a proxy for a given path/object. +(define (new-path PATH) + (list (context) PATH (%name) (%bus))) + ;; Update the connection serial and return it (define (connection++) (case (%bus)