Function: dbus-register-property

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

Signature

(dbus-register-property BUS SERVICE PATH INTERFACE PROPERTY ACCESS &rest ARGS)

Documentation

Register PROPERTY 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. 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 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 keyword :read, :write or :readwrite.

VALUE is the initial value of the property, it can be of any valid type (see dbus-call-method for details). VALUE can be preceded by a TYPE keyword.

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 :write or
: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. When EMITS-SIGNAL is non-nil,
the signal "PropertiesChanged" is sent when the property is changed by dbus-set-property.

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 property. 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.

(dbus-register-property BUS SERVICE PATH INTERFACE PROPERTY ACCESS [TYPE] VALUE &optional EMITS-SIGNAL DONT-REGISTER-SERVICE)

Probably introduced at or before Emacs version 24.1.

Source Code

;; Defined in /usr/src/emacs/lisp/net/dbus.el.gz
(defun dbus-register-property
    (bus service path interface property access &rest args)
  "Register PROPERTY 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.  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
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 keyword `:read', `:write' or `:readwrite'.

VALUE is the initial value of the property, it can be of any
valid type (see `dbus-call-method' for details).  VALUE can be
preceded by a TYPE keyword.

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 `:write' or
`: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.  When EMITS-SIGNAL is non-nil,
the signal \"PropertiesChanged\" is sent when the property is
changed by `dbus-set-property'.

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 property.  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.

\(dbus-register-property BUS SERVICE PATH INTERFACE PROPERTY ACCESS \
[TYPE] VALUE &optional EMITS-SIGNAL DONT-REGISTER-SERVICE)"
  (let (;; Read basic type keyword.
        (type (when (keywordp (car args)) (pop args)))
        (value (pop args))
        (emits-signal (pop args))
        (dont-register-service (pop args)))
    (unless (member access '(:read :write :readwrite))
      (signal 'wrong-type-argument (list "Access type invalid" access)))
    (unless (or type (consp value))
      (setq type
            (cond
             ((memq value '(t nil)) :boolean)
             ((natnump value) :uint32)
             ((fixnump value) :int32)
             ((floatp value) :double)
             ((stringp value) :string)
             (t
              (signal 'wrong-type-argument (list "Value type invalid" value))))))
    (unless (consp value)
      (setq value (list type value)))
    (setq value (if (member (car value) dbus-compound-types)
                    (list :variant value) (cons :variant value)))
    (dbus-check-arguments bus service value)

    ;; Add handlers for the three property-related methods.
    (dbus-register-method
     bus service path dbus-interface-properties "Get"
     #'dbus-property-handler 'dont-register)
    (dbus-register-method
     bus service path dbus-interface-properties "GetAll"
     #'dbus-property-handler 'dont-register)
    (dbus-register-method
     bus service path dbus-interface-properties "Set"
     #'dbus-property-handler 'dont-register)

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

    ;; Send the PropertiesChanged signal.
    (when emits-signal
      (dbus-send-signal
       bus service path dbus-interface-properties "PropertiesChanged"
       interface
       ;; changed_properties.
       (if (eq access :write)
           '(:array: :signature "{sv}")
         `(:array (:dict-entry ,property ,value)))
       ;; invalidated_properties.
       (if (eq access :write)
           `(:array ,property)
         '(:array))))

    ;; Create a hash table entry.  We use nil for the unique name,
    ;; because the property might be accessed from anybody.
    (let ((key (list :property bus interface property))
	  (val
           (cons
	    (list nil service path (list access emits-signal value))
            (dbus-get-other-registered-properties
             bus service path interface property))))
      (puthash key val dbus-registered-objects-table)

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