[Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       08/02/06 21:27:28

Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- dbus.texi   21 Jan 2008 20:00:50 -0000      1.14
+++ dbus.texi   6 Feb 2008 21:27:27 -0000       1.15
@@ -158,14 +158,33 @@
 
 @defun dbus-get-name-owner bus service
 For a given service, registered at D-Bus @var{bus} under the name
address@hidden, the unique name of the name owner is returned.  The result is a
-string, or @code{nil} when there exist no name owner of @var{service}.
address@hidden, the unique name of the name owner is returned.  The
+result is a string, or @code{nil} when there exist no name owner of
address@hidden
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.  @var{service} must be a known service name as
 string.
 @end defun
 
address@hidden dbus-ping bus service
+Check whether the service name @var{service} is registered at D-Bus
address@hidden  @var{service} might not have been started yet.  The result
+is either @code{t} or @code{nil}.
+
address@hidden must be either the symbol @code{:system} or the symbol
address@hidden:session}.  @var{service} must be a string.  Example:
+
address@hidden
+(message
+   "%s screensaver on board."
+   (cond
+     ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome")
+     ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE")
+     (t "No")))
address@hidden lisp
address@hidden defun
+
 @defun dbus-get-unique-name bus
 The unique name, under which Emacs is registered at D-Bus @var{bus},
 is returned as string.
@@ -185,7 +204,7 @@
 strings.  The result, the introspection data, is a string in XML
 format. Example:
 
address@hidden
address@hidden
 (dbus-introspect
   :system "org.freedesktop.Hal"
   "/org/freedesktop/Hal/devices/computer")
@@ -206,7 +225,7 @@
       </interface>
       @dots{}
     </node>"
address@hidden example
address@hidden lisp
 
 This example informs us, that the service @code{org.freedesktop.Hal}
 at object path @code{/org/freedesktop/Hal/devices/computer} offers the
@@ -422,20 +441,20 @@
 Lisp objects, according to the type conversion rules described in
 @ref{Type Conversion}.  Example:
 
address@hidden
address@hidden
 (dbus-call-method
   :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
   "org.gnome.seahorse.Keys" "GetKeyField"
   "openpgp:657984B8C7A966DD" "simple-name")
 
 @result{} (t ("Philip R. Zimmermann"))
address@hidden example
address@hidden lisp
 
 If the result of the method call is just one value, the converted Lisp
 object is returned instead of a list containing this single Lisp
 object.  Example:
 
address@hidden
address@hidden
 (dbus-call-method
   :system "org.freedesktop.Hal"
   "/org/freedesktop/Hal/devices/computer"
@@ -443,7 +462,7 @@
   "system.kernel.machine")
 
 @result{} "i686"
address@hidden example
address@hidden lisp
 
 With the @code{dbus-introspect} function it is possible to explore the
 interfaces of @samp{org.freedesktop.Hal} service. It offers the
@@ -454,7 +473,7 @@
 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
 emulate the @code{lshal} command on GNU/Linux systems:
 
address@hidden
address@hidden
 (dolist (device
           (dbus-call-method
             :system "org.freedesktop.Hal"
@@ -484,7 +503,7 @@
       system.chassis.type = \"Notebook\"
       system.firmware.release_date = \"03/19/2005\"
       @dots{}"
address@hidden example
address@hidden lisp
 @end defun
 
 
@@ -530,7 +549,7 @@
 as argument in @code{dbus-unregister-object} for removing the
 registration for @var{method}.  Example:
 
address@hidden
address@hidden
 (defun my-dbus-method-handler (filename)
   (let (result)
     (if (find-file filename)
@@ -548,7 +567,7 @@
 @result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
     ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
      my-method-handler))
address@hidden example
address@hidden lisp
 
 If you invoke the method @code{org.freedesktop.TextEditor.OpenFile}
 from another D-Bus application with a filename as parameter, the file
@@ -592,11 +611,11 @@
 They are converted into D-Bus types as described in @ref{Type
 Conversion}.  Example:
 
address@hidden
address@hidden
 (dbus-send-signal
   :session "org.gnu.Emacs" "/org/gnu/Emacs"
   "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
address@hidden example
address@hidden lisp
 @end defun
 
 @defun dbus-register-signal bus service path interface signal handler
@@ -626,7 +645,7 @@
 received.  It must accept as arguments the output parameters
 @var{signal} is sending.  Example:
 
address@hidden
address@hidden
 (defun my-dbus-signal-handler (device)
   (message "Device %s added" device))
 
@@ -640,7 +659,7 @@
 @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
     ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
      my-signal-handler))
address@hidden example
address@hidden lisp
 
 As we know from the inspection data of interface
 @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
@@ -687,9 +706,9 @@
 Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
 Events, , , elisp}).  The generated event has this form:
 
address@hidden
address@hidden
 (dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} 
@var{member} @var{handler} &rest @var{args})
address@hidden example
address@hidden lisp
 
 @var{bus} identifies the D-Bus the signal is coming from.  It is
 either the symbol @code{:system} or the symbol @code{:session}.
@@ -708,10 +727,10 @@
 In order to inspect the @code{dbus-event} data, you could extend the
 definition of the callback function in @ref{Signals}:
 
address@hidden
address@hidden
 (defun my-dbus-signal-handler (&rest args)
   (message "my-dbus-signal-handler: %S" last-input-event))
address@hidden example
address@hidden lisp
 
 There exist convenience functions which could be called inside a
 callback function in order to retrieve the information from the event.