annotate doc/misc/dbus.texi @ 96995:6587a1d0c457

*** empty log message ***
author Michael Albinus <michael.albinus@gmx.de>
date Thu, 24 Jul 2008 21:56:29 +0000
parents de3f169b53eb
children 48b3629e41d1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1 \input texinfo @c -*-texinfo-*-
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
2 @setfilename ../../info/dbus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
3 @c %**start of header
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
4 @settitle Using of D-Bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
5 @c @setchapternewpage odd
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
6 @c %**end of header
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
7
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
8 @copying
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
9 Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
10
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
11 @quotation
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
12 Permission is granted to copy, distribute and/or modify this document
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
13 under the terms of the GNU Free Documentation License, Version 1.2 or
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
14 any later version published by the Free Software Foundation; with no
95937
6f0fce2c3559 Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents: 95874
diff changeset
15 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
6f0fce2c3559 Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents: 95874
diff changeset
16 and with the Back-Cover Texts as in (a) below. A copy of the license
6f0fce2c3559 Remove references to external license, since doclicense is included.
Glenn Morris <rgm@gnu.org>
parents: 95874
diff changeset
17 is included in the section entitled ``GNU Free Documentation License''.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
18
95874
eafbd7a5c9be Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents: 93422
diff changeset
19 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
eafbd7a5c9be Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents: 93422
diff changeset
20 modify this GNU manual. Buying copies from the FSF supports it in
eafbd7a5c9be Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents: 93422
diff changeset
21 developing GNU and promoting software freedom.''
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
22 @end quotation
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
23 @end copying
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
24
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
25 @dircategory Emacs
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
26 @direntry
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
27 * D-Bus: (dbus). Using D-Bus in Emacs.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
28 @end direntry
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
29
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
30
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
31 @node Top, Overview, (dir), (dir)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
32 @top D-Bus integration in Emacs
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
33
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
34 This manual documents an API for usage of D-Bus in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
35 Emacs.@footnote{D-Bus is not enabled by default. You must run
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
36 @command{./configure --with-dbus} in Emacs' top level directory,
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
37 before you compile Emacs.} D-Bus is a message bus system, a simple
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
38 way for applications to talk to one another. An overview of D-Bus can
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
39 be found at @uref{http://dbus.freedesktop.org/}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
40
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
41 @insertcopying
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
42
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
43 @menu
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
44 * Overview:: An overview of D-Bus.
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
45 * Inspection:: Inspection of D-Bus services.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
46 * Type Conversion:: Mapping Lisp types and D-Bus types.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
47 * Synchronous Methods:: Calling methods in a blocking way.
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
48 * Receiving Method Calls:: Offering own methods.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
49 * Signals:: Sending and receiving signals.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
50 * Errors and Events:: Errors and events.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
51 * GNU Free Documentation License:: The license for this documentation.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
52 @end menu
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
53
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
54
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
55 @node Overview
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
56 @chapter An overview of D-Bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
57 @cindex overview
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
58
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
59 D-Bus is an inter-process communication mechanism for applications
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
60 residing on the same host. The communication is based on
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
61 @dfn{messages}. Data in the messages is carried in a structured way,
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
62 it is not just a byte stream.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
63
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
64 The communication is connection oriented to two kinds of message
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
65 buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
66 given machine, there is always one single system bus for miscellaneous
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
67 system-wide communication, like changing of hardware configuration.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
68 On the other hand, the session bus is always related to a single
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
69 user's session.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
70
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
71 Every client application, which is connected to a bus, registers under
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
72 a @dfn{unique name} at the bus. This name is used for identifying the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
73 client application. Such a unique name starts always with a colon,
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
74 and looks like @samp{:1.42}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
75
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
76 Additionally, a client application can register itself to a so called
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
77 @dfn{known name}, which is a series of identifiers separated by dots,
86972
acea77e0ee56 (Overview): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 86944
diff changeset
78 as in @samp{org.gnu.Emacs}. If several applications register to the
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
79 same known name, these registrations are queued, and only the first
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
80 application which has registered for the known name is reachable via
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
81 this name. If this application disconnects from the bus, the next
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
82 queued unique name becomes the owner of this known name.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
83
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
84 An application can install one or several objects under its name.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
85 Such objects are identified by an @dfn{object path}, which looks
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
86 similar to paths in a filesystem. An example of such an object path
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
87 could be @samp{/org/gnu/Emacs/}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
88
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
89 Applications might send a request to an object, that means sending a
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
90 message with some data as input parameters, and receiving a message
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
91 from that object with the result of this message, the output
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
92 parameters. Such a request is called @dfn{method} in D-Bus.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
93
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
94 The other form of communication are @dfn{signals}. The underlying
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
95 message is emitted from an object and will be received by all other
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
96 applications which have registered for such a signal.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
97
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
98 All methods and signals an object supports are called @dfn{interface}
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
99 of the object. Interfaces are specified under a hierarchical name in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
100 D-Bus; an object can support several interfaces. Such an interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
101 name could be @samp{org.gnu.Emacs.TextEditor} or
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
102 @samp{org.gnu.Emacs.FileManager}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
103
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
104
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
105 @node Inspection
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
106 @chapter Inspection of D-Bus services.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
107 @cindex inspection
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
108
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
109 @menu
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
110 * Bus names:: Discovering D-Bus names.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
111 * Introspection:: Knowing the details of D-Bus services.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
112 * Nodes and Interfaces:: Detecting object paths and interfaces.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
113 * Methods and Signal:: Applying the functionality.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
114 * Properties and Annotations:: What else to know about interfaces.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
115 * Arguments and Signatures:: The final details.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
116 @end menu
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
117
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
118
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
119 @node Bus names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
120 @section Bus names.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
121
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
122 There are several basic functions which inspect the buses for
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
123 registered names. Internally they use the basic interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
124 @samp{org.freedesktop.DBus}, which is supported by all objects of a bus.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
125
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
126 @defun dbus-list-activatable-names
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
127 This function returns the D-Bus service names, which can be activated.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
128 An activatable service is described in a service registration file.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
129 Under GNU/Linux, such files are located at
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
130 @file{/usr/share/dbus-1/services/}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
131
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
132 The result is a list of strings, which is @code{nil} when there are no
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
133 activatable service names at all.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
134 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
135
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
136 @defun dbus-list-names bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
137 All service names, which are registered at D-Bus @var{bus}, are
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
138 returned. The result is a list of strings, which is @code{nil} when
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
139 there are no registered service names at all. Well known names are
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
140 strings like @samp{org.freedesktop.DBus}. Names starting with
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
141 @samp{:} are unique names for services.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
142
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
143 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
144 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
145 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
146
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
147 @defun dbus-list-known-names bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
148 Retrieves all services which correspond to a known name in @var{bus}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
149 A service has a known name if it doesn't start with @samp{:}. The
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
150 result is a list of strings, which is @code{nil} when there are no
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
151 known names at all.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
152
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
153 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
154 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
155 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
156
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
157 @defun dbus-list-queued-owners bus service
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
158 For a given service, registered at D-Bus @var{bus} under the name
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
159 @var{service}, all queued unique names are returned. The result is a
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
160 list of strings, or @code{nil} when there are no queued names for
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
161 @var{service} at all.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
162
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
163 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
164 @code{:session}. @var{service} must be a known service name as
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
165 string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
166 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
167
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
168 @defun dbus-get-name-owner bus service
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
169 For a given service, registered at D-Bus @var{bus} under the name
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
170 @var{service}, the unique name of the name owner is returned. The
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
171 result is a string, or @code{nil} when there exist no name owner of
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
172 @var{service}.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
173
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
174 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
175 @code{:session}. @var{service} must be a known service name as
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
176 string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
177 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
178
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
179 @defun dbus-ping bus service
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
180 Check whether the service name @var{service} is registered at D-Bus
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
181 @var{bus}. @var{service} might not have been started yet. The result
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
182 is either @code{t} or @code{nil}.
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
183
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
184 @var{bus} must be either the symbol @code{:system} or the symbol
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
185 @code{:session}. @var{service} must be a string. Example:
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
186
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
187 @lisp
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
188 (message
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
189 "%s screensaver on board."
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
190 (cond
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
191 ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome")
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
192 ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE")
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
193 (t "No")))
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
194 @end lisp
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
195 @end defun
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
196
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
197 @defun dbus-get-unique-name bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
198 The unique name, under which Emacs is registered at D-Bus @var{bus},
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
199 is returned as string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
200
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
201 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
202 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
203 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
204
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
205
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
206 @node Introspection
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
207 @section Knowing the details of D-Bus services.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
208
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
209 D-Bus services publish their interfaces. This can be retrieved and
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
210 analyzed during runtime, in order to understand the used
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
211 implementation.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
212
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
213 The resulting introspection data are in XML format. The root
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
214 introspection element is always a @code{node} element. It might have
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
215 a @code{name} attribute, which denotes the (absolute) object path an
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
216 interface is introspected.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
217
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
218 The root @code{node} element may have @code{node} and @code{interface}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
219 children. A child @code{node} element must have a @code{name}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
220 attribute, this case it is the relative object path to the root
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
221 @code{node} element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
222
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
223 An @code{interface} element has just one attribute, @code{name}, which
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
224 is the full name of that interface. The default interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
225 @samp{org.freedesktop.DBus.Introspectable} is always present. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
226
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
227 @example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
228 <node name="/org/bluez">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
229 <interface name="org.freedesktop.DBus.Introspectable">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
230 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
231 </interface>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
232 <interface name="org.bluez.Manager">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
233 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
234 </interface>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
235 <interface name="org.bluez.Database">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
236 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
237 </interface>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
238 <interface name="org.bluez.Security">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
239 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
240 </interface>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
241 <node name="service_audio"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
242 <node name="service_input"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
243 <node name="service_network"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
244 <node name="service_serial"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
245 </node>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
246 @end example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
247
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
248 Children of an @code{interface} element can be @code{method},
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
249 @code{signal} and @code{property} elements. A @code{method} element
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
250 stands for a D-Bus method of the surrounding interface. The element
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
251 itself has a @code{name} attribute, showing the method name. Children
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
252 elements @code{arg} stand for the arguments of a method. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
253
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
254 @example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
255 <method name="ResolveHostName">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
256 <arg name="interface" type="i" direction="in"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
257 <arg name="protocol" type="i" direction="in"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
258 <arg name="name" type="s" direction="in"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
259 <arg name="aprotocol" type="i" direction="in"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
260 <arg name="flags" type="u" direction="in"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
261 <arg name="interface" type="i" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
262 <arg name="protocol" type="i" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
263 <arg name="name" type="s" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
264 <arg name="aprotocol" type="i" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
265 <arg name="address" type="s" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
266 <arg name="flags" type="u" direction="out"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
267 </method>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
268 @end example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
269
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
270 @code{arg} elements can have the attributes @code{name}, @code{type}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
271 and @code{direction}. The @code{name} attribute is optional. The
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
272 @code{type} attribute stands for the @dfn{signature} of the argument
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
273 in D-Bus. For a discussion of D-Bus types and their Lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
274 representation see @ref{Type Conversion}.@footnote{D-Bus signatures
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
275 are explained in the D-Bus specification
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
276 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
277 The @code{direction} attribute of an @code{arg} element can be only
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
278 @samp{in} or @samp{out}; in case it is omitted, it defaults to
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
279 @samp{in}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
280
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
281 A @code{signal} element of an @code{interface} has a similar
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
282 structure. The @code{direction} attribute of an @code{arg} child
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
283 element can be only @samp{out} here; which is also the default value.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
284 Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
285
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
286 @example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
287 <signal name="StateChanged">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
288 <arg name="state" type="i"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
289 <arg name="error" type="s"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
290 </signal>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
291 @end example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
292
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
293 A @code{property} element has no @code{arg} child
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
294 element. It just has the attributes @code{name}, @code{type} and
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
295 @code{access}, which are all mandatory. The @code{access} attribute
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
296 allows the values @samp{readwrite}, @samp{read}, and @samp{write}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
297 Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
298
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
299 @example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
300 <property name="Status" type="u" direction="read"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
301 @end example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
302
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
303 @code{annotation} elements can be children of @code{interface},
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
304 @code{method}, @code{signal}, and @code{property} elements. Unlike
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
305 properties, which can change their values during lifetime of a D-Bus
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
306 object, annotations are static. Often they are used for code
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
307 generators of D-Bus langugae bindings. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
308
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
309 @example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
310 <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
311 @end example
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
312
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
313 Annotations have just @code{name} and @code{value} attributes, both
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
314 must be strings.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
315
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
316 @defun dbus-introspect bus service path
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
317 This function returns all interfaces and sub-nodes of @var{service},
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
318 registered at object path @var{path} at bus @var{bus}.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
319
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
320 @var{bus} must be either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
321 @code{:session}. @var{service} must be a known service name, and
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
322 @var{path} must be a valid object path. The last two parameters are
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
323 strings. The result, the introspection data, is a string in XML
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
324 format. Example:
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
325
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
326 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
327 (dbus-introspect
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
328 :system "org.freedesktop.Hal"
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
329 "/org/freedesktop/Hal/devices/computer")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
330
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
331 @result{} "<!DOCTYPE node PUBLIC
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
332 "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
333 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
334 <node>
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
335 <interface name="org.freedesktop.Hal.Device">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
336 <method name="GetAllProperties">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
337 <arg name="properties" direction="out" type="a@{sv@}"/>
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
338 </method>
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
339 @dots{}
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
340 <signal name="PropertyModified">
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
341 <arg name="num_updates" type="i"/>
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
342 <arg name="updates" type="a(sbb)"/>
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
343 </signal>
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
344 </interface>
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
345 @dots{}
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
346 </node>"
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
347 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
348
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
349 This example informs us, that the service @samp{org.freedesktop.Hal}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
350 at object path @samp{/org/freedesktop/Hal/devices/computer} offers the
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
351 interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
352 not documented here). This interface contains the method
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
353 @samp{GetAllProperties}, which needs no input parameters, but returns
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
354 as output parameter an array of dictionary entries (key-value pairs).
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
355 Every dictionary entry has a string as key, and a variant as value.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
356
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
357 The interface offers also a signal, which returns 2 parameters: an
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
358 integer, and an array consisting of elements which are a struct of a
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
359 string and 2 boolean values.@footnote{ The interfaces of the service
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
360 @samp{org.freedesktop.Hal} are described at
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
361 @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
362 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
363
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
364 @defun dbus-introspect-xml bus service path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
365 This function has the same intention as function
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
366 @code{dbus-introspect}. The returned value is a parsed XML tree,
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
367 which can be used for further analysis. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
368
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
369 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
370 (dbus-introspect-xml
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
371 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
372 "/org/freedesktop/xesam/searcher/main")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
373
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
374 @result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
375 (interface ((name . "org.freedesktop.xesam.Search"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
376 (method ((name . "GetHitData"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
377 (arg ((name . "search") (type . "s") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
378 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
379 (arg ((name . "fields") (type . "as") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
380 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
381 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
382 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
383 (signal ((name . "HitsAdded"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
384 (arg ((name . "search") (type . "s")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
385 (arg ((name . "count") (type . "u")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
386 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
387 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
388 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
389 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
390 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
391 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
392
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
393 @defun dbus-introspect-get-attribute object attribute
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
394 It returns the @var{attribute} value of a D-Bus introspection
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
395 @var{object}. @var{object} can be every subtree of a parsed XML tree
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
396 as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
397 a string according to the attribute names in the D-Bus specification.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
398 Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
399
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
400 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
401 (dbus-introspect-get-attribute
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
402 (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
403 "/org/freedesktop/SystemToolsBackends/UsersConfig")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
404 "name")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
405
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
406 @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
407 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
408
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
409 If @var{object} has no @var{attribute}, the function returns nil.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
410 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
411
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
412
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
413 @node Nodes and Interfaces
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
414 @section Detecting object paths and interfaces.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
415
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
416 The first elements, to be introspected for a D-Bus object, are further
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
417 object paths and interfaces.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
418
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
419 @defun dbus-introspect-get-node-names bus service path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
420 All node names of @var{service} in D-Bus @var{bus} at object path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
421 @var{path} are returned as list of strings. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
422
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
423 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
424 (dbus-introspect-get-node-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
425 :session "org.gnome.seahorse" "/org/gnome/seahorse")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
426
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
427 @result{} ("crypto" "keys")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
428 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
429
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
430 The node names stand for further object paths of the D-Bus
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
431 @var{service}, relative to @var{path}. In the example,
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
432 @samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
433 are also object paths of the D-Bus service @samp{org.gnome.seahorse}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
434 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
435
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
436 @defun dbus-introspect-get-all-nodes bus service path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
437 This function returns all node names of @var{service} in D-Bus
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
438 @var{bus} at object path @var{path}. It returns a list of strings
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
439 with all object paths of @var{service}, starting at @var{path}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
440 Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
441
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
442 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
443 (dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
444
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
445 @result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
446 "/org/gnome/seahorse/crypto"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
447 "/org/gnome/seahorse/keys"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
448 "/org/gnome/seahorse/keys/openpgp"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
449 "/org/gnome/seahorse/keys/openpgp/local"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
450 "/org/gnome/seahorse/keys/openssh"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
451 "/org/gnome/seahorse/keys/openssh/local")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
452 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
453 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
454
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
455 @defun dbus-introspect-get-interface-names bus service path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
456 There will be returned a list strings of all interface names of
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
457 @var{service} in D-Bus @var{bus} at object path @var{path}. This list
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
458 will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
459
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
460 Another default interface is @samp{org.freedesktop.DBus.Properties}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
461 If present, @code{interface} elements can also have @code{property}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
462 children. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
463
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
464 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
465 (dbus-introspect-get-interface-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
466 :system "org.freedesktop.Hal"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
467 "/org/freedesktop/Hal/devices/computer")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
468
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
469 @result{} ("org.freedesktop.DBus.Introspectable"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
470 "org.freedesktop.Hal.Device"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
471 "org.freedesktop.Hal.Device.SystemPowerManagement"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
472 "org.freedesktop.Hal.Device.CPUFreq")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
473 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
474 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
475
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
476 @defun dbus-introspect-get-interface bus service path interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
477 Return @var{interface} of @var{service} in D-Bus @var{bus} at object
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
478 path @var{path}. The return value is an XML element. @var{interface}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
479 must be a string, element of the list returned by
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
480 @code{dbus-introspect-get-interface-names}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
481
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
482 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
483 (dbus-introspect-get-interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
484 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
485 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
486 "org.freedesktop.xesam.Search")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
487
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
488 @result{} (interface ((name . "org.freedesktop.xesam.Search"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
489 (method ((name . "GetHitData"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
490 (arg ((name . "search") (type . "s") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
491 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
492 (arg ((name . "fields") (type . "as") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
493 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
494 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
495 @dots{}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
496 (signal ((name . "HitsAdded"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
497 (arg ((name . "search") (type . "s")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
498 (arg ((name . "count") (type . "u")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
499 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
500 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
501 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
502 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
503
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
504 @noindent
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
505 With these functions, it is possible to retrieve all introspection
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
506 data from a running system:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
507
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
508 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
509 (with-current-buffer (switch-to-buffer "*introspect*")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
510 (erase-buffer)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
511 (dolist (service (dbus-list-known-names :session))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
512 (dolist (path (dbus-introspect-get-all-nodes :session service "/"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
513 ;; We want to introspect only elements, which have more than
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
514 ;; the default interface "org.freedesktop.DBus.Introspectable".
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
515 (when (delete
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
516 "org.freedesktop.DBus.Introspectable"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
517 (dbus-introspect-get-interface-names :session service path))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
518 (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
519 (dbus-introspect :session service path))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
520 (redisplay t)))))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
521 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
522
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
523
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
524 @node Methods and Signal
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
525 @section Applying the functionality.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
526
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
527 Methods and signals are the communicatione means to D-Bus. The
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
528 following functions return their specifications.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
529
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
530 @defun dbus-introspect-get-method-names bus service path interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
531 Return a list of strings of all method names of @var{interface} of
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
532 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
533
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
534 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
535 (dbus-introspect-get-method-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
536 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
537 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
538 "org.freedesktop.xesam.Search")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
539
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
540 @result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
541 "CloseSession" "GetHitData" "SetProperty" "NewSearch"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
542 "GetProperty" "CloseSearch")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
543 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
544 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
545
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
546 @defun dbus-introspect-get-method bus service path interface method
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
547 This function returns @var{method} of @var{interface} as XML element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
548 It must be located at @var{service} in D-Bus @var{bus} at object path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
549 @var{path}. @var{method} must be a string, element of the list
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
550 returned by @code{dbus-introspect-get-method-names}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
551
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
552 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
553 (dbus-introspect-get-method
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
554 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
555 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
556 "org.freedesktop.xesam.Search" "GetHitData")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
557
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
558 @result{} (method ((name . "GetHitData"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
559 (arg ((name . "search") (type . "s") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
560 (arg ((name . "hit_ids") (type . "au") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
561 (arg ((name . "fields") (type . "as") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
562 (arg ((name . "hit_data") (type . "aav") (direction . "out")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
563 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
564 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
565 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
566
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
567 @defun dbus-introspect-get-signal-names bus service path interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
568 Return a list of strings of all signal names of @var{interface} of
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
569 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
570
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
571 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
572 (dbus-introspect-get-signal-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
573 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
574 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
575 "org.freedesktop.xesam.Search")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
576
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
577 @result{} ("StateChanged" "SearchDone" "HitsModified"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
578 "HitsRemoved" "HitsAdded")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
579 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
580 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
581
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
582 @defun dbus-introspect-get-signal bus service path interface signal
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
583 This function returns @var{signal} of @var{interface} as XML element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
584 It must be located at @var{service} in D-Bus @var{bus} at object path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
585 @var{path}. @var{signal} must be a string, element of the list
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
586 returned by @code{dbus-introspect-get-signal-names}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
587
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
588 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
589 (dbus-introspect-get-signal
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
590 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
591 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
592 "org.freedesktop.xesam.Search" "HitsAdded")
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
593
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
594 @result{} (signal ((name . "HitsAdded"))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
595 (arg ((name . "search") (type . "s")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
596 (arg ((name . "count") (type . "u")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
597 )
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
598 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
599 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
600
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
601
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
602 @node Properties and Annotations
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
603 @section What else to know about interfaces.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
604
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
605 Interfaces can have properties. These can be exposed via the
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
606 @samp{org.freedesktop.DBus.Properties} interface@footnote{See
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
607 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
608 That is, properties can be retrieved and changed during lifetime of an
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
609 element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
610
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
611 Annotations, on the other hand, are static values for an element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
612 Often, they are used to instruct generators, how to generate code from
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
613 the interface for a given language binding.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
614
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
615 @defun dbus-introspect-get-property-names bus service path interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
616 Return a list of strings with all property names of @var{interface} of
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
617 @var{service} in D-Bus @var{bus} at object path @var{path}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
618
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
619 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
620 (dbus-introspect-get-property-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
621 :session "org.kde.kded" "/modules/networkstatus"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
622 "org.kde.Solid.Networking.Client")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
623
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
624 @result{} ("Status")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
625 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
626
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
627 If an interface declares properties, the corresponding element supports
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
628 also the @samp{org.freedesktop.DBus.Properties} interface.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
629 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
630
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
631 @defun dbus-introspect-get-property bus service path interface property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
632 This function returns @var{property} of @var{interface} as XML element.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
633 It must be located at @var{service} in D-Bus @var{bus} at object path
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
634 @var{path}. @var{property} must be a string, element of the list
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
635 returned by @code{dbus-introspect-get-property-names}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
636
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
637 A @var{property} value can be retrieved by the function
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
638 @code{dbus-introspect-get-attribute}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
639
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
640 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
641 (dbus-introspect-get-property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
642 :session "org.kde.kded" "/modules/networkstatus"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
643 "org.kde.Solid.Networking.Client" "Status")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
644
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
645 @result{} (property ((access . "read") (type . "u") (name . "Status")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
646
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
647 (dbus-introspect-get-attribute
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
648 (dbus-introspect-get-property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
649 :session "org.kde.kded" "/modules/networkstatus"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
650 "org.kde.Solid.Networking.Client" "Status")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
651 "access")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
652
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
653 @result{} "read"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
654 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
655 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
656
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
657 @defun dbus-get-property bus service path interface property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
658 This function returns the value of @var{property} of @var{interface}.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
659 It will be checked at @var{bus}, @var{service}, @var{path}. The
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
660 result can be any valid D-Bus value, or nil if there is no
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
661 @var{property}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
662
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
663 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
664 (dbus-get-property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
665 :session "org.kde.kded" "/modules/networkstatus"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
666 "org.kde.Solid.Networking.Client" "Status")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
667
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
668 @result{} 4
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
669 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
670 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
671
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
672 @defun dbus-set-property bus service path interface property value
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
673 Set value of @var{property} of @var{interface} to @var{value}. It
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
674 will be checked at @var{bus}, @var{service}, @var{path}. When the
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
675 value has been set successful, the result is @var{value}. Otherwise,
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
676 @code{nil} is returned. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
677
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
678 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
679 (dbus-set-property
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
680 :session "org.kde.kaccess" "/MainApplication"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
681 "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
682
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
683 @result{} 500
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
684 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
685 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
686
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
687 @defun dbus-get-all-properties bus service path interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
688 This function returns all properties of @var{interface}. It will be
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
689 checked at @var{bus}, @var{service}, @var{path}. The result is a list
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
690 of cons. Every cons contains the name of the property, and its value.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
691 If there are no properties, @code{nil} is returned. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
692
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
693 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
694 (dbus-get-all-properties
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
695 :session "org.kde.kaccess" "/MainApplication"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
696 "com.trolltech.Qt.QApplication")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
697
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
698 @result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
699 ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
700 ("globalStrut" 0 0) ("startDragTime" . 500)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
701 ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t)
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
702 ("styleSheet" . ""))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
703 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
704 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
705
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
706 @defun dbus-introspect-get-annotation-names bus service path interface &optional name
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
707 Return a list of all annotation names as list of strings. If
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
708 @var{name} is @code{nil}, the annotations are children of
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
709 @var{interface}, otherwise @var{name} must be a @code{method},
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
710 @code{signal}, or @code{property} XML element, where the annotations
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
711 belong to. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
712
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
713 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
714 (dbus-introspect-get-annotation-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
715 :session "de.berlios.Pinot" "/de/berlios/Pinot"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
716 "de.berlios.Pinot" "GetStatistics")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
717
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
718 @result{} ("de.berlios.Pinot.GetStatistics")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
719 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
720
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
721 Default annotation names@footnote{See
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
722 @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
723 are
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
724
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
725 @table @samp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
726 @item org.freedesktop.DBus.Deprecated
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
727 Whether or not the entity is deprecated; defaults to @code{nil}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
728
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
729 @item org.freedesktop.DBus.GLib.CSymbol
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
730 The C symbol; may be used for @code{methods} and @code{interfaces}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
731
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
732 @item org.freedesktop.DBus.Method.NoReply
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
733 If set, don't expect a reply to the @code{method} call; defaults to @code{nil}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
734 @end table
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
735 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
736
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
737 @defun dbus-introspect-get-annotation bus service path interface name annotation
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
738 Return annotation @var{ANNOTATION} as XML object. If @var{name} is
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
739 @code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
740 @var{name} must be the name of a @code{method}, @code{signal}, or
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
741 @code{property} XML element, where the @var{ANNOTATION} belongs to.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
742
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
743 An attribute value can be retrieved by
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
744 @code{dbus-introspect-get-attribute}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
745
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
746 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
747 (dbus-introspect-get-annotation
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
748 :session "de.berlios.Pinot" "/de/berlios/Pinot"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
749 "de.berlios.Pinot" "GetStatistics"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
750 "de.berlios.Pinot.GetStatistics")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
751
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
752 @result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
753 (value . "pinotDBus")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
754
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
755 (dbus-introspect-get-attribute
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
756 (dbus-introspect-get-annotation
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
757 :session "de.berlios.Pinot" "/de/berlios/Pinot"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
758 "de.berlios.Pinot" "GetStatistics"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
759 "de.berlios.Pinot.GetStatistics")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
760 "value")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
761
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
762 @result{} "pinotDBus"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
763 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
764 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
765
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
766
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
767 @node Arguments and Signatures
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
768 @section The final details.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
769
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
770 Methods and signals have arguments. They are described in the
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
771 @code{arg} XML elements.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
772
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
773 @defun dbus-introspect-get-argument-names bus service path interface name
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
774 Return a list of all argument names as list of strings. @var{name}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
775 must be a @code{method} or @code{signal} XML element. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
776
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
777 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
778 (dbus-introspect-get-argument-names
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
779 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
780 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
781 "org.freedesktop.xesam.Search" "GetHitData")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
782
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
783 @result{} ("search" "hit_ids" "fields" "hit_data")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
784 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
785
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
786 Argument names are optional; the function can return @code{nil}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
787 therefore, even if the method or signal has arguments.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
788 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
789
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
790 @defun dbus-introspect-get-argument bus service path interface name arg
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
791 Return argument @var{ARG} as XML object. @var{name}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
792 must be a @code{method} or @code{signal} XML element. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
793
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
794 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
795 (dbus-introspect-get-argument
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
796 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
797 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
798 "org.freedesktop.xesam.Search" "GetHitData" "search")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
799
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
800 @result{} (arg ((name . "search") (type . "s") (direction . "in")))
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
801 @end lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
802 @end defun
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
803
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
804 @defun dbus-introspect-get-signature bus service path interface name &optional direction
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
805 Return signature of a @code{method} or @code{signal}, represented by
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
806 @var{name}, as string.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
807
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
808 If @var{name} is a @code{method}, @var{direction} can be either
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
809 @samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in}
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
810 is assumed.
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
811
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
812 If @var{name} is a @code{signal}, and @var{direction} is
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
813 non-@code{nil}, @var{direction} must be @samp{out}. Example:
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
814
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
815 @lisp
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
816 (dbus-introspect-get-signature
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
817 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
818 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
819 "org.freedesktop.xesam.Search" "GetHitData" "in")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
820
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
821 @result{} "sauas"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
822
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
823 (dbus-introspect-get-signature
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
824 :session "org.freedesktop.xesam.searcher"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
825 "/org/freedesktop/xesam/searcher/main"
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
826 "org.freedesktop.xesam.Search" "HitsAdded")
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
827
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
828 @result{} \"su\""
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
829 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
830 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
831
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
832
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
833 @node Type Conversion
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
834 @chapter Mapping Lisp types and D-Bus types.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
835 @cindex type conversion
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
836
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
837 D-Bus method calls and signals accept usually several arguments as
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
838 parameters, either as input parameter, or as output parameter. Every
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
839 argument belongs to a D-Bus type.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
840
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
841 Such arguments must be mapped between the value encoded as a D-Bus
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
842 type, and the corresponding type of Lisp objects. The mapping is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
843 applied Lisp object @expansion{} D-Bus type for input parameters, and
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
844 D-Bus type @expansion{} Lisp object for output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
845
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
846
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
847 @section Input parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
848
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
849 Input parameters for D-Bus methods and signals occur as arguments of a
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
850 Lisp function call. The following mapping to D-Bus types is
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
851 applied, when the corresponding D-Bus message is created:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
852
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
853 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
854 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
855 @item Lisp type @tab @tab D-Bus type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
856 @item
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
857 @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
858 @item number @tab @expansion{} @tab DBUS_TYPE_UINT32
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
859 @item integer @tab @expansion{} @tab DBUS_TYPE_INT32
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
860 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
861 @item string @tab @expansion{} @tab DBUS_TYPE_STRING
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
862 @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
863 @end multitable
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
864 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
865
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
866 Other Lisp objects, like symbols or hash tables, are not accepted as
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
867 input parameter.
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
868
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
869 If it is necessary to use another D-Bus type, a corresponding type
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
870 symbol can be preceeded to the corresponding Lisp object. Basic D-Bus
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
871 types are represented by the type symbols @code{:byte},
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
872 @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32},
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
873 @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double},
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
874 @code{:string}, @code{:object-path} and @code{:signature}.
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
875
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
876 @noindent
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
877 Example:
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
878
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
879 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
880 (dbus-call-method @dots{} @var{NUMBER} @var{STRING})
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
881 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
882
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
883 is equivalent to
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
884
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
885 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
886 (dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING})
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
887 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
888
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
889 but different to
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
890
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
891 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
892 (dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING})
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
893 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
894
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
895 The value for a byte D-Bus type can be any integer in the range 0
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
896 through 255. If a character is used as argument, modifiers
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
897 represented outside this range are stripped of. For example,
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
898 @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
899 @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
900
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
901 A D-Bus compound type is always represented as a list. The @sc{car}
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
902 of this list can be the type symbol @code{:array}, @code{:variant},
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
903 @code{:struct} or @code{:dict-entry}, which would result in a
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
904 corresponding D-Bus container. @code{:array} is optional, because
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
905 this is the default compound D-Bus type for a list.
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
906
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
907 The objects being elements of the list are checked according to the
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
908 D-Bus compound type rules.
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
909
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
910 @itemize
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
911 @item An array must contain only elements of the same D-Bus type. It
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
912 can be empty.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
913
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
914 @item A variant must contain only one single element.
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
915
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
916 @item A dictionary entry must be element of an array, and it must
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
917 contain only a key-value pair of two elements, with a basic D-Bus type
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
918 key.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
919
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
920 @item There is no restriction for structs.
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
921 @end itemize
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
922
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
923 If an empty array needs an element D-Bus type other than string, it
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
924 can contain exactly one element of D-Bus type @code{:signature}. The
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
925 value of this element (a string) is used as the signature of the
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
926 elements of this array. Example:
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
927
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
928 @lisp
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
929 (dbus-call-method
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
930 :session "org.freedesktop.Notifications"
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
931 "/org/freedesktop/Notifications"
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
932 "org.freedesktop.Notifications" "Notify"
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
933 "GNU Emacs" ;; Application name.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
934 0 ;; No replacement of other notifications.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
935 "" ;; No icon.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
936 "Notification summary" ;; Summary.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
937 (format ;; Body.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
938 "This is a test notification, raised from %s" (emacs-version))
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
939 '(:array) ;; No actions (empty array of strings).
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
940 '(:array :signature "@{sv@}") ;; No hints
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
941 ;; (empty array of dictionary entries).
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
942 ':int32 -1) ;; Default timeout.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
943
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
944 @result{} 3
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
945 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
946
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
947
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
948 @section Output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
949
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
950 Output parameters of D-Bus methods and signals are mapped to Lisp
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
951 objects.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
952
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
953 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
954 @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}}
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
955 @item D-Bus type @tab @tab Lisp type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
956 @item
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
957 @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil}
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
958 @item DBUS_TYPE_BYTE @tab @expansion{} @tab number
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
959 @item DBUS_TYPE_UINT16 @tab @expansion{} @tab number
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
960 @item DBUS_TYPE_INT16 @tab @expansion{} @tab number
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
961 @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
962 @item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
963 @item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
964 @item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
965 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
966 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
967 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
968 @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
969 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
970 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
971 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
972 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
973 @end multitable
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
974 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
975
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
976 A float object in case of @code{DBUS_TYPE_UINT32},
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
977 @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
978 @code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
979 Emacs number size range.
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
980
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
981 The resulting list of the last 4 D-Bus compound types contains as
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
982 elements the elements of the D-Bus container, mapped according to the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
983 same rules.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
984
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
985 The signal @code{PropertyModified}, discussed as example in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
986 @ref{Inspection}, would offer as Lisp data the following object
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
987 (@var{BOOL} stands here for either @code{nil} or @code{t}):
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
988
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
989 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
990 (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
991 @end lisp
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
992
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
993
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
994 @node Synchronous Methods
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
995 @chapter Calling methods in a blocking way.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
996 @cindex method calls, synchronous
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
997 @cindex synchronous method calls
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
998
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
999 Methods can be called synchronously (@dfn{blocking}) or asynchronously
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1000 (@dfn{non-blocking}). Currently, just synchronous methods are
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1001 implemented.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1002
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1003 At D-Bus level, a method call consist of two messages: one message
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1004 which carries the input parameters to the object owning the method to
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1005 be called, and a reply message returning the resulting output
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1006 parameters from the object.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1007
93422
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1008 @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1009 This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1010 either the symbol @code{:system} or the symbol @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1011
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1012 @var{service} is the D-Bus service name to be used. @var{path} is the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1013 D-Bus object path, @var{service} is registered at. @var{interface} is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1014 an interface offered by @var{service}. It must provide @var{method}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1015
93422
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1016 If the parameter @code{:timeout} is given, the following integer
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1017 @var{timeout} specifies the maximun number of milliseconds the method
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1018 call must return. The default value is 25.000. If the method call
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1019 doesn't return in time, a D-Bus error is raised (@pxref{Errors and
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1020 Events}).
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1021
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1022 All other arguments args are passed to @var{method} as arguments.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1023 They are converted into D-Bus types as described in @ref{Type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1024 Conversion}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1025
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1026 The function returns the resulting values of @var{method} as a list of
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1027 Lisp objects, according to the type conversion rules described in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1028 @ref{Type Conversion}. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1029
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1030 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1031 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1032 :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1033 "org.gnome.seahorse.Keys" "GetKeyField"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1034 "openpgp:657984B8C7A966DD" "simple-name")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1035
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1036 @result{} (t ("Philip R. Zimmermann"))
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1037 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1038
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1039 If the result of the method call is just one value, the converted Lisp
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1040 object is returned instead of a list containing this single Lisp
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1041 object. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1042
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1043 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1044 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1045 :system "org.freedesktop.Hal"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1046 "/org/freedesktop/Hal/devices/computer"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1047 "org.freedesktop.Hal.Device" "GetPropertyString"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1048 "system.kernel.machine")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1049
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1050 @result{} "i686"
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1051 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1052
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1053 With the @code{dbus-introspect} function it is possible to explore the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1054 interfaces of @samp{org.freedesktop.Hal} service. It offers the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1055 interfaces @samp{org.freedesktop.Hal.Manager} for the object at the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1056 path @samp{/org/freedesktop/Hal/Manager} as well as the interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1057 @samp{org.freedesktop.Hal.Device} for all objects prefixed with the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1058 path @samp{/org/freedesktop/Hal/devices}. With the methods
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1059 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1060 emulate the @code{lshal} command on GNU/Linux systems:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1061
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1062 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1063 (dolist (device
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1064 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1065 :system "org.freedesktop.Hal"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1066 "/org/freedesktop/Hal/Manager"
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1067 "org.freedesktop.Hal.Manager" "GetAllDevices"))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1068 (message "\nudi = %s" device)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1069 (dolist (properties
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1070 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1071 :system "org.freedesktop.Hal" device
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1072 "org.freedesktop.Hal.Device" "GetAllProperties"))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1073 (message " %s = %S"
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1074 (car properties) (or (caar (cdr properties)) ""))))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1075
87004
0877a1d16074 * Makefile.in (INFO_TARGETS, DVI_TARGETS): Apply dbus and dbus.dvi
Michael Albinus <michael.albinus@gmx.de>
parents: 86972
diff changeset
1076 @print{} "udi = /org/freedesktop/Hal/devices/computer
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1077 info.addons = (\"hald-addon-acpi\")
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1078 info.bus = \"unknown\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1079 info.product = \"Computer\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1080 info.subsystem = \"unknown\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1081 info.udi = \"/org/freedesktop/Hal/devices/computer\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1082 linux.sysfs_path_device = \"(none)\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1083 power_management.acpi.linux.version = \"20051216\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1084 power_management.can_suspend_to_disk = t
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1085 power_management.can_suspend_to_ram = \"\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1086 power_management.type = \"acpi\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1087 smbios.bios.release_date = \"11/07/2001\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1088 system.chassis.manufacturer = \"COMPAL\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1089 system.chassis.type = \"Notebook\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
1090 system.firmware.release_date = \"03/19/2005\"
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1091 @dots{}"
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1092 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1093 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1094
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1095
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1096 @node Receiving Method Calls
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1097 @chapter Offering own methods.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1098 @cindex method calls, returning
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1099 @cindex returning method calls
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1100
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1101 Emacs can also offer own methods, which can be called by other
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1102 applications. These methods could be an implementation of an
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1103 interface of a well known service, like @samp{org.freedesktop.TextEditor}.
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1104
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1105 It could be also an implementation of an own interface. In this case,
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1106 the service name must be @samp{org.gnu.Emacs}. The object path shall
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1107 begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1108 interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1109 @samp{@strong{Application}} is the name of the application which
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1110 provides the interface.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1111
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1112 @defun dbus-register-method bus service path interface method handler
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1113 With this function, an application registers @var{method} on the D-Bus
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1114 @var{bus}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1115
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1116 @var{bus} is either the symbol @code{:system} or the symbol
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1117 @code{:session}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1118
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1119 @var{service} is the D-Bus service name of the D-Bus object
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1120 @var{method} is registered for. It must be a known name.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1121
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1122 @var{path} is the D-Bus object path @var{service} is
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1123 registered.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1124
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1125 @var{interface} is the interface offered by @var{service}. It must
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1126 provide @var{method}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1127
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1128 @var{handler} is a Lisp function to be called when when a @var{method}
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1129 call is is received. It must accept as arguments the input arguments
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1130 of @var{method}. @var{handler} must return a list, which elements are
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1131 used as arguments for the reply message of @var{method}. This list
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1132 can be composed like the input parameters in @ref{Type Conversion}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1133
93130
83be756929f1 * dbus.texi (Receiving Method Calls): Mention default D-Bus timeout.
Michael Albinus <michael.albinus@gmx.de>
parents: 91590
diff changeset
1134 The default D-Bus timeout when waiting for a message reply is 25
93422
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1135 seconds. This value could be even smaller, depending on the calling
d2f671c73132 * dbus.texi (Synchronous Methods): New parameter TIMEOUT for
Michael Albinus <michael.albinus@gmx.de>
parents: 93130
diff changeset
1136 client. Therefore, @var{handler} shall not last longer than
93130
83be756929f1 * dbus.texi (Receiving Method Calls): Mention default D-Bus timeout.
Michael Albinus <michael.albinus@gmx.de>
parents: 91590
diff changeset
1137 absolutely necessary.
83be756929f1 * dbus.texi (Receiving Method Calls): Mention default D-Bus timeout.
Michael Albinus <michael.albinus@gmx.de>
parents: 91590
diff changeset
1138
96646
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1139 @code{dbus-register-method} returns a Lisp object, which can be used
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1140 as argument in @code{dbus-unregister-object} for removing the
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1141 registration for @var{method}. Example:
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1142
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1143 @lisp
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1144 (defun my-dbus-method-handler (filename)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1145 (let (result)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1146 (if (find-file filename)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1147 (setq result '(:boolean t))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1148 (setq result '(:boolean nil)))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1149 result))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1150
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1151 @result{} my-dbus-method-handler
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1152
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1153 (dbus-register-method
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1154 :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1155 "org.freedesktop.TextEditor" "OpenFile"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1156 'my-dbus-method-handler)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1157
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1158 @result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1159 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1160 my-method-handler))
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1161 @end lisp
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1162
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1163 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1164 from another D-Bus application with a filename as parameter, the file
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1165 is opened in Emacs, and the method returns either @var{true} or
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1166 @var{false}, indicating the success if the method. As test tool one
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1167 could use the command line tool @code{dbus-send} in a shell:
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1168
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1169 @example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1170 # dbus-send --session --print-reply \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1171 --dest="org.freedesktop.TextEditor" \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1172 "/org/freedesktop/TextEditor" \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1173 "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1174
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1175 @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1176 boolean true
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1177 @end example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1178 @end defun
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1179
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1180
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1181 @node Signals
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1182 @chapter Sending and receiving signals.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1183 @cindex signals
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1184
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1185 Signals are broadcast messages. They carry input parameters, which
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1186 are received by all objects which have registered for such a signal.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1187
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1188 @defun dbus-send-signal bus service path interface signal &rest args
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1189 This function is similar to @code{dbus-call-method}. The difference
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1190 is, that there are no returning output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1191
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1192 The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1193 either the symbol @code{:system} or the symbol @code{:session}. It
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1194 doesn't matter whether another object has registered for @var{signal}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1195
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1196 @var{service} is the D-Bus service name of the object the signal is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1197 emitted from. @var{path} is the corresponding D-Bus object path,
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1198 @var{service} is registered at. @var{interface} is an interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1199 offered by @var{service}. It must provide @var{signal}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1200
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1201 All other arguments args are passed to @var{signal} as arguments.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1202 They are converted into D-Bus types as described in @ref{Type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1203 Conversion}. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1204
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1205 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1206 (dbus-send-signal
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1207 :session "org.gnu.Emacs" "/org/gnu/Emacs"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1208 "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1209 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1210 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1211
96646
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1212 @defun dbus-register-signal bus service path interface signal handler &rest args
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1213 With this function, an application registers for @var{signal} on the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1214 D-Bus @var{bus}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1215
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1216 @var{bus} is either the symbol @code{:system} or the symbol
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1217 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1218
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1219 @var{service} is the D-Bus service name used by the sending D-Bus
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1220 object. It can be either a known name or the unique name of the D-Bus
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1221 object sending the signal. In case of a unique name, signals won't be
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1222 received any longer once the object owning this unique name has
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1223 disappeared, and a new queued object has replaced it.
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1224
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1225 When @var{service} is @code{nil}, related signals from all D-Bus
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1226 objects shall be accepted.
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1227
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1228 @var{path} is the corresponding D-Bus object path, @var{service} is
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1229 registered at. It can also be @code{nil} if the path name of incoming
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1230 signals shall not be checked.
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1231
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1232 @var{interface} is an interface offered by @var{service}. It must
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1233 provide @var{signal}.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1234
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1235 @var{handler} is a Lisp function to be called when the @var{signal} is
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1236 received. It must accept as arguments the output parameters
96646
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1237 @var{signal} is sending.
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1238
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1239 All other arguments @var{args}, if specified, must be strings. They
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1240 stand for the respective arguments of @var{signal} in their order, and
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1241 are used for filtering as well. A @code{nil} argument might be used
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1242 to preserve the order.
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1243
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1244 @code{dbus-register-signal} returns a Lisp object, which can be used
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1245 as argument in @code{dbus-unregister-object} for removing the
5e58654e97ff * dbus.texi (Receiving Method Calls): Fix description of
Michael Albinus <michael.albinus@gmx.de>
parents: 95937
diff changeset
1246 registration for @var{signal}. Example:
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1247
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1248 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1249 (defun my-dbus-signal-handler (device)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1250 (message "Device %s added" device))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1251
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1252 @result{} my-dbus-signal-handler
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1253
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1254 (dbus-register-signal
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1255 :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1256 "org.freedesktop.Hal.Manager" "DeviceAdded"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1257 'my-dbus-signal-handler)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1258
87309
44eebe469b1f * dbus.texi (Signals): Fix example in dbus-register-signal.
Michael Albinus <michael.albinus@gmx.de>
parents: 87158
diff changeset
1259 @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded")
44eebe469b1f * dbus.texi (Signals): Fix example in dbus-register-signal.
Michael Albinus <michael.albinus@gmx.de>
parents: 87158
diff changeset
1260 ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
44eebe469b1f * dbus.texi (Signals): Fix example in dbus-register-signal.
Michael Albinus <michael.albinus@gmx.de>
parents: 87158
diff changeset
1261 my-signal-handler))
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1262 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1263
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1264 As we know from the introspection data of interface
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1265 @samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded}
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1266 provides one single parameter, which is mapped into a Lisp string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1267 The callback function @code{my-dbus-signal-handler} must define one
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1268 single string argument therefore. Plugging an USB device to your
96802
de3f169b53eb * dbus.texi (Inspection): Rework, introduce submenus.
Michael Albinus <michael.albinus@gmx.de>
parents: 96646
diff changeset
1269 machine, when registered for signal @samp{DeviceAdded}, will show you
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1270 which objects the GNU/Linux @code{hal} daemon adds.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1271 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1272
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1273 @defun dbus-unregister-object object
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1274 Unregister @var{object} from the the D-Bus. @var{object} must be the
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1275 result of a preceding @code{dbus-register-signal} or
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1276 @code{dbus-register-method} call. It returns @code{t} if @var{object}
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1277 has been unregistered, @code{nil} otherwise.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1278 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1279
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1280
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1281 @node Errors and Events
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1282 @chapter Errors and events.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1283 @cindex errors
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1284 @cindex events
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1285
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
1286 Input parameters of @code{dbus-call-method} and
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
1287 @code{dbus-register-signal} are checked for correct D-Bus types. If
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
1288 there is a type mismatch, the Lisp error @code{wrong-type-argument}
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
1289 @code{D-Bus ARG} is raised.
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
1290
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1291 All errors raised by D-Bus are signaled with the error symbol
87883
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1292 @code{dbus-error}. If possible, error messages from D-Bus are
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1293 appended to the @code{dbus-error}.
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1294
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1295 @defspec dbus-ignore-errors forms@dots{}
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1296 This executes @var{forms} exactly like a @code{progn}, except that
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1297 @code{dbus-error} errors are ignored during the @var{forms}. These
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1298 errors can be made visible when variable @code{dbus-debug} is set to
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1299 @code{t}.
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
1300 @end defspec
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1301
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1302 Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1303 Events, , , elisp}). The generated event has this form:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1304
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1305 @lisp
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1306 (dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} &rest @var{args})
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1307 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1308
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1309 @var{bus} identifies the D-Bus the signal is coming from. It is
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
1310 either the symbol @code{:system} or the symbol @code{:session}.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1311
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1312 @var{serial} is the serial number of the received D-Bus message if it
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1313 is a method call, or @code{nil}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1314
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1315 @var{service} and @var{path} are the unique name and the object path
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1316 of the D-Bus object emitting the message. @var{interface} and
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1317 @var{member} denote the message which has been sent.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1318
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1319 @var{handler} is the callback function which has been registered for
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1320 this message (see @pxref{Signals}). When a @code{dbus-event} event
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1321 arrives, @var{handler} is called with @var{args} as arguments.
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
1322
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1323 In order to inspect the @code{dbus-event} data, you could extend the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1324 definition of the callback function in @ref{Signals}:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1325
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1326 @lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1327 (defun my-dbus-signal-handler (&rest args)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1328 (message "my-dbus-signal-handler: %S" last-input-event))
91590
6834ec860aff * dbus.texi (all): Wrap Lisp code examples with @lisp ... @end lisp.
Michael Albinus <michael.albinus@gmx.de>
parents: 87883
diff changeset
1329 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1330
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1331 There exist convenience functions which could be called inside a
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1332 callback function in order to retrieve the information from the event.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1333
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1334 @defun dbus-event-bus-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1335 Returns the bus name @var{event} is coming from.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1336 The result is either the symbol @code{:system} or the symbol @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1337 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1338
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1339 @defun dbus-event-serial-number event
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1340 Returns the serial number of the corresponding D-Bus message.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1341 The result is a number in case the D-Bus message is a method
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1342 call, or @code{nil} for all other mesage types.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1343 @end defun
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
1344
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1345 @defun dbus-event-service-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1346 Returns the unique name of the D-Bus object @var{event} is coming from.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1347 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1348
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1349 @defun dbus-event-path-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1350 Returns the object path of the D-Bus object @var{event} is coming from.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1351 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1352
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1353 @defun dbus-event-interface-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1354 Returns the interface name of of the D-Bus object @var{event} is coming from.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1355 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1356
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1357 @defun dbus-event-member-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1358 Returns the member name of of the D-Bus object @var{event} is coming
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1359 from. It is either a signal name or a method name.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1360 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1361
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1362 D-Bus errors are not propagated during event handling, because it is
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1363 usually not desired. D-Bus errors in events can be made visible by
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1364 setting the variable @code{dbus-debug} to @code{t}.
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
1365
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1366
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1367 @node GNU Free Documentation License
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1368 @appendix GNU Free Documentation License
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1369 @include doclicense.texi
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1370
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1371 @contents
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1372 @c End of dbus.texi
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
1373 @bye
87053
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
1374
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
1375 @ignore
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
1376 arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
1377 @end ignore