[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v
From: |
Michael Albinus |
Subject: |
[Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v |
Date: |
Fri, 21 Dec 2007 22:05:24 +0000 |
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
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/02
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Richard M. Stallman, 2007/12/02
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/03
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/04
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Miles Bader, 2007/12/04
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/06
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/16
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v,
Michael Albinus <=
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/22
- [Emacs-diffs] Changes to emacs/doc/misc/dbus.texi,v, Michael Albinus, 2007/12/30