diff options
| -rw-r--r-- | doc/lispref/errors.texi | 5 | ||||
| -rw-r--r-- | doc/misc/dbus.texi | 826 | ||||
| -rw-r--r-- | 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 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. diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el index 4538399c751..06bd9e567fe 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. |