diff options
author | Basil L. Contovounesios <contovob@tcd.ie> | 2020-06-06 00:58:37 +0100 |
---|---|---|
committer | Basil L. Contovounesios <contovob@tcd.ie> | 2020-06-08 18:19:50 +0100 |
commit | 43ad7dc1af327486963e5e3a3ae8efdb454fd38d (patch) | |
tree | f070853bb6c91f94d87a6b461a2d40fc26556c6f /doc | |
parent | c43e5ed60d93bbe3f5f3936ccce6e77409cd6140 (diff) | |
download | emacs-43ad7dc1af327486963e5e3a3ae8efdb454fd38d.tar.gz |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/lispref/errors.texi | 5 | ||||
-rw-r--r-- | doc/misc/dbus.texi | 826 |
2 files changed, 416 insertions, 415 deletions
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index dc6877c9eca..cd8694be8a3 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 9e5f1ccc6fd..167d2bd5ac1 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. |