comparison doc/misc/dbus.texi @ 91590:6834ec860aff

* dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp. (Inspection): New function dbus-ping.

91589:12b2f1526656

string.
@end defun

@defun dbus-get-name-owner bus service
For a given service, registered at D-Bus @var{bus} under the name
@var{service}, 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}.

@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

@defun dbus-get-unique-name bus
The unique name, under which Emacs is registered at D-Bus @var{bus},
is returned as string.

@code{:session}.  @var{service} must be a known service name, and
@var{path} must be a valid object path.  The last two parameters are
strings.  The result, the introspection data, is a string in XML
format. Example:

@example
(dbus-introspect
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer")

@result{} "<!DOCTYPE node PUBLIC

          <arg name=\"updates\" type=\"a(sbb)\"/>
        </signal>
      </interface>
      @dots{}
    </node>"
@end example

This example informs us, that the service @code{org.freedesktop.Hal}
at object path @code{/org/freedesktop/Hal/devices/computer} offers the
interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
not documented here).  This interface contains the method

The function returns the resulting values of @var{method} as a list of
Lisp objects, according to the type conversion rules described in
@ref{Type Conversion}.  Example:

@example
(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"))
@end example

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:

@example
(dbus-call-method
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer"
  "org.freedesktop.Hal.Device" "GetPropertyString"
  "system.kernel.machine")

@result{} "i686"
@end example

With the @code{dbus-introspect} function it is possible to explore the
interfaces of @samp{org.freedesktop.Hal} service. It offers the
interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
path @samp{/org/freedesktop/Hal/Manager} as well as the interface
@samp{org.freedesktop.Hal.Device} for all objects prefixed with the
path @samp{/org/freedesktop/Hal/devices}.  With the methods
@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
emulate the @code{lshal} command on GNU/Linux systems:

@example
(dolist (device
          (dbus-call-method
            :system "org.freedesktop.Hal"
            "/org/freedesktop/Hal/Manager"
            "org.freedesktop.Hal.Manager" "GetAllDevices"))

      smbios.bios.release_date = \"11/07/2001\"
      system.chassis.manufacturer = \"COMPAL\"
      system.chassis.type = \"Notebook\"
      system.firmware.release_date = \"03/19/2005\"
      @dots{}"
@end example
@end defun


@node Receiving Method Calls
@chapter Offering own methods.

@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:

@example
(defun my-dbus-method-handler (filename)
  (let (result)
    (if (find-file filename)
        (setq result '(:boolean t))
      (setq result '(:boolean nil)))

  'my-dbus-method-handler)

@result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
     my-method-handler))
@end 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
@var{false}, indicating the success if the method.  As test tool one

All other arguments args are passed to @var{signal} as arguments.
They are converted into D-Bus types as described in @ref{Type
Conversion}.  Example:

@example
(dbus-send-signal
  :session "org.gnu.Emacs" "/org/gnu/Emacs"
  "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
@end example
@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{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:

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

@result{} my-dbus-signal-handler

  'my-dbus-signal-handler)

@result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
    ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
     my-signal-handler))
@end example

As we know from the inspection data of interface
@code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
provides one single parameter, which is mapped into a Lisp string.
The callback function @code{my-dbus-signal-handler} must define one

@end defspec

Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
Events, , , elisp}).  The generated event has this form:

@example
(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}.

@var{serial} is the serial number of the received D-Bus message if it

arrives, @var{handler} is called with @var{args} as arguments.

In order to inspect the @code{dbus-event} data, you could extend the
definition of the callback function in @ref{Signals}:

@example
(defun my-dbus-signal-handler (&rest args)
  (message "my-dbus-signal-handler: %S" last-input-event))
@end example

There exist convenience functions which could be called inside a
callback function in order to retrieve the information from the event.

@defun dbus-event-bus-name event

91590:6834ec860aff

string.
@end defun

@defun dbus-get-name-owner bus service
For a given service, registered at D-Bus @var{bus} under the name
@var{service}, 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}.

@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

@defun dbus-ping bus service
Check whether the service name @var{service} is registered at D-Bus
@var{bus}.  @var{service} might not have been started yet.  The result
is either @code{t} or @code{nil}.

@var{bus} must be either the symbol @code{:system} or the symbol
@code{:session}.  @var{service} must be a string.  Example:

@lisp
(message
   "%s screensaver on board."
   (cond
     ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome")
     ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE")
     (t "No")))
@end lisp
@end defun

@defun dbus-get-unique-name bus
The unique name, under which Emacs is registered at D-Bus @var{bus},
is returned as string.

@code{:session}.  @var{service} must be a known service name, and
@var{path} must be a valid object path.  The last two parameters are
strings.  The result, the introspection data, is a string in XML
format. Example:

@lisp
(dbus-introspect
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer")

@result{} "<!DOCTYPE node PUBLIC

          <arg name=\"updates\" type=\"a(sbb)\"/>
        </signal>
      </interface>
      @dots{}
    </node>"
@end lisp

This example informs us, that the service @code{org.freedesktop.Hal}
at object path @code{/org/freedesktop/Hal/devices/computer} offers the
interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
not documented here).  This interface contains the method

The function returns the resulting values of @var{method} as a list of
Lisp objects, according to the type conversion rules described in
@ref{Type Conversion}.  Example:

@lisp
(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"))
@end 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:

@lisp
(dbus-call-method
  :system "org.freedesktop.Hal"
  "/org/freedesktop/Hal/devices/computer"
  "org.freedesktop.Hal.Device" "GetPropertyString"
  "system.kernel.machine")

@result{} "i686"
@end lisp

With the @code{dbus-introspect} function it is possible to explore the
interfaces of @samp{org.freedesktop.Hal} service. It offers the
interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
path @samp{/org/freedesktop/Hal/Manager} as well as the interface
@samp{org.freedesktop.Hal.Device} for all objects prefixed with the
path @samp{/org/freedesktop/Hal/devices}.  With the methods
@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
emulate the @code{lshal} command on GNU/Linux systems:

@lisp
(dolist (device
          (dbus-call-method
            :system "org.freedesktop.Hal"
            "/org/freedesktop/Hal/Manager"
            "org.freedesktop.Hal.Manager" "GetAllDevices"))

      smbios.bios.release_date = \"11/07/2001\"
      system.chassis.manufacturer = \"COMPAL\"
      system.chassis.type = \"Notebook\"
      system.firmware.release_date = \"03/19/2005\"
      @dots{}"
@end lisp
@end defun


@node Receiving Method Calls
@chapter Offering own methods.

@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)
  (let (result)
    (if (find-file filename)
        (setq result '(:boolean t))
      (setq result '(:boolean nil)))

  'my-dbus-method-handler)

@result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
    ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
     my-method-handler))
@end lisp

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
@var{false}, indicating the success if the method.  As test tool one

All other arguments args are passed to @var{signal} as arguments.
They are converted into D-Bus types as described in @ref{Type
Conversion}.  Example:

@lisp
(dbus-send-signal
  :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{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))

@result{} my-dbus-signal-handler

  'my-dbus-signal-handler)

@result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
    ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
     my-signal-handler))
@end lisp

As we know from the inspection data of interface
@code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
provides one single parameter, which is mapped into a Lisp string.
The callback function @code{my-dbus-signal-handler} must define one

@end defspec

Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
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})
@end lisp

@var{bus} identifies the D-Bus the signal is coming from.  It is
either the symbol @code{:system} or the symbol @code{:session}.

@var{serial} is the serial number of the received D-Bus message if it

arrives, @var{handler} is called with @var{args} as arguments.

In order to inspect the @code{dbus-event} data, you could extend the
definition of the callback function in @ref{Signals}:

@lisp
(defun my-dbus-signal-handler (&rest args)
  (message "my-dbus-signal-handler: %S" last-input-event))
@end lisp

There exist convenience functions which could be called inside a
callback function in order to retrieve the information from the event.

@defun dbus-event-bus-name event