Next: Asynchronous Methods, Previous: Type Conversion, Up: Top [Contents][Index]

## 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\"
            …"

Next: Asynchronous Methods, Previous: Type Conversion, Up: Top [Contents][Index]