From: Michael Albinus Date: Fri, 21 Dec 2007 22:05:24 +0000 (+0000) Subject: * dbus.texi (Type Conversion): Extend for D-Bus compound types. X-Git-Tag: emacs-pretest-23.0.90~8867 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6a31c8196e70b966e7125914ba96897d91499196;p=emacs.git * dbus.texi (Type Conversion): Extend for D-Bus compound types. (Errors and Events): Mention wrong-type-argument error. --- diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 1aa10c82dbf..67ca3866e7d 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,8 @@ +2007-12-21 Michael Albinus + + * dbus.texi (Type Conversion): Extend for D-Bus compound types. + (Errors and Events): Mention wrong-type-argument error. + 2007-12-21 Alex Schroeder * rcirc.texi: Changed single spaces after sentence end to double diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 57aeb8aa435..7f4d0f7243b 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -238,7 +238,7 @@ D-Bus method calls and signals accept usually several arguments as 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 @@ D-Bus type @expansion{} Lisp object for output parameters. @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 @@ applied, when the corresponding D-Bus message is created: @item integer @tab @expansion{} @tab DBUS_TYPE_INT32 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE @item string @tab @expansion{} @tab DBUS_TYPE_STRING +@item 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: + +@lisp +(dbus-call-method ... @var{NUMBER} @var{STRING}) +@end lisp + +is equivalent to + +@lisp +(dbus-call-method ... :uint32 @var{NUMBER} :string @var{STRING}) +@end lisp + +but different to + +@lisp +(dbus-call-method ... :int32 @var{NUMBER} :signature @var{STRING}) +@end 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. + +@itemize +@item An array must contain only elements of the same D-Bus type. +@item A variant must contain only one single element. +@item 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. +@item There is no restriction for structs. +@end itemize + +@noindent +Example: + +@lisp +(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))) +@end 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} {@expansion{}} {@code{t} or @code{nil}} @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 +@item DBUS_TYPE_UINT16 @tab @expansion{} @tab number +@item DBUS_TYPE_INT32 @tab @expansion{} @tab number @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number @item DBUS_TYPE_INT32 @tab @expansion{} @tab number +@item DBUS_TYPE_UINT64 @tab @expansion{} @tab number +@item 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 +@item 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 @@ result of a preceding @code{dbus-register-signal} call. @cindex errors @cindex events +Input parameters of @code{dbus-call-method} 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. + 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