Next: Asynchronous Methods, Previous: Type Conversion, Up: Top

## 4 Calling methods in a blocking way.

Methods can be called synchronously (blocking) or asynchronously (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 be called, and a reply message returning the resulting output parameters from the object.

— Function: dbus-call-method bus service path interface method &optional :timeout timeout &rest args

> This function calls method on the D-Bus bus. bus is either the symbol `:system` or the symbol `:session`.

> service is the D-Bus service name to be used. path is the D-Bus object path, service is registered at. interface is an interface offered by service. It must provide method.

> If the parameter `:timeout` is given, the following integer timeout 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 (see Errors and Events).

> All other arguments args are passed to method as arguments. They are converted into D-Bus types as described in Type Conversion.

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

>               (dbus-call-method
>                 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
>                 "org.gnome.seahorse.Keys" "GetKeyField"
>                 "openpgp:657984B8C7A966DD" "simple-name")

>               ⇒ (t ("Philip R. Zimmermann"))

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

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

>               ⇒ "i686"

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

>               (dolist (device
>                         (dbus-call-method
>                           :system "org.freedesktop.Hal"
>                           "/org/freedesktop/Hal/Manager"
>                           "org.freedesktop.Hal.Manager" "GetAllDevices"))
>                 (message "\nudi = %s" device)
>                 (dolist (properties
>                           (dbus-call-method
>                             :system "org.freedesktop.Hal" device
>                             "org.freedesktop.Hal.Device" "GetAllProperties"))
>                   (message "  %s = %S"
>                            (car properties) (or (caar (cdr properties)) ""))))

>               -| "udi = /org/freedesktop/Hal/devices/computer
>                     info.addons = (\"hald-addon-acpi\")
>                     info.bus = \"unknown\"
>                     info.product = \"Computer\"
>                     info.subsystem = \"unknown\"
>                     info.udi = \"/org/freedesktop/Hal/devices/computer\"
>                     linux.sysfs_path_device = \"(none)\"
>                     power_management.acpi.linux.version = \"20051216\"
>                     power_management.can_suspend_to_disk = t
>                     power_management.can_suspend_to_ram = \"\"
>                     power_management.type = \"acpi\"
>                     smbios.bios.release_date = \"11/07/2001\"
>                     system.chassis.manufacturer = \"COMPAL\"
>                     system.chassis.type = \"Notebook\"
>                     system.firmware.release_date = \"03/19/2005\"
>                     ..."

— Function: dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args

> Call method on the D-Bus 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 `dbus-call-method`. Example:

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

>               ⇒ "i686"