comparison doc/misc/dbus.texi @ 96646:5e58654e97ff

* dbus.texi (Receiving Method Calls): Fix description of `dbus-register-method'. (Signals): Allow also signal arguments for filtering in `dbus-register-signal'.

96645:45b707df336e

The default D-Bus timeout when waiting for a message reply is 25
seconds.  This value could be even smaller, depending on the calling
client.  Therefore, @var{handler} shall not last longer than
absolutely necessary.

@code{dbus-register-method} returns a Lisp symbol, which can be used
as argument in @code{dbus-unregister-object} for removing the
registration for @var{method}.  Example:

@lisp
(defun my-dbus-method-handler (filename)

  :session "org.gnu.Emacs" "/org/gnu/Emacs"
  "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
@end lisp
@end defun

@defun dbus-register-signal bus service path interface signal handler
With this function, an application registers for @var{signal} on the
D-Bus @var{bus}.

@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.

@var{interface} is an interface offered by @var{service}.  It must
provide @var{signal}.

@var{handler} is a Lisp function to be called when the @var{signal} is
received.  It must accept as arguments the output parameters
@var{signal} is sending.  Example:

@lisp
(defun my-dbus-signal-handler (device)
  (message "Device %s added" device))

provides one single parameter, which is mapped into a Lisp string.
The callback function @code{my-dbus-signal-handler} must define one
single string argument therefore.  Plugging an USB device to your
machine, when registered for signal @code{DeviceAdded}, will show you
which objects the GNU/Linux @code{hal} daemon adds.

@code{dbus-register-signal} returns a Lisp symbol, which can be used
as argument in @code{dbus-unregister-object} for removing the
registration for @var{signal}.
@end defun

@defun dbus-unregister-object object
Unregister @var{object} from the the D-Bus.  @var{object} must be the
result of a preceding @code{dbus-register-signal} or

96646:5e58654e97ff

The default D-Bus timeout when waiting for a message reply is 25
seconds.  This value could be even smaller, depending on the calling
client.  Therefore, @var{handler} shall not last longer than
absolutely necessary.

@code{dbus-register-method} returns a Lisp object, which can be used
as argument in @code{dbus-unregister-object} for removing the
registration for @var{method}.  Example:

@lisp
(defun my-dbus-method-handler (filename)

  :session "org.gnu.Emacs" "/org/gnu/Emacs"
  "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
@end lisp
@end defun

@defun dbus-register-signal bus service path interface signal handler &rest args
With this function, an application registers for @var{signal} on the
D-Bus @var{bus}.

@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.

@var{interface} is an interface offered by @var{service}.  It must
provide @var{signal}.

@var{handler} is a Lisp function to be called when the @var{signal} is
received.  It must accept as arguments the output parameters
@var{signal} is sending.

All other arguments @var{args}, if specified, must be strings.  They
stand for the respective arguments of @var{signal} in their order, and
are used for filtering as well.  A @code{nil} argument might be used
to preserve the order.

@code{dbus-register-signal} returns a Lisp object, which can be used
as argument in @code{dbus-unregister-object} for removing the
registration for @var{signal}.  Example:

@lisp
(defun my-dbus-signal-handler (device)
  (message "Device %s added" device))

provides one single parameter, which is mapped into a Lisp string.
The callback function @code{my-dbus-signal-handler} must define one
single string argument therefore.  Plugging an USB device to your
machine, when registered for signal @code{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 the D-Bus.  @var{object} must be the
result of a preceding @code{dbus-register-signal} or