* dbus.texi (Type Conversion): Fix typo.

(Asynchronous Methods): Rename `dbus-registered-functions-table' to
`dbus-registered-objects-table'.
(Receiving Method Calls): New defun `dbus-register-property'.  Move
`dbus-unregister-object' here.

2 files changed, 113 insertions, 10 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index a50cd36d4c0..87cf5739f25 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,11 @@
+2009-11-13  Michael Albinus  <michael.albinus@gmx.de>
+
+        * dbus.texi (Type Conversion): Fix typo.
+        (Asynchronous Methods): Rename `dbus-registered-functions-table' to
+        `dbus-registered-objects-table'.
+        (Receiving Method Calls): New defun `dbus-register-property'.  Move
+        `dbus-unregister-object' here.
+
 2009-11-13  Carsten Dominik  <carsten.dominik@gmail.com>
 
         * org.texi: Removed @Ie, @ie, @Eg, @eg macros.
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 3e9d368a752..b4dc42ec3ef 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -950,7 +950,7 @@ elements of this array.  Example:
   '(:array)                   ;; No actions (empty array of strings).
   '(:array :signature "@{sv@}") ;; No hints
                               ;; (empty array of dictionary entries).
-  ':int32 -1)                 ;; Default timeout.
+  :int32 -1)                 ;; Default timeout.
 
 @result{} 3
 @end lisp
@@ -1210,7 +1210,7 @@ They are converted into D-Bus types as described in @ref{Type
 Conversion}.
 
 Unless @var{handler} is @code{nil}, the function returns a key into
-the hash table @code{dbus-registered-functions-table}.  The
+the hash table @code{dbus-registered-objects-table}.  The
 corresponding entry in the hash table is removed, when the return
 message has been arrived, and @var{handler} is called.  Example:
 
@@ -1316,7 +1316,7 @@ registration for @var{method}.  Example:
 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
 from another D-Bus application with a filename as parameter, the file
 is opened in Emacs, and the method returns either @var{true} or
-@var{false}, indicating the success if the method.  As test tool one
+@var{false}, indicating the success of the method.  As test tool one
 could use the command line tool @code{dbus-send} in a shell:
 
 @example
@@ -1358,6 +1358,108 @@ The test runs then
 @end example
 @end defun
 
+@defun dbus-register-property bus service path interface property access value
+With this function, an application declares a @var{property} on the D-Bus
+@var{bus}.
+
+@var{bus} is either the symbol @code{:system} or the symbol
+@code{:session}.
+
+@var{service} is the D-Bus service name of the D-Bus.  It must be a
+known name.
+
+@var{path} is the D-Bus object path @var{service} is
+registered.
+
+@var{interface} is the name of the interface used at @var{path},
+@var{property} is the name of the property of @var{interface}.
+
+@var{access} indicates, whether the property can be changed by other
+services via D-Bus.  It must be either the symbol @code{:read} or
+@code{:readwrite}.  @var{value} is the initial value of the property,
+it can be of any valid type (see @code{dbus-call-method} for details).
+
+If @var{property} already exists on @var{path}, it will be
+overwritten.  For properties with access type @code{:read} this is the
+only way to change their values.  Properties with access type
+@code{:readwrite} can be changed by @code{dbus-set-property}.
+
+The interface @samp{org.freedesktop.DBus.Properties} is added to
+@var{path}, including a default handler for the @samp{Get},
+@samp{GetAll} and @samp{Set} methods of this interface.  Example:
+
+@lisp
+(dbus-register-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
+
+@result{} ((:session "org.freedesktop.TextEditor" "name")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
+
+(dbus-register-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version" :readwrite emacs-version)
+
+@result{} ((:session "org.freedesktop.TextEditor" "version")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
+@end lisp
+
+Other D-Bus applications can read the property via the default methods
+@samp{org.freedesktop.DBus.Properties.Get} and
+@samp{org.freedesktop.DBus.Properties.GetAll}.  Testing is also
+possible via the command line tool @code{dbus-send} in a shell:
+
+@example
+# dbus-send --session --print-reply \
+    --dest="org.freedesktop.TextEditor" \
+    "/org/freedesktop/TextEditor" \
+    "org.freedesktop.DBus.Properties.GetAll" \
+    string:"org.freedesktop.TextEditor"
+
+@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3
+      array [
+         dict entry(
+            string "name"
+            variant             string "GNU Emacs"
+         )
+         dict entry(
+            string "version"
+            variant             string "23.1.50.5"
+         )
+      ]
+@end example
+
+It is also possible, to apply the @code{dbus-get-property},
+@code{dbus-get-all-properties} and @code{dbus-set-property} functions
+(@pxref{Properties and Annotations}).
+
+@lisp
+(dbus-set-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version" "23.1.50")
+
+@result{} "23.1.50"
+
+(dbus-get-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version")
+
+@result{} "23.1.50"
+@end lisp
+@end defun
+
+@defun dbus-unregister-object object
+Unregister @var{object} from the D-Bus.  @var{object} must be the
+result of a preceding @code{dbus-register-method},
+@code{dbus-register-property} or @code{dbus-register-signal} call
+(@pxref{Signals}).  It returns @code{t} if @var{object} has been
+unregistered, @code{nil} otherwise.
+
+When @var{object} identifies the last method or property, which is
+registered for the respective service, Emacs releases its association
+to the service from D-Bus.
+@end defun
+
 
 @node Signals
 @chapter Sending and receiving signals.
@@ -1452,13 +1554,6 @@ machine, when registered for signal @samp{DeviceAdded}, will show you
 which objects the GNU/Linux @code{hal} daemon adds.
 @end defun
 
-@defun dbus-unregister-object object
-Unregister @var{object} from the D-Bus.  @var{object} must be the
-result of a preceding @code{dbus-register-signal} or
-@code{dbus-register-method} call.  It returns @code{t} if @var{object}
-has been unregistered, @code{nil} otherwise.
-@end defun
-
 
 @node Errors and Events
 @chapter Errors and events.