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

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       08/01/04 21:44:23

Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -b -r1.12 -r1.13
--- dbus.texi   3 Jan 2008 21:32:04 -0000       1.12
+++ dbus.texi   4 Jan 2008 21:44:23 -0000       1.13
@@ -50,6 +50,7 @@
 * Inspection::                  Inspection of the bus names.
 * Type Conversion::             Mapping Lisp types and D-Bus types.
 * Synchronous Methods::         Calling methods in a blocking way.
+* Receiving Method Calls::      Offering own methods.
 * Signals::                     Sending and receiving signals.
 * Errors and Events::           Errors and events.
 * GNU Free Documentation License:: The license for this documentation.
@@ -487,6 +488,86 @@
 @end defun
 
 
address@hidden Receiving Method Calls
address@hidden Offering own methods.
address@hidden method calls, returning
address@hidden returning method calls
+
+Emacs can also offer own methods, which can be called by other
+applications.  These methods could be an implementation of an
+interface of a well known service, like @code{org.freedesktop.TextEditor}.
+
+It could be also an implementation of an own interface.  In this case,
+the service name must be @code{org.gnu.Emacs}.  The object path shall
+begin with @code{/org/gnu/Emacs/@strong{Application}/}, and the
+interface name shall be @address@hidden
address@hidden@strong{Application}} is the name of the application which
+provides the interface.
+
address@hidden dbus-register-method bus service path interface method handler
+With this function, an application registers @var{method} 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 object
address@hidden is registered for.  It must be a known name.
+
address@hidden is the D-Bus object path @var{service} is
+registered.
+
address@hidden is the interface offered by @var{service}.  It must
+provide @var{method}.
+
address@hidden is a Lisp function to be called when when a @var{method}
+call is is received.  It must accept as arguments the input arguments
+of @var{method}.  @var{handler} must return a list, which elements are
+used as arguments for the reply message of @var{method}.  This list
+can be composed like the input parameters in @ref{Type Conversion}.
+
address@hidden returns a Lisp symbol, which can be used
+as argument in @code{dbus-unregister-object} for removing the
+registration for @var{method}.  Example:
+
address@hidden
+(defun my-dbus-method-handler (filename)
+  (let (result)
+    (if (find-file filename)
+        (setq result '(:boolean t))
+      (setq result '(:boolean nil)))
+    result))
+
address@hidden my-dbus-method-handler
+
+(dbus-register-method
+  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+  "org.freedesktop.TextEditor" "OpenFile"
+  'my-dbus-method-handler)
+
address@hidden ((:system "org.freedesktop.TextEditor" "OpenFile")
+    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+     my-method-handler))
address@hidden example
+
+If you invoke the method @code{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
+could use 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.TextEditor.OpenFile" string:"/etc/hosts"
+
address@hidden method return sender=:1.22 -> dest=:1.23 reply_serial=2
+     boolean true
address@hidden example
address@hidden defun
+
+
 @node Signals
 @chapter Sending and receiving signals.
 @cindex signals
@@ -601,18 +682,21 @@
 Events, , , elisp}).  The generated event has this form:
 
 @example
-(dbus-event @var{bus} @var{service} @var{path} @var{interface} @var{member} 
@var{handler} &rest @var{args})
+(dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} 
@var{member} @var{handler} &rest @var{args})
 @end example
 
 @var{bus} identifies the D-Bus the signal 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}.
+
 @var{service} and @var{path} are the unique name and the object path
-of the D-Bus object emitting the signal.  @var{interface} and
address@hidden denote the signal which has been sent.
+of the D-Bus object emitting the message.  @var{interface} and
address@hidden denote the message which has been sent.
 
 @var{handler} is the callback function which has been registered for
-this signal (see @pxref{Signals}).  When a @code{dbus-event} event
+this message (see @pxref{Signals}).  When a @code{dbus-event} event
 arrives, @var{handler} is called with @var{args} as arguments.
 
 In order to inspect the @code{dbus-event} data, you could extend the
@@ -631,6 +715,12 @@
 The result is either the symbol @code{:system} or the symbol @code{:session}.
 @end defun
 
address@hidden 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.
address@hidden defun
+
 @defun dbus-event-service-name event
 Returns the unique name of the D-Bus object @var{event} is coming from.
 @end defun