* Signals:: Sending and receiving signals.
* Alternative Buses:: Alternative buses and environments.
* Errors and Events:: Errors and events.
+* Monitoring Events:: Monitoring events.
* Index:: Index including concepts, functions, variables.
* GNU Free Documentation License:: The license for this documentation.
@defun dbus-list-activatable-names &optional bus
This function returns the D-Bus service names, which can be activated
-for @var{bus}. It must be either the symbol @code{:system} (the
-default) or the symbol @code{:session}. An activatable service is
+for @var{bus}. It must be either the keyword @code{:system} (the
+default) or the keyword @code{:session}. An activatable service is
described in a service registration file. Under GNU/Linux, such files
are located at @file{/usr/share/dbus-1/system-services/} (for the
@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An
-activatable service is not necessarily registered at @var{bus} already.
+activatable service is not necessarily registered at @var{bus}
+already.
The result is a list of strings, which is @code{nil} when there are no
activatable service names at all. Example:
strings like @samp{org.freedesktop.DBus}. Names starting with
@samp{:} are unique names for services.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}.
@end defun
start with @samp{:}. The result is a list of strings, which is
@code{nil} when there are no known names at all.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}.
@end defun
result is a list of strings, or @code{nil} when there are no queued
names for @var{service} at all.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}. @var{service} must be a known service name as
string.
@end defun
owner. The result is a string, or @code{nil} when there is no name
owner of @var{service}.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}. @var{service} must be a known service name as
string.
@end defun
it is autostarted if possible. The result is either @code{t} or
@code{nil}.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}. @var{service} must be a string. @var{timeout}, a
nonnegative integer, specifies the maximum number of milliseconds
before @code{dbus-ping} must return. The default value is 25,000.
This function returns the unique name, under which Emacs is registered
at D-Bus @var{bus}, as a string.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}.
@end defun
This function returns all interfaces and sub-nodes of @var{service},
registered at object path @var{path} at bus @var{bus}.
-@var{bus} must be either the symbol @code{:system} or the symbol
+@var{bus} must be either the keyword @code{:system} or the keyword
@code{:session}. @var{service} must be a known service name, and
@var{path} must be a valid object path. The last two parameters are
strings. The result, the introspection data, is a string in XML
@defun dbus-set-property bus service path interface property [type] value
This function sets the value of @var{property} of @var{interface} to
@var{value}. It will be checked at @var{bus}, @var{service},
-@var{path}. @var{value} can be preceded by a @var{type} symbol. When
-the value is successfully set, this function returns @var{value}.
+@var{path}. @var{value} can be preceded by a @var{type} keyword.
+When the value is successfully set, this function returns @var{value}.
Example:
@lisp
input parameters.
If it is necessary to use another D-Bus type, a corresponding type
-symbol can be prepended to the corresponding Lisp object. Basic D-Bus
-types are represented by the type symbols @code{:byte},
+keyword can be prepended to the corresponding Lisp object. Basic
+D-Bus types are represented by the type keywords @code{:byte},
@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
@code{:string}, @code{:object-path}, @code{:signature} and
@code{:boolean 'symbol} is handled like @code{t} or @code{:boolean t}.
A D-Bus compound type is always represented as a list. The @sc{car}
-of this list can be the type symbol @code{:array}, @code{:variant},
+of this list can be the type keyword @code{:array}, @code{:variant},
@code{:struct} or @code{:dict-entry}, which would result in a
corresponding D-Bus container. @code{:array} is optional, because
this is the default compound D-Bus type for a list.
@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
@anchor{dbus-call-method}
This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
-either the symbol @code{:system} or the symbol @code{:session}.
+either the keyword @code{:system} or the keyword @code{:session}.
@var{service} is the D-Bus service name to be used. @var{path} is the
D-Bus object path, @var{service} is registered at. @var{interface} is
@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args
This function calls @var{method} on the D-Bus @var{bus}
-asynchronously. @var{bus} is either the symbol @code{:system} or the
-symbol @code{:session}.
+asynchronously. @var{bus} is either the keyword @code{:system} or the
+keyword @code{:session}.
@var{service} is the D-Bus service name to be used. @var{path} is the
D-Bus object path, @var{service} is registered at. @var{interface} is
This function registers the known name @var{service} on D-Bus
@var{bus}.
-@var{bus} is either the symbol @code{:system} or the symbol
+@var{bus} is either the keyword @code{:system} or the keyword
@code{:session}.
@var{service} is the service name to be registered on the D-Bus. It
This function unregisters all objects from D-Bus @var{bus}, that were
registered by Emacs for @var{service}.
-@var{bus} is either the symbol @code{:system} or the symbol
+@var{bus} is either the keyword @code{:system} or the keyword
@code{:session}.
@var{service} is the D-Bus service name of the D-Bus. It must be a
With this function, an application registers @var{method} on the D-Bus
@var{bus}.
-@var{bus} is either the symbol @code{:system} or the symbol
+@var{bus} is either the keyword @code{:system} or the keyword
@code{:session}.
@var{service} is the D-Bus service name of the D-Bus object
returning a list containing the object.
If @var{handler} returns a reply message with an empty argument list,
-@var{handler} must return the symbol @code{:ignore} in order
-to distinguish it from @code{nil} (the boolean false).
+@var{handler} must return the keyword @code{:ignore} in order to
+distinguish it from @code{nil} (the boolean false).
If @var{handler} detects an error, it shall return the list
@code{(:error @var{error-name} @var{error-message})}.
With this function, an application declares a @var{property} on the D-Bus
@var{bus}.
-@var{bus} is either the symbol @code{:system} or the symbol
+@var{bus} is either the keyword @code{:system} or the keyword
@code{:session}.
@var{service} is the D-Bus service name of the D-Bus. It must be a
@var{property} is the name of the property of @var{interface}.
@var{access} indicates, whether the property can be changed by other
-services via D-Bus. It must be either the symbol @code{:read},
+services via D-Bus. It must be either the keyword @code{:read},
@code{:write} or @code{:readwrite}.
@var{value} is the initial value of the property, it can be of any
valid type (@xref{dbus-call-method}, for details). @var{value} can be
-preceded by a @var{type} symbol.
+preceded by a @var{type} keyword.
If @var{property} already exists on @var{path}, it will be
overwritten. For properties with access type @code{:read} this is the
is, that there are no returning output parameters.
The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
-either the symbol @code{:system} or the symbol @code{:session}. It
+either the keyword @code{:system} or the keyword @code{:session}. It
doesn't matter whether another object has registered for @var{signal}.
Signals can be unicast or broadcast messages. For broadcast messages,
With this function, an application registers for a signal on the D-Bus
@var{bus}.
-@var{bus} is either the symbol @code{:system} or the symbol
+@var{bus} is either the keyword @code{:system} or the keyword
@code{:session}.
@var{service} is the D-Bus service name used by the sending D-Bus
which are the default buses to be connected to. However, it is
possible to connect to any bus with a known address. This is a UNIX
domain or TCP/IP socket. Everywhere, where a @var{bus} is mentioned
-as argument of a function (the symbol @code{:system} or the symbol
+as argument of a function (the keyword @code{:system} or the keyword
@code{:session}), this address can be used instead. The connection to
this bus must be initialized first.
@defun dbus-init-bus bus &optional private
This function establishes the connection to D-Bus @var{bus}.
-@var{bus} can be either the symbol @code{:system} or the symbol
+@var{bus} can be either the keyword @code{:system} or the keyword
@code{:session}, or it can be a string denoting the address of the
-corresponding bus. For the system and session buses, this function
-is called when loading @file{dbus.el}, there is no need to call it
-again.
+corresponding bus. For the system and session buses, this function is
+called when loading @file{dbus.el}, there is no need to call it again.
The function returns the number of connections this Emacs session has
established to the @var{bus} under the same unique name
When @var{private} is non-@code{nil}, a new connection is established
instead of reusing an existing one. It results in a new unique name
-at the bus. This can be used, if it is necessary to distinguish from
-another connection used in the same Emacs process, like the one
-established by GTK+. It should be used with care for at least the
-@code{:system} and @code{:session} buses, because other Emacs Lisp
-packages might already use this connection to those buses.
+at the @var{bus}. This can be used, if it is necessary to distinguish
+from another connection used in the same Emacs process, like the one
+established by GTK+. If @var{bus} is the keyword @code{:system} or
+the keyword @code{:session}, the new private connection is identified
+by the keywords @code{:system-private} or @code{:session-private},
+respectively.
Example: You initialize a connection to the AT-SPI bus on your host:
This function sets the value of the @var{bus} environment
@var{variable} to @var{value}.
-@var{bus} is either a Lisp symbol, @code{:system} or @code{:session},
+@var{bus} is either a Lisp keyword, @code{:system} or @code{:session},
or a string denoting the bus address. Both @var{variable} and
@var{value} should be strings.
interactive mode. The generated event has this form:
@lisp
-(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler}
- &rest @var{args})
+(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{destination} @var{path} @var{interface} @var{member}
+ @var{handler} &rest @var{args})
@end lisp
@var{bus} identifies the D-Bus the message is coming from. It is
-either the symbol @code{:system} or the symbol @code{:session}.
+either a Lisp keyword, @code{:system}, @code{:session},
+@code{:system-private} or @code{:session-private}, or a string
+denoting the bus address.
@var{type} is the D-Bus message type which has caused the event. It
can be @code{dbus-message-type-invalid},
@code{dbus-message-type-method-call},
@code{dbus-message-type-method-return},
@code{dbus-message-type-error}, or @code{dbus-message-type-signal}.
-@var{serial} is the serial number of the received D-Bus message.
+@var{serial} is the serial number of the received D-Bus message,
+unless @var{type} is equal @code{dbus-message-type-error}.
@var{service} and @var{path} are the unique name and the object path
-of the D-Bus object emitting the message. @var{interface} and
-@var{member} denote the message which has been sent.
+of the D-Bus object emitting the message. @var{destination} is the
+D-Bus name the message is dedicated to, or @code{nil} in case the
+message is a broadcast signal.
+
+@var{interface} and @var{member} denote the message which has been
+sent. When @var{type} is @code{dbus-message-type-error}, @var{member}
+is the error name.
@var{handler} is the callback function which has been registered for
this message (@pxref{Signals}). @var{args} are the typed arguments as
@defun dbus-event-bus-name event
This function returns the bus name @var{event} is coming from. The
-result is either the symbol @code{:system} or the symbol
+result is either the keyword @code{:system} or the keyword
@code{:session}.
@end defun
is coming from.
@end defun
+@defun dbus-event-destination-name event
+This function returns the unique name of the D-Bus object @var{event}
+is dedicated to.
+@end defun
+
@defun dbus-event-path-name event
This function returns the object path of the D-Bus object @var{event}
is coming from.
is coming from. It is either a signal name or a method name.
@end defun
+@defun dbus-event-handler event
+This function returns the handler the D-Bus object @var{event} is
+applied with.
+@end defun
+
+@defun dbus-event-arguments event
+This function returns the arguments the D-Bus object @var{event} is
+carrying on.
+@end defun
+
D-Bus errors are not propagated during event handling, because it is
usually not desired. D-Bus errors in events can be made visible by
setting the variable @code{dbus-debug} to non-@code{nil}. They can
whether a given D-Bus error is related to them.
+@node Monitoring Events
+@chapter Monitoring events.
+@cindex monitoring
+
+@defun dbus-register-monitor bus &optional handler &key type sender destination path interface member
+This function registers @var{handler} for monitor events on the D-Bus
+@var{bus}.
+
+@var{bus} is either a Lisp keyword, @code{:system} or @code{:session},
+or a string denoting the bus address.
+
+@findex dbus-monitor-handler
+@var{handler} is the function to be called when a monitor event
+arrives. It is called with the `args' slot of the monitor event,
+which are stripped off the type keywords. If @var{handler} is
+@code{nil}, the default handler @code{dbus-monitor-handler} is
+applied. This default handler behaves similar to the
+@command{dbus-monitor} program.
+
+The other arguments are keyword-value pairs. @code{:type @var{type}}
+defines the message type to be monitored. If given, it must be equal
+one of the strings @samp{method_call}, @samp{method_return},
+@samp{error} or @samp{signal}.
+
+@code{:sender @var{sender}} and @code{:destination @var{destination}}
+are D-Bus names. They can be unique names, or well-known service
+names.
+
+@code{:path @var{path}} is the D-Bus object to be monitored.
+@code{:interface @var{interface}} is the name of an interface, and
+@code{:member @var{member}} is either a method name, a signal name, or
+an error name.
+
+The following form shows all D-Bus events on the session bus in buffer
+@samp{*D-Bus Monitor*}:
+
+@lisp
+(dbus-register-monitor :session)
+@end lisp
+
+And this form restricts the monitoring on D-Bus errors:
+
+@lisp
+(dbus-register-monitor :session nil :type "error")
+@end lisp
+@end defun
+
+
@node Index
@unnumbered Index
(unless (boundp 'dbus-debug)
(defvar dbus-debug nil))
+(require 'cl-lib)
(require 'seq)
(require 'subr-x)
(require 'xml)
(defvar dbus-return-values-table (make-hash-table :test #'equal)
"Hash table for temporarily storing arguments of reply messages.
A key in this hash table is a list (:serial BUS SERIAL), like in
-`dbus-registered-objects-table'. BUS is either a Lisp symbol,
+`dbus-registered-objects-table'. BUS is either a Lisp keyword,
`:system' or `:session', or a string denoting the bus address.
SERIAL is the serial number of the reply message.
(defun dbus-call-method (bus service path interface method &rest args)
"Call METHOD on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+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
string => DBUS_TYPE_STRING
list => DBUS_TYPE_ARRAY
-All arguments can be preceded by a type symbol. For details about
-type symbols, see Info node `(dbus)Type Conversion'.
+All arguments can be preceded by a type keyword. For details
+about type keywords, see Info node `(dbus)Type Conversion'.
`dbus-call-method' returns the resulting values of METHOD as a list of
Lisp objects. The type conversion happens the other direction as for
(bus service path interface method handler &rest args)
"Call METHOD on the D-Bus BUS asynchronously.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+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
string => DBUS_TYPE_STRING
list => DBUS_TYPE_ARRAY
-All arguments can be preceded by a type symbol. For details about
-type symbols, see Info node `(dbus)Type Conversion'.
+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
(defun dbus-send-signal (bus service path interface signal &rest args)
"Send signal SIGNAL on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address. The signal is sent from the D-Bus object
-Emacs is registered at BUS.
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address. The signal is sent from the
+D-Bus object Emacs is registered at BUS.
SERVICE is the D-Bus name SIGNAL is sent to. It can be either a known
name or a unique name. If SERVICE is nil, the signal is sent as
string => DBUS_TYPE_STRING
list => DBUS_TYPE_ARRAY
-All arguments can be preceded by a type symbol. For details about
-type symbols, see Info node `(dbus)Type Conversion'.
+All arguments can be preceded by a type keyword. For details
+about type keywords, see Info node `(dbus)Type Conversion'.
Example:
(defun dbus-setenv (bus variable value)
"Set the value of the BUS environment variable named VARIABLE to VALUE.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address. Both VARIABLE and VALUE should be strings.
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address. Both VARIABLE and VALUE should
+be strings.
Normally, services inherit the environment of the BUS daemon. This
function adds to or modifies that environment when activating services.
(defun dbus-register-service (bus service &rest flags)
"Register known name SERVICE on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address.
SERVICE is the D-Bus service name that should be registered. It must
be a known name.
(defun dbus-unregister-service (bus service)
"Unregister all objects related to SERVICE from D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address. SERVICE must be a known service name.
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address. SERVICE must be a known service
+name.
The function returns a keyword, indicating the result of the
operation. One of the following keywords is returned:
(bus service path interface signal handler &rest args)
"Register for a signal on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address.
SERVICE is the D-Bus service name used by the sending D-Bus object.
It can be either a known name or the unique name of the D-Bus object
(bus service path interface method handler &optional dont-register-service)
"Register METHOD on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+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
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 symbol `:ignore' in order
+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
INTERFACE MEMBER HANDLER &rest ARGS)
BUS identifies the D-Bus the message is coming from. It is
-either a Lisp symbol, `:system', `:session', `:systemp-private'
+either a Lisp keyword, `:system', `:session', `:systemp-private'
or `:session-private', or a string denoting the bus address.
TYPE is the D-Bus message type which has caused the event, SERIAL
SERVICE and PATH are the unique name and the object path of the
D-Bus object emitting the message. DESTINATION is the D-Bus name
-the message is dedicated to, or nil in case thje message is a
+the message is dedicated to, or nil in case the message is a
broadcast signal.
INTERFACE and MEMBER denote the message which has been sent.
(when dbus-debug (message "DBus-Event %s" event))
(unless (and (listp event)
(eq (car event) 'dbus-event)
- ;; Bus symbol.
+ ;; Bus keyword.
(or (keywordp (nth 1 event))
(stringp (nth 1 event)))
;; Type.
(defun dbus-event-bus-name (event)
"Return the bus name the event is coming from.
-The result is either a Lisp symbol, `:system' or `:session', or a
-string denoting the bus address. EVENT is a D-Bus event, see
+The result is either a Lisp keyword, `:system' or `:session', or
+a string denoting the bus address. EVENT is a D-Bus event, see
`dbus-check-event'. This function signals a `dbus-error' if the
event is not well formed."
(dbus-check-event event)
"Return all interfaces and sub-nodes of SERVICE,
registered at object path PATH at bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address. SERVICE must be a known service name,
-and PATH must be a valid object path. The last two parameters
-are strings. The result, the introspection data, is a string in
-XML format."
+BUS is either a Lisp keyword, `:system' or `:session', or a
+string denoting the bus address. SERVICE must be a known service
+name, and PATH must be a valid object path. The last two
+parameters are strings. The result, the introspection data, is a
+string in XML format."
;; We don't want to raise errors.
(let (dbus-debug)
(dbus-ignore-errors
(defun dbus-set-property (bus service path interface property &rest args)
"Set value of PROPERTY of INTERFACE to VALUE.
It will be checked at BUS, SERVICE, PATH. VALUE can be preceded
-by a TYPE symbol. When the value is successfully set, and the
+by a TYPE keyword. When the value is successfully set, and the
property's access type is not `:write', return VALUE. Otherwise,
return nil.
(bus service path interface property access &rest args)
"Register PROPERTY on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+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).
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', `:write' or `:readwrite'.
+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 symbol.
+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
\(dbus-register-property BUS SERVICE PATH INTERFACE PROPERTY ACCESS \
[TYPE] VALUE &optional EMITS-SIGNAL DONT-REGISTER-SERVICE)"
- (let (;; Read basic type symbol.
+ (let (;; Read basic type keyword.
(type (when (keywordp (car args)) (pop args)))
(value (pop args))
(emits-signal (pop args))
result)
'(:signature "{oa{sa{sv}}}"))))))
-(defun dbus-register-monitor
- (bus &optional service path interface member handler &rest args)
+(cl-defun dbus-register-monitor
+ (bus &optional handler &key type sender destination path interface member)
"Register HANDLER for monitor events on the D-Bus BUS.
-BUS is either a Lisp symbol, `:system' or `:session', or a string
-denoting the bus address.
+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).
+HANDLER is the function to be called when a monitor event
+arrives. It is called with the `args' slot of the monitor event,
+which are stripped off the type keywords. If HANDLER is nil, the
+default handler `dbus-monitor-handler' is applied.
-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. MEMBER is either a method
-name, a signal name, or an error name.
+The other arguments are keyword-value pairs. `:type TYPE'
+defines the message type to be monitored. If given, it must be
+equal one of the strings \"method_call\", \"method_return\",
+\"error\" or \"signal\".
-HANDLER is the function to be called when a monitor event
-arrives. If nil, the default handler `dbus-monitor-handler' is
-applied. It is called with ARGS as arguments."
+`:sender SENDER' and `:destination DESTINATION' are D-Bus names.
+They can be unique names, or well-known service names.
+`:path PATH' is the D-Bus object to be monitored. `:interface
+INTERFACE' is the name of an interface, and `:member MEMBER' is
+either a method name, a signal name, or an error name."
(let ((bus-private (if (eq bus :system) :system-private
(if (eq bus :session) :session-private bus)))
- keyword type rule1 rule2 key key1 value)
+ rule key key1 value)
(unless handler (setq handler #'dbus-monitor-handler))
- ;; Read arguments.
- (while args
- (when (keywordp (setq keyword (pop args)))
- (cond
- ((eq :type keyword)
- ;; Must be "signal", "method_call", "method_return", or "error".
- (setq type (pop args))))))
- ;; Compose rules.
- (setq rule1
- (or
- (string-join
- (delq nil
- (list (when service (format "sender='%s'" service))
- (when path (format "path='%s'" path))
- (when interface (format "interface='%s'" interface))
- (when member (format "member='%s'" member))
- (when type (format "type='%s'" type))))
- ",")
- "")
- rule2
- (when service
- (string-join
- (delq nil
- (list (format "destination='%s'" service)
- (when path (format "path='%s'" path))
- (when interface (format "interface='%s'" interface))
- (when member (format "member='%s'" member))
- (when type (format "type='%s'" type))))
- ",")))
+ ;; Compose rule.
+ (setq rule
+ (string-join
+ (delq nil (mapcar
+ (lambda (item)
+ (when (cdr item)
+ (format "%s='%s'" (car item) (cdr item))))
+ `(("type" . ,type) ("sender" . ,sender)
+ ("destination" . ,destination) ("path" . ,path)
+ ("interface" . ,interface) ("member" . ,member))))
+ ",")
+ rule (or rule ""))
(unless (ignore-errors (dbus-get-unique-name bus-private))
(dbus-init-bus bus 'private))
(dbus-call-method
bus-private dbus-service-dbus dbus-path-dbus dbus-interface-monitoring
- "BecomeMonitor"
- (append `(:array :string ,rule1) (when rule2 `(:string ,rule2)))
- :uint32 0)
+ "BecomeMonitor" `(:array :string ,rule) :uint32 0)
- (when dbus-debug (message "Matching rule \"%s\" created" rule1))
+ (when dbus-debug (message "Matching rule \"%s\" created" rule))
;; Create a hash table entry.
(setq key (list :monitor bus-private)
(when dbus-debug (message "%s" dbus-registered-objects-table))
;; Return the object.
- (list key (list service path handler))))
+ (list key key1)))
(defun dbus-monitor-handler (&rest _args)
"Default handler for the \"org.freedesktop.DBus.Monitoring.BecomeMonitor\" interface.
-It will be applied all objects created by `dbus-register-monitor'."
+It will be applied for all objects created by
+`dbus-register-monitor' which don't declare an own handler.."
(with-current-buffer (get-buffer-create "*D-Bus Monitor*")
(special-mode)
+ ;; Move forward and backward between messages.
+ (local-set-key [?n] #'forward-paragraph)
+ (local-set-key [?p] #'backward-paragraph)
(let* ((inhibit-read-only t)
+ (point (point))
(eobp (eobp))
(event last-input-event)
(type (dbus-event-message-type event))
sender destination serial path interface member))
(dolist (arg arguments)
(pp (dbus-flatten-types arg) (current-buffer)))
- (insert "\n"))
+ (insert "\n")
+ ;; Show byte arrays as string.
+ (goto-char point)
+ (while (re-search-forward
+ "(:array\\( :byte [[:digit:]]+\\)+)" nil 'noerror)
+ (put-text-property
+ (match-beginning 0) (match-end 0)
+ 'help-echo (dbus-byte-array-to-string (read (match-string 0)))))
+ ;; Show fixed numbers.
+ (goto-char point)
+ (while (re-search-forward
+ (concat
+ (regexp-opt
+ '(":int16" ":uint16" ":int32" ":uint32" ":int64" ":uint64"))
+ " \\([-+[:digit:]]+\\)")
+ nil 'noerror)
+ (put-text-property
+ (match-beginning 1) (match-end 1)
+ 'help-echo
+ (format
+ "#o%o, #x%X" (read (match-string 1)) (read (match-string 1)))))
+ ;; Show floating numbers.
+ (goto-char point)
+ (while (re-search-forward ":double \\([-+.[:digit:]]+\\)" nil 'noerror)
+ (put-text-property
+ (match-beginning 1) (match-end 1)
+ 'help-echo (format "%e" (read (match-string 1))))))
(when eobp
(goto-char (point-max))))))
(defun dbus-init-bus (bus &optional private)
"Establish the connection to D-Bus BUS.
-BUS can be either the symbol `:system' or the symbol `:session', or it
-can be a string denoting the address of the corresponding bus. For
-the system and session buses, this function is called when loading
-`dbus.el', there is no need to call it again.
+BUS can be either the keyword `:system' or the keyword
+`:session', or it can be a string denoting the address of the
+corresponding bus. For the system and session buses, this
+function is called when loading `dbus.el', there is no need to
+call it again.
The function returns the number of connections this Emacs session
has established to the BUS under the same unique name (see
a GTK+-aware environment like GNOME, another connection might
already be established.
-When PRIVATE is non-nil, a new connection is established instead of
-reusing an existing one. It results in a new unique name at the bus.
-This can be used, if it is necessary to distinguish from another
-connection used in the same Emacs process, like the one established by
-GTK+. It should be used with care for at least the `:system' and
-`:session' buses, because other Emacs Lisp packages might already use
-this connection to those buses."
+When PRIVATE is non-nil, a new connection is established instead
+of reusing an existing one. It results in a new unique name at
+the bus. This can be used, if it is necessary to distinguish
+from another connection used in the same Emacs process, like the
+one established by GTK+. If BUS is the keyword `:system' or the
+keyword `:session', the new connection is identified by the
+keywords `:system-private' or `:session-private', respectively."
(or (featurep 'dbusbind)
(signal 'dbus-error (list "Emacs not compiled with dbus support")))
(prog1
projects / emacs.git / commitdiff