[Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v

[Michael Albinus]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Michael Albinus <albinus>       07/12/21 22:05:24

Index: dbus.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/misc/dbus.texi,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- dbus.texi   16 Dec 2007 22:45:21 -0000      1.8
+++ dbus.texi   21 Dec 2007 22:05:24 -0000      1.9
@@ -238,7 +238,7 @@
 parameters, either as input parameter, or as output parameter.  Every
 argument belongs to a D-Bus type.
 
-Such arguments must be mapped between the the value encoded as a D-Bus
+Such arguments must be mapped between the value encoded as a D-Bus
 type, and the corresponding type of Lisp objects.  The mapping is
 applied Lisp object @expansion{} D-Bus type for input parameters, and
 D-Bus type @expansion{} Lisp object for output parameters.
@@ -247,8 +247,7 @@
 @section Input parameters.
 
 Input parameters for D-Bus methods and signals occur as arguments of a
-Lisp function call.  Only some primitive Lisp types are supported in
-the current implementation.  The following mapping to D-Bus types is
+Lisp function call.  The following mapping to D-Bus types is
 applied, when the corresponding D-Bus message is created:
 
 @example
@@ -260,30 +259,90 @@
 @item integer                 @tab @expansion{} @tab DBUS_TYPE_INT32
 @item float                   @tab @expansion{} @tab DBUS_TYPE_DOUBLE
 @item string                  @tab @expansion{} @tab DBUS_TYPE_STRING
address@hidden list                    @tab @expansion{} @tab DBUS_TYPE_ARRAY
 @end multitable
 @end example
 
+Other Lisp objects, like symbols or hash tables, are not accepted as
+input parameter.
+
+If it is necessary to use another D-Bus type, a corresponding type
+symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
+types are represented by the type symbols `:byte', `:boolean',
+`:int16', `:uint16', `:int32', `:uint32', `:int64', `:uint64',
+`:double', `:string', `:object-path' and `:signature'.
+
 @noindent
-Other Lisp types, especially lists, are not supported (yet).
+Example:
+
address@hidden
+(dbus-call-method ... @var{NUMBER} @var{STRING})
address@hidden lisp
+
+is equivalent to
+
address@hidden
+(dbus-call-method ... :uint32 @var{NUMBER} :string @var{STRING})
address@hidden lisp
+
+but different to
+
address@hidden
+(dbus-call-method ... :int32 @var{NUMBER} :signature @var{STRING})
address@hidden lisp
+
+A D-Bus compound type is always represented as list.  The car of this
+list can be the type symbol `:array', `:variant', `:struct' or
+`:dict-entry', which would result in a corresponding D-Bus container.
+`:array' is optional, because this is the default compoud type for a
+list.
+
+The objects being elements of the list are checked according to the
+D-Bus compound type rules.
+
address@hidden
address@hidden An array must contain only elements of the same D-Bus type.
address@hidden A variant must contain only one single element.
address@hidden A dictionary entry must be element of an array, and it must
+contain only a key-value pair of two element, with a basic type key.
address@hidden There is no restriction for structs.
address@hidden itemize
+
address@hidden
+Example:
+
address@hidden
+(dbus-send-signal ...
+  :object-path STRING '(:variant :boolean BOOL)
+  '(:array NUMBER NUMBER) '(:array BOOL :boolean BOOL)
+  '(:struct BOOL :boolean BOOL BOOL
+    (:array NUMBER NUMBER) (:array BOOL BOOL))
+  '(:struct NUMBER NUMBER) '((:dict-entry NUMBER (NUMBER)))
+  '(:array (:dict-entry NUMBER :int32 NUMBER)))
address@hidden lisp
 
 
 @section Output parameters.
 
 Output parameters of D-Bus methods and signals are mapped to Lisp
-objects.  This mapping is more powerful than the one for input
-parameters, i.e., more D-Bus types are supported by the current
-implementation.
+objects.
 
 @example
 @multitable {DBUS_TYPE_OBJECT_PATH} address@hidden address@hidden or 
@code{nil}}
 @item D-Bus type            @tab              @tab Lisp type
 @item
 @item DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or @code{nil}
address@hidden DBUS_TYPE_BYTE        @tab @expansion{} @tab
address@hidden DBUS_TYPE_UINT16      @tab @expansion{} @tab number
address@hidden DBUS_TYPE_INT32       @tab @expansion{} @tab number
 @item DBUS_TYPE_UINT32      @tab @expansion{} @tab number
 @item DBUS_TYPE_INT32       @tab @expansion{} @tab number
address@hidden DBUS_TYPE_UINT64      @tab @expansion{} @tab number
address@hidden DBUS_TYPE_INT64       @tab @expansion{} @tab number
 @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
address@hidden DBUS_TYPE_SIGNATURE   @tab @expansion{} @tab string
 @item DBUS_TYPE_ARRAY       @tab @expansion{} @tab list
 @item DBUS_TYPE_VARIANT     @tab @expansion{} @tab list
 @item DBUS_TYPE_STRUCT      @tab @expansion{} @tab list
@@ -498,6 +557,11 @@
 @cindex errors
 @cindex events
 
+Input parameters of @code{dbus-call-method} and
address@hidden are checked for correct D-Bus types. If
+there is a type mismatch, the Lisp error @code{wrong-type-argument}
address@hidden ARG} is raised.
+
 All errors raised by D-Bus are signaled with the error symbol
 @code{dbus-error}.  As usual, such an error can be trapped with a
 @code{condition-case} form.  If possible, error messages from D-Bus