From: "Basil L. Contovounesios" <contovob@tcd.ie>
To: 41744@debbugs.gnu.org
Cc: michael albinus <michael.albinus@gmx.de>
Subject: bug#41744: 27.0.91; Various D-Bus cleanups
Date: Sun, 07 Jun 2020 00:26:50 +0100 [thread overview]
Message-ID: <87mu5fpyh1.fsf@tcd.ie> (raw)
[-- Attachment #1: Type: text/plain, Size: 247 bytes --]
X-Debbugs-Cc: Michael Albinus <michael.albinus@gmx.de>
Severity: minor
Tags: patch
While reading through the D-Bus manual and implementation, I noticed
some opportunities for small cleanups.
I propose these documentation cleanups for emacs-27:
[-- Attachment #2: 0001-Clean-up-D-Bus-documentation.patch --]
[-- Type: text/x-diff, Size: 92871 bytes --]
From 962f2af23a0d71638e14bb143de866862d51d0d2 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sat, 6 Jun 2020 00:58:37 +0100
Subject: [PATCH] Clean up D-Bus documentation
* doc/lispref/errors.texi (Standard Errors): The error symbol
dbus-error is defined even when Emacs is built without D-Bus.
* doc/misc/dbus.texi (Bus Names, Introspection)
(Nodes and Interfaces, Methods and Signal)
(Properties and Annotations, Arguments and Signatures)
(Synchronous Methods, Receiving Method Calls, Signals)
(Alternative Buses, Errors and Events): Clarify wording. Fix
indentation of and simplify examples where possible. Improve
Texinfo markup and cross-referencing where possible.
(Type Conversion): Ditto. Remove mentions of Emacs' fixnum range
now that we have bignums.
* lisp/net/dbus.el (dbus-return-values-table)
(dbus-call-method-asynchronously, dbus-send-signal)
(dbus-register-signal, dbus-register-method)
(dbus-string-to-byte-array, dbus-byte-array-to-string)
(dbus-escape-as-identifier, dbus-check-event, dbus-event-bus-name)
(dbus-event-message-type, dbus-event-serial-number)
(dbus-event-service-name, dbus-event-path-name)
(dbus-event-interface-name, dbus-event-member-name)
(dbus-list-activatable-names, dbus-list-queued-owners, dbus-ping)
(dbus-introspect-get-interface-names, dbus-introspect-get-interface)
(dbus-introspect-get-method, dbus-introspect-get-signal)
(dbus-introspect-get-property, dbus-introspect-get-annotation-names)
(dbus-introspect-get-annotation, dbus-introspect-get-argument-names)
(dbus-introspect-get-argument, dbus-introspect-get-signature)
(dbus-set-property, dbus-register-property)
(dbus-get-all-managed-objects, dbus-init-bus): Clarify docstring and
improve formatting where possible.
(dbus-call-method): Ditto. Remove mentions of Emacs' fixnum range
now that we have bignums.
---
doc/lispref/errors.texi | 5 +-
doc/misc/dbus.texi | 795 ++++++++++++++++++++--------------------
lisp/net/dbus.el | 228 ++++++------
3 files changed, 511 insertions(+), 517 deletions(-)
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index dc6877c9ec..cd8694be8a 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -79,9 +79,8 @@ Standard Errors
a loop}. @xref{Variable Aliases}.
@item dbus-error
-The message is @samp{D-Bus error}. This is only defined if Emacs was
-compiled with D-Bus support. @xref{Errors and Events,,, dbus, D-Bus
-integration in Emacs}.
+The message is @samp{D-Bus error}. @xref{Errors and Events,,, dbus,
+D-Bus integration in Emacs}.
@item end-of-buffer
The message is @samp{End of buffer}. @xref{Character Motion}.
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 9e5f1ccc6f..eaf77ffa8f 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -167,7 +167,7 @@ Bus names
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} at 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:
@@ -180,8 +180,8 @@ Bus names
@end defun
@defun dbus-list-names bus
-All service names, which are registered at D-Bus @var{bus}, are
-returned. The result is a list of strings, which is @code{nil} when
+This function returns all service names, which are registered at D-Bus
+@var{bus}. The result is a list of strings, which is @code{nil} when
there are no registered service names at all. Well known names are
strings like @samp{org.freedesktop.DBus}. Names starting with
@samp{:} are unique names for services.
@@ -191,10 +191,10 @@ Bus names
@end defun
@defun dbus-list-known-names bus
-Retrieves all registered services which correspond to a known name in @var{bus}.
-A service has a known name if it doesn't start with @samp{:}. The
-result is a list of strings, which is @code{nil} when there are no
-known names at all.
+This function retrieves all registered services which correspond to a
+known name in @var{bus}. A service has a known name if it doesn't
+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
@code{:session}.
@@ -202,9 +202,9 @@ Bus names
@defun dbus-list-queued-owners bus service
For a given service, registered at D-Bus @var{bus} under the name
-@var{service}, all queued unique names are returned. The result is a
-list of strings, or @code{nil} when there are no queued names for
-@var{service} at all.
+@var{service}, this function returns all queued unique names. The
+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
@code{:session}. @var{service} must be a known service name as
@@ -213,9 +213,9 @@ Bus names
@defun dbus-get-name-owner bus service
For a given service, registered at D-Bus @var{bus} under the name
-@var{service}, the unique name of the name owner is returned. The
-result is a string, or @code{nil} when there exist no name owner of
-@var{service}.
+@var{service}, this function returns the unique name of the name
+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
@code{:session}. @var{service} must be a known service name as
@@ -223,26 +223,28 @@ Bus names
@end defun
@defun dbus-ping bus service &optional timeout
-Check whether the service name @var{service} is registered at D-Bus
-@var{bus}. @var{service} might not have been started yet, it is
-autostarted if possible. The result is either @code{t} or @code{nil}.
+This function checks whether the service name @var{service} is
+registered at D-Bus @var{bus}. If @var{service} has not yet started,
+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
@code{:session}. @var{service} must be a string. @var{timeout}, a
nonnegative integer, specifies the maximum number of milliseconds
-@code{dbus-ping} must return. The default value is 25,000. Example:
+before @code{dbus-ping} must return. The default value is 25,000.
+Example:
@lisp
(message
- "%s screensaver on board."
- (cond
- ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
- ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
- (t "No")))
+ "%s screensaver on board."
+ (cond
+ ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
+ ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
+ (t "No")))
@end lisp
-If it shall be checked whether @var{service} is already running
-without autostarting it, one shall apply
+To check whether @var{service} is already running without autostarting
+it, you can instead write:
@lisp
(member service (dbus-list-known-names bus))
@@ -250,8 +252,9 @@ Bus names
@end defun
@defun dbus-get-unique-name bus
-The unique name, under which Emacs is registered at D-Bus @var{bus},
-is returned as string.
+@anchor{dbus-get-unique-name}
+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
@code{:session}.
@@ -380,8 +383,8 @@ Introspection
@lisp
(dbus-introspect
- :system "org.freedesktop.Hal"
- "/org/freedesktop/Hal/devices/computer")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer")
@result{} "<!DOCTYPE node PUBLIC
"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
@@ -420,14 +423,14 @@ Introspection
@end defun
@defun dbus-introspect-xml bus service path
-This function has the same intention as function
+This function serves a similar purpose to the function
@code{dbus-introspect}. The returned value is a parsed XML tree,
which can be used for further analysis. Example:
@lisp
(dbus-introspect-xml
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main")
@result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
(interface ((name . "org.freedesktop.xesam.Search"))
@@ -435,31 +438,27 @@ Introspection
(arg ((name . "search") (type . "s") (direction . "in")))
(arg ((name . "hit_ids") (type . "au") (direction . "in")))
(arg ((name . "fields") (type . "as") (direction . "in")))
- (arg ((name . "hit_data") (type . "aav") (direction . "out")))
- )
+ (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
@dots{}
(signal ((name . "HitsAdded"))
(arg ((name . "search") (type . "s")))
- (arg ((name . "count") (type . "u")))
- )
- )
- @dots{}
- )
+ (arg ((name . "count") (type . "u")))))
+ @dots{})
@end lisp
@end defun
@defun dbus-introspect-get-attribute object attribute
-It returns the @var{attribute} value of a D-Bus introspection
-@var{object}. @var{object} can be every subtree of a parsed XML tree
-as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be
-a string according to the attribute names in the D-Bus specification.
-Example:
+This function returns the @var{attribute} value of a D-Bus
+introspection @var{object}. The value of @var{object} can be any
+subtree of a parsed XML tree as retrieved with
+@code{dbus-introspect-xml}. @var{attribute} must be a string
+according to the attribute names in the D-Bus specification. Example:
@lisp
(dbus-introspect-get-attribute
- (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
- "/org/freedesktop/SystemToolsBackends/UsersConfig")
- "name")
+ (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
+ "/org/freedesktop/SystemToolsBackends/UsersConfig")
+ "name")
@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
@end lisp
@@ -476,12 +475,12 @@ Nodes and Interfaces
object paths and interfaces.
@defun dbus-introspect-get-node-names bus service path
-All node names of @var{service} in D-Bus @var{bus} at object path
-@var{path} are returned as list of strings. Example:
+This function returns all node names of @var{service} in D-Bus
+@var{bus} at object path @var{path} as a list of strings. Example:
@lisp
(dbus-introspect-get-node-names
- :session "org.gnome.seahorse" "/org/gnome/seahorse")
+ :session "org.gnome.seahorse" "/org/gnome/seahorse")
@result{} ("crypto" "keys")
@end lisp
@@ -512,9 +511,10 @@ Nodes and Interfaces
@end defun
@defun dbus-introspect-get-interface-names bus service path
-There will be returned a list strings of all interface names of
+This function returns a list strings of all interface names of
@var{service} in D-Bus @var{bus} at object path @var{path}. This list
-will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.
+will contain the default interface
+@samp{org.freedesktop.DBus.Introspectable}.
Another default interface is @samp{org.freedesktop.DBus.Properties}.
If present, @code{interface} elements can also have @code{property}
@@ -522,8 +522,8 @@ Nodes and Interfaces
@lisp
(dbus-introspect-get-interface-names
- :system "org.freedesktop.Hal"
- "/org/freedesktop/Hal/devices/computer")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer")
@result{} ("org.freedesktop.DBus.Introspectable"
"org.freedesktop.Hal.Device"
@@ -533,30 +533,27 @@ Nodes and Interfaces
@end defun
@defun dbus-introspect-get-interface bus service path interface
-Return @var{interface} of @var{service} in D-Bus @var{bus} at object
-path @var{path}. The return value is an XML element. @var{interface}
-must be a string, element of the list returned by
-@code{dbus-introspect-get-interface-names}. Example:
+This function returns @var{interface} of @var{service} in D-Bus
+@var{bus} at object path @var{path}. The return value is an XML
+element. @var{interface} must be a string and a member of the list
+returned by @code{dbus-introspect-get-interface-names}. Example:
@lisp
(dbus-introspect-get-interface
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
@result{} (interface ((name . "org.freedesktop.xesam.Search"))
(method ((name . "GetHitData"))
(arg ((name . "search") (type . "s") (direction . "in")))
(arg ((name . "hit_ids") (type . "au") (direction . "in")))
(arg ((name . "fields") (type . "as") (direction . "in")))
- (arg ((name . "hit_data") (type . "aav") (direction . "out")))
- )
+ (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
@dots{}
(signal ((name . "HitsAdded"))
(arg ((name . "search") (type . "s")))
- (arg ((name . "count") (type . "u")))
- )
- )
+ (arg ((name . "count") (type . "u")))))
@end lisp
@end defun
@@ -565,7 +562,8 @@ Nodes and Interfaces
data from a running system:
@lisp
-(with-current-buffer (switch-to-buffer "*introspect*")
+(progn
+ (pop-to-buffer "*introspect*")
(erase-buffer)
(dolist (service (dbus-list-known-names :session))
(dolist (path (dbus-introspect-get-all-nodes :session service "/"))
@@ -574,7 +572,7 @@ Nodes and Interfaces
(when (delete
"org.freedesktop.DBus.Introspectable"
(dbus-introspect-get-interface-names :session service path))
- (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
+ (insert (format "\nservice: \"%s\" path: \"%s\"\n" service path)
(dbus-introspect :session service path))
(redisplay t)))))
@end lisp
@@ -587,14 +585,15 @@ Methods and Signal
following functions return their specifications.
@defun dbus-introspect-get-method-names bus service path interface
-Return a list of strings of all method names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}. Example:
+This function returns a list of strings of all method names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}. Example:
@lisp
(dbus-introspect-get-method-names
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
"CloseSession" "GetHitData" "SetProperty" "NewSearch"
@@ -603,35 +602,36 @@ Methods and Signal
@end defun
@defun dbus-introspect-get-method bus service path interface method
-This function returns @var{method} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}. @var{method} must be a string, element of the list
-returned by @code{dbus-introspect-get-method-names}. Example:
+This function returns @var{method} of @var{interface} as an XML
+element. It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}. @var{method} must be a string and a member of
+the list returned by @code{dbus-introspect-get-method-names}.
+Example:
@lisp
(dbus-introspect-get-method
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "GetHitData")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData")
@result{} (method ((name . "GetHitData"))
(arg ((name . "search") (type . "s") (direction . "in")))
(arg ((name . "hit_ids") (type . "au") (direction . "in")))
(arg ((name . "fields") (type . "as") (direction . "in")))
- (arg ((name . "hit_data") (type . "aav") (direction . "out")))
- )
+ (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
@end lisp
@end defun
@defun dbus-introspect-get-signal-names bus service path interface
-Return a list of strings of all signal names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}. Example:
+This function returns a list of strings of all signal names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}. Example:
@lisp
(dbus-introspect-get-signal-names
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
@result{} ("StateChanged" "SearchDone" "HitsModified"
"HitsRemoved" "HitsAdded")
@@ -639,21 +639,21 @@ Methods and Signal
@end defun
@defun dbus-introspect-get-signal bus service path interface signal
-This function returns @var{signal} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}. @var{signal} must be a string, element of the list
-returned by @code{dbus-introspect-get-signal-names}. Example:
+This function returns @var{signal} of @var{interface} as an XML
+element. It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}. @var{signal} must be a string and a member of
+the list returned by @code{dbus-introspect-get-signal-names}.
+Example:
@lisp
(dbus-introspect-get-signal
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "HitsAdded")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "HitsAdded")
@result{} (signal ((name . "HitsAdded"))
(arg ((name . "search") (type . "s")))
- (arg ((name . "count") (type . "u")))
- )
+ (arg ((name . "count") (type . "u"))))
@end lisp
@end defun
@@ -664,8 +664,8 @@ Properties and Annotations
Interfaces can have properties. These can be exposed via the
@samp{org.freedesktop.DBus.Properties} interface@footnote{See
@uref{https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
-That is, properties can be retrieved and changed during lifetime of an
-element.
+That is, properties can be retrieved and changed during the lifetime
+of an element.
A generalized interface is
@samp{org.freedesktop.DBus.Objectmanager}@footnote{See
@@ -678,13 +678,14 @@ Properties and Annotations
the interface for a given language binding.
@defun dbus-introspect-get-property-names bus service path interface
-Return a list of strings with all property names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}. Example:
+This function returns a list of strings with all property names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}. Example:
@lisp
(dbus-introspect-get-property-names
- :session "org.kde.kded" "/modules/networkstatus"
- "org.kde.Solid.Networking.Client")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client")
@result{} ("Status")
@end lisp
@@ -694,26 +695,26 @@ Properties and Annotations
@end defun
@defun dbus-introspect-get-property bus service path interface property
-This function returns @var{property} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}. @var{property} must be a string, element of the list
-returned by @code{dbus-introspect-get-property-names}.
+This function returns @var{property} of @var{interface} as an XML
+element. It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}. @var{property} must be a string and a member
+of the list returned by @code{dbus-introspect-get-property-names}.
A @var{property} value can be retrieved by the function
@code{dbus-introspect-get-attribute}. Example:
@lisp
(dbus-introspect-get-property
- :session "org.kde.kded" "/modules/networkstatus"
- "org.kde.Solid.Networking.Client" "Status")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client" "Status")
@result{} (property ((access . "read") (type . "u") (name . "Status")))
(dbus-introspect-get-attribute
- (dbus-introspect-get-property
- :session "org.kde.kded" "/modules/networkstatus"
- "org.kde.Solid.Networking.Client" "Status")
- "access")
+ (dbus-introspect-get-property
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client" "Status")
+ "access")
@result{} "read"
@end lisp
@@ -727,23 +728,23 @@ Properties and Annotations
@lisp
(dbus-get-property
- :session "org.kde.kded" "/modules/networkstatus"
- "org.kde.Solid.Networking.Client" "Status")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client" "Status")
@result{} 4
@end lisp
@end defun
@defun dbus-set-property bus service path interface property value
-Set value of @var{property} of @var{interface} to @var{value}. It
-will be checked at @var{bus}, @var{service}, @var{path}. When the
-value has been set successful, the result is @var{value}. Otherwise,
-@code{nil} is returned. Example:
+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}. When the value is successfully set, this function returns
+@var{value}. Otherwise, it returns @code{nil}. Example:
@lisp
(dbus-set-property
- :session "org.kde.kaccess" "/MainApplication"
- "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
+ :session "org.kde.kaccess" "/MainApplication"
+ "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
@result{} 500
@end lisp
@@ -757,8 +758,8 @@ Properties and Annotations
@lisp
(dbus-get-all-properties
- :session "org.kde.kaccess" "/MainApplication"
- "com.trolltech.Qt.QApplication")
+ :session "org.kde.kaccess" "/MainApplication"
+ "com.trolltech.Qt.QApplication")
@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
@@ -773,13 +774,13 @@ Properties and Annotations
@var{path}, and the children of @var{path}. The result is a list of
objects. Every object is a cons of an existing path name, and the
list of available interface objects. An interface object is another
-cons, which car is the interface name, and the cdr is the list of
+cons, whose car is the interface name and cdr is the list of
properties as returned by @code{dbus-get-all-properties} for that path
-and interface. Example:
+and interface. Example:
@lisp
(dbus-get-all-managed-objects
- :session "org.gnome.SettingsDaemon" "/")
+ :session "org.gnome.SettingsDaemon" "/")
@result{} (("/org/gnome/SettingsDaemon/MediaKeys"
("org.gnome.SettingsDaemon.MediaKeys")
@@ -809,31 +810,28 @@ Properties and Annotations
properties could be retrieved by the following code:
@lisp
-(with-current-buffer (switch-to-buffer "*objectmanager*")
+(let ((result (mapcar (lambda (service)
+ (cons service
+ (dbus-get-all-managed-objects
+ :session service "/")))
+ (dbus-list-known-names :session))))
+ (pop-to-buffer "*objectmanager*")
(erase-buffer)
- (let (result)
- (dolist (service (dbus-list-known-names :session) result)
- (message "%s" service)
- (add-to-list
- 'result
- (cons service
- (dbus-get-all-managed-objects :session service "/"))))
- (insert (message "%s" (pp result)))
- (redisplay t)))
+ (pp result (current-buffer)))
@end lisp
@end defun
@defun dbus-introspect-get-annotation-names bus service path interface &optional name
-Return a list of all annotation names as list of strings. If
-@var{name} is @code{nil}, the annotations are children of
+This function returns a list of all annotation names as list of
+strings. If @var{name} is @code{nil}, the annotations are children of
@var{interface}, otherwise @var{name} must be a @code{method},
@code{signal}, or @code{property} XML element, where the annotations
belong to. Example:
@lisp
(dbus-introspect-get-annotation-names
- :session "de.berlios.Pinot" "/de/berlios/Pinot"
- "de.berlios.Pinot" "GetStatistics")
+ :session "de.berlios.Pinot" "/de/berlios/Pinot"
+ "de.berlios.Pinot" "GetStatistics")
@result{} ("de.berlios.Pinot.GetStatistics")
@end lisp
@@ -855,29 +853,30 @@ Properties and Annotations
@end defun
@defun dbus-introspect-get-annotation bus service path interface name annotation
-Return annotation @var{ANNOTATION} as XML object. If @var{name} is
-@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
-@var{name} must be the name of a @code{method}, @code{signal}, or
-@code{property} XML element, where the @var{ANNOTATION} belongs to.
+This function returns @var{annotation} as an XML object. If
+@var{name} is @code{nil}, @var{annotation} is a child of
+@var{interface}, otherwise @var{name} must be the name of a
+@code{method}, @code{signal}, or @code{property} XML element, where
+the @var{annotation} belongs to.
An attribute value can be retrieved by
@code{dbus-introspect-get-attribute}. Example:
@lisp
(dbus-introspect-get-annotation
- :session "de.berlios.Pinot" "/de/berlios/Pinot"
- "de.berlios.Pinot" "GetStatistics"
- "de.berlios.Pinot.GetStatistics")
+ :session "de.berlios.Pinot" "/de/berlios/Pinot"
+ "de.berlios.Pinot" "GetStatistics"
+ "de.berlios.Pinot.GetStatistics")
@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
(value . "pinotDBus")))
(dbus-introspect-get-attribute
- (dbus-introspect-get-annotation
- :session "de.berlios.Pinot" "/de/berlios/Pinot"
- "de.berlios.Pinot" "GetStatistics"
- "de.berlios.Pinot.GetStatistics")
- "value")
+ (dbus-introspect-get-annotation
+ :session "de.berlios.Pinot" "/de/berlios/Pinot"
+ "de.berlios.Pinot" "GetStatistics"
+ "de.berlios.Pinot.GetStatistics")
+ "value")
@result{} "pinotDBus"
@end lisp
@@ -891,39 +890,41 @@ Arguments and Signatures
@code{arg} XML elements.
@defun dbus-introspect-get-argument-names bus service path interface name
-Return a list of all argument names as list of strings. @var{name}
-must be a @code{method} or @code{signal} XML element. Example:
+This function returns a list of all argument names as strings.
+@var{name} must be a @code{method} or @code{signal} XML element.
+Example:
@lisp
(dbus-introspect-get-argument-names
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "GetHitData")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData")
@result{} ("search" "hit_ids" "fields" "hit_data")
@end lisp
-Argument names are optional; the function can return @code{nil}
-therefore, even if the method or signal has arguments.
+Argument names are optional; the function can therefore return
+@code{nil}, even if the method or signal has arguments.
@end defun
@defun dbus-introspect-get-argument bus service path interface name arg
-Return argument @var{ARG} as XML object. @var{name}
-must be a @code{method} or @code{signal} XML element. Example:
+This function returns the argument @var{arg} as an XML object.
+@var{name} must be a @code{method} or @code{signal} XML element.
+Example:
@lisp
(dbus-introspect-get-argument
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "GetHitData" "search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData" "search")
@result{} (arg ((name . "search") (type . "s") (direction . "in")))
@end lisp
@end defun
@defun dbus-introspect-get-signature bus service path interface name &optional direction
-Return signature of a @code{method} or @code{signal}, represented by
-@var{name}, as string.
+This function returns the signature of a @code{method} or
+@code{signal}, represented by @var{name}, as a string.
If @var{name} is a @code{method}, @var{direction} can be either
@samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in}
@@ -934,16 +935,16 @@ Arguments and Signatures
@lisp
(dbus-introspect-get-signature
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "GetHitData" "in")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData" "in")
@result{} "sauas"
(dbus-introspect-get-signature
- :session "org.freedesktop.xesam.searcher"
- "/org/freedesktop/xesam/searcher/main"
- "org.freedesktop.xesam.Search" "HitsAdded")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "HitsAdded")
@result{} "su"
@end lisp
@@ -998,30 +999,27 @@ Type Conversion
Example:
@lisp
-(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING})
+(dbus-call-method @dots{} @var{nat-number} @var{string})
@end lisp
is equivalent to
@lisp
-(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING})
+(dbus-call-method @dots{} :uint32 @var{nat-number} :string @var{string})
@end lisp
but different to
@lisp
-(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING})
+(dbus-call-method @dots{} :int32 @var{nat-number} :signature @var{string})
@end lisp
The value for a byte D-Bus type can be any integer in the range 0
through 255. If a character is used as argument, modifiers
represented outside this range are stripped off. For example,
@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
-@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
-
-Signed and unsigned integer D-Bus types expect a corresponding integer
-value. If the value does not fit Emacs's integer range, it is also
-possible to use an equivalent floating point number.
+@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. Signed and unsigned
+integer D-Bus types expect a corresponding integer value.
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},
@@ -1036,13 +1034,13 @@ Type Conversion
@item An array must contain only elements of the same D-Bus type. It
can be empty.
-@item A variant must contain only one single element.
+@item A variant must contain only a single element.
-@item A dictionary entry must be element of an array, and it must
+@item A dictionary entry must be an element of an array, and it must
contain only a key-value pair of two elements, with a basic D-Bus type
key.
-@item There is no restriction for structs.
+@item There are no restrictions for structs.
@end itemize
If an empty array needs an element D-Bus type other than string, it
@@ -1052,27 +1050,27 @@ Type Conversion
@lisp
(dbus-call-method
- :session "org.freedesktop.Notifications"
- "/org/freedesktop/Notifications"
- "org.freedesktop.Notifications" "Notify"
- "GNU Emacs" ;; Application name.
- 0 ;; No replacement of other notifications.
- "" ;; No icon.
- "Notification summary" ;; Summary.
- (format ;; Body.
- "This is a test notification, raised from\n%S" (emacs-version))
- '(:array) ;; No actions (empty array of strings).
- '(:array :signature "@{sv@}") ;; No hints
- ;; (empty array of dictionary entries).
- :int32 -1) ;; Default timeout.
+ :session "org.freedesktop.Notifications"
+ "/org/freedesktop/Notifications"
+ "org.freedesktop.Notifications" "Notify"
+ "GNU Emacs" ; Application name.
+ 0 ; No replacement of other notifications.
+ "" ; No icon.
+ "Notification summary" ; Summary.
+ (format ; Body.
+ "This is a test notification, raised from\n%S" (emacs-version))
+ '(:array) ; No actions (empty array of strings).
+ '(:array :signature "@{sv@}") ; No hints
+ ; (empty array of dictionary entries).
+ :int32 -1) ; Default timeout.
@result{} 3
@end lisp
@defun dbus-string-to-byte-array string
Sometimes, D-Bus methods require as input parameter an array of bytes,
-instead of a string. If it is guaranteed, that @var{string} is an
-UTF8 string, this function performs the conversion. Example:
+instead of a string. If it is guaranteed, that @var{string} is a
+UTF-8 string, this function performs the conversion. Example:
@lisp
(dbus-string-to-byte-array "/etc/hosts")
@@ -1083,10 +1081,10 @@ Type Conversion
@end defun
@defun dbus-escape-as-identifier string
-Escape an arbitrary @var{string} so it follows the rules for a C
-identifier. The escaped string can be used as object path component,
-interface element component, bus name component or member name in
-D-Bus.
+This function escapes an arbitrary @var{string} so it follows the
+rules for a C identifier. The escaped string can be used as object
+path component, interface element component, bus name component or
+member name in D-Bus.
The escaping consists of replacing all non-alphanumerics, and the
first character if it's a digit, with an underscore and two
@@ -1107,18 +1105,18 @@ Type Conversion
objects.
@example
-@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float}
+@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number}
@item D-Bus type @tab @tab Lisp type
@item
@item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
@item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number
@item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number
@item DBUS_TYPE_INT16 @tab @expansion{} @tab integer
-@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float
-@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float
+@item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number
+@item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number
+@item DBUS_TYPE_INT32 @tab @expansion{} @tab integer
+@item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number
+@item DBUS_TYPE_INT64 @tab @expansion{} @tab integer
@item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
@item DBUS_TYPE_STRING @tab @expansion{} @tab string
@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
@@ -1130,26 +1128,21 @@ Type Conversion
@end multitable
@end example
-A float object in case of @code{DBUS_TYPE_UINT32},
-@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64},
-@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when
-the C value exceeds the Emacs number size range.
-
The resulting list of the last 4 D-Bus compound types contains as
elements the elements of the D-Bus container, mapped according to the
same rules.
-The signal @code{PropertyModified}, discussed as example in
+The signal @code{PropertyModified}, discussed as an example in
@ref{Inspection}, would offer as Lisp data the following object
-(@var{BOOL} stands here for either @code{nil} or @code{t}):
+(@var{bool} stands here for either @code{nil} or @code{t}):
@lisp
-(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
+(@var{integer} ((@var{string} @var{bool} @var{bool}) (@var{string} @var{bool} @var{bool}) @dots{}))
@end lisp
@defun dbus-byte-array-to-string byte-array &optional multibyte
If a D-Bus method or signal returns an array of bytes, which are known
-to represent an UTF8 string, this function converts @var{byte-array}
+to represent a UTF-8 string, this function converts @var{byte-array}
to the corresponding string. The string is unibyte encoded, unless
@var{multibyte} is non-@code{nil}. Example:
@@ -1161,9 +1154,9 @@ Type Conversion
@end defun
@defun dbus-unescape-from-identifier string
-Retrieve the original string from the encoded @var{string} as unibyte
-string. @var{string} must have been encoded with
-@code{dbus-escape-as-identifier}. Example:
+This function retrieves the original string from the encoded
+@var{string} as a unibyte string. The value of @var{string} must have
+been encoded with @code{dbus-escape-as-identifier}. Example:
@lisp
(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
@@ -1177,9 +1170,9 @@ Type Conversion
@lisp
(string-equal
- (dbus-unescape-from-identifier
- (dbus-escape-as-identifier "Grüß Göttin"))
- "Grüß Göttin")
+ (dbus-unescape-from-identifier
+ (dbus-escape-as-identifier "Grüß Göttin"))
+ "Grüß Göttin")
@result{} nil
@end lisp
@@ -1196,12 +1189,13 @@ Synchronous Methods
Methods can be called synchronously (@dfn{blocking}) or asynchronously
(@dfn{non-blocking}).
-At D-Bus level, a method call consist of two messages: one message
+At the D-Bus level, a method call consist of two messages: one message
which carries the input parameters to the object owning the method to
be called, and a reply message returning the resulting output
parameters from the object.
@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}.
@@ -1210,14 +1204,14 @@ Synchronous Methods
an interface offered by @var{service}. It must provide @var{method}.
If the parameter @code{:timeout} is given, the following integer
-@var{timeout} specifies the maximum number of milliseconds 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 (@pxref{Errors and
-Events}).
+@var{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 (@pxref{Errors
+and Events}).
-All other arguments args are passed to @var{method} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}.
+The remaining arguments @var{args} are passed to @var{method} as
+arguments. They are converted into D-Bus types as described in
+@ref{Type Conversion}.
The function returns the resulting values of @var{method} as a list of
Lisp objects, according to the type conversion rules described in
@@ -1225,9 +1219,9 @@ Synchronous Methods
@lisp
(dbus-call-method
- :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
- "org.gnome.seahorse.Keys" "GetKeyField"
- "openpgp:657984B8C7A966DD" "simple-name")
+ :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
+ "org.gnome.seahorse.Keys" "GetKeyField"
+ "openpgp:657984B8C7A966DD" "simple-name")
@result{} (t ("Philip R. Zimmermann"))
@end lisp
@@ -1238,10 +1232,10 @@ Synchronous Methods
@lisp
(dbus-call-method
- :system "org.freedesktop.Hal"
- "/org/freedesktop/Hal/devices/computer"
- "org.freedesktop.Hal.Device" "GetPropertyString"
- "system.kernel.machine")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer"
+ "org.freedesktop.Hal.Device" "GetPropertyString"
+ "system.kernel.machine")
@result{} "i686"
@end lisp
@@ -1257,17 +1251,17 @@ Synchronous Methods
@lisp
(dolist (device
- (dbus-call-method
- :system "org.freedesktop.Hal"
- "/org/freedesktop/Hal/Manager"
- "org.freedesktop.Hal.Manager" "GetAllDevices"))
+ (dbus-call-method
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/Manager"
+ "org.freedesktop.Hal.Manager" "GetAllDevices"))
(message "\nudi = %s" device)
(dolist (properties
- (dbus-call-method
- :system "org.freedesktop.Hal" device
- "org.freedesktop.Hal.Device" "GetAllProperties"))
+ (dbus-call-method
+ :system "org.freedesktop.Hal" device
+ "org.freedesktop.Hal.Device" "GetAllProperties"))
(message " %s = %S"
- (car properties) (or (caar (cdr properties)) ""))))
+ (car properties) (or (caadr properties) ""))))
@print{} "udi = /org/freedesktop/Hal/devices/computer
info.addons = (\"hald-addon-acpi\")
@@ -1304,34 +1298,35 @@ Asynchronous Methods
an interface offered by @var{service}. It must provide @var{method}.
@var{handler} is a Lisp function, which is called when the
-corresponding return message has arrived. If @var{handler} is
-@code{nil}, no return message will be expected.
+corresponding return message arrives. If @var{handler} is @code{nil},
+no return message will be expected.
If the parameter @code{:timeout} is given, the following integer
-@var{timeout} specifies the maximum number of milliseconds a reply
-message must arrive. The default value is 25,000. If there is no
-reply message in time, a D-Bus error is raised (@pxref{Errors and
+@var{timeout} specifies the maximum number of milliseconds before a
+reply message must arrive. The default value is 25,000. If there is
+no reply message in time, a D-Bus error is raised (@pxref{Errors and
Events}).
-All other arguments args are passed to @var{method} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}.
+The remaining arguments @var{args} are passed to @var{method} as
+arguments. They are converted into D-Bus types as described in
+@ref{Type Conversion}.
If @var{handler} is a Lisp function, the function returns a key into
the hash table @code{dbus-registered-objects-table}. The
corresponding entry in the hash table is removed, when the return
-message has been arrived, and @var{handler} is called. Example:
+message arrives, and @var{handler} is called. Example:
@lisp
(dbus-call-method-asynchronously
- :system "org.freedesktop.Hal"
- "/org/freedesktop/Hal/devices/computer"
- "org.freedesktop.Hal.Device" "GetPropertyString" 'message
- "system.kernel.machine")
-
-@result{} (:serial :system 2)
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer"
+ "org.freedesktop.Hal.Device" "GetPropertyString"
+ (lambda (msg) (message "%s" msg))
+ "system.kernel.machine")
@print{} i686
+
+@result{} (:serial :system 2)
@end lisp
@end defun
@@ -1347,7 +1342,8 @@ Receiving Method Calls
the following functions:
@defun dbus-register-service bus service &rest flags
-Register the known name @var{service} on D-Bus @var{bus}.
+This function registers the known name @var{service} on D-Bus
+@var{bus}.
@var{bus} is either the symbol @code{:system} or the symbol
@code{:session}.
@@ -1357,36 +1353,33 @@ Receiving Method Calls
@var{flags} is a subset of the following keywords:
-@itemize
-@item @code{:allow-replacement}: Allow another service to become the primary
-owner if requested.
-
-@item @code{:replace-existing}: Request to replace the current primary owner.
-
-@item @code{:do-not-queue}: If we can not become the primary owner do not
-place us in the queue.
-@end itemize
+@table @code
+@item :allow-replacement
+Allow another service to become the primary owner if requested.
+@item :replace-existing
+Request to replace the current primary owner.
+@item :do-not-queue
+If we can not become the primary owner do not place us in the queue.
+@end table
One of the following keywords is returned:
-@itemize
-
-@item @code{:primary-owner}: We have become the primary owner of the name
-@var{service}.
-
-@item @code{:in-queue}: We could not become the primary owner and
-have been placed in the queue.
-
-@item @code{:exists}: We already are in the queue.
-
-@item @code{:already-owner}: We already are the primary
-owner.
-@end itemize
+@table @code
+@item :primary-owner
+We have become the primary owner of the name @var{service}.
+@item :in-queue
+We could not become the primary owner and have been placed in the
+queue.
+@item :exists
+We already are in the queue.
+@item :already-owner
+We already are the primary owner.
+@end table
@end defun
@defun dbus-unregister-service bus service
-Unregister all objects from D-Bus @var{bus}, registered by Emacs for
-@var{service}.
+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
@code{:session}.
@@ -1397,24 +1390,27 @@ Receiving Method Calls
One of the following keywords is returned:
-@itemize
-@item @code{:released}: We successfully released the name @var{service}.
-@item @code{:non-existent}: The name @var{service} does not exist on the bus.
-@item @code{:not-owner}: We are not an owner of the name @var{service}.
-@end itemize
+@table @code
+@item :released
+We successfully released the name @var{service}.
+@item :non-existent
+The name @var{service} does not exist on the bus.
+@item :not-owner
+We are not an owner of the name @var{service}.
+@end table
@end defun
-When a name has been chosen, Emacs can offer own methods, which can be
-called by other applications. These methods could be an
+When a name has been chosen, Emacs can offer its own methods, which
+can be called by other applications. These methods could be an
implementation of an interface of a well known service, like
@samp{org.freedesktop.TextEditor}.
-It could be also an implementation of an own interface. In this case,
-the service name must be @samp{org.gnu.Emacs}. The object path shall
-begin with @samp{/org/gnu/Emacs/@strong{Application}}, and the
-interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
-@samp{@strong{Application}} is the name of the application which
-provides the interface.
+They could also be an implementation of its own interface. In this
+case, the service name must be @samp{org.gnu.Emacs}. The object path
+shall begin with @samp{/org/gnu/Emacs/@var{application}}, and the
+interface name shall be @code{org.gnu.Emacs.@var{application}}, where
+@var{application} is the name of the application which provides the
+interface.
@deffn Constant dbus-service-emacs
The well known service name @samp{org.gnu.Emacs} of Emacs.
@@ -1436,10 +1432,10 @@ Receiving Method Calls
@code{:session}.
@var{service} is the D-Bus service name of the D-Bus object
-@var{method} is registered for. It must be a known name (See
+@var{method} is registered for. It must be a known name (see
discussion of @var{dont-register-service} below).
-@var{path} is the D-Bus object path @var{service} is registered (See
+@var{path} is the D-Bus object path @var{service} is registered (see
discussion of @var{dont-register-service} below).
@var{interface} is the interface offered by @var{service}. It must
@@ -1456,8 +1452,8 @@ Receiving Method Calls
cons cell, @var{handler} can return this object directly, instead of
returning a list containing the object.
-In case @var{handler} shall return a reply message with an empty
-argument list, @var{handler} must return the symbol @code{:ignore}.
+If @var{handler} returns a reply message with an empty argument list,
+@var{handler} must return the symbol @code{:ignore}.
When @var{dont-register-service} is non-@code{nil}, the known name
@var{service} is not registered. This means that other D-Bus clients
@@ -1468,7 +1464,7 @@ Receiving Method Calls
The default D-Bus timeout when waiting for a message reply is 25
seconds. This value could be even smaller, depending on the calling
-client. Therefore, @var{handler} shall not last longer than
+client. Therefore, @var{handler} should not last longer than
absolutely necessary.
@code{dbus-register-method} returns a Lisp object, which can be used
@@ -1477,18 +1473,14 @@ Receiving Method Calls
@lisp
(defun my-dbus-method-handler (filename)
- (let (result)
- (if (find-file filename)
- (setq result '(:boolean t))
- (setq result '(:boolean nil)))
- result))
-
-@result{} my-dbus-method-handler
+ (if (find-file filename)
+ '(:boolean t)
+ '(:boolean nil)))
(dbus-register-method
- :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
- "org.freedesktop.TextEditor" "OpenFile"
- 'my-dbus-method-handler)
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "OpenFile"
+ #'my-dbus-method-handler)
@result{} ((:method :session "org.freedesktop.TextEditor" "OpenFile")
("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
@@ -1496,9 +1488,9 @@ Receiving Method Calls
@end lisp
If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
-from another D-Bus application with a filename as parameter, the file
+from another D-Bus application with a file name as parameter, the file
is opened in Emacs, and the method returns either @var{true} or
-@var{false}, indicating the success of the method. As test tool one
+@var{false}, indicating the success of the method. As a test tool one
could use the command line tool @code{dbus-send} in a shell:
@example
@@ -1522,11 +1514,9 @@ Receiving Method Calls
(find-file (car args))
(error (signal 'dbus-error (cdr err))))
t)
-
-@result{} my-dbus-method-handler
@end lisp
-The test runs then
+The test then runs
@example
# dbus-send --session --print-reply \
@@ -1550,7 +1540,7 @@ Receiving Method Calls
@var{service} is the D-Bus service name of the D-Bus. It must be a
known name.
-@var{path} is the D-Bus object path @var{service} is registered (See
+@var{path} is the D-Bus object path @var{service} is registered (see
discussion of @var{dont-register-service} below).
@var{interface} is the name of the interface used at @var{path},
@@ -1559,7 +1549,7 @@ Receiving Method Calls
@var{access} indicates, whether the property can be changed by other
services via D-Bus. It must be either the symbol @code{:read} or
@code{:readwrite}. @var{value} is the initial value of the property,
-it can be of any valid type (see @code{dbus-call-method} for details).
+it can be of any valid type (@xref{dbus-call-method}, for details).
If @var{property} already exists on @var{path}, it will be
overwritten. For properties with access type @code{:read} this is the
@@ -1584,15 +1574,15 @@ Receiving Method Calls
@lisp
(dbus-register-property
- :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
- "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
@result{} ((:property :session "org.freedesktop.TextEditor" "name")
("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
(dbus-register-property
- :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
- "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
@result{} ((:property :session "org.freedesktop.TextEditor" "version")
("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
@@ -1623,28 +1613,28 @@ Receiving Method Calls
]
@end example
-It is also possible, to apply the @code{dbus-get-property},
+It is also possible to apply the @code{dbus-get-property},
@code{dbus-get-all-properties} and @code{dbus-set-property} functions
(@pxref{Properties and Annotations}).
@lisp
(dbus-set-property
- :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
- "org.freedesktop.TextEditor" "version" "23.1.50")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version" "23.1.50")
@result{} "23.1.50"
(dbus-get-property
- :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
- "org.freedesktop.TextEditor" "version")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version")
@result{} "23.1.50"
@end lisp
@end defun
@defun dbus-unregister-object object
-Unregister @var{object} from the D-Bus. @var{object} must be the
-result of a preceding @code{dbus-register-method},
+This function unregisters @var{object} from the D-Bus. @var{object}
+must be the result of a preceding @code{dbus-register-method},
@code{dbus-register-property} or @code{dbus-register-signal} call
(@pxref{Signals}). It returns @code{t} if @var{object} has been
unregistered, @code{nil} otherwise.
@@ -1672,22 +1662,22 @@ Signals
Signals can be unicast or broadcast messages. For broadcast messages,
@var{service} must be @code{nil}. Otherwise, @var{service} is the
-D-Bus service name the signal is sent to as unicast
+D-Bus service name the signal is sent to as a unicast
message.@footnote{For backward compatibility, a broadcast message is
also emitted if @var{service} is the known or unique name Emacs is
registered at D-Bus @var{bus}.} @var{path} is the D-Bus object path
@var{signal} is sent from. @var{interface} is an interface available
at @var{path}. It must provide @var{signal}.
-All other arguments args are passed to @var{signal} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}. Example:
+The remaining arguments @var{args} are passed to @var{signal} as
+arguments. They are converted into D-Bus types as described in
+@ref{Type Conversion}. Example:
@lisp
(dbus-send-signal
- :session nil dbus-path-emacs
- (concat dbus-interface-emacs ".FileManager") "FileModified"
- "/home/albinus/.emacs")
+ :session nil dbus-path-emacs
+ (concat dbus-interface-emacs ".FileManager") "FileModified"
+ "/home/albinus/.emacs")
@end lisp
@end defun
@@ -1702,11 +1692,11 @@ Signals
object. It can be either a known name or the unique name of the D-Bus
object sending the signal. A known name will be mapped onto the
unique name of the object, owning @var{service} at registration time.
-When the corresponding D-Bus object disappears, signals won't be
-received any longer.
+When the corresponding D-Bus object disappears, signals will no longer
+be received.
-@var{path} is the corresponding D-Bus object path, @var{service} is
-registered at. @var{interface} is an interface offered by
+@var{path} is the corresponding D-Bus object path that @var{service}
+is registered at. @var{interface} is an interface offered by
@var{service}. It must provide @var{signal}.
@var{service}, @var{path}, @var{interface} and @var{signal} can be
@@ -1721,30 +1711,31 @@ Signals
pairs.@footnote{For backward compatibility, the arguments @var{args}
can also be just strings. They stand for the respective arguments of
@var{signal} in their order, and are used for filtering as well. A
-@code{nil} argument might be used to preserve the order.} The meaning
-is as follows:
+@code{nil} argument might be used to preserve the order.} Their
+meaning is as follows:
-@itemize
-@item @code{:argN} @var{string}:@*
-@code{:pathN} @var{string}:@*
-This stands for the Nth argument of the signal. @code{:pathN}
-arguments can be used for object path wildcard matches as specified by
-D-Bus, while an @code{:argN} argument requires an exact match.
+@table @code
+@item :arg@var{n} @var{string}
+@item :path@var{n} @var{string}
+This stands for the @var{n}th argument of the signal.
+@code{:path@var{n}} arguments can be used for object path wildcard
+matches as specified by D-Bus, while an @code{:argN} argument requires
+an exact match.
-@item @code{:arg-namespace} @var{string}:@*
-Register for the signals, which first argument defines the service or
-interface namespace @var{string}.
+@item :arg-namespace @var{string}
+Register for those signals, whose first argument names a service or
+interface within the namespace @var{string}.
-@item @code{:path-namespace} @var{string}:@*
+@item :path-namespace @var{string}
Register for the object path namespace @var{string}. All signals sent
from an object path, which has @var{string} as the preceding string,
are matched. This requires @var{path} to be @code{nil}.
-@item @code{:eavesdrop}:@*
+@item :eavesdrop
Register for unicast signals which are not directed to the D-Bus
object Emacs is registered at D-Bus BUS, if the security policy of BUS
allows this. Otherwise, this argument is ignored.
-@end itemize
+@end table
@code{dbus-register-signal} returns a Lisp object, which can be used
as argument in @code{dbus-unregister-object} for removing the
@@ -1754,12 +1745,10 @@ Signals
(defun my-dbus-signal-handler (device)
(message "Device %s added" device))
-@result{} my-dbus-signal-handler
-
(dbus-register-signal
- :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
- "org.freedesktop.Hal.Manager" "DeviceAdded"
- 'my-dbus-signal-handler)
+ :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
+ "org.freedesktop.Hal.Manager" "DeviceAdded"
+ #'my-dbus-signal-handler)
@result{} ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded")
("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
@@ -1769,8 +1758,8 @@ Signals
As we know from the introspection data of interface
@samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded}
provides one single parameter, which is mapped into a Lisp string.
-The callback function @code{my-dbus-signal-handler} must define one
-single string argument therefore. Plugging an USB device to your
+The callback function @code{my-dbus-signal-handler} must therefore
+define a single string argument. Plugging a USB device into your
machine, when registered for signal @samp{DeviceAdded}, will show you
which objects the GNU/Linux @code{hal} daemon adds.
@@ -1781,7 +1770,7 @@ Signals
@lisp
(dbus-ignore-errors
(dbus-register-signal
- :system nil nil nil nil 'ignore :path-namespace "/invalid/path"))
+ :system nil nil nil nil #'ignore :path-namespace "/invalid/path"))
@result{} nil
@end lisp
@@ -1796,14 +1785,14 @@ Alternative Buses
Until now, we have spoken about the system and the session buses,
which are the default buses to be connected to. However, it is
-possible to connect to any bus, from which the address is known. 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 @code{:session}), this address can be used instead. The
-connection to this bus must be initialized first.
+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
+@code{:session}), this address can be used instead. The connection to
+this bus must be initialized first.
@defun dbus-init-bus bus &optional private
-Establish the connection to D-Bus @var{bus}.
+This function establishes the connection to D-Bus @var{bus}.
@var{bus} can be either the symbol @code{:system} or the symbol
@code{:session}, or it can be a string denoting the address of the
@@ -1811,12 +1800,12 @@ Alternative Buses
is called when loading @file{dbus.el}, there is no need to call it
again.
-The function returns a number, which counts the connections this Emacs
-session has established to the @var{bus} under the same unique name
-(see @code{dbus-get-unique-name}). It depends on the libraries Emacs
-is linked with, and on the environment Emacs is running. For example,
-if Emacs is linked with the GTK+ toolkit, and it runs in a GTK+-aware
-environment like Gnome, another connection might already be
+The function returns the number of connections this Emacs session has
+established to the @var{bus} under the same unique name
+(@pxref{dbus-get-unique-name}). It depends on the libraries Emacs is
+linked with, and on the environment Emacs is running. For example, if
+Emacs is linked with the GTK+ toolkit, and it runs in a GTK+-aware
+environment like GNOME, another connection might already be
established.
When @var{private} is non-@code{nil}, a new connection is established
@@ -1831,9 +1820,9 @@ Alternative Buses
@lisp
(setq my-bus
- (dbus-call-method
- :session "org.a11y.Bus" "/org/a11y/bus"
- "org.a11y.Bus" "GetAddress"))
+ (dbus-call-method
+ :session "org.a11y.Bus" "/org/a11y/bus"
+ "org.a11y.Bus" "GetAddress"))
@result{} "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f"
@@ -1848,7 +1837,7 @@ Alternative Buses
@result{} ":1.19"
-;; Open a new connection to the same bus. This obsoletes the
+;; Open a new connection to the same bus. This supersedes the
;; previous one.
(dbus-init-bus my-bus 'private)
@@ -1859,14 +1848,14 @@ Alternative Buses
@result{} ":1.20"
@end lisp
-D-Bus addresses can specify different transport. A possible address
-could be based on TCP/IP sockets, see next example. However, it
-depends on the bus daemon configuration, which transport is supported.
+D-Bus addresses can specify a different transport. A possible address
+could be based on TCP/IP sockets, see next example. Which transport
+is supported depends on the bus daemon configuration, however.
@end defun
@defun dbus-setenv bus variable value
-Set the value of the @var{bus} environment variable @var{variable} to
-@var{value}.
+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},
or a string denoting the bus address. Both @var{variable} and
@@ -1877,7 +1866,7 @@ Alternative Buses
Some bus instances, such as @code{:system}, may disable setting the
environment. In such cases, or if this feature is not available in
-older D-Bus versions, a @code{dbus-error} error is raised.
+older D-Bus versions, this function signals a @code{dbus-error}.
As an example, it might be desirable to start X11 enabled services on
a remote host's bus on the same X11 server the local Emacs is
@@ -1916,7 +1905,7 @@ Errors and Events
@code{dbus-register-method}, @code{dbus-register-property} and
@code{dbus-register-signal} are checked for correct D-Bus types. If
there is a type mismatch, the Lisp error @code{wrong-type-argument}
-@code{D-Bus ARG} is raised.
+@code{D-Bus @var{arg}} is raised.
All errors raised by D-Bus are signaled with the error symbol
@code{dbus-error}. If possible, error messages from D-Bus are
@@ -1967,35 +1956,39 @@ Errors and Events
callback function in order to retrieve the information from the event.
@defun dbus-event-bus-name event
-Returns the bus name @var{event} is coming from.
-The result is either the symbol @code{:system} or the symbol @code{:session}.
+This function returns the bus name @var{event} is coming from. The
+result is either the symbol @code{:system} or the symbol
+@code{:session}.
@end defun
@defun dbus-event-message-type event
-Returns the message type of the corresponding D-Bus message. The
-result is a natural number.
+This function returns the message type of the corresponding D-Bus
+message. The result is a natural number.
@end defun
@defun dbus-event-serial-number event
-Returns the serial number of the corresponding D-Bus message.
-The result is a natural number.
+This function returns the serial number of the corresponding D-Bus
+message. The result is a natural number.
@end defun
@defun dbus-event-service-name event
-Returns the unique name of the D-Bus object @var{event} is coming from.
+This function returns the unique name of the D-Bus object @var{event}
+is coming from.
@end defun
@defun dbus-event-path-name event
-Returns the object path of the D-Bus object @var{event} is coming from.
+This function returns the object path of the D-Bus object @var{event}
+is coming from.
@end defun
@defun dbus-event-interface-name event
-Returns the interface name of the D-Bus object @var{event} is coming from.
+This function returns the interface name of the D-Bus object
+@var{event} is coming from.
@end defun
@defun dbus-event-member-name event
-Returns the member name of the D-Bus object @var{event} is coming
-from. It is either a signal name or a method name.
+This function returns the member name of the D-Bus object @var{event}
+is coming from. It is either a signal name or a method name.
@end defun
D-Bus errors are not propagated during event handling, because it is
@@ -2009,7 +2002,7 @@ Errors and Events
two arguments, the event and the error variable caught in
@code{condition-case} by @code{dbus-error}.
-Such functions can be used the adapt the error signal to be raised.
+Such functions can be used to adapt the error signal to be raised.
Example:
@lisp
@@ -2019,12 +2012,12 @@ Errors and Events
(message "my-dbus-event-error-handler: %S %S" event error)
(signal 'file-error (cdr error))))
-(add-hook 'dbus-event-error-functions 'my-dbus-event-error-handler)
+(add-hook 'dbus-event-error-functions #'my-dbus-event-error-handler)
@end lisp
@end defvar
-Hook functions shall take into account, that there might be other
-D-Bus applications running. Therefore, they shall check carefully,
+Hook functions should take into account that there might be other
+D-Bus applications running. They should therefore check carefully,
whether a given D-Bus error is related to them.
diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 4538399c75..06bd9e567f 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -182,7 +182,7 @@ dbus-event-error-functions
;;; Basic D-Bus message functions.
(defvar dbus-return-values-table (make-hash-table :test 'equal)
- "Hash table for temporary storing arguments of reply messages.
+ "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,
`:system' or `:session', or a string denoting the bus address.
@@ -225,10 +225,10 @@ dbus-call-method
object path SERVICE is registered at. INTERFACE is an interface
offered by SERVICE. It must provide METHOD.
-If the parameter `:timeout' is given, the following integer TIMEOUT
-specifies the maximum number of milliseconds 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 `: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.
All other arguments ARGS are passed to METHOD as arguments. They are
converted into D-Bus types via the following rules:
@@ -248,14 +248,14 @@ dbus-call-method
input arguments. It follows the mapping rules:
DBUS_TYPE_BOOLEAN => t or nil
- DBUS_TYPE_BYTE => number
- DBUS_TYPE_UINT16 => number
+ DBUS_TYPE_BYTE => natural number
+ DBUS_TYPE_UINT16 => natural number
DBUS_TYPE_INT16 => integer
- DBUS_TYPE_UINT32 => number or float
- DBUS_TYPE_UNIX_FD => number or float
- DBUS_TYPE_INT32 => integer or float
- DBUS_TYPE_UINT64 => number or float
- DBUS_TYPE_INT64 => integer or float
+ DBUS_TYPE_UINT32 => natural number
+ DBUS_TYPE_UNIX_FD => natural number
+ DBUS_TYPE_INT32 => integer
+ DBUS_TYPE_UINT64 => natural number
+ DBUS_TYPE_INT64 => integer
DBUS_TYPE_DOUBLE => float
DBUS_TYPE_STRING => string
DBUS_TYPE_OBJECT_PATH => string
@@ -268,9 +268,9 @@ dbus-call-method
Example:
\(dbus-call-method
- :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\"
- \"org.gnome.seahorse.Keys\" \"GetKeyField\"
- \"openpgp:657984B8C7A966DD\" \"simple-name\")
+ :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\"
+ \"org.gnome.seahorse.Keys\" \"GetKeyField\"
+ \"openpgp:657984B8C7A966DD\" \"simple-name\")
=> (t (\"Philip R. Zimmermann\"))
@@ -278,9 +278,9 @@ dbus-call-method
object is returned instead of a list containing this single Lisp object.
\(dbus-call-method
- :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
- \"org.freedesktop.Hal.Device\" \"GetPropertyString\"
- \"system.kernel.machine\")
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
+ \"org.freedesktop.Hal.Device\" \"GetPropertyString\"
+ \"system.kernel.machine\")
=> \"i686\""
@@ -357,10 +357,10 @@ dbus-call-method-asynchronously
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 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 `: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.
All other arguments ARGS are passed to METHOD as arguments. They are
converted into D-Bus types via the following rules:
@@ -377,19 +377,19 @@ dbus-call-method-asynchronously
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 has been arrived,
+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\")
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
+ \"org.freedesktop.Hal.Device\" \"GetPropertyString\" \\='message
+ \"system.kernel.machine\")
- => (:serial :system 2)
+ -| i686
- -| i686"
+ => (:serial :system 2)"
(or (featurep 'dbusbind)
(signal 'dbus-error (list "Emacs not compiled with dbus support")))
@@ -438,8 +438,8 @@ dbus-send-signal
Example:
\(dbus-send-signal
- :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\"
- \"FileModified\" \"/home/albinus/.emacs\")"
+ :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\"
+ \"FileModified\" \"/home/albinus/.emacs\")"
(or (featurep 'dbusbind)
(signal 'dbus-error (list "Emacs not compiled with dbus support")))
@@ -625,17 +625,17 @@ dbus-register-signal
It can be either a known name or the unique name of the D-Bus object
sending the signal.
-PATH is the D-Bus object path SERVICE is registered. INTERFACE
-is an interface offered by SERVICE. It must provide SIGNAL.
-HANDLER is a Lisp function to be called when the signal is
-received. It must accept as arguments the values SIGNAL is
+PATH is the D-Bus object path SERVICE is registered at.
+INTERFACE is an interface offered by SERVICE. It must provide
+SIGNAL. HANDLER is a Lisp function to be called when the signal
+is received. It must accept as arguments the values SIGNAL is
sending.
SERVICE, PATH, INTERFACE and SIGNAL can be nil. This is
interpreted as a wildcard for the respective argument.
The remaining arguments ARGS can be keywords or keyword string pairs.
-The meaning is as follows:
+Their meaning is as follows:
`:argN' STRING:
`:pathN' STRING: This stands for the Nth argument of the
@@ -643,8 +643,9 @@ dbus-register-signal
matches as specified by D-Bus, while an `:argN' argument
requires an exact match.
-`:arg-namespace' STRING: Register for the signals, which first
-argument defines the service or interface namespace STRING.
+`:arg-namespace' STRING: Register for those signals, whose first
+argument names a service or interface within the namespace
+STRING.
`:path-namespace' STRING: Register for the object path namespace
STRING. All signals sent from an object path, which has STRING as
@@ -660,8 +661,8 @@ dbus-register-signal
(message \"Device %s added\" device))
\(dbus-register-signal
- :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\"
- \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler)
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\"
+ \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler)
=> ((:signal :system \"org.freedesktop.Hal.Manager\" \"DeviceAdded\")
(\"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\" my-signal-handler))
@@ -773,24 +774,24 @@ dbus-register-signal
(defun dbus-register-method
(bus service path interface method handler &optional dont-register-service)
- "Register for method METHOD on the D-Bus BUS.
+ "Register METHOD on the D-Bus BUS.
BUS is either a Lisp symbol, `: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
+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 (See discussion of
-DONT-REGISTER-SERVICE below). INTERFACE is the interface offered by
-SERVICE. It must provide METHOD.
+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.
-In case HANDLER shall return a reply message with an empty argument
-list, HANDLER must return the symbol `:ignore'.
+If HANDLER returns a reply message with an empty argument list,
+HANDLER must return the symbol `:ignore'.
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
@@ -888,8 +889,8 @@ dbus-unregister-object
;;; D-Bus type conversion.
(defun dbus-string-to-byte-array (string)
- "Transform STRING to list (:array :byte c1 :byte c2 ...).
-STRING shall be UTF8 coded."
+ "Transform STRING to list (:array :byte C1 :byte C2 ...).
+STRING shall be UTF-8 coded."
(if (zerop (length string))
'(:array :signature "y")
(let (result)
@@ -897,7 +898,7 @@ dbus-string-to-byte-array
(setq result (append result (list :byte elt)))))))
(defun dbus-byte-array-to-string (byte-array &optional multibyte)
- "Transform BYTE-ARRAY into UTF8 coded string.
+ "Transform BYTE-ARRAY into UTF-8 coded string.
BYTE-ARRAY must be a list of structure (c1 c2 ...), or a byte
array as produced by `dbus-string-to-byte-array'. The resulting
string is unibyte encoded, unless MULTIBYTE is non-nil."
@@ -920,9 +921,9 @@ dbus-escape-as-identifier
\"0123abc_xyz\\x01\\xff\" -> \"_30123abc_5fxyz_01_ff\"
-i.e. similar to URI encoding, but with \"_\" taking the role of \"%\",
-and a smaller allowed set. As a special case, \"\" is escaped to
-\"_\".
+i.e. similar to URI encoding, but with \"_\" taking the role of
+\"%\", and a smaller allowed set. As a special case, \"\" is
+escaped to \"_\".
Returns the escaped string. Algorithm taken from
telepathy-glib's `tp_escape_as_identifier'."
@@ -963,8 +964,8 @@ dbus-check-event
are the arguments passed to HANDLER, when it is called during
event handling in `dbus-handle-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
(when dbus-debug (message "DBus-Event %s" event))
(unless (and (listp event)
(eq (car event) 'dbus-event)
@@ -1038,16 +1039,16 @@ dbus-event-bus-name
"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
-`dbus-check-event'. This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'. This function signals a `dbus-error' if the
+event is not well formed."
(dbus-check-event event)
(nth 1 event))
(defun dbus-event-message-type (event)
"Return the message type of the corresponding D-Bus message.
The result is a number. EVENT is a D-Bus event, see
-`dbus-check-event'. This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'. This function signals a `dbus-error' if the
+event is not well formed."
(dbus-check-event event)
(nth 2 event))
@@ -1055,41 +1056,40 @@ dbus-event-serial-number
"Return the serial number of the corresponding D-Bus message.
The result is a number. The serial number is needed for
generating a reply message. EVENT is a D-Bus event, see
-`dbus-check-event'. This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'. This function signals a `dbus-error' if the
+event is not well formed."
(dbus-check-event event)
(nth 3 event))
(defun dbus-event-service-name (event)
"Return the name of the D-Bus object the event is coming from.
The result is a string. EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
(dbus-check-event event)
(nth 4 event))
(defun dbus-event-path-name (event)
"Return the object path of the D-Bus object the event is coming from.
The result is a string. EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
(dbus-check-event event)
(nth 5 event))
(defun dbus-event-interface-name (event)
"Return the interface name of the D-Bus object the event is coming from.
The result is a string. EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
(dbus-check-event event)
(nth 6 event))
(defun dbus-event-member-name (event)
"Return the member name the event is coming from.
-It is either a signal name or a method name. The result is a
+It is either a signal name or a method name. The result is a
string. EVENT is a D-Bus event, see `dbus-check-event'. This
-function raises a `dbus-error' signal in case the event is not
-well formed."
+function signals a `dbus-error' if the event is not well formed."
(dbus-check-event event)
(nth 7 event))
@@ -1097,10 +1097,10 @@ dbus-event-member-name
;;; D-Bus registered names.
(defun dbus-list-activatable-names (&optional bus)
- "Return the D-Bus service names which can be activated as list.
-If BUS is left nil, `:system' is assumed. The result is a list
-of strings, which is nil when there are no activatable service
-names at all."
+ "Return a list of the D-Bus service names which can be activated.
+BUS defaults to `:system' when nil or omitted. The result is a
+list of strings, which is nil when there are no activatable
+service names at all."
(dbus-ignore-errors
(dbus-call-method
(or bus :system) dbus-service-dbus
@@ -1126,8 +1126,8 @@ dbus-list-known-names
(defun dbus-list-queued-owners (bus service)
"Return the unique names registered at D-Bus BUS and queued for SERVICE.
-The result is a list of strings, or nil when there are no
-queued name owners service names at all."
+The result is a list of strings, or nil when there are no queued
+name owner service names at all."
(dbus-ignore-errors
(dbus-call-method
bus dbus-service-dbus dbus-path-dbus
@@ -1144,13 +1144,13 @@ dbus-get-name-owner
(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.
+milliseconds before `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
+Note, that this autoloads SERVICE if it is not running yet. To
+check whether SERVICE is already running, you can instead write
- (member service \(dbus-list-known-names bus))"
+ (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
@@ -1239,11 +1239,11 @@ dbus-introspect-get-interface-names
"Return all interface names of SERVICE in D-Bus BUS at object path PATH.
It returns a list of strings.
-There will be always the default interface
-\"org.freedesktop.DBus.Introspectable\". Another default
-interface is \"org.freedesktop.DBus.Properties\". If present,
-\"interface\" objects can also have \"property\" objects as
-children, beside \"method\" and \"signal\" objects."
+The default interface \"org.freedesktop.DBus.Introspectable\" is
+always present. Another default interface is
+\"org.freedesktop.DBus.Properties\". If present, \"interface\"
+objects can also have \"property\" objects as children, beside
+\"method\" and \"signal\" objects."
(let ((object (dbus-introspect-xml bus service path))
result)
(dolist (elt (xml-get-children object 'interface) (nreverse result))
@@ -1251,9 +1251,10 @@ dbus-introspect-get-interface-names
(defun dbus-introspect-get-interface (bus service path interface)
"Return the INTERFACE of SERVICE in D-Bus BUS at object path PATH.
-The return value is an XML object. INTERFACE must be a string,
-element of the list returned by `dbus-introspect-get-interface-names'.
-The resulting \"interface\" object can contain \"method\", \"signal\",
+The return value is an XML object. INTERFACE must be a string
+and a member of the list returned by
+`dbus-introspect-get-interface-names'. The resulting
+\"interface\" object can contain \"method\", \"signal\",
\"property\" and \"annotation\" children."
(let ((elt (xml-get-children
(dbus-introspect-xml bus service path) 'interface)))
@@ -1273,9 +1274,9 @@ dbus-introspect-get-method-names
(push (dbus-introspect-get-attribute elt "name") result))))
(defun dbus-introspect-get-method (bus service path interface method)
- "Return method METHOD of interface INTERFACE as XML object.
+ "Return method METHOD of interface INTERFACE as an XML object.
It must be located at SERVICE in D-Bus BUS at object path PATH.
-METHOD must be a string, element of the list returned by
+METHOD must be a string and a member of the list returned by
`dbus-introspect-get-method-names'. The resulting \"method\"
object can contain \"arg\" and \"annotation\" children."
(let ((elt (xml-get-children
@@ -1296,7 +1297,7 @@ dbus-introspect-get-signal-names
(push (dbus-introspect-get-attribute elt "name") result))))
(defun dbus-introspect-get-signal (bus service path interface signal)
- "Return signal SIGNAL of interface INTERFACE as XML object.
+ "Return signal SIGNAL of interface INTERFACE as an XML object.
It must be located at SERVICE in D-Bus BUS at object path PATH.
SIGNAL must be a string, element of the list returned by
`dbus-introspect-get-signal-names'. The resulting \"signal\"
@@ -1319,9 +1320,9 @@ dbus-introspect-get-property-names
(push (dbus-introspect-get-attribute elt "name") result))))
(defun dbus-introspect-get-property (bus service path interface property)
- "Return PROPERTY of INTERFACE as XML object.
+ "Return PROPERTY of INTERFACE as an XML object.
It must be located at SERVICE in D-Bus BUS at object path PATH.
-PROPERTY must be a string, element of the list returned by
+PROPERTY must be a string and a member of the list returned by
`dbus-introspect-get-property-names'. The resulting PROPERTY
object can contain \"annotation\" children."
(let ((elt (xml-get-children
@@ -1336,7 +1337,7 @@ dbus-introspect-get-property
(defun dbus-introspect-get-annotation-names
(bus service path interface &optional name)
- "Return all annotation names as list of strings.
+ "Return all annotation names as a list of strings.
If NAME is nil, the annotations are children of INTERFACE,
otherwise NAME must be a \"method\", \"signal\", or \"property\"
object, where the annotations belong to."
@@ -1352,7 +1353,7 @@ dbus-introspect-get-annotation-names
(defun dbus-introspect-get-annotation
(bus service path interface name annotation)
- "Return ANNOTATION as XML object.
+ "Return ANNOTATION as an XML object.
If NAME is nil, ANNOTATION is a child of INTERFACE, otherwise
NAME must be the name of a \"method\", \"signal\", or
\"property\" object, where the ANNOTATION belongs to."
@@ -1374,7 +1375,7 @@ dbus-introspect-get-annotation
(car elt)))
(defun dbus-introspect-get-argument-names (bus service path interface name)
- "Return a list of all argument names as list of strings.
+ "Return a list of all argument names as a list of strings.
NAME must be a \"method\" or \"signal\" object.
Argument names are optional, the function can return nil
@@ -1388,8 +1389,9 @@ dbus-introspect-get-argument-names
(defun dbus-introspect-get-argument (bus service path interface name arg)
"Return argument ARG as XML object.
-NAME must be a \"method\" or \"signal\" object. ARG must be a string,
-element of the list returned by `dbus-introspect-get-argument-names'."
+NAME must be a \"method\" or \"signal\" object. ARG must be a
+string and a member of the list returned by
+`dbus-introspect-get-argument-names'."
(let ((elt (xml-get-children
(or (dbus-introspect-get-method bus service path interface name)
(dbus-introspect-get-signal bus service path interface name))
@@ -1402,7 +1404,7 @@ dbus-introspect-get-argument
(defun dbus-introspect-get-signature
(bus service path interface name &optional direction)
- "Return signature of a `method' or `signal', represented by NAME, as string.
+ "Return signature of a `method' or `signal' represented by NAME as a string.
If NAME is a `method', DIRECTION can be either \"in\" or \"out\".
If DIRECTION is nil, \"in\" is assumed.
@@ -1450,9 +1452,8 @@ dbus-get-property
(defun dbus-set-property (bus service path interface property value)
"Set value of PROPERTY of INTERFACE to VALUE.
-It will be checked at BUS, SERVICE, PATH. When the value has
-been set successful, the result is VALUE. Otherwise, nil is
-returned."
+It will be checked at BUS, SERVICE, PATH. When the value is
+successfully set return VALUE. Otherwise, return nil."
(dbus-ignore-errors
;; "Set" requires a variant.
(dbus-call-method
@@ -1479,15 +1480,15 @@ dbus-get-all-properties
(defun dbus-register-property
(bus service path interface property access value
&optional emits-signal dont-register-service)
- "Register property PROPERTY on the D-Bus BUS.
+ "Register PROPERTY on the D-Bus BUS.
BUS is either a Lisp symbol, `: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).
+known name (see discussion of DONT-REGISTER-SERVICE below).
-PATH is the D-Bus object path SERVICE is registered (See
+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
@@ -1625,8 +1626,8 @@ dbus-get-all-managed-objects
"Return all objects at BUS, SERVICE, PATH, and the children of PATH.
The result is a list of objects. Every object is a cons of an
existing path name, and the list of available interface objects.
-An interface object is another cons, which car is the interface
-name, and the cdr is the list of properties as returned by
+An interface object is another cons, whose car is the interface
+name and cdr is the list of properties as returned by
`dbus-get-all-properties' for that path and interface. Example:
\(dbus-get-all-managed-objects :session \"org.gnome.SettingsDaemon\" \"/\")
@@ -1782,12 +1783,13 @@ dbus-init-bus
the system and session buses, this function is called when loading
`dbus.el', there is no need to call it again.
-The function returns a number, which counts the connections this Emacs
-session has established to the BUS under the same unique name (see
-`dbus-get-unique-name'). It depends on the libraries Emacs is linked
-with, and on the environment Emacs is running. For example, if Emacs
-is linked with the gtk toolkit, and it runs in a GTK-aware environment
-like Gnome, another connection might already be established.
+The function returns the number of connections this Emacs session
+has established to the BUS under the same unique name (see
+`dbus-get-unique-name'). It depends on the libraries Emacs is
+linked with, and on the environment Emacs is running. For
+example, if Emacs is linked with the GTK+ toolkit, and it runs in
+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.
--
2.26.2
[-- Attachment #3: Type: text/plain, Size: 48 bytes --]
And these implementation cleanups for master:
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #4: 0001-Various-dbus.el-cleanups.patch --]
[-- Type: text/x-diff, Size: 25746 bytes --]
From dad68bc11e6b0a64a733029804f88e0f18a5401c Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sat, 6 Jun 2020 13:20:06 +0100
Subject: [PATCH] Various dbus.el cleanups
* lisp/net/dbus.el: Remove unneeded dependency on cl-lib.el. Quote
function symbols as such.
(dbus-ignore-errors): Don't add macro name to font-lock keywords, as
emacs-lisp-mode now dynamically fontifies new macro definitions.
(dbus-call-method-non-blocking): Define as obosolete alias using
define-obsolete-function-alias.
(dbus-register-signal, dbus-escape-as-identifier): Simplify. Use
regexp \` and \' in place of ^ and $.
(dbus--parse-xml-buffer): New function for libxml2 compatibility.
(dbus-introspect-xml): Use it.
(dbus-string-to-byte-array, dbus-byte-array-to-string)
(dbus-unescape-from-identifier, dbus-list-known-names)
(dbus-introspect-get-all-nodes, dbus-get-all-properties)
(dbus-get-all-managed-objects): Simplify.
(dbus--introspect-names, dbus--introspect-name): New convenience
functions.
(dbus-introspect-get-node-names)
(dbus-introspect-get-interface-names)
(dbus-introspect-get-interface, dbus-introspect-get-method-names)
(dbus-introspect-get-method, dbus-introspect-get-signal-names)
(dbus-introspect-get-signal, dbus-introspect-get-property-names)
(dbus-introspect-get-property)
(dbus-introspect-get-annotation-names)
(dbus-introspect-get-annotation)
(dbus-introspect-get-argument-names, dbus-introspect-get-argument):
Use them to DRY.
* test/lisp/net/dbus-tests.el (dbus-test-all): Quote function
symbols as such.
---
lisp/net/dbus.el | 269 +++++++++++++++---------------------
test/lisp/net/dbus-tests.el | 4 +-
2 files changed, 111 insertions(+), 162 deletions(-)
diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 4538399c75..c882d1ae7a 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -51,9 +51,6 @@ dbus-registered-objects-table
(unless (boundp 'dbus-debug)
(defvar dbus-debug nil))
-;; Pacify byte compiler.
-(eval-when-compile (require 'cl-lib))
-
(require 'xml)
(defconst dbus-service-dbus "org.freedesktop.DBus"
@@ -169,7 +166,6 @@ dbus-ignore-errors
`(condition-case err
(progn ,@body)
(dbus-error (when dbus-debug (signal (car err) (cdr err))))))
-(font-lock-add-keywords 'emacs-lisp-mode '("\\<dbus-ignore-errors\\>"))
(define-obsolete-variable-alias 'dbus-event-error-hooks
'dbus-event-error-functions "24.3")
@@ -181,7 +177,7 @@ dbus-event-error-functions
\f
;;; Basic D-Bus message functions.
-(defvar dbus-return-values-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.
A key in this hash table is a list (:serial BUS SERIAL), like in
`dbus-registered-objects-table'. BUS is either a Lisp symbol,
@@ -301,8 +297,8 @@ dbus-call-method
(check-interval 0.001)
(key
(apply
- 'dbus-message-internal dbus-message-type-method-call
- bus service path interface method 'dbus-call-method-handler args))
+ #'dbus-message-internal dbus-message-type-method-call
+ bus service path interface method #'dbus-call-method-handler args))
(result (cons :pending nil)))
;; Wait until `dbus-call-method-handler' has put the result into
@@ -339,8 +335,8 @@ dbus-call-method
(remhash key dbus-return-values-table))))
;; `dbus-call-method' works non-blocking now.
-(defalias 'dbus-call-method-non-blocking 'dbus-call-method)
-(make-obsolete 'dbus-call-method-non-blocking 'dbus-call-method "24.3")
+(define-obsolete-function-alias 'dbus-call-method-non-blocking
+ #'dbus-call-method "24.3")
(defun dbus-call-method-asynchronously
(bus service path interface method handler &rest args)
@@ -406,7 +402,7 @@ dbus-call-method-asynchronously
(or (null handler) (functionp handler)
(signal 'wrong-type-argument (list 'functionp handler)))
- (apply 'dbus-message-internal dbus-message-type-method-call
+ (apply #'dbus-message-internal dbus-message-type-method-call
bus service path interface method handler args))
(defun dbus-send-signal (bus service path interface signal &rest args)
@@ -454,7 +450,7 @@ dbus-send-signal
(or (stringp signal)
(signal 'wrong-type-argument (list 'stringp signal)))
- (apply 'dbus-message-internal dbus-message-type-signal
+ (apply #'dbus-message-internal dbus-message-type-signal
bus service path interface signal args))
(defun dbus-method-return-internal (bus service serial &rest args)
@@ -470,7 +466,7 @@ dbus-method-return-internal
(or (natnump serial)
(signal 'wrong-type-argument (list 'natnump serial)))
- (apply 'dbus-message-internal dbus-message-type-method-return
+ (apply #'dbus-message-internal dbus-message-type-method-return
bus service serial args))
(defun dbus-method-error-internal (bus service serial &rest args)
@@ -486,7 +482,7 @@ dbus-method-error-internal
(or (natnump serial)
(signal 'wrong-type-argument (list 'natnump serial)))
- (apply 'dbus-message-internal dbus-message-type-error
+ (apply #'dbus-message-internal dbus-message-type-error
bus service serial args))
\f
@@ -552,13 +548,13 @@ dbus-register-service
`:already-owner': Service is already the primary owner."
;; Add Peer handler.
- (dbus-register-method
- bus service nil dbus-interface-peer "Ping" 'dbus-peer-handler 'dont-register)
+ (dbus-register-method bus service nil dbus-interface-peer "Ping"
+ #'dbus-peer-handler 'dont-register)
;; Add ObjectManager handler.
(dbus-register-method
bus service nil dbus-interface-objectmanager "GetManagedObjects"
- 'dbus-managed-objects-handler 'dont-register)
+ #'dbus-managed-objects-handler 'dont-register)
(let ((arg 0)
reply)
@@ -680,7 +676,7 @@ dbus-register-signal
(if (and (stringp service)
(not (zerop (length service)))
(not (string-equal service dbus-service-dbus))
- (not (string-match "^:" service)))
+ (/= (string-to-char service) ?:))
(setq uname (dbus-get-name-owner bus service))
(setq uname service))
@@ -709,7 +705,7 @@ dbus-register-signal
;; `:arg0' .. `:arg63', `:path0' .. `:path63'.
((and (keywordp key)
(string-match
- "^:\\(arg\\|path\\)\\([[:digit:]]+\\)$"
+ "\\`:\\(arg\\|path\\)\\([[:digit:]]+\\)\\'"
(symbol-name key)))
(setq counter (match-string 2 (symbol-name key))
args (cdr args)
@@ -725,9 +721,7 @@ dbus-register-signal
"path" "")
value))
;; `:arg-namespace', `:path-namespace'.
- ((and (keywordp key)
- (string-match
- "^:\\(arg\\|path\\)-namespace$" (symbol-name key)))
+ ((memq key '(:arg-namespace :path-namespace))
(setq args (cdr args)
value (car args))
(unless (stringp value)
@@ -735,8 +729,7 @@ dbus-register-signal
(list "Wrong argument" key value)))
(format
",%s='%s'"
- (if (string-equal (match-string 1 (symbol-name key)) "path")
- "path_namespace" "arg0namespace")
+ (if (eq key :path-namespace) "path_namespace" "arg0namespace")
value))
;; `:eavesdrop'.
((eq key :eavesdrop)
@@ -750,11 +743,11 @@ dbus-register-signal
bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
"AddMatch" rule)
(dbus-error
- (if (not (string-match "eavesdrop" rule))
+ (if (not (string-match-p "eavesdrop" rule))
(signal (car err) (cdr err))
;; The D-Bus spec says we shall fall back to a rule without eavesdrop.
(when dbus-debug (message "Removing eavesdrop from rule %s" rule))
- (setq rule (replace-regexp-in-string ",eavesdrop='true'" "" rule))
+ (setq rule (replace-regexp-in-string ",eavesdrop='true'" "" rule t t))
(dbus-call-method
bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
"AddMatch" rule))))
@@ -892,9 +885,7 @@ dbus-string-to-byte-array
STRING shall be UTF8 coded."
(if (zerop (length string))
'(:array :signature "y")
- (let (result)
- (dolist (elt (string-to-list string) (append '(:array) result))
- (setq result (append result (list :byte elt)))))))
+ (cons :array (mapcan (lambda (c) (list :byte c)) string))))
(defun dbus-byte-array-to-string (byte-array &optional multibyte)
"Transform BYTE-ARRAY into UTF8 coded string.
@@ -902,12 +893,9 @@ dbus-byte-array-to-string
array as produced by `dbus-string-to-byte-array'. The resulting
string is unibyte encoded, unless MULTIBYTE is non-nil."
(apply
- (if multibyte 'string 'unibyte-string)
- (if (equal byte-array '(:array :signature "y"))
- nil
- (let (result)
- (dolist (elt byte-array result)
- (when (characterp elt) (setq result (append result `(,elt)))))))))
+ (if multibyte #'string #'unibyte-string)
+ (unless (equal byte-array '(:array :signature "y"))
+ (seq-filter #'characterp byte-array))))
(defun dbus-escape-as-identifier (string)
"Escape an arbitrary STRING so it follows the rules for a C identifier.
@@ -929,9 +917,9 @@ dbus-escape-as-identifier
(if (zerop (length string))
"_"
(replace-regexp-in-string
- "^[0-9]\\|[^A-Za-z0-9]"
+ "\\`[0-9]\\|[^A-Za-z0-9]"
(lambda (x) (format "_%2x" (aref x 0)))
- string)))
+ string nil t)))
(defun dbus-unescape-from-identifier (string)
"Retrieve the original string from the encoded STRING as unibyte string.
@@ -941,7 +929,7 @@ dbus-unescape-from-identifier
(replace-regexp-in-string
"_.."
(lambda (x) (byte-to-string (string-to-number (substring x 1) 16)))
- string)))
+ string nil t)))
\f
;;; D-Bus events.
@@ -1019,7 +1007,7 @@ dbus-handle-event
(if (eq result :ignore)
(dbus-method-return-internal
(nth 1 event) (nth 4 event) (nth 3 event))
- (apply 'dbus-method-return-internal
+ (apply #'dbus-method-return-internal
(nth 1 event) (nth 4 event) (nth 3 event)
(if (consp result) result (list result)))))))
;; Error handling.
@@ -1119,10 +1107,9 @@ dbus-list-names
(defun dbus-list-known-names (bus)
"Retrieve all services which correspond to a known name in BUS.
A service has a known name if it doesn't start with \":\"."
- (let (result)
- (dolist (name (dbus-list-names bus) (nreverse result))
- (unless (string-equal ":" (substring name 0 1))
- (push name result)))))
+ (seq-remove (lambda (name)
+ (= (string-to-char name) ?:))
+ (dbus-list-names bus)))
(defun dbus-list-queued-owners (bus service)
"Return the unique names registered at D-Bus BUS and queued for SERVICE.
@@ -1182,6 +1169,18 @@ dbus-peer-handler
\f
;;; D-Bus introspection.
+(defsubst dbus--introspect-names (object tag)
+ "Return the names of the children of OBJECT with TAG."
+ (mapcar (lambda (elt)
+ (dbus-introspect-get-attribute elt "name"))
+ (xml-get-children object tag)))
+
+(defsubst dbus--introspect-name (object tag name)
+ "Return the first child of OBJECT with TAG, whose name is NAME."
+ (seq-find (lambda (elt)
+ (string-equal (dbus-introspect-get-attribute elt "name") name))
+ (xml-get-children object tag)))
+
(defun dbus-introspect (bus service path)
"Return all interfaces and sub-nodes of SERVICE,
registered at object path PATH at bus BUS.
@@ -1197,17 +1196,25 @@ dbus-introspect
bus service path dbus-interface-introspectable "Introspect"
:timeout 1000)))
+(defalias 'dbus--parse-xml-buffer
+ (if (libxml-available-p)
+ (lambda ()
+ (xml-remove-comments (point-min) (point-max))
+ (libxml-parse-xml-region (point-min) (point-max)))
+ (lambda ()
+ (car (xml-parse-region (point-min) (point-max)))))
+ "Compatibility shim for `libxml-parse-xml-region'.")
+
(defun dbus-introspect-xml (bus service path)
"Return the introspection data of SERVICE in D-Bus BUS at object path PATH.
The data are a parsed list. The root object is a \"node\",
representing the object path PATH. The root object can contain
\"interface\" and further \"node\" objects."
- ;; We don't want to raise errors.
- (xml-node-name
- (ignore-errors
- (with-temp-buffer
- (insert (dbus-introspect bus service path))
- (xml-parse-region (point-min) (point-max))))))
+ (with-temp-buffer
+ ;; We don't want to raise errors.
+ (ignore-errors
+ (insert (dbus-introspect bus service path))
+ (dbus--parse-xml-buffer))))
(defun dbus-introspect-get-attribute (object attribute)
"Return the ATTRIBUTE value of D-Bus introspection OBJECT.
@@ -1219,21 +1226,15 @@ dbus-introspect-get-node-names
"Return all node names of SERVICE in D-Bus BUS at object path PATH.
It returns a list of strings. The node names stand for further
object paths of the D-Bus service."
- (let ((object (dbus-introspect-xml bus service path))
- result)
- (dolist (elt (xml-get-children object 'node) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names (dbus-introspect-xml bus service path) 'node))
(defun dbus-introspect-get-all-nodes (bus service path)
"Return all node names of SERVICE in D-Bus BUS at object path PATH.
It returns a list of strings, which are further object paths of SERVICE."
- (let ((result (list path)))
- (dolist (elt
- (dbus-introspect-get-node-names bus service path)
- result)
- (setq elt (expand-file-name elt path))
- (setq result
- (append result (dbus-introspect-get-all-nodes bus service elt))))))
+ (cons path (mapcan (lambda (elt)
+ (setq elt (expand-file-name elt path))
+ (dbus-introspect-get-all-nodes bus service elt))
+ (dbus-introspect-get-node-names bus service path))))
(defun dbus-introspect-get-interface-names (bus service path)
"Return all interface names of SERVICE in D-Bus BUS at object path PATH.
@@ -1244,10 +1245,7 @@ dbus-introspect-get-interface-names
interface is \"org.freedesktop.DBus.Properties\". If present,
\"interface\" objects can also have \"property\" objects as
children, beside \"method\" and \"signal\" objects."
- (let ((object (dbus-introspect-xml bus service path))
- result)
- (dolist (elt (xml-get-children object 'interface) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names (dbus-introspect-xml bus service path) 'interface))
(defun dbus-introspect-get-interface (bus service path interface)
"Return the INTERFACE of SERVICE in D-Bus BUS at object path PATH.
@@ -1255,22 +1253,14 @@ dbus-introspect-get-interface
element of the list returned by `dbus-introspect-get-interface-names'.
The resulting \"interface\" object can contain \"method\", \"signal\",
\"property\" and \"annotation\" children."
- (let ((elt (xml-get-children
- (dbus-introspect-xml bus service path) 'interface)))
- (while (and elt
- (not (string-equal
- interface
- (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name (dbus-introspect-xml bus service path)
+ 'interface interface))
(defun dbus-introspect-get-method-names (bus service path interface)
"Return a list of strings of all method names of INTERFACE.
SERVICE is a service of D-Bus BUS at object path PATH."
- (let ((object (dbus-introspect-get-interface bus service path interface))
- result)
- (dolist (elt (xml-get-children object 'method) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names
+ (dbus-introspect-get-interface bus service path interface) 'method))
(defun dbus-introspect-get-method (bus service path interface method)
"Return method METHOD of interface INTERFACE as XML object.
@@ -1278,22 +1268,15 @@ dbus-introspect-get-method
METHOD must be a string, element of the list returned by
`dbus-introspect-get-method-names'. The resulting \"method\"
object can contain \"arg\" and \"annotation\" children."
- (let ((elt (xml-get-children
- (dbus-introspect-get-interface bus service path interface)
- 'method)))
- (while (and elt
- (not (string-equal
- method (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name
+ (dbus-introspect-get-interface bus service path interface)
+ 'method method))
(defun dbus-introspect-get-signal-names (bus service path interface)
"Return a list of strings of all signal names of INTERFACE.
SERVICE is a service of D-Bus BUS at object path PATH."
- (let ((object (dbus-introspect-get-interface bus service path interface))
- result)
- (dolist (elt (xml-get-children object 'signal) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names
+ (dbus-introspect-get-interface bus service path interface) 'signal))
(defun dbus-introspect-get-signal (bus service path interface signal)
"Return signal SIGNAL of interface INTERFACE as XML object.
@@ -1301,22 +1284,15 @@ dbus-introspect-get-signal
SIGNAL must be a string, element of the list returned by
`dbus-introspect-get-signal-names'. The resulting \"signal\"
object can contain \"arg\" and \"annotation\" children."
- (let ((elt (xml-get-children
- (dbus-introspect-get-interface bus service path interface)
- 'signal)))
- (while (and elt
- (not (string-equal
- signal (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name
+ (dbus-introspect-get-interface bus service path interface)
+ 'signal signal))
(defun dbus-introspect-get-property-names (bus service path interface)
"Return a list of strings of all property names of INTERFACE.
SERVICE is a service of D-Bus BUS at object path PATH."
- (let ((object (dbus-introspect-get-interface bus service path interface))
- result)
- (dolist (elt (xml-get-children object 'property) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names
+ (dbus-introspect-get-interface bus service path interface) 'property))
(defun dbus-introspect-get-property (bus service path interface property)
"Return PROPERTY of INTERFACE as XML object.
@@ -1324,15 +1300,9 @@ dbus-introspect-get-property
PROPERTY must be a string, element of the list returned by
`dbus-introspect-get-property-names'. The resulting PROPERTY
object can contain \"annotation\" children."
- (let ((elt (xml-get-children
- (dbus-introspect-get-interface bus service path interface)
- 'property)))
- (while (and elt
- (not (string-equal
- property
- (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name
+ (dbus-introspect-get-interface bus service path interface)
+ 'property property))
(defun dbus-introspect-get-annotation-names
(bus service path interface &optional name)
@@ -1340,15 +1310,13 @@ dbus-introspect-get-annotation-names
If NAME is nil, the annotations are children of INTERFACE,
otherwise NAME must be a \"method\", \"signal\", or \"property\"
object, where the annotations belong to."
- (let ((object
- (if name
- (or (dbus-introspect-get-method bus service path interface name)
- (dbus-introspect-get-signal bus service path interface name)
- (dbus-introspect-get-property bus service path interface name))
- (dbus-introspect-get-interface bus service path interface)))
- result)
- (dolist (elt (xml-get-children object 'annotation) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names
+ (if name
+ (or (dbus-introspect-get-method bus service path interface name)
+ (dbus-introspect-get-signal bus service path interface name)
+ (dbus-introspect-get-property bus service path interface name))
+ (dbus-introspect-get-interface bus service path interface))
+ 'annotation))
(defun dbus-introspect-get-annotation
(bus service path interface name annotation)
@@ -1356,22 +1324,13 @@ dbus-introspect-get-annotation
If NAME is nil, ANNOTATION is a child of INTERFACE, otherwise
NAME must be the name of a \"method\", \"signal\", or
\"property\" object, where the ANNOTATION belongs to."
- (let ((elt (xml-get-children
- (if name
- (or (dbus-introspect-get-method
- bus service path interface name)
- (dbus-introspect-get-signal
- bus service path interface name)
- (dbus-introspect-get-property
- bus service path interface name))
- (dbus-introspect-get-interface bus service path interface))
- 'annotation)))
- (while (and elt
- (not (string-equal
- annotation
- (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name
+ (if name
+ (or (dbus-introspect-get-method bus service path interface name)
+ (dbus-introspect-get-signal bus service path interface name)
+ (dbus-introspect-get-property bus service path interface name))
+ (dbus-introspect-get-interface bus service path interface))
+ 'annotation annotation))
(defun dbus-introspect-get-argument-names (bus service path interface name)
"Return a list of all argument names as list of strings.
@@ -1379,26 +1338,19 @@ dbus-introspect-get-argument-names
Argument names are optional, the function can return nil
therefore, even if the method or signal has arguments."
- (let ((object
- (or (dbus-introspect-get-method bus service path interface name)
- (dbus-introspect-get-signal bus service path interface name)))
- result)
- (dolist (elt (xml-get-children object 'arg) (nreverse result))
- (push (dbus-introspect-get-attribute elt "name") result))))
+ (dbus--introspect-names
+ (or (dbus-introspect-get-method bus service path interface name)
+ (dbus-introspect-get-signal bus service path interface name))
+ 'arg))
(defun dbus-introspect-get-argument (bus service path interface name arg)
"Return argument ARG as XML object.
NAME must be a \"method\" or \"signal\" object. ARG must be a string,
element of the list returned by `dbus-introspect-get-argument-names'."
- (let ((elt (xml-get-children
- (or (dbus-introspect-get-method bus service path interface name)
- (dbus-introspect-get-signal bus service path interface name))
- 'arg)))
- (while (and elt
- (not (string-equal
- arg (dbus-introspect-get-attribute (car elt) "name"))))
- (setq elt (cdr elt)))
- (car elt)))
+ (dbus--introspect-name
+ (or (dbus-introspect-get-method bus service path interface name)
+ (dbus-introspect-get-signal bus service path interface name))
+ 'arg arg))
(defun dbus-introspect-get-signature
(bus service path interface name &optional direction)
@@ -1468,13 +1420,10 @@ dbus-get-all-properties
nil is returned."
(dbus-ignore-errors
;; "GetAll" returns "a{sv}".
- (let (result)
- (dolist (dict
- (dbus-call-method
- bus service path dbus-interface-properties
- "GetAll" :timeout 500 interface)
- (nreverse result))
- (push (cons (car dict) (cl-caadr dict)) result)))))
+ (mapcar (lambda (dict)
+ (cons (car dict) (caadr dict)))
+ (dbus-call-method bus service path dbus-interface-properties
+ "GetAll" :timeout 500 interface))))
(defun dbus-register-property
(bus service path interface property access value
@@ -1519,13 +1468,13 @@ dbus-register-property
;; Add handlers for the three property-related methods.
(dbus-register-method
bus service path dbus-interface-properties "Get"
- 'dbus-property-handler 'dont-register)
+ #'dbus-property-handler 'dont-register)
(dbus-register-method
bus service path dbus-interface-properties "GetAll"
- 'dbus-property-handler 'dont-register)
+ #'dbus-property-handler 'dont-register)
(dbus-register-method
bus service path dbus-interface-properties "Set"
- 'dbus-property-handler 'dont-register)
+ #'dbus-property-handler 'dont-register)
;; Register SERVICE.
(unless (or dont-register-service (member service (dbus-list-names bus)))
@@ -1672,7 +1621,7 @@ dbus-get-all-managed-objects
(if (cadr entry2)
;; "sv".
(dolist (entry3 (cadr entry2))
- (setcdr entry3 (cl-caadr entry3)))
+ (setcdr entry3 (caadr entry3)))
(setcdr entry2 nil)))))
;; Fallback: collect the information. Slooow!
@@ -1729,7 +1678,7 @@ dbus-managed-objects-handler
(append
(butlast last-input-event 4)
(list object dbus-interface-properties
- "GetAll" 'dbus-property-handler))))
+ "GetAll" #'dbus-property-handler))))
(dbus-property-handler interface))))
(cdr (assoc object result)))))))))
dbus-registered-objects-table)
diff --git a/test/lisp/net/dbus-tests.el b/test/lisp/net/dbus-tests.el
index e263c4563f..45c9851365 100644
--- a/test/lisp/net/dbus-tests.el
+++ b/test/lisp/net/dbus-tests.el
@@ -176,8 +176,8 @@ dbus-test03-peer-interface
(defun dbus-test-all (&optional interactive)
"Run all tests for \\[dbus]."
(interactive "p")
- (funcall
- (if interactive 'ert-run-tests-interactively 'ert-run-tests-batch) "^dbus"))
+ (funcall (if interactive #'ert-run-tests-interactively #'ert-run-tests-batch)
+ "^dbus"))
(provide 'dbus-tests)
;;; dbus-tests.el ends here
--
2.26.2
[-- Attachment #5: Type: text/plain, Size: 919 bytes --]
Are these changes acceptable? WDYT?
Thanks,
--
Basil
In GNU Emacs 27.0.91 (build 12, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
of 2020-06-06 built on thunk
Repository revision: c1f4c0bc839324d2049ae45a74381684a5727f60
Repository branch: blc/27/dbus
Windowing system distributor 'The X.Org Foundation', version 11.0.12008000
System Description: Debian GNU/Linux bullseye/sid
Configured using:
'configure 'CC=ccache gcc' 'CFLAGS=-O0 -g3 -ggdb -gdwarf-4'
--config-cache --prefix=/home/blc/.local --program-suffix=27
--enable-checking=yes,glyphs --enable-check-lisp-object-type
--with-x-toolkit=lucid --with-file-notification=yes --with-x'
Configured features:
XAW3D XPM JPEG TIFF GIF PNG RSVG SOUND GPM DBUS GSETTINGS GLIB NOTIFY
INOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE HARFBUZZ M17N_FLT LIBOTF
XFT ZLIB TOOLKIT_SCROLL_BARS LUCID X11 XDBE XIM MODULES THREADS
LIBSYSTEMD JSON PDUMPER LCMS2 GMP
next reply other threads:[~2020-06-06 23:26 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-06-06 23:26 Basil L. Contovounesios [this message]
2020-06-08 11:06 ` bug#41744: 27.0.91; Various D-Bus cleanups Michael Albinus
2020-06-08 14:00 ` Basil L. Contovounesios
2020-06-08 14:20 ` Michael Albinus
2020-06-08 14:48 ` Eli Zaretskii
2020-06-08 14:52 ` Michael Albinus
2020-06-08 17:28 ` Basil L. Contovounesios
2020-06-17 20:08 ` Basil L. Contovounesios
2020-06-18 9:59 ` Michael Albinus
2020-06-18 15:34 ` Basil L. Contovounesios
2020-06-18 16:59 ` Michael Albinus
2020-06-18 17:05 ` Basil L. Contovounesios
2020-06-18 18:02 ` Michael Albinus
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87mu5fpyh1.fsf@tcd.ie \
--to=contovob@tcd.ie \
--cc=41744@debbugs.gnu.org \
--cc=michael.albinus@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).