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