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

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       08/07/31 18:49:26

Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -b -r1.21 -r1.22
--- dbus.texi   18 Jul 2008 20:25:54 -0000      1.21
+++ dbus.texi   31 Jul 2008 18:49:25 -0000      1.22
@@ -45,6 +45,7 @@
 * Inspection::                  Inspection of D-Bus services.
 * Type Conversion::             Mapping Lisp types and D-Bus types.
 * Synchronous Methods::         Calling methods in a blocking way.
+* Asynchronous Methods::        Calling methods non-blocking.
 * Receiving Method Calls::      Offering own methods.
 * Signals::                     Sending and receiving signals.
 * Errors and Events::           Errors and events.
@@ -825,7 +826,7 @@
   "/org/freedesktop/xesam/searcher/main"
   "org.freedesktop.xesam.Search" "HitsAdded")
 
address@hidden \"su\""
address@hidden "su"
 @end lisp
 @end defun
 
@@ -997,8 +998,7 @@
 @cindex synchronous method calls
 
 Methods can be called synchronously (@dfn{blocking}) or asynchronously
-(@dfn{non-blocking}).  Currently, just synchronous methods are
-implemented.
+(@dfn{non-blocking}).
 
 At D-Bus level, a method call consist of two messages: one message
 which carries the input parameters to the object owning the method to
@@ -1014,7 +1014,7 @@
 an interface offered by @var{service}.  It must provide @var{method}.
 
 If the parameter @code{:timeout} is given, the following integer
address@hidden specifies the maximun number of milliseconds the method
address@hidden specifies the maximum number of milliseconds the method
 call must return.  The default value is 25.000.  If the method call
 doesn't return in time, a D-Bus error is raised (@pxref{Errors and
 Events}).
@@ -1092,6 +1092,70 @@
 @end lisp
 @end defun
 
address@hidden dbus-call-method-non-blocking bus service path interface method 
&optional :timeout timeout &rest args
+Call @var{method} on the D-Bus @var{bus}, but don't block the event queue.
+This is necessary for communicating to registered D-Bus methods,
+which are running in the same Emacs process.
+
+The arguments are the same as in @code{dbus-call-method}.  Example:
+
address@hidden
+(dbus-call-method-non-blocking
+  :system "org.freedesktop.Hal"
+  "/org/freedesktop/Hal/devices/computer"
+  "org.freedesktop.Hal.Device" "GetPropertyString"
+  "system.kernel.machine")
+
address@hidden "i686"
address@hidden lisp
address@hidden defun
+
+
address@hidden Asynchronous Methods
address@hidden Calling methods non-blocking.
address@hidden method calls, asynchronous
address@hidden asynchronous method calls
+
address@hidden dbus-call-method-asynchronously bus service path interface 
method handler &optional :timeout timeout &rest args
+This function calls @var{method} on the D-Bus @var{bus}
+asynchronously.  @var{bus} is either the symbol @code{:system} or the
+symbol @code{:session}.
+
address@hidden is the D-Bus service name to be used.  @var{path} is the
+D-Bus object path, @var{service} is registered at.  @var{interface} is
+an interface offered by @var{service}.  It must provide @var{method}.
+
address@hidden is a Lisp function, which is called when the
+corresponding return message has arrived.
+
+If the parameter @code{:timeout} is given, the following integer
address@hidden specifies the maximum number of milliseconds a reply
+message must arrive.  The default value is 25.000.  If there is no
+reply message in time, a D-Bus error is raised (@pxref{Errors and
+Events}).
+
+All other arguments args are passed to @var{method} as arguments.
+They are converted into D-Bus types as described in @ref{Type
+Conversion}.
+
+The function returns a key into the hash table
address@hidden  The corresponding entry in
+the hash table is removed, when the return message has been arrived,
+and @var{handler} is called.  Example:
+
address@hidden
+(dbus-call-method-asynchronously
+  :system "org.freedesktop.Hal"
+  "/org/freedesktop/Hal/devices/computer"
+  "org.freedesktop.Hal.Device" "GetPropertyString" 'message
+  "system.kernel.machine")
+
address@hidden (:system 2)
+
address@hidden i686
address@hidden lisp
address@hidden defun
+
 
 @node Receiving Method Calls
 @chapter Offering own methods.
@@ -1283,7 +1347,9 @@
 @cindex errors
 @cindex events
 
-Input parameters of @code{dbus-call-method} and
+Input parameters of @code{dbus-call-method},
address@hidden,
address@hidden, and
 @code{dbus-register-signal} are checked for correct D-Bus types. If
 there is a type mismatch, the Lisp error @code{wrong-type-argument}
 @code{D-Bus ARG} is raised.
@@ -1303,14 +1369,19 @@
 Events, , , elisp}).  The generated event has this form:
 
 @lisp
-(dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} 
@var{member} @var{handler} &rest @var{args})
+(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} 
@var{interface} @var{member} @var{handler}
+        &rest @var{args})
 @end lisp
 
address@hidden identifies the D-Bus the signal is coming from.  It is
address@hidden identifies the D-Bus the message is coming from.  It is
 either the symbol @code{:system} or the symbol @code{:session}.
 
address@hidden is the serial number of the received D-Bus message if it
-is a method call, or @code{nil}.
address@hidden is the D-Bus message type which has caused the event.  It
+can be @code{dbus-message-type-invalid},
address@hidden,
address@hidden,
address@hidden, or @code{dbus-message-type-signal}.
address@hidden is the serial number of the received D-Bus message.
 
 @var{service} and @var{path} are the unique name and the object path
 of the D-Bus object emitting the message.  @var{interface} and
@@ -1336,10 +1407,14 @@
 The result is either the symbol @code{:system} or the symbol @code{:session}.
 @end defun
 
address@hidden dbus-event-message-type event
+Returns the message type of the corresponding D-Bus message.  The
+result is a number.
address@hidden defun
+
 @defun dbus-event-serial-number event
 Returns the serial number of the corresponding D-Bus message.
-The result is a number in case the D-Bus message is a method
-call, or @code{nil} for all other mesage types.
+The result is a number.
 @end defun
 
 @defun dbus-event-service-name event