Function: dbus-call-method-asynchronously

dbus-call-method-asynchronously is a byte-compiled function defined in dbus.el.gz.

Signature

(dbus-call-method-asynchronously BUS SERVICE PATH INTERFACE METHOD HANDLER &rest ARGS)

Documentation

Call METHOD on the D-Bus BUS asynchronously.

BUS is either a Lisp keyword, :system or :session, or a string denoting the bus address.

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.

HANDLER is a Lisp function, which is called when the corresponding return message has arrived. If HANDLER is nil, no return message will be expected.

If the parameter :timeout is given, the following integer TIMEOUT specifies the maximum number of milliseconds before 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.

If the parameter :authorizable is given and the following AUTH is non-nil, the invoked method may interactively prompt the user for authorization. The default is nil.

All other arguments ARGS are passed to METHOD as arguments. They are converted into D-Bus types via the following rules:

  t and nil => DBUS_TYPE_BOOLEAN
  number => DBUS_TYPE_UINT32
  integer => DBUS_TYPE_INT32
  float => DBUS_TYPE_DOUBLE
  string => DBUS_TYPE_STRING
  list => DBUS_TYPE_ARRAY

All arguments can be preceded by a type keyword. For details about type keywords, see Info node (dbus)Type Conversion.

If HANDLER is a Lisp function, the function returns a key into the hash table dbus-registered-objects-table. The corresponding entry in the hash table is removed, when the return message arrives, and HANDLER is called.

Example:

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

  -| i686

  => (:serial :system 2)

Probably introduced at or before Emacs version 31.1.

Source Code

;; Defined in /usr/src/emacs/lisp/net/dbus.el.gz
(defun dbus-call-method-asynchronously
 (bus service path interface method handler &rest args)
 "Call METHOD on the D-Bus BUS asynchronously.

BUS is either a Lisp keyword, `:system' or `:session', or a
string denoting the bus address.

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.

HANDLER is a Lisp function, which is called when the corresponding
return message has arrived.  If HANDLER is nil, no return message
will be expected.

If the parameter `:timeout' is given, the following integer
TIMEOUT specifies the maximum number of milliseconds before 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.

If the parameter `:authorizable' is given and the following AUTH
is non-nil, the invoked method may interactively prompt the user
for authorization.  The default is nil.

All other arguments ARGS are passed to METHOD as arguments.  They are
converted into D-Bus types via the following rules:

  t and nil => DBUS_TYPE_BOOLEAN
  number    => DBUS_TYPE_UINT32
  integer   => DBUS_TYPE_INT32
  float     => DBUS_TYPE_DOUBLE
  string    => DBUS_TYPE_STRING
  list      => DBUS_TYPE_ARRAY

All arguments can be preceded by a type keyword.  For details
about type keywords, see Info node `(dbus)Type Conversion'.

If HANDLER is a Lisp function, the function returns a key into the
hash table `dbus-registered-objects-table'.  The corresponding entry
in the hash table is removed, when the return message arrives,
and HANDLER is called.

Example:

\(dbus-call-method-asynchronously
 :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
 \"org.freedesktop.Hal.Device\" \"GetPropertyString\" #\\='message
 \"system.kernel.machine\")

  -| i686

  => (:serial :system 2)"

  (or (featurep 'dbusbind)
      (signal 'dbus-error (list "Emacs not compiled with dbus support")))
  (or (memq bus '(:system :session :system-private :session-private))
      (stringp bus)
      (signal 'wrong-type-argument (list 'keywordp bus)))
  (or (stringp service)
      (signal 'wrong-type-argument (list 'stringp service)))
  (or (stringp path)
      (signal 'wrong-type-argument (list 'stringp path)))
  (or (stringp interface)
      (signal 'wrong-type-argument (list 'stringp interface)))
  (or (stringp method)
      (signal 'wrong-type-argument (list 'stringp method)))
  (or (null handler) (functionp handler)
      (signal 'wrong-type-argument (list 'functionp handler)))

  (apply #'dbus-message-internal dbus-message-type-method-call
	 bus service path interface method handler args))