[Emacs-diffs] emacs/doc/misc dbus.texi

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       09/11/13 16:18:57

Modified files:
        doc/misc       : dbus.texi 

Log message:
        * 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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/misc/dbus.texi?cvsroot=emacs&r1=1.37&r2=1.38

Patches:
Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -b -r1.37 -r1.38
--- dbus.texi   25 Aug 2009 19:26:07 -0000      1.37
+++ dbus.texi   13 Nov 2009 16:18:57 -0000      1.38
@@ -950,7 +950,7 @@
   '(:array)                   ;; No actions (empty array of strings).
   '(:array :signature "@address@hidden") ;; No hints
                               ;; (empty array of dictionary entries).
-  ':int32 -1)                 ;; Default timeout.
+  :int32 -1)                 ;; Default timeout.
 
 @result{} 3
 @end lisp
@@ -1210,7 +1210,7 @@
 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 @@
 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
address@hidden, indicating the success if the method.  As test tool one
address@hidden, 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 @@
 @end example
 @end defun
 
address@hidden dbus-register-property bus service path interface property 
access value
+With this function, an application declares a @var{property} on the D-Bus
address@hidden
+
address@hidden is either the symbol @code{:system} or the symbol
address@hidden:session}.
+
address@hidden is the D-Bus service name of the D-Bus.  It must be a
+known name.
+
address@hidden is the D-Bus object path @var{service} is
+registered.
+
address@hidden is the name of the interface used at @var{path},
address@hidden is the name of the property of @var{interface}.
+
address@hidden indicates, whether the property can be changed by other
+services via D-Bus.  It must be either the symbol @code{:read} or
address@hidden: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
address@hidden:readwrite} can be changed by @code{dbus-set-property}.
+
+The interface @samp{org.freedesktop.DBus.Properties} is added to
address@hidden, including a default handler for the @samp{Get},
address@hidden and @samp{Set} methods of this interface.  Example:
+
address@hidden
+(dbus-register-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
+
address@hidden ((: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)
+
address@hidden ((:session "org.freedesktop.TextEditor" "version")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
address@hidden lisp
+
+Other D-Bus applications can read the property via the default methods
address@hidden and
address@hidden  Testing is also
+possible via the command line tool @code{dbus-send} in a shell:
+
address@hidden
+# dbus-send --session --print-reply \
+    --dest="org.freedesktop.TextEditor" \
+    "/org/freedesktop/TextEditor" \
+    "org.freedesktop.DBus.Properties.GetAll" \
+    string:"org.freedesktop.TextEditor"
+
address@hidden 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"
+         )
+      ]
address@hidden example
+
+It is also possible, to apply the @code{dbus-get-property},
address@hidden and @code{dbus-set-property} functions
+(@pxref{Properties and Annotations}).
+
address@hidden
+(dbus-set-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version" "23.1.50")
+
address@hidden "23.1.50"
+
+(dbus-get-property
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "version")
+
address@hidden "23.1.50"
address@hidden lisp
address@hidden defun
+
address@hidden dbus-unregister-object object
+Unregister @var{object} from the D-Bus.  @var{object} must be the
+result of a preceding @code{dbus-register-method},
address@hidden 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.
address@hidden defun
+
 
 @node Signals
 @chapter Sending and receiving signals.
@@ -1452,13 +1554,6 @@
 which objects the GNU/Linux @code{hal} daemon adds.
 @end defun
 
address@hidden 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
address@hidden call.  It returns @code{t} if @var{object}
-has been unregistered, @code{nil} otherwise.
address@hidden defun
-
 
 @node Errors and Events
 @chapter Errors and events.