Function: dbus-register-method

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

Signature

(dbus-register-method BUS SERVICE PATH INTERFACE METHOD HANDLER &optional DONT-REGISTER-SERVICE)

Documentation

Register METHOD on the D-Bus BUS.

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

SERVICE is the D-Bus service name of the D-Bus object METHOD is registered for. It must be a known name (see discussion of DONT-REGISTER-SERVICE below).

PATH is the D-Bus object path SERVICE is registered at (see discussion of DONT-REGISTER-SERVICE below). INTERFACE is the interface offered by SERVICE. It must provide METHOD.

HANDLER is a Lisp function to be called when a method call is received. It must accept the input arguments of METHOD. The return value of HANDLER is used for composing the returning D-Bus message. If HANDLER returns a reply message with an empty argument list, HANDLER must return the keyword :ignore in order to distinguish it from nil (the boolean false).

If HANDLER detects an error, it shall return the list (:error ERROR-NAME ERROR-MESSAGE). ERROR-NAME is a namespaced string which characterizes the error type, and ERROR-MESSAGE is a free text string. Alternatively, any Emacs signal dbus-error in HANDLER raises a D-Bus error message with the error name
"org.freedesktop.DBus.Error.Failed".

When DONT-REGISTER-SERVICE is non-nil, the known name SERVICE is not registered. This means that other D-Bus clients have no way of noticing the newly registered method. When interfaces are constructed incrementally by adding single methods or properties at a time, DONT-REGISTER-SERVICE can be used to prevent other clients from discovering the still incomplete interface.

Probably introduced at or before Emacs version 24.1.

Source Code

;; Defined in /usr/src/emacs/lisp/net/dbus.el.gz
(defun dbus-register-method
  (bus service path interface method handler &optional dont-register-service)
  "Register METHOD on the D-Bus BUS.

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

SERVICE is the D-Bus service name of the D-Bus object METHOD is
registered for.  It must be a known name (see discussion of
DONT-REGISTER-SERVICE below).

PATH is the D-Bus object path SERVICE is registered at (see
discussion of DONT-REGISTER-SERVICE below).  INTERFACE is the
interface offered by SERVICE.  It must provide METHOD.

HANDLER is a Lisp function to be called when a method call is
received.  It must accept the input arguments of METHOD.  The
return value of HANDLER is used for composing the returning D-Bus
message.  If HANDLER returns a reply message with an empty
argument list, HANDLER must return the keyword `:ignore' in order
to distinguish it from nil (the boolean false).

If HANDLER detects an error, it shall return the list `(:error
ERROR-NAME ERROR-MESSAGE)'.  ERROR-NAME is a namespaced string
which characterizes the error type, and ERROR-MESSAGE is a free
text string.  Alternatively, any Emacs signal `dbus-error' in
HANDLER raises a D-Bus error message with the error name
\"org.freedesktop.DBus.Error.Failed\".

When DONT-REGISTER-SERVICE is non-nil, the known name SERVICE is not
registered.  This means that other D-Bus clients have no way of
noticing the newly registered method.  When interfaces are constructed
incrementally by adding single methods or properties at a time,
DONT-REGISTER-SERVICE can be used to prevent other clients from
discovering the still incomplete interface."

  ;; Register SERVICE.
  (unless (or dont-register-service
	      (member service (dbus-list-names bus)))
    (dbus-register-service bus service))

  ;; Create a hash table entry.  We use nil for the unique name,
  ;; because the method might be called from anybody.
  (let* ((key (list :method bus interface method))
	 (key1 (list nil service path handler))
	 (value (gethash key dbus-registered-objects-table)))

    (unless  (member key1 value)
      (puthash key (cons key1 value) dbus-registered-objects-table))

    ;; Return the object.
    (list key (list service path handler))))