[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-27 43ad7dc: Clean up D-Bus documentation (bug#41744)
|
From: |
Basil L. Contovounesios |
|
Subject: |
emacs-27 43ad7dc: Clean up D-Bus documentation (bug#41744) |
|
Date: |
Mon, 8 Jun 2020 13:24:50 -0400 (EDT) |
branch: emacs-27
commit 43ad7dc1af327486963e5e3a3ae8efdb454fd38d
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>
Clean up D-Bus documentation (bug#41744)
* 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 | 826 ++++++++++++++++++++++++------------------------
lisp/net/dbus.el | 228 ++++++-------
3 files changed, 531 insertions(+), 528 deletions(-)
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index dc6877c..cd8694b 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -79,9 +79,8 @@ The message is @samp{Symbol's chain of variable indirections
contains
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 9e5f1cc..167d2bd 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -167,7 +167,7 @@ default) or the symbol @code{:session}. An activatable
service is
described in a service registration file. Under GNU/Linux, such files
are located at @file{/usr/share/dbus-1/system-services/} (for the
@code{:system} bus) or @file{/usr/share/dbus-1/services/}. An
-activatable service is not necessarily registered at @var{bus} 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 @@ activatable service names at all. Example:
@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 @@ strings like @samp{org.freedesktop.DBus}. Names starting
with
@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 @@ known names at all.
@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 @@ string.
@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 @@ string.
@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 @@ without autostarting it, one shall apply
@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 @@ format. Example:
@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,46 +423,51 @@ the HAL specification}.}
@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"))
- (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")))
- )
- @dots{}
- (signal ((name . "HitsAdded"))
- (arg ((name . "search") (type . "s")))
- (arg ((name . "count") (type . "u")))
- )
- )
- @dots{}
- )
+ (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"))))
+ @dots{}
+ (signal ((name . "HitsAdded"))
+ (arg ((name . "search") (type . "s")))
+ (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 +484,12 @@ The first elements, to be introspected for a D-Bus
object, are further
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 +520,10 @@ Example:
@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 +531,8 @@ children. Example:
@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 +542,27 @@ children. Example:
@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 +571,8 @@ With these functions, it is possible to retrieve all
introspection
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 +581,7 @@ data from a running system:
(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 +594,15 @@ Methods and signals are the communication means to D-Bus.
The
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 +611,36 @@ Return a list of strings of all method names of
@var{interface} of
@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 +648,21 @@ Return a list of strings of all signal names of
@var{interface} of
@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 +673,8 @@ returned by @code{dbus-introspect-get-signal-names}.
Example:
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 +687,14 @@ Often, they are used to instruct generators, how to
generate code from
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 +704,26 @@ also the @samp{org.freedesktop.DBus.Properties} interface.
@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 +737,23 @@ result can be any valid D-Bus value, or @code{nil} if
there is no
@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 +767,8 @@ If there are no properties, @code{nil} is returned.
Example:
@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 +783,13 @@ This function returns all objects at @var{bus},
@var{service},
@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 +819,28 @@ An overview of all existing object paths, their
interfaces and
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 +862,30 @@ If set, don't expect a reply to the @code{method} call;
defaults to @code{nil}
@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 +899,41 @@ Methods and signals have arguments. They are described
in the
@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 +944,16 @@ non-@code{nil}, @var{direction} must be @samp{out}.
Example:
@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 +1008,27 @@ types are represented by the type symbols @code{:byte},
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 +1043,13 @@ D-Bus compound type rules.
@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 +1059,27 @@ elements of this array. Example:
@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 +1090,10 @@ UTF8 string, this function performs the conversion.
Example:
@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 +1114,18 @@ Output parameters of D-Bus methods and signals are
mapped to Lisp
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 +1137,21 @@ objects.
@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 +1163,9 @@ to the corresponding string. The string is unibyte
encoded, unless
@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 +1179,9 @@ that string:
@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 +1198,13 @@ that string:
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 +1213,14 @@ D-Bus object path, @var{service} is registered at.
@var{interface} is
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 +1228,9 @@ Lisp objects, according to the type conversion rules
described in
@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 +1241,10 @@ object. Example:
@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 +1260,17 @@ emulate the @code{lshal} command on GNU/Linux systems:
@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 +1307,35 @@ D-Bus object path, @var{service} is registered at.
@var{interface} is
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 +1351,8 @@ clients. Names on the D-Bus can be registered and
unregistered using
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 +1362,33 @@ must be a known name.
@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 +1399,27 @@ D-Bus.
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 +1441,10 @@ With this function, an application registers
@var{method} on the D-Bus
@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 +1461,8 @@ If @var{handler} wants to return just one Lisp object and
it is not a
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 +1473,7 @@ clients from discovering the still incomplete interface.
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 +1482,14 @@ registration for @var{method}. Example:
@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 +1497,9 @@ registration for @var{method}. Example:
@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 +1523,9 @@ You can indicate an error by raising the Emacs signal
(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 +1549,7 @@ With this function, an application declares a
@var{property} on the D-Bus
@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 +1558,7 @@ discussion of @var{dont-register-service} below).
@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 +1583,15 @@ clients from discovering the still incomplete interface.
@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 +1622,28 @@ possible via the command line tool @code{dbus-send} in
a shell:
]
@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 +1671,22 @@ doesn't matter whether another object has registered
for @var{signal}.
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 +1701,11 @@ With this function, an application registers for a
signal on the D-Bus
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 +1720,31 @@ The remaining arguments @var{args} can be keywords or
keyword string
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:
-
-@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.
-
-@item @code{:arg-namespace} @var{string}:@*
-Register for the signals, which first argument defines the service or
-interface namespace @var{string}.
-
-@item @code{:path-namespace} @var{string}:@*
+@code{nil} argument might be used to preserve the order.} Their
+meaning is as follows:
+
+@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 :arg-namespace @var{string}
+Register for those signals, whose first argument names a service or
+interface within the 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 +1754,10 @@ registration for @var{signal}. Example:
(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 +1767,8 @@ registration for @var{signal}. Example:
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 +1779,7 @@ for a dummy signal, and check the result:
@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 +1794,14 @@ for a dummy signal, and check the result:
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 +1809,12 @@ corresponding bus. For the system and session buses,
this function
is called when loading @file{dbus.el}, there is no need to call it
again.
-The function returns 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 +1829,9 @@ Example: You initialize a connection to the AT-SPI bus on
your host:
@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 +1846,7 @@ Example: You initialize a connection to the AT-SPI bus on
your host:
@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 +1857,14 @@ Example: You initialize a connection to the AT-SPI bus
on your host:
@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 +1875,7 @@ function adds to or modifies that environment when
activating services.
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 +1914,7 @@ Input parameters of @code{dbus-call-method},
@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 +1965,39 @@ There exist convenience functions which could be called
inside a
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 +2011,7 @@ D-Bus error happens in the event handler. Every function
must accept
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 +2021,12 @@ Example:
(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 4538399..06bd9e5 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -182,7 +182,7 @@ caught in `condition-case' by `dbus-error'.")
;;; 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 @@ SERVICE is the D-Bus service name to be used. PATH is
the D-Bus
object path SERVICE is registered at. INTERFACE is an interface
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 @@ Lisp objects. The type conversion happens the other
direction as for
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 @@ input arguments. It follows the mapping rules:
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 @@ If the result of the METHOD call is just one value, the
converted Lisp
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 @@ HANDLER is a Lisp function, which is called when the
corresponding
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 @@ type symbols, see Info node `(dbus)Type Conversion'.
If HANDLER is a Lisp function, the function returns a key into the
hash table `dbus-registered-objects-table'. The corresponding entry
-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 @@ type symbols, see Info node `(dbus)Type Conversion'.
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 @@ SERVICE is the D-Bus service name used by the sending
D-Bus object.
It can be either a known name or the unique name of the D-Bus object
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 @@ signal. `:pathN' arguments can be used for object path
wildcard
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 @@ Example:
(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 @@ Example:
(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 @@ association to the service from D-Bus."
;;; 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 @@ STRING shall be UTF8 coded."
(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 @@ lower-case hex digits:
\"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 @@ the function which has been registered for this message.
ARGS
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 @@ If the HANDLER returns a `dbus-error', it is propagated
as return message."
"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 @@ in case the event is not well formed."
"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 @@ well formed."
;;; 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 @@ A service has a known name if it doesn't start with
\":\"."
(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 @@ The result is either a string, or nil if there is no
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 @@ It returns a list of strings, which are further object
paths of SERVICE."
"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 @@ children, beside \"method\" and \"signal\" objects."
(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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
(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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
(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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
(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 @@ object can contain \"annotation\" children."
(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 @@ object, where the annotations belong to."
(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 @@ NAME must be the name of a \"method\", \"signal\", or
(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 @@ therefore, even if the method or signal has arguments."
(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 @@ element of the list returned by
`dbus-introspect-get-argument-names'."
(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 @@ valid D-Bus value, or nil if there is no 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 @@ nil is returned."
(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 @@ It will be registered for all objects created by
`dbus-register-property'."
"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 @@ can be a string denoting the address of the
corresponding bus. For
the system and session buses, this function is called when loading
`dbus.el', there is no need to call it again.
-The function returns 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.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-27 43ad7dc: Clean up D-Bus documentation (bug#41744),
Basil L. Contovounesios <=