added new-path method

diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc
index a5cc14ffb5794ad54ac57947ab99ddf4bcc9548e..c840c5d2c66553a849d48bd607459c0724d86360 100644 (file)
--- 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 8a4f7c47d2ee07524b7ac74c04dd7f40a15fc23a..a8109981268bc9e61fdc1dfb03c602ee529a78f3 100644 (file)
--- 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)