>From 962f2af23a0d71638e14bb143de866862d51d0d2 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Sat, 6 Jun 2020 00:58:37 +0100 Subject: [PATCH] Clean up D-Bus documentation * doc/lispref/errors.texi (Standard Errors): The error symbol dbus-error is defined even when Emacs is built without D-Bus. * doc/misc/dbus.texi (Bus Names, Introspection) (Nodes and Interfaces, Methods and Signal) (Properties and Annotations, Arguments and Signatures) (Synchronous Methods, Receiving Method Calls, Signals) (Alternative Buses, Errors and Events): Clarify wording. Fix indentation of and simplify examples where possible. Improve Texinfo markup and cross-referencing where possible. (Type Conversion): Ditto. Remove mentions of Emacs' fixnum range now that we have bignums. * lisp/net/dbus.el (dbus-return-values-table) (dbus-call-method-asynchronously, dbus-send-signal) (dbus-register-signal, dbus-register-method) (dbus-string-to-byte-array, dbus-byte-array-to-string) (dbus-escape-as-identifier, dbus-check-event, dbus-event-bus-name) (dbus-event-message-type, dbus-event-serial-number) (dbus-event-service-name, dbus-event-path-name) (dbus-event-interface-name, dbus-event-member-name) (dbus-list-activatable-names, dbus-list-queued-owners, dbus-ping) (dbus-introspect-get-interface-names, dbus-introspect-get-interface) (dbus-introspect-get-method, dbus-introspect-get-signal) (dbus-introspect-get-property, dbus-introspect-get-annotation-names) (dbus-introspect-get-annotation, dbus-introspect-get-argument-names) (dbus-introspect-get-argument, dbus-introspect-get-signature) (dbus-set-property, dbus-register-property) (dbus-get-all-managed-objects, dbus-init-bus): Clarify docstring and improve formatting where possible. (dbus-call-method): Ditto. Remove mentions of Emacs' fixnum range now that we have bignums. --- doc/lispref/errors.texi | 5 +- doc/misc/dbus.texi | 795 ++++++++++++++++++++-------------------- lisp/net/dbus.el | 228 ++++++------ 3 files changed, 511 insertions(+), 517 deletions(-) diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index dc6877c9ec..cd8694be8a 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -79,9 +79,8 @@ Standard Errors a loop}. @xref{Variable Aliases}. @item dbus-error -The message is @samp{D-Bus error}. This is only defined if Emacs was -compiled with D-Bus support. @xref{Errors and Events,,, dbus, D-Bus -integration in Emacs}. +The message is @samp{D-Bus error}. @xref{Errors and Events,,, dbus, +D-Bus integration in Emacs}. @item end-of-buffer The message is @samp{End of buffer}. @xref{Character Motion}. diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 9e5f1ccc6f..eaf77ffa8f 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -167,7 +167,7 @@ Bus names described in a service registration file. Under GNU/Linux, such files are located at @file{/usr/share/dbus-1/system-services/} (for the @code{:system} bus) or @file{/usr/share/dbus-1/services/}. An -activatable service is not necessarily registered at @var{bus} at already. +activatable service is not necessarily registered at @var{bus} already. The result is a list of strings, which is @code{nil} when there are no activatable service names at all. Example: @@ -180,8 +180,8 @@ Bus names @end defun @defun dbus-list-names bus -All service names, which are registered at D-Bus @var{bus}, are -returned. The result is a list of strings, which is @code{nil} when +This function returns all service names, which are registered at D-Bus +@var{bus}. The result is a list of strings, which is @code{nil} when there are no registered service names at all. Well known names are strings like @samp{org.freedesktop.DBus}. Names starting with @samp{:} are unique names for services. @@ -191,10 +191,10 @@ Bus names @end defun @defun dbus-list-known-names bus -Retrieves all registered services which correspond to a known name in @var{bus}. -A service has a known name if it doesn't start with @samp{:}. The -result is a list of strings, which is @code{nil} when there are no -known names at all. +This function retrieves all registered services which correspond to a +known name in @var{bus}. A service has a known name if it doesn't +start with @samp{:}. The result is a list of strings, which is +@code{nil} when there are no known names at all. @var{bus} must be either the symbol @code{:system} or the symbol @code{:session}. @@ -202,9 +202,9 @@ Bus names @defun dbus-list-queued-owners bus service For a given service, registered at D-Bus @var{bus} under the name -@var{service}, all queued unique names are returned. The result is a -list of strings, or @code{nil} when there are no queued names for -@var{service} at all. +@var{service}, this function returns all queued unique names. The +result is a list of strings, or @code{nil} when there are no queued +names for @var{service} at all. @var{bus} must be either the symbol @code{:system} or the symbol @code{:session}. @var{service} must be a known service name as @@ -213,9 +213,9 @@ Bus names @defun dbus-get-name-owner bus service For a given service, registered at D-Bus @var{bus} under the name -@var{service}, the unique name of the name owner is returned. The -result is a string, or @code{nil} when there exist no name owner of -@var{service}. +@var{service}, this function returns the unique name of the name +owner. The result is a string, or @code{nil} when there is no name +owner of @var{service}. @var{bus} must be either the symbol @code{:system} or the symbol @code{:session}. @var{service} must be a known service name as @@ -223,26 +223,28 @@ Bus names @end defun @defun dbus-ping bus service &optional timeout -Check whether the service name @var{service} is registered at D-Bus -@var{bus}. @var{service} might not have been started yet, it is -autostarted if possible. The result is either @code{t} or @code{nil}. +This function checks whether the service name @var{service} is +registered at D-Bus @var{bus}. If @var{service} has not yet started, +it is autostarted if possible. The result is either @code{t} or +@code{nil}. @var{bus} must be either the symbol @code{:system} or the symbol @code{:session}. @var{service} must be a string. @var{timeout}, a nonnegative integer, specifies the maximum number of milliseconds -@code{dbus-ping} must return. The default value is 25,000. Example: +before @code{dbus-ping} must return. The default value is 25,000. +Example: @lisp (message - "%s screensaver on board." - (cond - ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome") - ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE") - (t "No"))) + "%s screensaver on board." + (cond + ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome") + ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE") + (t "No"))) @end lisp -If it shall be checked whether @var{service} is already running -without autostarting it, one shall apply +To check whether @var{service} is already running without autostarting +it, you can instead write: @lisp (member service (dbus-list-known-names bus)) @@ -250,8 +252,9 @@ Bus names @end defun @defun dbus-get-unique-name bus -The unique name, under which Emacs is registered at D-Bus @var{bus}, -is returned as string. +@anchor{dbus-get-unique-name} +This function returns the unique name, under which Emacs is registered +at D-Bus @var{bus}, as a string. @var{bus} must be either the symbol @code{:system} or the symbol @code{:session}. @@ -380,8 +383,8 @@ Introspection @lisp (dbus-introspect - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") + :system "org.freedesktop.Hal" + "/org/freedesktop/Hal/devices/computer") @result{} " t or nil - DBUS_TYPE_BYTE => number - DBUS_TYPE_UINT16 => number + DBUS_TYPE_BYTE => natural number + DBUS_TYPE_UINT16 => natural number DBUS_TYPE_INT16 => integer - DBUS_TYPE_UINT32 => number or float - DBUS_TYPE_UNIX_FD => number or float - DBUS_TYPE_INT32 => integer or float - DBUS_TYPE_UINT64 => number or float - DBUS_TYPE_INT64 => integer or float + DBUS_TYPE_UINT32 => natural number + DBUS_TYPE_UNIX_FD => natural number + DBUS_TYPE_INT32 => integer + DBUS_TYPE_UINT64 => natural number + DBUS_TYPE_INT64 => integer DBUS_TYPE_DOUBLE => float DBUS_TYPE_STRING => string DBUS_TYPE_OBJECT_PATH => string @@ -268,9 +268,9 @@ dbus-call-method Example: \(dbus-call-method - :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\" - \"org.gnome.seahorse.Keys\" \"GetKeyField\" - \"openpgp:657984B8C7A966DD\" \"simple-name\") + :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\" + \"org.gnome.seahorse.Keys\" \"GetKeyField\" + \"openpgp:657984B8C7A966DD\" \"simple-name\") => (t (\"Philip R. Zimmermann\")) @@ -278,9 +278,9 @@ dbus-call-method object is returned instead of a list containing this single Lisp object. \(dbus-call-method - :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\" - \"org.freedesktop.Hal.Device\" \"GetPropertyString\" - \"system.kernel.machine\") + :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\" + \"org.freedesktop.Hal.Device\" \"GetPropertyString\" + \"system.kernel.machine\") => \"i686\"" @@ -357,10 +357,10 @@ dbus-call-method-asynchronously return message has arrived. If HANDLER is nil, no return message will be expected. -If the parameter `:timeout' is given, the following integer TIMEOUT -specifies the maximum number of milliseconds the method call must -return. The default value is 25,000. If the method call doesn't -return in time, a D-Bus error is raised. +If the parameter `:timeout' is given, the following integer +TIMEOUT specifies the maximum number of milliseconds before the +method call must return. The default value is 25,000. If the +method call doesn't return in time, a D-Bus error is raised. All other arguments ARGS are passed to METHOD as arguments. They are converted into D-Bus types via the following rules: @@ -377,19 +377,19 @@ dbus-call-method-asynchronously If HANDLER is a Lisp function, the function returns a key into the hash table `dbus-registered-objects-table'. The corresponding entry -in the hash table is removed, when the return message has been arrived, +in the hash table is removed, when the return message arrives, and HANDLER is called. Example: \(dbus-call-method-asynchronously - :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\" - \"org.freedesktop.Hal.Device\" \"GetPropertyString\" \\='message - \"system.kernel.machine\") + :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\" + \"org.freedesktop.Hal.Device\" \"GetPropertyString\" \\='message + \"system.kernel.machine\") - => (:serial :system 2) + -| i686 - -| i686" + => (:serial :system 2)" (or (featurep 'dbusbind) (signal 'dbus-error (list "Emacs not compiled with dbus support"))) @@ -438,8 +438,8 @@ dbus-send-signal Example: \(dbus-send-signal - :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\" - \"FileModified\" \"/home/albinus/.emacs\")" + :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\" + \"FileModified\" \"/home/albinus/.emacs\")" (or (featurep 'dbusbind) (signal 'dbus-error (list "Emacs not compiled with dbus support"))) @@ -625,17 +625,17 @@ dbus-register-signal It can be either a known name or the unique name of the D-Bus object sending the signal. -PATH is the D-Bus object path SERVICE is registered. INTERFACE -is an interface offered by SERVICE. It must provide SIGNAL. -HANDLER is a Lisp function to be called when the signal is -received. It must accept as arguments the values SIGNAL is +PATH is the D-Bus object path SERVICE is registered at. +INTERFACE is an interface offered by SERVICE. It must provide +SIGNAL. HANDLER is a Lisp function to be called when the signal +is received. It must accept as arguments the values SIGNAL is sending. SERVICE, PATH, INTERFACE and SIGNAL can be nil. This is interpreted as a wildcard for the respective argument. The remaining arguments ARGS can be keywords or keyword string pairs. -The meaning is as follows: +Their meaning is as follows: `:argN' STRING: `:pathN' STRING: This stands for the Nth argument of the @@ -643,8 +643,9 @@ dbus-register-signal matches as specified by D-Bus, while an `:argN' argument requires an exact match. -`:arg-namespace' STRING: Register for the signals, which first -argument defines the service or interface namespace STRING. +`:arg-namespace' STRING: Register for those signals, whose first +argument names a service or interface within the namespace +STRING. `:path-namespace' STRING: Register for the object path namespace STRING. All signals sent from an object path, which has STRING as @@ -660,8 +661,8 @@ dbus-register-signal (message \"Device %s added\" device)) \(dbus-register-signal - :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\" - \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler) + :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\" + \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler) => ((:signal :system \"org.freedesktop.Hal.Manager\" \"DeviceAdded\") (\"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\" my-signal-handler)) @@ -773,24 +774,24 @@ dbus-register-signal (defun dbus-register-method (bus service path interface method handler &optional dont-register-service) - "Register for method METHOD on the D-Bus BUS. + "Register METHOD on the D-Bus BUS. BUS is either a Lisp symbol, `:system' or `:session', or a string denoting the bus address. SERVICE is the D-Bus service name of the D-Bus object METHOD is -registered for. It must be a known name (See discussion of +registered for. It must be a known name (see discussion of DONT-REGISTER-SERVICE below). -PATH is the D-Bus object path SERVICE is registered (See discussion of -DONT-REGISTER-SERVICE below). INTERFACE is the interface offered by -SERVICE. It must provide METHOD. +PATH is the D-Bus object path SERVICE is registered at (see +discussion of DONT-REGISTER-SERVICE below). INTERFACE is the +interface offered by SERVICE. It must provide METHOD. HANDLER is a Lisp function to be called when a method call is received. It must accept the input arguments of METHOD. The return value of HANDLER is used for composing the returning D-Bus message. -In case HANDLER shall return a reply message with an empty argument -list, HANDLER must return the symbol `:ignore'. +If HANDLER returns a reply message with an empty argument list, +HANDLER must return the symbol `:ignore'. When DONT-REGISTER-SERVICE is non-nil, the known name SERVICE is not registered. This means that other D-Bus clients have no way of @@ -888,8 +889,8 @@ dbus-unregister-object ;;; D-Bus type conversion. (defun dbus-string-to-byte-array (string) - "Transform STRING to list (:array :byte c1 :byte c2 ...). -STRING shall be UTF8 coded." + "Transform STRING to list (:array :byte C1 :byte C2 ...). +STRING shall be UTF-8 coded." (if (zerop (length string)) '(:array :signature "y") (let (result) @@ -897,7 +898,7 @@ dbus-string-to-byte-array (setq result (append result (list :byte elt))))))) (defun dbus-byte-array-to-string (byte-array &optional multibyte) - "Transform BYTE-ARRAY into UTF8 coded string. + "Transform BYTE-ARRAY into UTF-8 coded string. BYTE-ARRAY must be a list of structure (c1 c2 ...), or a byte array as produced by `dbus-string-to-byte-array'. The resulting string is unibyte encoded, unless MULTIBYTE is non-nil." @@ -920,9 +921,9 @@ dbus-escape-as-identifier \"0123abc_xyz\\x01\\xff\" -> \"_30123abc_5fxyz_01_ff\" -i.e. similar to URI encoding, but with \"_\" taking the role of \"%\", -and a smaller allowed set. As a special case, \"\" is escaped to -\"_\". +i.e. similar to URI encoding, but with \"_\" taking the role of +\"%\", and a smaller allowed set. As a special case, \"\" is +escaped to \"_\". Returns the escaped string. Algorithm taken from telepathy-glib's `tp_escape_as_identifier'." @@ -963,8 +964,8 @@ dbus-check-event are the arguments passed to HANDLER, when it is called during event handling in `dbus-handle-event'. -This function raises a `dbus-error' signal in case the event is -not well formed." +This function signals a `dbus-error' if the event is not well +formed." (when dbus-debug (message "DBus-Event %s" event)) (unless (and (listp event) (eq (car event) 'dbus-event) @@ -1038,16 +1039,16 @@ dbus-event-bus-name "Return the bus name the event is coming from. The result is either a Lisp symbol, `:system' or `:session', or a string denoting the bus address. EVENT is a D-Bus event, see -`dbus-check-event'. This function raises a `dbus-error' signal -in case the event is not well formed." +`dbus-check-event'. This function signals a `dbus-error' if the +event is not well formed." (dbus-check-event event) (nth 1 event)) (defun dbus-event-message-type (event) "Return the message type of the corresponding D-Bus message. The result is a number. EVENT is a D-Bus event, see -`dbus-check-event'. This function raises a `dbus-error' signal -in case the event is not well formed." +`dbus-check-event'. This function signals a `dbus-error' if the +event is not well formed." (dbus-check-event event) (nth 2 event)) @@ -1055,41 +1056,40 @@ dbus-event-serial-number "Return the serial number of the corresponding D-Bus message. The result is a number. The serial number is needed for generating a reply message. EVENT is a D-Bus event, see -`dbus-check-event'. This function raises a `dbus-error' signal -in case the event is not well formed." +`dbus-check-event'. This function signals a `dbus-error' if the +event is not well formed." (dbus-check-event event) (nth 3 event)) (defun dbus-event-service-name (event) "Return the name of the D-Bus object the event is coming from. The result is a string. EVENT is a D-Bus event, see `dbus-check-event'. -This function raises a `dbus-error' signal in case the event is -not well formed." +This function signals a `dbus-error' if the event is not well +formed." (dbus-check-event event) (nth 4 event)) (defun dbus-event-path-name (event) "Return the object path of the D-Bus object the event is coming from. The result is a string. EVENT is a D-Bus event, see `dbus-check-event'. -This function raises a `dbus-error' signal in case the event is -not well formed." +This function signals a `dbus-error' if the event is not well +formed." (dbus-check-event event) (nth 5 event)) (defun dbus-event-interface-name (event) "Return the interface name of the D-Bus object the event is coming from. The result is a string. EVENT is a D-Bus event, see `dbus-check-event'. -This function raises a `dbus-error' signal in case the event is -not well formed." +This function signals a `dbus-error' if the event is not well +formed." (dbus-check-event event) (nth 6 event)) (defun dbus-event-member-name (event) "Return the member name the event is coming from. -It is either a signal name or a method name. The result is a +It is either a signal name or a method name. The result is a string. EVENT is a D-Bus event, see `dbus-check-event'. This -function raises a `dbus-error' signal in case the event is not -well formed." +function signals a `dbus-error' if the event is not well formed." (dbus-check-event event) (nth 7 event)) @@ -1097,10 +1097,10 @@ dbus-event-member-name ;;; D-Bus registered names. (defun dbus-list-activatable-names (&optional bus) - "Return the D-Bus service names which can be activated as list. -If BUS is left nil, `:system' is assumed. The result is a list -of strings, which is nil when there are no activatable service -names at all." + "Return a list of the D-Bus service names which can be activated. +BUS defaults to `:system' when nil or omitted. The result is a +list of strings, which is nil when there are no activatable +service names at all." (dbus-ignore-errors (dbus-call-method (or bus :system) dbus-service-dbus @@ -1126,8 +1126,8 @@ dbus-list-known-names (defun dbus-list-queued-owners (bus service) "Return the unique names registered at D-Bus BUS and queued for SERVICE. -The result is a list of strings, or nil when there are no -queued name owners service names at all." +The result is a list of strings, or nil when there are no queued +name owner service names at all." (dbus-ignore-errors (dbus-call-method bus dbus-service-dbus dbus-path-dbus @@ -1144,13 +1144,13 @@ dbus-get-name-owner (defun dbus-ping (bus service &optional timeout) "Check whether SERVICE is registered for D-Bus BUS. TIMEOUT, a nonnegative integer, specifies the maximum number of -milliseconds `dbus-ping' must return. The default value is 25,000. +milliseconds before `dbus-ping' must return. The default value +is 25,000. -Note, that this autoloads SERVICE if it is not running yet. If -it shall be checked whether SERVICE is already running, one shall -apply +Note, that this autoloads SERVICE if it is not running yet. To +check whether SERVICE is already running, you can instead write - (member service \(dbus-list-known-names bus))" + (member service (dbus-list-known-names bus))" ;; "Ping" raises a D-Bus error if SERVICE does not exist. ;; Otherwise, it returns silently with nil. (condition-case nil @@ -1239,11 +1239,11 @@ dbus-introspect-get-interface-names "Return all interface names of SERVICE in D-Bus BUS at object path PATH. It returns a list of strings. -There will be always the default interface -\"org.freedesktop.DBus.Introspectable\". Another default -interface is \"org.freedesktop.DBus.Properties\". If present, -\"interface\" objects can also have \"property\" objects as -children, beside \"method\" and \"signal\" objects." +The default interface \"org.freedesktop.DBus.Introspectable\" is +always present. Another default interface is +\"org.freedesktop.DBus.Properties\". If present, \"interface\" +objects can also have \"property\" objects as children, beside +\"method\" and \"signal\" objects." (let ((object (dbus-introspect-xml bus service path)) result) (dolist (elt (xml-get-children object 'interface) (nreverse result)) @@ -1251,9 +1251,10 @@ dbus-introspect-get-interface-names (defun dbus-introspect-get-interface (bus service path interface) "Return the INTERFACE of SERVICE in D-Bus BUS at object path PATH. -The return value is an XML object. INTERFACE must be a string, -element of the list returned by `dbus-introspect-get-interface-names'. -The resulting \"interface\" object can contain \"method\", \"signal\", +The return value is an XML object. INTERFACE must be a string +and a member of the list returned by +`dbus-introspect-get-interface-names'. The resulting +\"interface\" object can contain \"method\", \"signal\", \"property\" and \"annotation\" children." (let ((elt (xml-get-children (dbus-introspect-xml bus service path) 'interface))) @@ -1273,9 +1274,9 @@ dbus-introspect-get-method-names (push (dbus-introspect-get-attribute elt "name") result)))) (defun dbus-introspect-get-method (bus service path interface method) - "Return method METHOD of interface INTERFACE as XML object. + "Return method METHOD of interface INTERFACE as an XML object. It must be located at SERVICE in D-Bus BUS at object path PATH. -METHOD must be a string, element of the list returned by +METHOD must be a string and a member of the list returned by `dbus-introspect-get-method-names'. The resulting \"method\" object can contain \"arg\" and \"annotation\" children." (let ((elt (xml-get-children @@ -1296,7 +1297,7 @@ dbus-introspect-get-signal-names (push (dbus-introspect-get-attribute elt "name") result)))) (defun dbus-introspect-get-signal (bus service path interface signal) - "Return signal SIGNAL of interface INTERFACE as XML object. + "Return signal SIGNAL of interface INTERFACE as an XML object. It must be located at SERVICE in D-Bus BUS at object path PATH. SIGNAL must be a string, element of the list returned by `dbus-introspect-get-signal-names'. The resulting \"signal\" @@ -1319,9 +1320,9 @@ dbus-introspect-get-property-names (push (dbus-introspect-get-attribute elt "name") result)))) (defun dbus-introspect-get-property (bus service path interface property) - "Return PROPERTY of INTERFACE as XML object. + "Return PROPERTY of INTERFACE as an XML object. It must be located at SERVICE in D-Bus BUS at object path PATH. -PROPERTY must be a string, element of the list returned by +PROPERTY must be a string and a member of the list returned by `dbus-introspect-get-property-names'. The resulting PROPERTY object can contain \"annotation\" children." (let ((elt (xml-get-children @@ -1336,7 +1337,7 @@ dbus-introspect-get-property (defun dbus-introspect-get-annotation-names (bus service path interface &optional name) - "Return all annotation names as list of strings. + "Return all annotation names as a list of strings. If NAME is nil, the annotations are children of INTERFACE, otherwise NAME must be a \"method\", \"signal\", or \"property\" object, where the annotations belong to." @@ -1352,7 +1353,7 @@ dbus-introspect-get-annotation-names (defun dbus-introspect-get-annotation (bus service path interface name annotation) - "Return ANNOTATION as XML object. + "Return ANNOTATION as an XML object. If NAME is nil, ANNOTATION is a child of INTERFACE, otherwise NAME must be the name of a \"method\", \"signal\", or \"property\" object, where the ANNOTATION belongs to." @@ -1374,7 +1375,7 @@ dbus-introspect-get-annotation (car elt))) (defun dbus-introspect-get-argument-names (bus service path interface name) - "Return a list of all argument names as list of strings. + "Return a list of all argument names as a list of strings. NAME must be a \"method\" or \"signal\" object. Argument names are optional, the function can return nil @@ -1388,8 +1389,9 @@ dbus-introspect-get-argument-names (defun dbus-introspect-get-argument (bus service path interface name arg) "Return argument ARG as XML object. -NAME must be a \"method\" or \"signal\" object. ARG must be a string, -element of the list returned by `dbus-introspect-get-argument-names'." +NAME must be a \"method\" or \"signal\" object. ARG must be a +string and a member of the list returned by +`dbus-introspect-get-argument-names'." (let ((elt (xml-get-children (or (dbus-introspect-get-method bus service path interface name) (dbus-introspect-get-signal bus service path interface name)) @@ -1402,7 +1404,7 @@ dbus-introspect-get-argument (defun dbus-introspect-get-signature (bus service path interface name &optional direction) - "Return signature of a `method' or `signal', represented by NAME, as string. + "Return signature of a `method' or `signal' represented by NAME as a string. If NAME is a `method', DIRECTION can be either \"in\" or \"out\". If DIRECTION is nil, \"in\" is assumed. @@ -1450,9 +1452,8 @@ dbus-get-property (defun dbus-set-property (bus service path interface property value) "Set value of PROPERTY of INTERFACE to VALUE. -It will be checked at BUS, SERVICE, PATH. When the value has -been set successful, the result is VALUE. Otherwise, nil is -returned." +It will be checked at BUS, SERVICE, PATH. When the value is +successfully set return VALUE. Otherwise, return nil." (dbus-ignore-errors ;; "Set" requires a variant. (dbus-call-method @@ -1479,15 +1480,15 @@ dbus-get-all-properties (defun dbus-register-property (bus service path interface property access value &optional emits-signal dont-register-service) - "Register property PROPERTY on the D-Bus BUS. + "Register PROPERTY on the D-Bus BUS. BUS is either a Lisp symbol, `:system' or `:session', or a string denoting the bus address. SERVICE is the D-Bus service name of the D-Bus. It must be a -known name (See discussion of DONT-REGISTER-SERVICE below). +known name (see discussion of DONT-REGISTER-SERVICE below). -PATH is the D-Bus object path SERVICE is registered (See +PATH is the D-Bus object path SERVICE is registered at (see discussion of DONT-REGISTER-SERVICE below). INTERFACE is the name of the interface used at PATH, PROPERTY is the name of the property of INTERFACE. ACCESS indicates, whether the property @@ -1625,8 +1626,8 @@ dbus-get-all-managed-objects "Return all objects at BUS, SERVICE, PATH, and the children of PATH. The result is a list of objects. Every object is a cons of an existing path name, and the list of available interface objects. -An interface object is another cons, which car is the interface -name, and the cdr is the list of properties as returned by +An interface object is another cons, whose car is the interface +name and cdr is the list of properties as returned by `dbus-get-all-properties' for that path and interface. Example: \(dbus-get-all-managed-objects :session \"org.gnome.SettingsDaemon\" \"/\") @@ -1782,12 +1783,13 @@ dbus-init-bus the system and session buses, this function is called when loading `dbus.el', there is no need to call it again. -The function returns a number, which counts the connections this Emacs -session has established to the BUS under the same unique name (see -`dbus-get-unique-name'). It depends on the libraries Emacs is linked -with, and on the environment Emacs is running. For example, if Emacs -is linked with the gtk toolkit, and it runs in a GTK-aware environment -like Gnome, another connection might already be established. +The function returns the number of connections this Emacs session +has established to the BUS under the same unique name (see +`dbus-get-unique-name'). It depends on the libraries Emacs is +linked with, and on the environment Emacs is running. For +example, if Emacs is linked with the GTK+ toolkit, and it runs in +a GTK+-aware environment like GNOME, another connection might +already be established. When PRIVATE is non-nil, a new connection is established instead of reusing an existing one. It results in a new unique name at the bus. -- 2.26.2