;;; dbus.el --- Elisp bindings for D-Bus.
-;; Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc.
+;; Copyright (C) 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
;; Author: Michael Albinus <michael.albinus@gmx.de>
;; Keywords: comm, hardware
;; option "--without-dbus". Declare used subroutines and variables.
(declare-function dbus-call-method "dbusbind.c")
(declare-function dbus-call-method-asynchronously "dbusbind.c")
+(declare-function dbus-init-bus "dbusbind.c")
(declare-function dbus-method-return-internal "dbusbind.c")
(declare-function dbus-method-error-internal "dbusbind.c")
(declare-function dbus-register-signal "dbusbind.c")
(defvar dbus-debug)
-(defvar dbus-registered-functions-table)
+(defvar dbus-registered-objects-table)
;; Pacify byte compiler.
(eval-when-compile
(defvar dbus-event-error-hooks nil
"Functions to be called when a D-Bus error happens in the event handler.
-Every function must accept one argument, the error variable
+Every function must accept two arguments, the event and the error variable
catched in `condition-case' by `dbus-error'.")
\f
;; We create it here. So we have a simple test in dbusbind.c, whether
;; the Lisp code has been loaded.
-(setq dbus-registered-functions-table (make-hash-table :test 'equal))
+(setq dbus-registered-objects-table (make-hash-table :test 'equal))
(defvar dbus-return-values-table (make-hash-table :test 'equal)
"Hash table for temporary storing arguments of reply messages.
(defun dbus-list-hash-table ()
"Returns all registered member registrations to D-Bus.
The return value is a list, with elements of kind (KEY . VALUE).
-See `dbus-registered-functions-table' for a description of the
+See `dbus-registered-objects-table' for a description of the
hash table."
(let (result)
(maphash
'(lambda (key value) (add-to-list 'result (cons key value) 'append))
- dbus-registered-functions-table)
+ dbus-registered-objects-table)
result))
(defun dbus-unregister-object (object)
"Unregister OBJECT from D-Bus.
-OBJECT must be the result of a preceding `dbus-register-method'
-or `dbus-register-signal' call. It returns `t' if OBJECT has
-been unregistered, `nil' otherwise."
+OBJECT must be the result of a preceding `dbus-register-method',
+`dbus-register-property' or `dbus-register-signal' call. It
+returns `t' if OBJECT has been unregistered, `nil' otherwise.
+
+When OBJECT identifies the last method or property, which is
+registered for the respective service, Emacs releases its
+association to the service from D-Bus."
;; Check parameter.
(unless (and (consp object) (not (null (car object))) (consp (cdr object)))
(signal 'wrong-type-argument (list 'D-Bus object)))
;; Find the corresponding entry in the hash table.
(let* ((key (car object))
- (value (gethash key dbus-registered-functions-table)))
+ (value (cdr object))
+ (entry (gethash key dbus-registered-objects-table))
+ ret)
+ ;; entry has the structure ((UNAME SERVICE PATH MEMBER) ...).
+ ;; value has the structure ((SERVICE PATH [HANDLER]) ...).
+ ;; MEMBER is either a string (the handler), or a cons cell (a
+ ;; property value). UNAME and property values are not taken into
+ ;; account for comparision.
+
;; Loop over the registered functions.
- (while (consp value)
- ;; (car value) has the structure (UNAME SERVICE PATH HANDLER).
- ;; (cdr object) has the structure ((SERVICE PATH HANDLER) ...).
- (if (not (equal (cdr (car value)) (car (cdr object))))
- (setq value (cdr value))
- ;; Compute new hash value. If it is empty, remove it from
+ (dolist (elt entry)
+ (when (equal
+ (car value)
+ (butlast (cdr elt) (- (length (cdr elt)) (length (car value)))))
+ ;; Compute new hash value. If it is empty, remove it from the
;; hash table.
- (unless
- (puthash
- key
- (delete (car value) (gethash key dbus-registered-functions-table))
- dbus-registered-functions-table)
- (remhash key dbus-registered-functions-table))
- (setq value t)))
- value))
+ (unless (puthash key (delete elt entry) dbus-registered-objects-table)
+ (remhash key dbus-registered-objects-table))
+ (setq ret t)))
+ ;; Check, whether there is still a registered function or property
+ ;; for the given service. If not, unregister the service from the
+ ;; bus.
+ (dolist (elt entry)
+ (let ((service (cadr elt))
+ (bus (car key))
+ found)
+ (maphash
+ (lambda (k v)
+ (dolist (e v)
+ (ignore-errors
+ (when (and (equal bus (car k)) (string-equal service (cadr e)))
+ (setq found t)))))
+ dbus-registered-objects-table)
+ (unless found
+ (dbus-call-method
+ bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
+ "ReleaseName" service))))
+ ;; Return.
+ ret))
+
+(defun dbus-unregister-service (bus service)
+ "Unregister all objects related to SERVICE from D-Bus BUS.
+BUS must be either the symbol `:system' or the symbol `:session'.
+SERVICE must be a known service name."
+ (maphash
+ (lambda (key value)
+ (dolist (elt value)
+ (ignore-errors
+ (when (and (equal bus (car key)) (string-equal service (cadr elt)))
+ (unless
+ (puthash key (delete elt value) dbus-registered-objects-table)
+ (remhash key dbus-registered-objects-table))))))
+ dbus-registered-objects-table)
+ (dbus-call-method
+ bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
+ "ReleaseName" service))
(defun dbus-call-method-non-blocking-handler (&rest args)
"Handler for reply messages of asynchronous D-Bus message calls.
-It calls the function stored in `dbus-registered-functions-table'.
+It calls the function stored in `dbus-registered-objects-table'.
The result will be made available in `dbus-return-values-table'."
(puthash (list (dbus-event-bus-name last-input-event)
(dbus-event-serial-number last-input-event))
'dbus-call-method-non-blocking-handler args)))
;; Wait until `dbus-call-method-non-blocking-handler' has put the
;; result into `dbus-return-values-table'.
- (while (not (gethash key dbus-return-values-table nil))
+ (while (eq (gethash key dbus-return-values-table :ignore) :ignore)
(read-event nil nil 0.1))
;; Cleanup `dbus-return-values-table'. Return the result.
(nth 0 key) (nth 1 elt) (nth 2 elt)
;; INTERFACE MEMBER HANDLER
(nth 1 key) (nth 2 key) (nth 3 elt)))))
- (copy-hash-table dbus-registered-functions-table))))
+ (copy-hash-table dbus-registered-objects-table))))
;; The error is reported only in debug mode.
(when dbus-debug
(signal
;; Return a message when it is a message call.
(when (= dbus-message-type-method-call (nth 2 event))
(dbus-ignore-errors
- (apply 'dbus-method-return-internal
- (nth 1 event) (nth 3 event) (nth 4 event)
- (if (consp result) result (list result))))))
+ (if (eq result :ignore)
+ (dbus-method-return-internal
+ (nth 1 event) (nth 3 event) (nth 4 event))
+ (apply 'dbus-method-return-internal
+ (nth 1 event) (nth 3 event) (nth 4 event)
+ (if (consp result) result (list result)))))))
;; Error handling.
(dbus-error
;; Return an error message when it is a message call.
(dbus-method-error-internal
(nth 1 event) (nth 3 event) (nth 4 event) (cadr err))))
;; Propagate D-Bus error messages.
- (run-hook-with-args 'dbus-event-error-hooks err)
+ (run-hook-with-args 'dbus-event-error-hooks event err)
(when (or dbus-debug (= dbus-message-type-error (nth 2 event)))
(signal (car err) (cdr err))))))
bus dbus-service-dbus dbus-path-dbus
dbus-interface-dbus "GetNameOwner" service)))
-(defun dbus-ping (bus service)
- "Check whether SERVICE is registered for D-Bus BUS."
+(defun dbus-ping (bus service &optional timeout)
+ "Check whether SERVICE is registered for D-Bus BUS.
+TIMEOUT, a nonnegative integer, specifies the maximum number of
+milliseconds `dbus-ping' must return. The default value is 25,000.
+
+Note, that this autoloads SERVICE if it is not running yet. If
+it shall be checked whether SERVICE is already running, one shall
+apply
+
+ \(member service \(dbus-list-known-names bus))"
;; "Ping" raises a D-Bus error if SERVICE does not exist.
;; Otherwise, it returns silently with `nil'.
(condition-case nil
(not
- (dbus-call-method bus service dbus-path-dbus dbus-interface-peer "Ping"))
+ (if (natnump timeout)
+ (dbus-call-method
+ bus service dbus-path-dbus dbus-interface-peer
+ "Ping" :timeout timeout)
+ (dbus-call-method
+ bus service dbus-path-dbus dbus-interface-peer "Ping")))
(dbus-error nil)))
\f
It will be checked at BUS, SERVICE, PATH. The result can be any
valid D-Bus value, or `nil' if there is no PROPERTY."
(dbus-ignore-errors
- ;; We must check, whether the "org.freedesktop.DBus.Properties"
- ;; interface is supported; otherwise the call blocks.
- (when
- (member
- "Get"
- (dbus-introspect-get-method-names
- bus service path "org.freedesktop.DBus.Properties"))
- ;; "Get" returns a variant, so we must use the car.
- (car
- (dbus-call-method
- bus service path dbus-interface-properties
- "Get" interface property)))))
+ ;; "Get" returns a variant, so we must use the `car'.
+ (car
+ (dbus-call-method-non-blocking
+ bus service path dbus-interface-properties
+ "Get" :timeout 500 interface property))))
(defun dbus-set-property (bus service path interface property value)
"Set value of PROPERTY of INTERFACE to VALUE.
been set successful, the result is VALUE. Otherwise, `nil' is
returned."
(dbus-ignore-errors
- (when
- (and
- ;; We must check, whether the
- ;; "org.freedesktop.DBus.Properties" interface is supported;
- ;; otherwise the call blocks.
- (member
- "Set"
- (dbus-introspect-get-method-names
- bus service path "org.freedesktop.DBus.Properties"))
- ;; PROPERTY must be writable.
- (string-equal
- "readwrite"
- (dbus-introspect-get-attribute
- (dbus-introspect-get-property bus service path interface property)
- "access")))
- ;; "Set" requires a variant.
- (dbus-call-method
- bus service path dbus-interface-properties
- "Set" interface property (list :variant value))
- ;; Return VALUE.
- (dbus-get-property bus service path interface property))))
+ ;; "Set" requires a variant.
+ (dbus-call-method-non-blocking
+ bus service path dbus-interface-properties
+ "Set" :timeout 500 interface property (list :variant value))
+ ;; Return VALUE.
+ (dbus-get-property bus service path interface property)))
(defun dbus-get-all-properties (bus service path interface)
"Return all properties of INTERFACE at BUS, SERVICE, PATH.
The result is a list of entries. Every entry is a cons of the
name of the property, and its value. If there are no properties,
`nil' is returned."
- ;; "org.freedesktop.DBus.Properties.GetAll" is not supported at
- ;; all interfaces. Therefore, we do it ourselves.
(dbus-ignore-errors
+ ;; "GetAll" returns "a{sv}".
(let (result)
- (dolist (property
- (dbus-introspect-get-property-names
- bus service path interface)
+ (dolist (dict
+ (dbus-call-method-non-blocking
+ bus service path dbus-interface-properties
+ "GetAll" :timeout 500 interface)
result)
- (add-to-list
- 'result
- (cons property (dbus-get-property bus service path interface property))
- 'append)))))
+ (add-to-list 'result (cons (car dict) (caadr dict)) 'append)))))
+
+(defun dbus-register-property
+ (bus service path interface property access value)
+ "Register property PROPERTY on the D-Bus BUS.
+
+BUS is either the symbol `:system' or the symbol `:session'.
+
+SERVICE is the D-Bus service name of the D-Bus. It must be a
+known name.
+
+PATH is the D-Bus object path SERVICE is registered. INTERFACE
+is the name of the interface used at PATH, PROPERTY is the name
+of the property of INTERFACE. ACCESS indicates, whether the
+property can be changed by other services via D-Bus. It must be
+either the symbol `:read' or `:readwrite'. VALUE is the initial
+value of the property, it can be of any valid type (see
+`dbus-call-method' for details).
+
+If PROPERTY already exists on PATH, it will be overwritten. For
+properties with access type `:read' this is the only way to
+change their values. Properties with access type `:readwrite'
+can be changed by `dbus-set-property'.
+
+The interface \"org.freedesktop.DBus.Properties\" is added to
+PATH, including a default handler for the \"Get\", \"GetAll\" and
+\"Set\" methods of this interface."
+ (unless (member access '(:read :readwrite))
+ (signal 'dbus-error (list "Access type invalid" access)))
+
+ ;; Register SERVICE.
+ (unless (member service (dbus-list-names bus))
+ (dbus-call-method
+ bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
+ "RequestName" service 0))
+
+ ;; Add the handler. We use `dbus-service-emacs' as service name, in
+ ;; order to let unregister SERVICE despite of this default handler.
+ (dbus-register-method
+ bus service path dbus-interface-properties "Get" 'dbus-property-handler)
+ (dbus-register-method
+ bus service path dbus-interface-properties "GetAll" 'dbus-property-handler)
+ (dbus-register-method
+ bus service path dbus-interface-properties "Set" 'dbus-property-handler)
+
+ ;; Create a hash table entry. We use nil for the unique name,
+ ;; because the property might be accessed from anybody.
+ (let ((key (list bus interface property))
+ (val (list (list nil service path (cons access value)))))
+ (puthash key val dbus-registered-objects-table)
+
+ ;; Return the object.
+ (list key (list service path))))
+
+(defun dbus-property-handler (&rest args)
+ "Default Handler for the \"org.freedesktop.DBus.Properties\" interface.
+It will be registered for all objects created by `dbus-register-object'."
+ (let ((bus (dbus-event-bus-name last-input-event))
+ (path (dbus-event-path-name last-input-event))
+ (method (dbus-event-member-name last-input-event))
+ (interface (car args))
+ (property (cadr args)))
+ (cond
+ ;; "Get" returns a variant.
+ ((string-equal method "Get")
+ (let ((val (gethash (list bus interface property)
+ dbus-registered-objects-table)))
+ (when (string-equal path (nth 2 (car val)))
+ (list (list :variant (cdar (last (car val))))))))
+
+ ;; "Set" expects a variant.
+ ((string-equal method "Set")
+ (let ((val (gethash (list bus interface property)
+ dbus-registered-objects-table)))
+ (unless (consp (car (last (car val))))
+ (signal 'dbus-error
+ (list "Property not registered at path" property path)))
+ (unless (equal (caar (last (car val))) :readwrite)
+ (signal 'dbus-error
+ (list "Property not writable at path" property path)))
+ (puthash (list bus interface property)
+ (list (append (butlast (car val))
+ (list (cons :readwrite (caar (cddr args))))))
+ dbus-registered-objects-table)
+ :ignore))
+
+ ;; "GetAll" returns "a{sv}".
+ ((string-equal method "GetAll")
+ (let (result)
+ (maphash
+ (lambda (key val)
+ (when (and (equal (butlast key) (list bus interface))
+ (string-equal path (nth 2 (car val)))
+ (not (functionp (car (last (car val))))))
+ (add-to-list
+ 'result
+ (list :dict-entry
+ (car (last key))
+ (list :variant (cdar (last (car val))))))))
+ dbus-registered-objects-table)
+ (list result))))))
+
+ \f
+;; Initialize :system and :session buses. This adds their file
+;; descriptors to input_wait_mask, in order to detect incoming
+;; messages immediately.
+(when (featurep 'dbusbind)
+ (dbus-ignore-errors
+ (dbus-init-bus :system)
+ (dbus-init-bus :session)))
(provide 'dbus)