Commit | Line | Data |
---|---|---|
22d8ac3a | 1 | \input texinfo @c -*-texinfo-*- |
29993416 | 2 | @setfilename ../../info/dbus.info |
22d8ac3a MA |
3 | @c %**start of header |
4 | @settitle Using of D-Bus | |
c6ab4664 | 5 | @documentencoding UTF-8 |
22d8ac3a MA |
6 | @c @setchapternewpage odd |
7 | @c %**end of header | |
8 | ||
5bd55c3c MA |
9 | @syncodeindex vr cp |
10 | @syncodeindex fn cp | |
11 | ||
22d8ac3a | 12 | @copying |
6bc383b1 | 13 | Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. |
22d8ac3a MA |
14 | |
15 | @quotation | |
16 | Permission is granted to copy, distribute and/or modify this document | |
6a2c4aec | 17 | under the terms of the GNU Free Documentation License, Version 1.3 or |
22d8ac3a | 18 | any later version published by the Free Software Foundation; with no |
551a89e1 | 19 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', |
debf4439 GM |
20 | and with the Back-Cover Texts as in (a) below. A copy of the license |
21 | is included in the section entitled ``GNU Free Documentation License''. | |
22d8ac3a | 22 | |
6f093307 | 23 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
6bf430d1 | 24 | modify this GNU manual.'' |
22d8ac3a MA |
25 | @end quotation |
26 | @end copying | |
27 | ||
0c973505 | 28 | @dircategory Emacs lisp libraries |
22d8ac3a MA |
29 | @direntry |
30 | * D-Bus: (dbus). Using D-Bus in Emacs. | |
31 | @end direntry | |
32 | ||
4a970ff5 GM |
33 | @titlepage |
34 | @title Using D-Bus in Emacs | |
35 | @page | |
36 | @vskip 0pt plus 1filll | |
37 | @insertcopying | |
38 | @end titlepage | |
39 | ||
40 | ||
5dc584b5 | 41 | @contents |
cd71b9ae | 42 | |
977640ed | 43 | |
22d8ac3a MA |
44 | @node Top, Overview, (dir), (dir) |
45 | @top D-Bus integration in Emacs | |
46 | ||
78176e69 MA |
47 | This manual documents an API for usage of D-Bus in Emacs. D-Bus is a |
48 | message bus system, a simple way for applications to talk to one | |
49 | another. An overview of D-Bus can be found at | |
50 | @uref{http://dbus.freedesktop.org/}. | |
22d8ac3a | 51 | |
5dc584b5 | 52 | @ifnottex |
22d8ac3a | 53 | @insertcopying |
5dc584b5 | 54 | @end ifnottex |
22d8ac3a MA |
55 | |
56 | @menu | |
57 | * Overview:: An overview of D-Bus. | |
cd71b9ae | 58 | * Inspection:: Inspection of D-Bus services. |
22d8ac3a MA |
59 | * Type Conversion:: Mapping Lisp types and D-Bus types. |
60 | * Synchronous Methods:: Calling methods in a blocking way. | |
21956b56 | 61 | * Asynchronous Methods:: Calling methods non-blocking. |
addb7f2e | 62 | * Receiving Method Calls:: Offering own methods. |
22d8ac3a | 63 | * Signals:: Sending and receiving signals. |
dcbf5805 | 64 | * Alternative Buses:: Alternative buses and environments. |
22d8ac3a | 65 | * Errors and Events:: Errors and events. |
5bd55c3c MA |
66 | * Index:: Index including concepts, functions, variables. |
67 | ||
22d8ac3a MA |
68 | * GNU Free Documentation License:: The license for this documentation. |
69 | @end menu | |
70 | ||
cd71b9ae | 71 | |
22d8ac3a MA |
72 | @node Overview |
73 | @chapter An overview of D-Bus | |
74 | @cindex overview | |
75 | ||
76 | D-Bus is an inter-process communication mechanism for applications | |
77 | residing on the same host. The communication is based on | |
78 | @dfn{messages}. Data in the messages is carried in a structured way, | |
79 | it is not just a byte stream. | |
80 | ||
81 | The communication is connection oriented to two kinds of message | |
82 | buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a | |
83 | given machine, there is always one single system bus for miscellaneous | |
84 | system-wide communication, like changing of hardware configuration. | |
85 | On the other hand, the session bus is always related to a single | |
86 | user's session. | |
87 | ||
88 | Every client application, which is connected to a bus, registers under | |
89 | a @dfn{unique name} at the bus. This name is used for identifying the | |
90 | client application. Such a unique name starts always with a colon, | |
91 | and looks like @samp{:1.42}. | |
92 | ||
93 | Additionally, a client application can register itself to a so called | |
94 | @dfn{known name}, which is a series of identifiers separated by dots, | |
7ef92bc9 | 95 | as in @samp{org.gnu.Emacs}. If several applications register to the |
22d8ac3a MA |
96 | same known name, these registrations are queued, and only the first |
97 | application which has registered for the known name is reachable via | |
98 | this name. If this application disconnects from the bus, the next | |
99 | queued unique name becomes the owner of this known name. | |
100 | ||
101 | An application can install one or several objects under its name. | |
102 | Such objects are identified by an @dfn{object path}, which looks | |
103 | similar to paths in a filesystem. An example of such an object path | |
104 | could be @samp{/org/gnu/Emacs/}. | |
105 | ||
106 | Applications might send a request to an object, that means sending a | |
107 | message with some data as input parameters, and receiving a message | |
108 | from that object with the result of this message, the output | |
109 | parameters. Such a request is called @dfn{method} in D-Bus. | |
110 | ||
111 | The other form of communication are @dfn{signals}. The underlying | |
112 | message is emitted from an object and will be received by all other | |
113 | applications which have registered for such a signal. | |
114 | ||
115 | All methods and signals an object supports are called @dfn{interface} | |
116 | of the object. Interfaces are specified under a hierarchical name in | |
117 | D-Bus; an object can support several interfaces. Such an interface | |
118 | name could be @samp{org.gnu.Emacs.TextEditor} or | |
119 | @samp{org.gnu.Emacs.FileManager}. | |
120 | ||
121 | ||
122 | @node Inspection | |
cd71b9ae | 123 | @chapter Inspection of D-Bus services. |
22d8ac3a MA |
124 | @cindex inspection |
125 | ||
cd71b9ae | 126 | @menu |
dcbf5805 | 127 | * Version:: Determining the D-Bus version. |
cd71b9ae MA |
128 | * Bus names:: Discovering D-Bus names. |
129 | * Introspection:: Knowing the details of D-Bus services. | |
130 | * Nodes and Interfaces:: Detecting object paths and interfaces. | |
131 | * Methods and Signal:: Applying the functionality. | |
132 | * Properties and Annotations:: What else to know about interfaces. | |
133 | * Arguments and Signatures:: The final details. | |
134 | @end menu | |
135 | ||
136 | ||
dcbf5805 MA |
137 | @node Version |
138 | @section D-Bus version. | |
139 | ||
140 | D-Bus has evolved over the years. New features have been added with | |
141 | new D-Bus versions. There are two variables, which allow to determine | |
142 | the used D-Bus version. | |
143 | ||
144 | @defvar dbus-compiled-version | |
145 | This variable, a string, determines the version of D-Bus Emacs is | |
146 | compiled against. If it cannot be determined the value is @code{nil}. | |
147 | @end defvar | |
148 | ||
149 | @defvar dbus-runtime-version | |
150 | The other D-Bus version to be checked is the version of D-Bus Emacs | |
151 | runs with. This string can be different from @code{dbus-compiled-version}. | |
152 | It is also @code{nil}, if it cannot be determined at runtime. | |
153 | @end defvar | |
154 | ||
155 | ||
cd71b9ae MA |
156 | @node Bus names |
157 | @section Bus names. | |
158 | ||
22d8ac3a MA |
159 | There are several basic functions which inspect the buses for |
160 | registered names. Internally they use the basic interface | |
161 | @samp{org.freedesktop.DBus}, which is supported by all objects of a bus. | |
162 | ||
1ff98217 MA |
163 | @defun dbus-list-activatable-names &optional bus |
164 | This function returns the D-Bus service names, which can be activated | |
165 | for @var{bus}. It must be either the symbol @code{:system} (the | |
166 | default) or the symbol @code{:session}. An activatable service is | |
167 | described in a service registration file. Under GNU/Linux, such files | |
168 | are located at @file{/usr/share/dbus-1/system-services/} (for the | |
169 | @code{:system} bus) or @file{/usr/share/dbus-1/services/}. An | |
170 | activatable service is not necessarily registered at @var{bus} at already. | |
22d8ac3a MA |
171 | |
172 | The result is a list of strings, which is @code{nil} when there are no | |
1ff98217 MA |
173 | activatable service names at all. Example: |
174 | ||
175 | @lisp | |
176 | ;; Check, whether the document viewer can be accessed via D-Bus. | |
177 | (member "org.gnome.evince.Daemon" | |
178 | (dbus-list-activatable-names :session)) | |
179 | @end lisp | |
22d8ac3a MA |
180 | @end defun |
181 | ||
182 | @defun dbus-list-names bus | |
22d8ac3a MA |
183 | All service names, which are registered at D-Bus @var{bus}, are |
184 | returned. The result is a list of strings, which is @code{nil} when | |
185 | there are no registered service names at all. Well known names are | |
186 | strings like @samp{org.freedesktop.DBus}. Names starting with | |
187 | @samp{:} are unique names for services. | |
188 | ||
189 | @var{bus} must be either the symbol @code{:system} or the symbol | |
190 | @code{:session}. | |
191 | @end defun | |
192 | ||
193 | @defun dbus-list-known-names bus | |
1ff98217 | 194 | Retrieves all registered services which correspond to a known name in @var{bus}. |
22d8ac3a MA |
195 | A service has a known name if it doesn't start with @samp{:}. The |
196 | result is a list of strings, which is @code{nil} when there are no | |
197 | known names at all. | |
198 | ||
199 | @var{bus} must be either the symbol @code{:system} or the symbol | |
200 | @code{:session}. | |
201 | @end defun | |
202 | ||
203 | @defun dbus-list-queued-owners bus service | |
22d8ac3a MA |
204 | For a given service, registered at D-Bus @var{bus} under the name |
205 | @var{service}, all queued unique names are returned. The result is a | |
206 | list of strings, or @code{nil} when there are no queued names for | |
207 | @var{service} at all. | |
208 | ||
209 | @var{bus} must be either the symbol @code{:system} or the symbol | |
210 | @code{:session}. @var{service} must be a known service name as | |
211 | string. | |
212 | @end defun | |
213 | ||
214 | @defun dbus-get-name-owner bus service | |
22d8ac3a | 215 | For a given service, registered at D-Bus @var{bus} under the name |
06c0751a MA |
216 | @var{service}, the unique name of the name owner is returned. The |
217 | result is a string, or @code{nil} when there exist no name owner of | |
218 | @var{service}. | |
22d8ac3a MA |
219 | |
220 | @var{bus} must be either the symbol @code{:system} or the symbol | |
221 | @code{:session}. @var{service} must be a known service name as | |
222 | string. | |
223 | @end defun | |
224 | ||
ecd3d54f | 225 | @defun dbus-ping bus service &optional timeout |
06c0751a | 226 | Check whether the service name @var{service} is registered at D-Bus |
ecd3d54f MA |
227 | @var{bus}. @var{service} might not have been started yet, it is |
228 | autostarted if possible. The result is either @code{t} or @code{nil}. | |
06c0751a MA |
229 | |
230 | @var{bus} must be either the symbol @code{:system} or the symbol | |
ecd3d54f MA |
231 | @code{:session}. @var{service} must be a string. @var{timeout}, a |
232 | nonnegative integer, specifies the maximum number of milliseconds | |
233 | @code{dbus-ping} must return. The default value is 25,000. Example: | |
06c0751a MA |
234 | |
235 | @lisp | |
236 | (message | |
237 | "%s screensaver on board." | |
238 | (cond | |
ecd3d54f MA |
239 | ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome") |
240 | ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE") | |
06c0751a MA |
241 | (t "No"))) |
242 | @end lisp | |
ecd3d54f MA |
243 | |
244 | If it shall be checked whether @var{service} is already running | |
245 | without autostarting it, one shall apply | |
246 | ||
247 | @lisp | |
248 | (member service (dbus-list-known-names bus)) | |
249 | @end lisp | |
06c0751a MA |
250 | @end defun |
251 | ||
22d8ac3a | 252 | @defun dbus-get-unique-name bus |
22d8ac3a MA |
253 | The unique name, under which Emacs is registered at D-Bus @var{bus}, |
254 | is returned as string. | |
255 | ||
256 | @var{bus} must be either the symbol @code{:system} or the symbol | |
257 | @code{:session}. | |
258 | @end defun | |
259 | ||
cd71b9ae MA |
260 | |
261 | @node Introspection | |
262 | @section Knowing the details of D-Bus services. | |
263 | ||
264 | D-Bus services publish their interfaces. This can be retrieved and | |
265 | analyzed during runtime, in order to understand the used | |
266 | implementation. | |
267 | ||
268 | The resulting introspection data are in XML format. The root | |
269 | introspection element is always a @code{node} element. It might have | |
270 | a @code{name} attribute, which denotes the (absolute) object path an | |
271 | interface is introspected. | |
272 | ||
273 | The root @code{node} element may have @code{node} and @code{interface} | |
274 | children. A child @code{node} element must have a @code{name} | |
275 | attribute, this case it is the relative object path to the root | |
276 | @code{node} element. | |
277 | ||
278 | An @code{interface} element has just one attribute, @code{name}, which | |
279 | is the full name of that interface. The default interface | |
280 | @samp{org.freedesktop.DBus.Introspectable} is always present. Example: | |
281 | ||
282 | @example | |
283 | <node name="/org/bluez"> | |
284 | <interface name="org.freedesktop.DBus.Introspectable"> | |
285 | @dots{} | |
286 | </interface> | |
287 | <interface name="org.bluez.Manager"> | |
288 | @dots{} | |
289 | </interface> | |
290 | <interface name="org.bluez.Database"> | |
291 | @dots{} | |
292 | </interface> | |
293 | <interface name="org.bluez.Security"> | |
294 | @dots{} | |
295 | </interface> | |
296 | <node name="service_audio"/> | |
297 | <node name="service_input"/> | |
298 | <node name="service_network"/> | |
299 | <node name="service_serial"/> | |
300 | </node> | |
301 | @end example | |
302 | ||
303 | Children of an @code{interface} element can be @code{method}, | |
304 | @code{signal} and @code{property} elements. A @code{method} element | |
305 | stands for a D-Bus method of the surrounding interface. The element | |
306 | itself has a @code{name} attribute, showing the method name. Children | |
307 | elements @code{arg} stand for the arguments of a method. Example: | |
308 | ||
309 | @example | |
310 | <method name="ResolveHostName"> | |
311 | <arg name="interface" type="i" direction="in"/> | |
312 | <arg name="protocol" type="i" direction="in"/> | |
313 | <arg name="name" type="s" direction="in"/> | |
314 | <arg name="aprotocol" type="i" direction="in"/> | |
315 | <arg name="flags" type="u" direction="in"/> | |
316 | <arg name="interface" type="i" direction="out"/> | |
317 | <arg name="protocol" type="i" direction="out"/> | |
318 | <arg name="name" type="s" direction="out"/> | |
319 | <arg name="aprotocol" type="i" direction="out"/> | |
320 | <arg name="address" type="s" direction="out"/> | |
321 | <arg name="flags" type="u" direction="out"/> | |
322 | </method> | |
323 | @end example | |
324 | ||
325 | @code{arg} elements can have the attributes @code{name}, @code{type} | |
326 | and @code{direction}. The @code{name} attribute is optional. The | |
327 | @code{type} attribute stands for the @dfn{signature} of the argument | |
328 | in D-Bus. For a discussion of D-Bus types and their Lisp | |
329 | representation see @ref{Type Conversion}.@footnote{D-Bus signatures | |
330 | are explained in the D-Bus specification | |
331 | @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.} | |
332 | The @code{direction} attribute of an @code{arg} element can be only | |
333 | @samp{in} or @samp{out}; in case it is omitted, it defaults to | |
334 | @samp{in}. | |
335 | ||
336 | A @code{signal} element of an @code{interface} has a similar | |
337 | structure. The @code{direction} attribute of an @code{arg} child | |
338 | element can be only @samp{out} here; which is also the default value. | |
339 | Example: | |
340 | ||
341 | @example | |
342 | <signal name="StateChanged"> | |
343 | <arg name="state" type="i"/> | |
344 | <arg name="error" type="s"/> | |
345 | </signal> | |
346 | @end example | |
347 | ||
348 | A @code{property} element has no @code{arg} child | |
349 | element. It just has the attributes @code{name}, @code{type} and | |
350 | @code{access}, which are all mandatory. The @code{access} attribute | |
351 | allows the values @samp{readwrite}, @samp{read}, and @samp{write}. | |
352 | Example: | |
353 | ||
354 | @example | |
355 | <property name="Status" type="u" direction="read"/> | |
356 | @end example | |
357 | ||
358 | @code{annotation} elements can be children of @code{interface}, | |
359 | @code{method}, @code{signal}, and @code{property} elements. Unlike | |
360 | properties, which can change their values during lifetime of a D-Bus | |
361 | object, annotations are static. Often they are used for code | |
53964682 | 362 | generators of D-Bus language bindings. Example: |
cd71b9ae MA |
363 | |
364 | @example | |
365 | <annotation name="de.berlios.Pinot.GetStatistics" value="pinotDBus"/> | |
366 | @end example | |
367 | ||
368 | Annotations have just @code{name} and @code{value} attributes, both | |
369 | must be strings. | |
370 | ||
22d8ac3a | 371 | @defun dbus-introspect bus service path |
cd71b9ae MA |
372 | This function returns all interfaces and sub-nodes of @var{service}, |
373 | registered at object path @var{path} at bus @var{bus}. | |
22d8ac3a MA |
374 | |
375 | @var{bus} must be either the symbol @code{:system} or the symbol | |
376 | @code{:session}. @var{service} must be a known service name, and | |
377 | @var{path} must be a valid object path. The last two parameters are | |
378 | strings. The result, the introspection data, is a string in XML | |
cd71b9ae | 379 | format. Example: |
22d8ac3a | 380 | |
06c0751a | 381 | @lisp |
22d8ac3a MA |
382 | (dbus-introspect |
383 | :system "org.freedesktop.Hal" | |
384 | "/org/freedesktop/Hal/devices/computer") | |
385 | ||
d9e21158 | 386 | @result{} "<!DOCTYPE node PUBLIC |
cd71b9ae MA |
387 | "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" |
388 | "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> | |
d9e21158 | 389 | <node> |
cd71b9ae MA |
390 | <interface name="org.freedesktop.Hal.Device"> |
391 | <method name="GetAllProperties"> | |
392 | <arg name="properties" direction="out" type="a@{sv@}"/> | |
d9e21158 | 393 | </method> |
c9ecb5a7 | 394 | @dots{} |
cd71b9ae MA |
395 | <signal name="PropertyModified"> |
396 | <arg name="num_updates" type="i"/> | |
397 | <arg name="updates" type="a(sbb)"/> | |
d9e21158 MA |
398 | </signal> |
399 | </interface> | |
c9ecb5a7 | 400 | @dots{} |
d9e21158 | 401 | </node>" |
06c0751a | 402 | @end lisp |
22d8ac3a | 403 | |
cd71b9ae MA |
404 | This example informs us, that the service @samp{org.freedesktop.Hal} |
405 | at object path @samp{/org/freedesktop/Hal/devices/computer} offers the | |
406 | interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces | |
22d8ac3a | 407 | not documented here). This interface contains the method |
cd71b9ae | 408 | @samp{GetAllProperties}, which needs no input parameters, but returns |
22d8ac3a MA |
409 | as output parameter an array of dictionary entries (key-value pairs). |
410 | Every dictionary entry has a string as key, and a variant as value. | |
411 | ||
412 | The interface offers also a signal, which returns 2 parameters: an | |
413 | integer, and an array consisting of elements which are a struct of a | |
cd71b9ae | 414 | string and 2 boolean values.@footnote{ The interfaces of the service |
97df87bb | 415 | @samp{org.freedesktop.Hal} are described in |
7964e6f9 GM |
416 | @c Previous link is gone. Since HAL is now obsolete, this URL |
417 | @c (unchanged in ~ 4 years) feels like it might go too... | |
97df87bb GM |
418 | @uref{http://people.freedesktop.org/~dkukawka/hal-spec-git/hal-spec.html#interfaces, |
419 | the HAL specification}.} | |
22d8ac3a MA |
420 | @end defun |
421 | ||
cd71b9ae MA |
422 | @defun dbus-introspect-xml bus service path |
423 | This function has the same intention as function | |
424 | @code{dbus-introspect}. The returned value is a parsed XML tree, | |
425 | which can be used for further analysis. Example: | |
426 | ||
427 | @lisp | |
428 | (dbus-introspect-xml | |
429 | :session "org.freedesktop.xesam.searcher" | |
430 | "/org/freedesktop/xesam/searcher/main") | |
431 | ||
432 | @result{} (node ((name . "/org/freedesktop/xesam/searcher/main")) | |
433 | (interface ((name . "org.freedesktop.xesam.Search")) | |
434 | (method ((name . "GetHitData")) | |
435 | (arg ((name . "search") (type . "s") (direction . "in"))) | |
436 | (arg ((name . "hit_ids") (type . "au") (direction . "in"))) | |
437 | (arg ((name . "fields") (type . "as") (direction . "in"))) | |
438 | (arg ((name . "hit_data") (type . "aav") (direction . "out"))) | |
439 | ) | |
440 | @dots{} | |
441 | (signal ((name . "HitsAdded")) | |
442 | (arg ((name . "search") (type . "s"))) | |
443 | (arg ((name . "count") (type . "u"))) | |
444 | ) | |
445 | ) | |
446 | @dots{} | |
447 | ) | |
448 | @end lisp | |
449 | @end defun | |
450 | ||
451 | @defun dbus-introspect-get-attribute object attribute | |
452 | It returns the @var{attribute} value of a D-Bus introspection | |
453 | @var{object}. @var{object} can be every subtree of a parsed XML tree | |
454 | as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be | |
455 | a string according to the attribute names in the D-Bus specification. | |
456 | Example: | |
457 | ||
458 | @lisp | |
459 | (dbus-introspect-get-attribute | |
460 | (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends" | |
461 | "/org/freedesktop/SystemToolsBackends/UsersConfig") | |
462 | "name") | |
463 | ||
464 | @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" | |
465 | @end lisp | |
466 | ||
5bd55c3c MA |
467 | If @var{object} has no @var{attribute}, the function returns |
468 | @code{nil}. | |
cd71b9ae MA |
469 | @end defun |
470 | ||
471 | ||
472 | @node Nodes and Interfaces | |
473 | @section Detecting object paths and interfaces. | |
474 | ||
475 | The first elements, to be introspected for a D-Bus object, are further | |
476 | object paths and interfaces. | |
477 | ||
478 | @defun dbus-introspect-get-node-names bus service path | |
479 | All node names of @var{service} in D-Bus @var{bus} at object path | |
480 | @var{path} are returned as list of strings. Example: | |
481 | ||
482 | @lisp | |
483 | (dbus-introspect-get-node-names | |
484 | :session "org.gnome.seahorse" "/org/gnome/seahorse") | |
485 | ||
486 | @result{} ("crypto" "keys") | |
487 | @end lisp | |
488 | ||
489 | The node names stand for further object paths of the D-Bus | |
490 | @var{service}, relative to @var{path}. In the example, | |
491 | @samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys} | |
492 | are also object paths of the D-Bus service @samp{org.gnome.seahorse}. | |
493 | @end defun | |
494 | ||
495 | @defun dbus-introspect-get-all-nodes bus service path | |
496 | This function returns all node names of @var{service} in D-Bus | |
497 | @var{bus} at object path @var{path}. It returns a list of strings | |
498 | with all object paths of @var{service}, starting at @var{path}. | |
499 | Example: | |
500 | ||
501 | @lisp | |
502 | (dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/") | |
503 | ||
504 | @result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse" | |
505 | "/org/gnome/seahorse/crypto" | |
506 | "/org/gnome/seahorse/keys" | |
507 | "/org/gnome/seahorse/keys/openpgp" | |
508 | "/org/gnome/seahorse/keys/openpgp/local" | |
509 | "/org/gnome/seahorse/keys/openssh" | |
510 | "/org/gnome/seahorse/keys/openssh/local") | |
511 | @end lisp | |
512 | @end defun | |
513 | ||
514 | @defun dbus-introspect-get-interface-names bus service path | |
515 | There will be returned a list strings of all interface names of | |
516 | @var{service} in D-Bus @var{bus} at object path @var{path}. This list | |
517 | will contain the default interface @samp{org.freedesktop.DBus.Introspectable}. | |
518 | ||
519 | Another default interface is @samp{org.freedesktop.DBus.Properties}. | |
520 | If present, @code{interface} elements can also have @code{property} | |
521 | children. Example: | |
522 | ||
523 | @lisp | |
524 | (dbus-introspect-get-interface-names | |
525 | :system "org.freedesktop.Hal" | |
526 | "/org/freedesktop/Hal/devices/computer") | |
527 | ||
528 | @result{} ("org.freedesktop.DBus.Introspectable" | |
529 | "org.freedesktop.Hal.Device" | |
530 | "org.freedesktop.Hal.Device.SystemPowerManagement" | |
531 | "org.freedesktop.Hal.Device.CPUFreq") | |
532 | @end lisp | |
533 | @end defun | |
534 | ||
535 | @defun dbus-introspect-get-interface bus service path interface | |
536 | Return @var{interface} of @var{service} in D-Bus @var{bus} at object | |
537 | path @var{path}. The return value is an XML element. @var{interface} | |
538 | must be a string, element of the list returned by | |
539 | @code{dbus-introspect-get-interface-names}. Example: | |
540 | ||
541 | @lisp | |
542 | (dbus-introspect-get-interface | |
543 | :session "org.freedesktop.xesam.searcher" | |
544 | "/org/freedesktop/xesam/searcher/main" | |
545 | "org.freedesktop.xesam.Search") | |
546 | ||
547 | @result{} (interface ((name . "org.freedesktop.xesam.Search")) | |
548 | (method ((name . "GetHitData")) | |
549 | (arg ((name . "search") (type . "s") (direction . "in"))) | |
550 | (arg ((name . "hit_ids") (type . "au") (direction . "in"))) | |
551 | (arg ((name . "fields") (type . "as") (direction . "in"))) | |
552 | (arg ((name . "hit_data") (type . "aav") (direction . "out"))) | |
553 | ) | |
554 | @dots{} | |
555 | (signal ((name . "HitsAdded")) | |
556 | (arg ((name . "search") (type . "s"))) | |
557 | (arg ((name . "count") (type . "u"))) | |
558 | ) | |
559 | ) | |
560 | @end lisp | |
561 | @end defun | |
562 | ||
563 | @noindent | |
564 | With these functions, it is possible to retrieve all introspection | |
565 | data from a running system: | |
566 | ||
567 | @lisp | |
568 | (with-current-buffer (switch-to-buffer "*introspect*") | |
569 | (erase-buffer) | |
570 | (dolist (service (dbus-list-known-names :session)) | |
571 | (dolist (path (dbus-introspect-get-all-nodes :session service "/")) | |
572 | ;; We want to introspect only elements, which have more than | |
573 | ;; the default interface "org.freedesktop.DBus.Introspectable". | |
574 | (when (delete | |
575 | "org.freedesktop.DBus.Introspectable" | |
576 | (dbus-introspect-get-interface-names :session service path)) | |
577 | (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path) | |
578 | (dbus-introspect :session service path)) | |
579 | (redisplay t))))) | |
580 | @end lisp | |
581 | ||
582 | ||
583 | @node Methods and Signal | |
584 | @section Applying the functionality. | |
585 | ||
da6062e6 | 586 | Methods and signals are the communication means to D-Bus. The |
cd71b9ae MA |
587 | following functions return their specifications. |
588 | ||
589 | @defun dbus-introspect-get-method-names bus service path interface | |
590 | Return a list of strings of all method names of @var{interface} of | |
591 | @var{service} in D-Bus @var{bus} at object path @var{path}. Example: | |
592 | ||
593 | @lisp | |
594 | (dbus-introspect-get-method-names | |
595 | :session "org.freedesktop.xesam.searcher" | |
596 | "/org/freedesktop/xesam/searcher/main" | |
597 | "org.freedesktop.xesam.Search") | |
598 | ||
599 | @result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession" | |
600 | "CloseSession" "GetHitData" "SetProperty" "NewSearch" | |
601 | "GetProperty" "CloseSearch") | |
602 | @end lisp | |
603 | @end defun | |
604 | ||
605 | @defun dbus-introspect-get-method bus service path interface method | |
606 | This function returns @var{method} of @var{interface} as XML element. | |
607 | It must be located at @var{service} in D-Bus @var{bus} at object path | |
608 | @var{path}. @var{method} must be a string, element of the list | |
609 | returned by @code{dbus-introspect-get-method-names}. Example: | |
610 | ||
611 | @lisp | |
612 | (dbus-introspect-get-method | |
613 | :session "org.freedesktop.xesam.searcher" | |
614 | "/org/freedesktop/xesam/searcher/main" | |
615 | "org.freedesktop.xesam.Search" "GetHitData") | |
616 | ||
617 | @result{} (method ((name . "GetHitData")) | |
618 | (arg ((name . "search") (type . "s") (direction . "in"))) | |
619 | (arg ((name . "hit_ids") (type . "au") (direction . "in"))) | |
620 | (arg ((name . "fields") (type . "as") (direction . "in"))) | |
621 | (arg ((name . "hit_data") (type . "aav") (direction . "out"))) | |
622 | ) | |
623 | @end lisp | |
624 | @end defun | |
625 | ||
626 | @defun dbus-introspect-get-signal-names bus service path interface | |
627 | Return a list of strings of all signal names of @var{interface} of | |
628 | @var{service} in D-Bus @var{bus} at object path @var{path}. Example: | |
629 | ||
630 | @lisp | |
631 | (dbus-introspect-get-signal-names | |
632 | :session "org.freedesktop.xesam.searcher" | |
633 | "/org/freedesktop/xesam/searcher/main" | |
634 | "org.freedesktop.xesam.Search") | |
635 | ||
636 | @result{} ("StateChanged" "SearchDone" "HitsModified" | |
637 | "HitsRemoved" "HitsAdded") | |
638 | @end lisp | |
639 | @end defun | |
640 | ||
641 | @defun dbus-introspect-get-signal bus service path interface signal | |
642 | This function returns @var{signal} of @var{interface} as XML element. | |
643 | It must be located at @var{service} in D-Bus @var{bus} at object path | |
644 | @var{path}. @var{signal} must be a string, element of the list | |
645 | returned by @code{dbus-introspect-get-signal-names}. Example: | |
646 | ||
647 | @lisp | |
648 | (dbus-introspect-get-signal | |
649 | :session "org.freedesktop.xesam.searcher" | |
650 | "/org/freedesktop/xesam/searcher/main" | |
651 | "org.freedesktop.xesam.Search" "HitsAdded") | |
652 | ||
653 | @result{} (signal ((name . "HitsAdded")) | |
654 | (arg ((name . "search") (type . "s"))) | |
655 | (arg ((name . "count") (type . "u"))) | |
656 | ) | |
657 | @end lisp | |
658 | @end defun | |
659 | ||
660 | ||
661 | @node Properties and Annotations | |
662 | @section What else to know about interfaces. | |
663 | ||
664 | Interfaces can have properties. These can be exposed via the | |
665 | @samp{org.freedesktop.DBus.Properties} interface@footnote{See | |
666 | @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}. | |
667 | That is, properties can be retrieved and changed during lifetime of an | |
668 | element. | |
669 | ||
dcbf5805 MA |
670 | A generalized interface is |
671 | @samp{org.freedesktop.DBus.Objectmanager}@footnote{See | |
672 | @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager}}, | |
673 | which returns objects, their interfaces and properties for a given | |
674 | service in just one call. | |
675 | ||
cd71b9ae MA |
676 | Annotations, on the other hand, are static values for an element. |
677 | Often, they are used to instruct generators, how to generate code from | |
678 | the interface for a given language binding. | |
679 | ||
680 | @defun dbus-introspect-get-property-names bus service path interface | |
681 | Return a list of strings with all property names of @var{interface} of | |
682 | @var{service} in D-Bus @var{bus} at object path @var{path}. Example: | |
683 | ||
684 | @lisp | |
685 | (dbus-introspect-get-property-names | |
686 | :session "org.kde.kded" "/modules/networkstatus" | |
687 | "org.kde.Solid.Networking.Client") | |
688 | ||
689 | @result{} ("Status") | |
690 | @end lisp | |
691 | ||
692 | If an interface declares properties, the corresponding element supports | |
693 | also the @samp{org.freedesktop.DBus.Properties} interface. | |
694 | @end defun | |
695 | ||
696 | @defun dbus-introspect-get-property bus service path interface property | |
697 | This function returns @var{property} of @var{interface} as XML element. | |
698 | It must be located at @var{service} in D-Bus @var{bus} at object path | |
699 | @var{path}. @var{property} must be a string, element of the list | |
700 | returned by @code{dbus-introspect-get-property-names}. | |
701 | ||
702 | A @var{property} value can be retrieved by the function | |
703 | @code{dbus-introspect-get-attribute}. Example: | |
704 | ||
705 | @lisp | |
706 | (dbus-introspect-get-property | |
707 | :session "org.kde.kded" "/modules/networkstatus" | |
708 | "org.kde.Solid.Networking.Client" "Status") | |
709 | ||
710 | @result{} (property ((access . "read") (type . "u") (name . "Status"))) | |
711 | ||
712 | (dbus-introspect-get-attribute | |
713 | (dbus-introspect-get-property | |
714 | :session "org.kde.kded" "/modules/networkstatus" | |
715 | "org.kde.Solid.Networking.Client" "Status") | |
716 | "access") | |
717 | ||
718 | @result{} "read" | |
719 | @end lisp | |
720 | @end defun | |
721 | ||
722 | @defun dbus-get-property bus service path interface property | |
723 | This function returns the value of @var{property} of @var{interface}. | |
724 | It will be checked at @var{bus}, @var{service}, @var{path}. The | |
5bd55c3c | 725 | result can be any valid D-Bus value, or @code{nil} if there is no |
cd71b9ae MA |
726 | @var{property}. Example: |
727 | ||
728 | @lisp | |
729 | (dbus-get-property | |
730 | :session "org.kde.kded" "/modules/networkstatus" | |
731 | "org.kde.Solid.Networking.Client" "Status") | |
732 | ||
733 | @result{} 4 | |
734 | @end lisp | |
735 | @end defun | |
736 | ||
737 | @defun dbus-set-property bus service path interface property value | |
738 | Set value of @var{property} of @var{interface} to @var{value}. It | |
739 | will be checked at @var{bus}, @var{service}, @var{path}. When the | |
740 | value has been set successful, the result is @var{value}. Otherwise, | |
741 | @code{nil} is returned. Example: | |
742 | ||
743 | @lisp | |
744 | (dbus-set-property | |
745 | :session "org.kde.kaccess" "/MainApplication" | |
746 | "com.trolltech.Qt.QApplication" "doubleClickInterval" 500) | |
747 | ||
748 | @result{} 500 | |
749 | @end lisp | |
750 | @end defun | |
751 | ||
752 | @defun dbus-get-all-properties bus service path interface | |
753 | This function returns all properties of @var{interface}. It will be | |
754 | checked at @var{bus}, @var{service}, @var{path}. The result is a list | |
755 | of cons. Every cons contains the name of the property, and its value. | |
756 | If there are no properties, @code{nil} is returned. Example: | |
757 | ||
758 | @lisp | |
759 | (dbus-get-all-properties | |
760 | :session "org.kde.kaccess" "/MainApplication" | |
761 | "com.trolltech.Qt.QApplication") | |
762 | ||
763 | @result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500) | |
764 | ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3) | |
765 | ("globalStrut" 0 0) ("startDragTime" . 500) | |
766 | ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t) | |
767 | ("styleSheet" . "")) | |
768 | @end lisp | |
769 | @end defun | |
770 | ||
dcbf5805 | 771 | @defun dbus-get-all-managed-objects bus service path |
36291308 | 772 | This function returns all objects at @var{bus}, @var{service}, |
dcbf5805 MA |
773 | @var{path}, and the children of @var{path}. The result is a list of |
774 | objects. Every object is a cons of an existing path name, and the | |
775 | list of available interface objects. An interface object is another | |
776 | cons, which car is the interface name, and the cdr is the list of | |
777 | properties as returned by @code{dbus-get-all-properties} for that path | |
778 | and interface. Example: | |
779 | ||
780 | @lisp | |
781 | (dbus-get-all-managed-objects | |
782 | :session "org.gnome.SettingsDaemon" "/") | |
783 | ||
784 | @result{} (("/org/gnome/SettingsDaemon/MediaKeys" | |
785 | ("org.gnome.SettingsDaemon.MediaKeys") | |
786 | ("org.freedesktop.DBus.Peer") | |
787 | ("org.freedesktop.DBus.Introspectable") | |
788 | ("org.freedesktop.DBus.Properties") | |
789 | ("org.freedesktop.DBus.ObjectManager")) | |
790 | ("/org/gnome/SettingsDaemon/Power" | |
791 | ("org.gnome.SettingsDaemon.Power.Keyboard") | |
792 | ("org.gnome.SettingsDaemon.Power.Screen") | |
793 | ("org.gnome.SettingsDaemon.Power" | |
794 | ("Icon" . ". GThemedIcon battery-full-charged-symbolic ") | |
795 | ("Tooltip" . "Laptop battery is charged")) | |
796 | ("org.freedesktop.DBus.Peer") | |
797 | ("org.freedesktop.DBus.Introspectable") | |
798 | ("org.freedesktop.DBus.Properties") | |
799 | ("org.freedesktop.DBus.ObjectManager")) | |
800 | @dots{}) | |
801 | @end lisp | |
802 | ||
803 | If possible, @samp{org.freedesktop.DBus.ObjectManager.GetManagedObjects} | |
804 | is used for retrieving the information. Otherwise, the information | |
805 | is collected via @samp{org.freedesktop.DBus.Introspectable.Introspect} | |
806 | and @samp{org.freedesktop.DBus.Properties.GetAll}, which is slow. | |
807 | ||
808 | An overview of all existing object paths, their interfaces and | |
809 | properties could be retrieved by the following code: | |
810 | ||
811 | @lisp | |
812 | (with-current-buffer (switch-to-buffer "*objectmanager*") | |
813 | (erase-buffer) | |
814 | (let (result) | |
815 | (dolist (service (dbus-list-known-names :session) result) | |
816 | (message "%s" service) | |
817 | (add-to-list | |
818 | 'result | |
819 | (cons service | |
820 | (dbus-get-all-managed-objects :session service "/")))) | |
821 | (insert (message "%s" (pp result))) | |
822 | (redisplay t))) | |
823 | @end lisp | |
824 | @end defun | |
825 | ||
cd71b9ae MA |
826 | @defun dbus-introspect-get-annotation-names bus service path interface &optional name |
827 | Return a list of all annotation names as list of strings. If | |
828 | @var{name} is @code{nil}, the annotations are children of | |
829 | @var{interface}, otherwise @var{name} must be a @code{method}, | |
830 | @code{signal}, or @code{property} XML element, where the annotations | |
831 | belong to. Example: | |
832 | ||
833 | @lisp | |
834 | (dbus-introspect-get-annotation-names | |
835 | :session "de.berlios.Pinot" "/de/berlios/Pinot" | |
836 | "de.berlios.Pinot" "GetStatistics") | |
837 | ||
838 | @result{} ("de.berlios.Pinot.GetStatistics") | |
839 | @end lisp | |
840 | ||
841 | Default annotation names@footnote{See | |
842 | @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}} | |
843 | are | |
844 | ||
845 | @table @samp | |
846 | @item org.freedesktop.DBus.Deprecated | |
847 | Whether or not the entity is deprecated; defaults to @code{nil} | |
848 | ||
849 | @item org.freedesktop.DBus.GLib.CSymbol | |
850 | The C symbol; may be used for @code{methods} and @code{interfaces} | |
851 | ||
852 | @item org.freedesktop.DBus.Method.NoReply | |
853 | If set, don't expect a reply to the @code{method} call; defaults to @code{nil} | |
854 | @end table | |
855 | @end defun | |
856 | ||
857 | @defun dbus-introspect-get-annotation bus service path interface name annotation | |
858 | Return annotation @var{ANNOTATION} as XML object. If @var{name} is | |
859 | @code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise | |
860 | @var{name} must be the name of a @code{method}, @code{signal}, or | |
861 | @code{property} XML element, where the @var{ANNOTATION} belongs to. | |
862 | ||
863 | An attribute value can be retrieved by | |
864 | @code{dbus-introspect-get-attribute}. Example: | |
865 | ||
866 | @lisp | |
867 | (dbus-introspect-get-annotation | |
868 | :session "de.berlios.Pinot" "/de/berlios/Pinot" | |
869 | "de.berlios.Pinot" "GetStatistics" | |
870 | "de.berlios.Pinot.GetStatistics") | |
871 | ||
872 | @result{} (annotation ((name . "de.berlios.Pinot.GetStatistics") | |
873 | (value . "pinotDBus"))) | |
874 | ||
875 | (dbus-introspect-get-attribute | |
876 | (dbus-introspect-get-annotation | |
877 | :session "de.berlios.Pinot" "/de/berlios/Pinot" | |
878 | "de.berlios.Pinot" "GetStatistics" | |
879 | "de.berlios.Pinot.GetStatistics") | |
880 | "value") | |
881 | ||
882 | @result{} "pinotDBus" | |
883 | @end lisp | |
884 | @end defun | |
885 | ||
886 | ||
887 | @node Arguments and Signatures | |
888 | @section The final details. | |
889 | ||
890 | Methods and signals have arguments. They are described in the | |
891 | @code{arg} XML elements. | |
892 | ||
893 | @defun dbus-introspect-get-argument-names bus service path interface name | |
894 | Return a list of all argument names as list of strings. @var{name} | |
895 | must be a @code{method} or @code{signal} XML element. Example: | |
896 | ||
897 | @lisp | |
898 | (dbus-introspect-get-argument-names | |
899 | :session "org.freedesktop.xesam.searcher" | |
900 | "/org/freedesktop/xesam/searcher/main" | |
901 | "org.freedesktop.xesam.Search" "GetHitData") | |
902 | ||
903 | @result{} ("search" "hit_ids" "fields" "hit_data") | |
904 | @end lisp | |
905 | ||
906 | Argument names are optional; the function can return @code{nil} | |
907 | therefore, even if the method or signal has arguments. | |
908 | @end defun | |
909 | ||
910 | @defun dbus-introspect-get-argument bus service path interface name arg | |
911 | Return argument @var{ARG} as XML object. @var{name} | |
912 | must be a @code{method} or @code{signal} XML element. Example: | |
913 | ||
914 | @lisp | |
915 | (dbus-introspect-get-argument | |
916 | :session "org.freedesktop.xesam.searcher" | |
917 | "/org/freedesktop/xesam/searcher/main" | |
918 | "org.freedesktop.xesam.Search" "GetHitData" "search") | |
919 | ||
920 | @result{} (arg ((name . "search") (type . "s") (direction . "in"))) | |
921 | @end lisp | |
922 | @end defun | |
923 | ||
924 | @defun dbus-introspect-get-signature bus service path interface name &optional direction | |
925 | Return signature of a @code{method} or @code{signal}, represented by | |
926 | @var{name}, as string. | |
927 | ||
928 | If @var{name} is a @code{method}, @var{direction} can be either | |
929 | @samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in} | |
930 | is assumed. | |
931 | ||
932 | If @var{name} is a @code{signal}, and @var{direction} is | |
933 | non-@code{nil}, @var{direction} must be @samp{out}. Example: | |
934 | ||
935 | @lisp | |
936 | (dbus-introspect-get-signature | |
937 | :session "org.freedesktop.xesam.searcher" | |
938 | "/org/freedesktop/xesam/searcher/main" | |
939 | "org.freedesktop.xesam.Search" "GetHitData" "in") | |
940 | ||
941 | @result{} "sauas" | |
942 | ||
943 | (dbus-introspect-get-signature | |
944 | :session "org.freedesktop.xesam.searcher" | |
945 | "/org/freedesktop/xesam/searcher/main" | |
946 | "org.freedesktop.xesam.Search" "HitsAdded") | |
947 | ||
21956b56 | 948 | @result{} "su" |
cd71b9ae MA |
949 | @end lisp |
950 | @end defun | |
951 | ||
22d8ac3a MA |
952 | |
953 | @node Type Conversion | |
954 | @chapter Mapping Lisp types and D-Bus types. | |
955 | @cindex type conversion | |
956 | ||
957 | D-Bus method calls and signals accept usually several arguments as | |
958 | parameters, either as input parameter, or as output parameter. Every | |
959 | argument belongs to a D-Bus type. | |
960 | ||
6a31c819 | 961 | Such arguments must be mapped between the value encoded as a D-Bus |
22d8ac3a MA |
962 | type, and the corresponding type of Lisp objects. The mapping is |
963 | applied Lisp object @expansion{} D-Bus type for input parameters, and | |
964 | D-Bus type @expansion{} Lisp object for output parameters. | |
965 | ||
966 | ||
967 | @section Input parameters. | |
968 | ||
969 | Input parameters for D-Bus methods and signals occur as arguments of a | |
6a31c819 | 970 | Lisp function call. The following mapping to D-Bus types is |
22d8ac3a MA |
971 | applied, when the corresponding D-Bus message is created: |
972 | ||
973 | @example | |
5bd55c3c | 974 | @multitable {negative integer} {@expansion{}} {DBUS_TYPE_BOOLEAN} |
22d8ac3a MA |
975 | @item Lisp type @tab @tab D-Bus type |
976 | @item | |
977 | @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN | |
5bd55c3c MA |
978 | @item natural number @tab @expansion{} @tab DBUS_TYPE_UINT32 |
979 | @item negative integer @tab @expansion{} @tab DBUS_TYPE_INT32 | |
22d8ac3a MA |
980 | @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE |
981 | @item string @tab @expansion{} @tab DBUS_TYPE_STRING | |
6a31c819 | 982 | @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY |
22d8ac3a MA |
983 | @end multitable |
984 | @end example | |
985 | ||
6a31c819 | 986 | Other Lisp objects, like symbols or hash tables, are not accepted as |
61cf3a76 | 987 | input parameters. |
6a31c819 MA |
988 | |
989 | If it is necessary to use another D-Bus type, a corresponding type | |
61cf3a76 | 990 | symbol can be prepended to the corresponding Lisp object. Basic D-Bus |
d4e67bc5 MA |
991 | types are represented by the type symbols @code{:byte}, |
992 | @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, | |
993 | @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, | |
6f8fc60c MA |
994 | @code{:string}, @code{:object-path}, @code{:signature} and |
995 | @code{:unix-fd}. | |
6a31c819 | 996 | |
22d8ac3a | 997 | @noindent |
6a31c819 MA |
998 | Example: |
999 | ||
1000 | @lisp | |
5bd55c3c | 1001 | (dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING}) |
6a31c819 MA |
1002 | @end lisp |
1003 | ||
1004 | is equivalent to | |
1005 | ||
1006 | @lisp | |
5bd55c3c | 1007 | (dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING}) |
6a31c819 MA |
1008 | @end lisp |
1009 | ||
1010 | but different to | |
1011 | ||
1012 | @lisp | |
5bd55c3c | 1013 | (dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING}) |
6a31c819 MA |
1014 | @end lisp |
1015 | ||
4db2806c MA |
1016 | The value for a byte D-Bus type can be any integer in the range 0 |
1017 | through 255. If a character is used as argument, modifiers | |
1018 | represented outside this range are stripped of. For example, | |
1019 | @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to | |
1020 | @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. | |
c9ecb5a7 | 1021 | |
dcbf5805 MA |
1022 | Signed and unsigned integer D-Bus types expect a corresponding integer |
1023 | value. If the value does not fit Emacs's integer range, it is also | |
1024 | possible to use an equivalent floating point number. | |
1025 | ||
4db2806c MA |
1026 | A D-Bus compound type is always represented as a list. The @sc{car} |
1027 | of this list can be the type symbol @code{:array}, @code{:variant}, | |
d4e67bc5 MA |
1028 | @code{:struct} or @code{:dict-entry}, which would result in a |
1029 | corresponding D-Bus container. @code{:array} is optional, because | |
4db2806c | 1030 | this is the default compound D-Bus type for a list. |
6a31c819 MA |
1031 | |
1032 | The objects being elements of the list are checked according to the | |
1033 | D-Bus compound type rules. | |
1034 | ||
1035 | @itemize | |
4db2806c MA |
1036 | @item An array must contain only elements of the same D-Bus type. It |
1037 | can be empty. | |
1038 | ||
6a31c819 | 1039 | @item A variant must contain only one single element. |
4db2806c | 1040 | |
6a31c819 | 1041 | @item A dictionary entry must be element of an array, and it must |
4db2806c MA |
1042 | contain only a key-value pair of two elements, with a basic D-Bus type |
1043 | key. | |
1044 | ||
6a31c819 MA |
1045 | @item There is no restriction for structs. |
1046 | @end itemize | |
1047 | ||
4db2806c MA |
1048 | If an empty array needs an element D-Bus type other than string, it |
1049 | can contain exactly one element of D-Bus type @code{:signature}. The | |
1050 | value of this element (a string) is used as the signature of the | |
1051 | elements of this array. Example: | |
6a31c819 MA |
1052 | |
1053 | @lisp | |
4db2806c MA |
1054 | (dbus-call-method |
1055 | :session "org.freedesktop.Notifications" | |
1056 | "/org/freedesktop/Notifications" | |
1057 | "org.freedesktop.Notifications" "Notify" | |
1058 | "GNU Emacs" ;; Application name. | |
1059 | 0 ;; No replacement of other notifications. | |
1060 | "" ;; No icon. | |
1061 | "Notification summary" ;; Summary. | |
1062 | (format ;; Body. | |
dce5a71f | 1063 | "This is a test notification, raised from\n%S" (emacs-version)) |
4db2806c MA |
1064 | '(:array) ;; No actions (empty array of strings). |
1065 | '(:array :signature "@{sv@}") ;; No hints | |
1066 | ;; (empty array of dictionary entries). | |
dce5a71f | 1067 | :int32 -1) ;; Default timeout. |
4db2806c MA |
1068 | |
1069 | @result{} 3 | |
6a31c819 | 1070 | @end lisp |
22d8ac3a | 1071 | |
ace706d1 MA |
1072 | @defun dbus-string-to-byte-array string |
1073 | Sometimes, D-Bus methods require as input parameter an array of bytes, | |
1074 | instead of a string. If it is guaranteed, that @var{string} is an | |
1075 | UTF8 string, this function performs the conversion. Example: | |
1076 | ||
1077 | @lisp | |
1078 | (dbus-string-to-byte-array "/etc/hosts") | |
1079 | ||
1080 | @result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47 | |
1081 | :byte 104 :byte 111 :byte 115 :byte 116 :byte 115) | |
1082 | @end lisp | |
1083 | @end defun | |
1084 | ||
1085 | @defun dbus-escape-as-identifier string | |
1086 | Escape an arbitrary @var{string} so it follows the rules for a C | |
1087 | identifier. The escaped string can be used as object path component, | |
1088 | interface element component, bus name component or member name in | |
1089 | D-Bus. | |
1090 | ||
1091 | The escaping consists of replacing all non-alphanumerics, and the | |
1092 | first character if it's a digit, with an underscore and two | |
1093 | lower-case hex digits. As a special case, "" is escaped to | |
1094 | "_". Example: | |
1095 | ||
1096 | @lisp | |
1097 | (dbus-escape-as-identifier "0123abc_xyz\x01\xff") | |
1098 | ||
1099 | @result{} "_30123abc_5fxyz_01_ff" | |
1100 | @end lisp | |
1101 | @end defun | |
1102 | ||
22d8ac3a MA |
1103 | |
1104 | @section Output parameters. | |
1105 | ||
1106 | Output parameters of D-Bus methods and signals are mapped to Lisp | |
6a31c819 | 1107 | objects. |
22d8ac3a MA |
1108 | |
1109 | @example | |
5bd55c3c | 1110 | @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float} |
22d8ac3a MA |
1111 | @item D-Bus type @tab @tab Lisp type |
1112 | @item | |
1113 | @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} | |
5bd55c3c MA |
1114 | @item DBUS_TYPE_BYTE @tab @expansion{} @tab natural number |
1115 | @item DBUS_TYPE_UINT16 @tab @expansion{} @tab natural number | |
1116 | @item DBUS_TYPE_INT16 @tab @expansion{} @tab integer | |
1117 | @item DBUS_TYPE_UINT32 @tab @expansion{} @tab natural number or float | |
6f8fc60c | 1118 | @item DBUS_TYPE_UNIX_FD @tab @expansion{} @tab natural number or float |
5bd55c3c MA |
1119 | @item DBUS_TYPE_INT32 @tab @expansion{} @tab integer or float |
1120 | @item DBUS_TYPE_UINT64 @tab @expansion{} @tab natural number or float | |
1121 | @item DBUS_TYPE_INT64 @tab @expansion{} @tab integer or float | |
22d8ac3a MA |
1122 | @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float |
1123 | @item DBUS_TYPE_STRING @tab @expansion{} @tab string | |
1124 | @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string | |
6a31c819 | 1125 | @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string |
22d8ac3a MA |
1126 | @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list |
1127 | @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list | |
1128 | @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list | |
1129 | @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list | |
1130 | @end multitable | |
1131 | @end example | |
1132 | ||
d4e67bc5 | 1133 | A float object in case of @code{DBUS_TYPE_UINT32}, |
6f8fc60c MA |
1134 | @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64}, |
1135 | @code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when | |
1136 | the C value exceeds the Emacs number size range. | |
d4e67bc5 | 1137 | |
22d8ac3a MA |
1138 | The resulting list of the last 4 D-Bus compound types contains as |
1139 | elements the elements of the D-Bus container, mapped according to the | |
1140 | same rules. | |
1141 | ||
1142 | The signal @code{PropertyModified}, discussed as example in | |
1143 | @ref{Inspection}, would offer as Lisp data the following object | |
1144 | (@var{BOOL} stands here for either @code{nil} or @code{t}): | |
1145 | ||
1146 | @lisp | |
5bd55c3c | 1147 | (@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) |
22d8ac3a MA |
1148 | @end lisp |
1149 | ||
543dd969 | 1150 | @defun dbus-byte-array-to-string byte-array &optional multibyte |
ace706d1 MA |
1151 | If a D-Bus method or signal returns an array of bytes, which are known |
1152 | to represent an UTF8 string, this function converts @var{byte-array} | |
543dd969 MA |
1153 | to the corresponding string. The string is unibyte encoded, unless |
1154 | @var{multibyte} is non-@code{nil}. Example: | |
ace706d1 MA |
1155 | |
1156 | @lisp | |
1157 | (dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) | |
1158 | ||
1159 | @result{} "/etc/hosts" | |
1160 | @end lisp | |
1161 | @end defun | |
1162 | ||
1163 | @defun dbus-unescape-from-identifier string | |
543dd969 MA |
1164 | Retrieve the original string from the encoded @var{string} as unibyte |
1165 | string. @var{string} must have been encoded with | |
ace706d1 MA |
1166 | @code{dbus-escape-as-identifier}. Example: |
1167 | ||
1168 | @lisp | |
1169 | (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") | |
1170 | ||
543dd969 | 1171 | @result{} "0123abc_xyz\x01\xff" |
ace706d1 | 1172 | @end lisp |
543dd969 MA |
1173 | |
1174 | If the original string used in @code{dbus-escape-as-identifier} is a | |
1175 | multibyte string, it cannot be expected that this function returns | |
1176 | that string: | |
1177 | ||
1178 | @lisp | |
1179 | (string-equal | |
1180 | (dbus-unescape-from-identifier | |
1181 | (dbus-escape-as-identifier "Grüß Göttin")) | |
1182 | "Grüß Göttin") | |
1183 | ||
1184 | @result{} nil | |
1185 | @end lisp | |
1186 | ||
1187 | ||
ace706d1 MA |
1188 | @end defun |
1189 | ||
22d8ac3a MA |
1190 | |
1191 | @node Synchronous Methods | |
1192 | @chapter Calling methods in a blocking way. | |
1193 | @cindex method calls, synchronous | |
1194 | @cindex synchronous method calls | |
1195 | ||
1196 | Methods can be called synchronously (@dfn{blocking}) or asynchronously | |
21956b56 | 1197 | (@dfn{non-blocking}). |
22d8ac3a MA |
1198 | |
1199 | At D-Bus level, a method call consist of two messages: one message | |
1200 | which carries the input parameters to the object owning the method to | |
1201 | be called, and a reply message returning the resulting output | |
1202 | parameters from the object. | |
1203 | ||
134ce16c | 1204 | @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args |
22d8ac3a MA |
1205 | This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is |
1206 | either the symbol @code{:system} or the symbol @code{:session}. | |
1207 | ||
1208 | @var{service} is the D-Bus service name to be used. @var{path} is the | |
1209 | D-Bus object path, @var{service} is registered at. @var{interface} is | |
1210 | an interface offered by @var{service}. It must provide @var{method}. | |
1211 | ||
134ce16c | 1212 | If the parameter @code{:timeout} is given, the following integer |
21956b56 | 1213 | @var{timeout} specifies the maximum number of milliseconds the method |
ecd3d54f | 1214 | call must return. The default value is 25,000. If the method call |
134ce16c MA |
1215 | doesn't return in time, a D-Bus error is raised (@pxref{Errors and |
1216 | Events}). | |
1217 | ||
22d8ac3a MA |
1218 | All other arguments args are passed to @var{method} as arguments. |
1219 | They are converted into D-Bus types as described in @ref{Type | |
1220 | Conversion}. | |
1221 | ||
1222 | The function returns the resulting values of @var{method} as a list of | |
1223 | Lisp objects, according to the type conversion rules described in | |
1224 | @ref{Type Conversion}. Example: | |
1225 | ||
06c0751a | 1226 | @lisp |
22d8ac3a | 1227 | (dbus-call-method |
0ce574ef MA |
1228 | :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" |
1229 | "org.gnome.seahorse.Keys" "GetKeyField" | |
22d8ac3a MA |
1230 | "openpgp:657984B8C7A966DD" "simple-name") |
1231 | ||
1232 | @result{} (t ("Philip R. Zimmermann")) | |
06c0751a | 1233 | @end lisp |
22d8ac3a MA |
1234 | |
1235 | If the result of the method call is just one value, the converted Lisp | |
1236 | object is returned instead of a list containing this single Lisp | |
1237 | object. Example: | |
1238 | ||
06c0751a | 1239 | @lisp |
22d8ac3a | 1240 | (dbus-call-method |
0ce574ef MA |
1241 | :system "org.freedesktop.Hal" |
1242 | "/org/freedesktop/Hal/devices/computer" | |
1243 | "org.freedesktop.Hal.Device" "GetPropertyString" | |
22d8ac3a MA |
1244 | "system.kernel.machine") |
1245 | ||
1246 | @result{} "i686" | |
06c0751a | 1247 | @end lisp |
22d8ac3a MA |
1248 | |
1249 | With the @code{dbus-introspect} function it is possible to explore the | |
1250 | interfaces of @samp{org.freedesktop.Hal} service. It offers the | |
1251 | interfaces @samp{org.freedesktop.Hal.Manager} for the object at the | |
1252 | path @samp{/org/freedesktop/Hal/Manager} as well as the interface | |
1253 | @samp{org.freedesktop.Hal.Device} for all objects prefixed with the | |
1254 | path @samp{/org/freedesktop/Hal/devices}. With the methods | |
1255 | @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to | |
1256 | emulate the @code{lshal} command on GNU/Linux systems: | |
1257 | ||
06c0751a | 1258 | @lisp |
22d8ac3a MA |
1259 | (dolist (device |
1260 | (dbus-call-method | |
0ce574ef | 1261 | :system "org.freedesktop.Hal" |
22d8ac3a | 1262 | "/org/freedesktop/Hal/Manager" |
0ce574ef | 1263 | "org.freedesktop.Hal.Manager" "GetAllDevices")) |
22d8ac3a MA |
1264 | (message "\nudi = %s" device) |
1265 | (dolist (properties | |
1266 | (dbus-call-method | |
0ce574ef MA |
1267 | :system "org.freedesktop.Hal" device |
1268 | "org.freedesktop.Hal.Device" "GetAllProperties")) | |
22d8ac3a MA |
1269 | (message " %s = %S" |
1270 | (car properties) (or (caar (cdr properties)) "")))) | |
1271 | ||
7b13a0f2 | 1272 | @print{} "udi = /org/freedesktop/Hal/devices/computer |
d9e21158 MA |
1273 | info.addons = (\"hald-addon-acpi\") |
1274 | info.bus = \"unknown\" | |
1275 | info.product = \"Computer\" | |
1276 | info.subsystem = \"unknown\" | |
1277 | info.udi = \"/org/freedesktop/Hal/devices/computer\" | |
1278 | linux.sysfs_path_device = \"(none)\" | |
1279 | power_management.acpi.linux.version = \"20051216\" | |
1280 | power_management.can_suspend_to_disk = t | |
1281 | power_management.can_suspend_to_ram = \"\" | |
1282 | power_management.type = \"acpi\" | |
1283 | smbios.bios.release_date = \"11/07/2001\" | |
1284 | system.chassis.manufacturer = \"COMPAL\" | |
1285 | system.chassis.type = \"Notebook\" | |
1286 | system.firmware.release_date = \"03/19/2005\" | |
c9ecb5a7 | 1287 | @dots{}" |
06c0751a | 1288 | @end lisp |
22d8ac3a MA |
1289 | @end defun |
1290 | ||
21956b56 MA |
1291 | |
1292 | @node Asynchronous Methods | |
1293 | @chapter Calling methods non-blocking. | |
1294 | @cindex method calls, asynchronous | |
1295 | @cindex asynchronous method calls | |
1296 | ||
1297 | @defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args | |
1298 | This function calls @var{method} on the D-Bus @var{bus} | |
1299 | asynchronously. @var{bus} is either the symbol @code{:system} or the | |
1300 | symbol @code{:session}. | |
1301 | ||
1302 | @var{service} is the D-Bus service name to be used. @var{path} is the | |
1303 | D-Bus object path, @var{service} is registered at. @var{interface} is | |
1304 | an interface offered by @var{service}. It must provide @var{method}. | |
1305 | ||
1306 | @var{handler} is a Lisp function, which is called when the | |
4f22e84d MA |
1307 | corresponding return message has arrived. If @var{handler} is |
1308 | @code{nil}, no return message will be expected. | |
21956b56 MA |
1309 | |
1310 | If the parameter @code{:timeout} is given, the following integer | |
1311 | @var{timeout} specifies the maximum number of milliseconds a reply | |
ecd3d54f | 1312 | message must arrive. The default value is 25,000. If there is no |
21956b56 MA |
1313 | reply message in time, a D-Bus error is raised (@pxref{Errors and |
1314 | Events}). | |
1315 | ||
1316 | All other arguments args are passed to @var{method} as arguments. | |
1317 | They are converted into D-Bus types as described in @ref{Type | |
1318 | Conversion}. | |
1319 | ||
dcbf5805 | 1320 | If @var{handler} is a Lisp function, the function returns a key into |
0ecd3c90 | 1321 | the hash table @code{dbus-registered-objects-table}. The |
4f22e84d MA |
1322 | corresponding entry in the hash table is removed, when the return |
1323 | message has been arrived, and @var{handler} is called. Example: | |
21956b56 MA |
1324 | |
1325 | @lisp | |
1326 | (dbus-call-method-asynchronously | |
1327 | :system "org.freedesktop.Hal" | |
1328 | "/org/freedesktop/Hal/devices/computer" | |
1329 | "org.freedesktop.Hal.Device" "GetPropertyString" 'message | |
1330 | "system.kernel.machine") | |
1331 | ||
dcbf5805 | 1332 | @result{} (:serial :system 2) |
21956b56 MA |
1333 | |
1334 | @print{} i686 | |
1335 | @end lisp | |
1336 | @end defun | |
1337 | ||
22d8ac3a | 1338 | |
addb7f2e MA |
1339 | @node Receiving Method Calls |
1340 | @chapter Offering own methods. | |
1341 | @cindex method calls, returning | |
1342 | @cindex returning method calls | |
1343 | ||
8c904d82 MA |
1344 | In order to register methods on the D-Bus, Emacs has to request a well |
1345 | known name on the D-Bus under which it will be available for other | |
1346 | clients. Names on the D-Bus can be registered and unregistered using | |
1347 | the following functions: | |
1348 | ||
1349 | @defun dbus-register-service bus service &rest flags | |
1350 | Register the known name @var{service} on D-Bus @var{bus}. | |
1351 | ||
1352 | @var{bus} is either the symbol @code{:system} or the symbol | |
1353 | @code{:session}. | |
1354 | ||
1355 | @var{service} is the service name to be registered on the D-Bus. It | |
1356 | must be a known name. | |
1357 | ||
1358 | @var{flags} is a subset of the following keywords: | |
1359 | ||
1360 | @itemize | |
1361 | @item @code{:allow-replacement}: Allow another service to become the primary | |
1362 | owner if requested. | |
1363 | ||
1364 | @item @code{:replace-existing}: Request to replace the current primary owner. | |
1365 | ||
1366 | @item @code{:do-not-queue}: If we can not become the primary owner do not | |
1367 | place us in the queue. | |
1368 | @end itemize | |
1369 | ||
1370 | One of the following keywords is returned: | |
1371 | ||
1372 | @itemize | |
1373 | ||
1374 | @item @code{:primary-owner}: We have become the primary owner of the name | |
1375 | @var{service}. | |
1376 | ||
1377 | @item @code{:in-queue}: We could not become the primary owner and | |
1378 | have been placed in the queue. | |
1379 | ||
1380 | @item @code{:exists}: We already are in the queue. | |
1381 | ||
1382 | @item @code{:already-owner}: We already are the primary | |
1383 | owner. | |
1384 | @end itemize | |
1385 | @end defun | |
1386 | ||
1387 | @defun dbus-unregister-service bus service | |
1388 | Unregister all objects from D-Bus @var{bus}, registered by Emacs for | |
1389 | @var{service}. | |
1390 | ||
1391 | @var{bus} is either the symbol @code{:system} or the symbol | |
1392 | @code{:session}. | |
1393 | ||
1394 | @var{service} is the D-Bus service name of the D-Bus. It must be a | |
1395 | known name. Emacs releases its association to @var{service} from | |
1396 | D-Bus. | |
1397 | ||
1398 | One of the following keywords is returned: | |
1399 | ||
1400 | @itemize | |
1401 | @item @code{:released}: We successfully released the name @var{service}. | |
1402 | @item @code{:non-existent}: The name @var{service} does not exist on the bus. | |
1403 | @item @code{:not-owner}: We are not an owner of the name @var{service}. | |
1404 | @end itemize | |
1405 | @end defun | |
1406 | ||
1407 | When a name has been chosen, Emacs can offer own methods, which can be | |
1408 | called by other applications. These methods could be an | |
1409 | implementation of an interface of a well known service, like | |
1410 | @samp{org.freedesktop.TextEditor}. | |
addb7f2e MA |
1411 | |
1412 | It could be also an implementation of an own interface. In this case, | |
cd71b9ae | 1413 | the service name must be @samp{org.gnu.Emacs}. The object path shall |
dcbf5805 | 1414 | begin with @samp{/org/gnu/Emacs/@strong{Application}}, and the |
addb7f2e | 1415 | interface name shall be @code{org.gnu.Emacs.@strong{Application}}. |
cd71b9ae | 1416 | @samp{@strong{Application}} is the name of the application which |
addb7f2e MA |
1417 | provides the interface. |
1418 | ||
ace706d1 | 1419 | @deffn Constant dbus-service-emacs |
dcbf5805 | 1420 | The well known service name @samp{org.gnu.Emacs} of Emacs. |
ace706d1 MA |
1421 | @end deffn |
1422 | ||
1423 | @deffn Constant dbus-path-emacs | |
dcbf5805 MA |
1424 | The object path namespace @samp{/org/gnu/Emacs} used by Emacs. |
1425 | @end deffn | |
1426 | ||
1427 | @deffn Constant dbus-interface-emacs | |
1428 | The interface namespace @code{org.gnu.Emacs} used by Emacs. | |
ace706d1 MA |
1429 | @end deffn |
1430 | ||
0fadf00e | 1431 | @defun dbus-register-method bus service path interface method handler dont-register-service |
addb7f2e MA |
1432 | With this function, an application registers @var{method} on the D-Bus |
1433 | @var{bus}. | |
1434 | ||
1435 | @var{bus} is either the symbol @code{:system} or the symbol | |
1436 | @code{:session}. | |
1437 | ||
1438 | @var{service} is the D-Bus service name of the D-Bus object | |
0fadf00e MA |
1439 | @var{method} is registered for. It must be a known name (See |
1440 | discussion of @var{dont-register-service} below). | |
addb7f2e | 1441 | |
0fadf00e MA |
1442 | @var{path} is the D-Bus object path @var{service} is registered (See |
1443 | discussion of @var{dont-register-service} below). | |
addb7f2e MA |
1444 | |
1445 | @var{interface} is the interface offered by @var{service}. It must | |
1446 | provide @var{method}. | |
1447 | ||
ac134f2f RS |
1448 | @var{handler} is a Lisp function to be called when a @var{method} call |
1449 | is received. It must accept as arguments the input arguments of | |
1450 | @var{method}. @var{handler} should return a list, whose elements are | |
1451 | to be used as arguments for the reply message of @var{method}. This | |
1452 | list can be composed like the input parameters in @ref{Type | |
1453 | Conversion}. | |
1454 | ||
1455 | If @var{handler} wants to return just one Lisp object and it is not a | |
1456 | cons cell, @var{handler} can return this object directly, instead of | |
1457 | returning a list containing the object. | |
addb7f2e | 1458 | |
42fb7e61 MA |
1459 | In case @var{handler} shall return a reply message with an empty |
1460 | argument list, @var{handler} must return the symbol @code{:ignore}. | |
1461 | ||
0fadf00e MA |
1462 | When @var{dont-register-service} is non-@code{nil}, the known name |
1463 | @var{service} is not registered. This means that other D-Bus clients | |
1464 | have no way of noticing the newly registered method. When interfaces | |
1465 | are constructed incrementally by adding single methods or properties | |
8c904d82 | 1466 | at a time, @var{dont-register-service} can be used to prevent other |
0fadf00e MA |
1467 | clients from discovering the still incomplete interface. |
1468 | ||
4a7c4c40 | 1469 | The default D-Bus timeout when waiting for a message reply is 25 |
134ce16c MA |
1470 | seconds. This value could be even smaller, depending on the calling |
1471 | client. Therefore, @var{handler} shall not last longer than | |
4a7c4c40 MA |
1472 | absolutely necessary. |
1473 | ||
9b7993b4 | 1474 | @code{dbus-register-method} returns a Lisp object, which can be used |
addb7f2e MA |
1475 | as argument in @code{dbus-unregister-object} for removing the |
1476 | registration for @var{method}. Example: | |
1477 | ||
06c0751a | 1478 | @lisp |
addb7f2e MA |
1479 | (defun my-dbus-method-handler (filename) |
1480 | (let (result) | |
1481 | (if (find-file filename) | |
1482 | (setq result '(:boolean t)) | |
1483 | (setq result '(:boolean nil))) | |
1484 | result)) | |
1485 | ||
1486 | @result{} my-dbus-method-handler | |
1487 | ||
1488 | (dbus-register-method | |
1489 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
1490 | "org.freedesktop.TextEditor" "OpenFile" | |
1491 | 'my-dbus-method-handler) | |
1492 | ||
dcbf5805 | 1493 | @result{} ((:method :session "org.freedesktop.TextEditor" "OpenFile") |
addb7f2e | 1494 | ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" |
eb932e8a | 1495 | my-dbus-method-handler)) |
06c0751a | 1496 | @end lisp |
addb7f2e | 1497 | |
cd71b9ae | 1498 | If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile} |
addb7f2e MA |
1499 | from another D-Bus application with a filename as parameter, the file |
1500 | is opened in Emacs, and the method returns either @var{true} or | |
0ecd3c90 | 1501 | @var{false}, indicating the success of the method. As test tool one |
addb7f2e MA |
1502 | could use the command line tool @code{dbus-send} in a shell: |
1503 | ||
1504 | @example | |
1505 | # dbus-send --session --print-reply \ | |
1506 | --dest="org.freedesktop.TextEditor" \ | |
1507 | "/org/freedesktop/TextEditor" \ | |
1508 | "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" | |
1509 | ||
1510 | @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 | |
eb932e8a MA |
1511 | boolean true |
1512 | @end example | |
1513 | ||
1514 | You can indicate an error by raising the Emacs signal | |
1515 | @code{dbus-error}. The handler above could be changed like this: | |
1516 | ||
1517 | @lisp | |
1518 | (defun my-dbus-method-handler (&rest args) | |
1519 | (unless (and (= (length args) 1) (stringp (car args))) | |
1520 | (signal 'dbus-error (list (format "Wrong argument list: %S" args)))) | |
1521 | (condition-case err | |
1522 | (find-file (car args)) | |
1523 | (error (signal 'dbus-error (cdr err)))) | |
1524 | t) | |
1525 | ||
1526 | @result{} my-dbus-method-handler | |
1527 | @end lisp | |
1528 | ||
1529 | The test runs then | |
1530 | ||
1531 | @example | |
1532 | # dbus-send --session --print-reply \ | |
1533 | --dest="org.freedesktop.TextEditor" \ | |
1534 | "/org/freedesktop/TextEditor" \ | |
1535 | "org.freedesktop.TextEditor.OpenFile" \ | |
1536 | string:"/etc/hosts" string:"/etc/passwd" | |
1537 | ||
1538 | @print{} Error org.freedesktop.DBus.Error.Failed: | |
1539 | Wrong argument list: ("/etc/hosts" "/etc/passwd") | |
addb7f2e MA |
1540 | @end example |
1541 | @end defun | |
1542 | ||
0fadf00e | 1543 | @defun dbus-register-property bus service path interface property access value &optional emits-signal dont-register-service |
0ecd3c90 MA |
1544 | With this function, an application declares a @var{property} on the D-Bus |
1545 | @var{bus}. | |
1546 | ||
1547 | @var{bus} is either the symbol @code{:system} or the symbol | |
1548 | @code{:session}. | |
1549 | ||
1550 | @var{service} is the D-Bus service name of the D-Bus. It must be a | |
1551 | known name. | |
1552 | ||
0fadf00e MA |
1553 | @var{path} is the D-Bus object path @var{service} is registered (See |
1554 | discussion of @var{dont-register-service} below). | |
0ecd3c90 MA |
1555 | |
1556 | @var{interface} is the name of the interface used at @var{path}, | |
1557 | @var{property} is the name of the property of @var{interface}. | |
1558 | ||
1559 | @var{access} indicates, whether the property can be changed by other | |
1560 | services via D-Bus. It must be either the symbol @code{:read} or | |
1561 | @code{:readwrite}. @var{value} is the initial value of the property, | |
1562 | it can be of any valid type (see @code{dbus-call-method} for details). | |
1563 | ||
1564 | If @var{property} already exists on @var{path}, it will be | |
1565 | overwritten. For properties with access type @code{:read} this is the | |
1566 | only way to change their values. Properties with access type | |
1567 | @code{:readwrite} can be changed by @code{dbus-set-property}. | |
1568 | ||
1569 | The interface @samp{org.freedesktop.DBus.Properties} is added to | |
1570 | @var{path}, including a default handler for the @samp{Get}, | |
820ae8fe | 1571 | @samp{GetAll} and @samp{Set} methods of this interface. When |
5bd55c3c MA |
1572 | @var{emits-signal} is non-@code{nil}, the signal |
1573 | @samp{PropertiesChanged} is sent when the property is changed by | |
1574 | @code{dbus-set-property}. | |
820ae8fe | 1575 | |
0fadf00e MA |
1576 | When @var{dont-register-service} is non-@code{nil}, the known name |
1577 | @var{service} is not registered. This means that other D-Bus clients | |
1578 | have no way of noticing the newly registered method. When interfaces | |
1579 | are constructed incrementally by adding single methods or properties | |
8c904d82 | 1580 | at a time, @var{dont-register-service} can be used to prevent other |
0fadf00e MA |
1581 | clients from discovering the still incomplete interface. |
1582 | ||
820ae8fe | 1583 | @noindent Example: |
0ecd3c90 MA |
1584 | |
1585 | @lisp | |
1586 | (dbus-register-property | |
1587 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
1588 | "org.freedesktop.TextEditor" "name" :read "GNU Emacs") | |
1589 | ||
dcbf5805 | 1590 | @result{} ((:property :session "org.freedesktop.TextEditor" "name") |
0ecd3c90 MA |
1591 | ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) |
1592 | ||
1593 | (dbus-register-property | |
1594 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
820ae8fe | 1595 | "org.freedesktop.TextEditor" "version" :readwrite emacs-version t) |
0ecd3c90 | 1596 | |
dcbf5805 | 1597 | @result{} ((:property :session "org.freedesktop.TextEditor" "version") |
0ecd3c90 MA |
1598 | ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor")) |
1599 | @end lisp | |
1600 | ||
1601 | Other D-Bus applications can read the property via the default methods | |
1602 | @samp{org.freedesktop.DBus.Properties.Get} and | |
1603 | @samp{org.freedesktop.DBus.Properties.GetAll}. Testing is also | |
1604 | possible via the command line tool @code{dbus-send} in a shell: | |
1605 | ||
1606 | @example | |
1607 | # dbus-send --session --print-reply \ | |
1608 | --dest="org.freedesktop.TextEditor" \ | |
1609 | "/org/freedesktop/TextEditor" \ | |
1610 | "org.freedesktop.DBus.Properties.GetAll" \ | |
1611 | string:"org.freedesktop.TextEditor" | |
1612 | ||
1613 | @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=3 | |
1614 | array [ | |
1615 | dict entry( | |
1616 | string "name" | |
1617 | variant string "GNU Emacs" | |
1618 | ) | |
1619 | dict entry( | |
1620 | string "version" | |
1621 | variant string "23.1.50.5" | |
1622 | ) | |
1623 | ] | |
1624 | @end example | |
1625 | ||
1626 | It is also possible, to apply the @code{dbus-get-property}, | |
1627 | @code{dbus-get-all-properties} and @code{dbus-set-property} functions | |
1628 | (@pxref{Properties and Annotations}). | |
1629 | ||
1630 | @lisp | |
1631 | (dbus-set-property | |
1632 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
1633 | "org.freedesktop.TextEditor" "version" "23.1.50") | |
1634 | ||
1635 | @result{} "23.1.50" | |
1636 | ||
1637 | (dbus-get-property | |
1638 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
1639 | "org.freedesktop.TextEditor" "version") | |
1640 | ||
1641 | @result{} "23.1.50" | |
1642 | @end lisp | |
1643 | @end defun | |
1644 | ||
1645 | @defun dbus-unregister-object object | |
1646 | Unregister @var{object} from the D-Bus. @var{object} must be the | |
1647 | result of a preceding @code{dbus-register-method}, | |
1648 | @code{dbus-register-property} or @code{dbus-register-signal} call | |
1649 | (@pxref{Signals}). It returns @code{t} if @var{object} has been | |
1650 | unregistered, @code{nil} otherwise. | |
1651 | ||
1652 | When @var{object} identifies the last method or property, which is | |
1653 | registered for the respective service, Emacs releases its association | |
1654 | to the service from D-Bus. | |
1655 | @end defun | |
977640ed | 1656 | |
addb7f2e | 1657 | |
22d8ac3a MA |
1658 | @node Signals |
1659 | @chapter Sending and receiving signals. | |
1660 | @cindex signals | |
1661 | ||
dcbf5805 MA |
1662 | Signals are one way messages. They carry input parameters, which are |
1663 | received by all objects which have registered for such a signal. | |
22d8ac3a | 1664 | |
0ce574ef | 1665 | @defun dbus-send-signal bus service path interface signal &rest args |
22d8ac3a MA |
1666 | This function is similar to @code{dbus-call-method}. The difference |
1667 | is, that there are no returning output parameters. | |
1668 | ||
1669 | The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is | |
1670 | either the symbol @code{:system} or the symbol @code{:session}. It | |
1671 | doesn't matter whether another object has registered for @var{signal}. | |
1672 | ||
dcbf5805 MA |
1673 | Signals can be unicast or broadcast messages. For broadcast messages, |
1674 | @var{service} must be @code{nil}. Otherwise, @var{service} is the | |
1675 | D-Bus service name the signal is sent to as unicast | |
1676 | message.@footnote{For backward compatibility, a broadcast message is | |
1677 | also emitted if @var{service} is the known or unique name Emacs is | |
1678 | registered at D-Bus @var{bus}.} @var{path} is the D-Bus object path | |
1679 | @var{signal} is sent from. @var{interface} is an interface available | |
1680 | at @var{path}. It must provide @var{signal}. | |
22d8ac3a MA |
1681 | |
1682 | All other arguments args are passed to @var{signal} as arguments. | |
1683 | They are converted into D-Bus types as described in @ref{Type | |
1684 | Conversion}. Example: | |
1685 | ||
06c0751a | 1686 | @lisp |
22d8ac3a | 1687 | (dbus-send-signal |
dcbf5805 MA |
1688 | :session nil dbus-path-emacs |
1689 | (concat dbus-interface-emacs ".FileManager") "FileModified" | |
ace706d1 | 1690 | "/home/albinus/.emacs") |
06c0751a | 1691 | @end lisp |
22d8ac3a MA |
1692 | @end defun |
1693 | ||
9b7993b4 | 1694 | @defun dbus-register-signal bus service path interface signal handler &rest args |
dcbf5805 MA |
1695 | With this function, an application registers for a signal on the D-Bus |
1696 | @var{bus}. | |
22d8ac3a MA |
1697 | |
1698 | @var{bus} is either the symbol @code{:system} or the symbol | |
1699 | @code{:session}. | |
1700 | ||
a4397af9 MA |
1701 | @var{service} is the D-Bus service name used by the sending D-Bus |
1702 | object. It can be either a known name or the unique name of the D-Bus | |
d49902e4 MA |
1703 | object sending the signal. A known name will be mapped onto the |
1704 | unique name of the object, owning @var{service} at registration time. | |
1705 | When the corresponding D-Bus object disappears, signals won't be | |
1706 | received any longer. | |
a4397af9 | 1707 | |
a4397af9 | 1708 | @var{path} is the corresponding D-Bus object path, @var{service} is |
dcbf5805 MA |
1709 | registered at. @var{interface} is an interface offered by |
1710 | @var{service}. It must provide @var{signal}. | |
a4397af9 | 1711 | |
dcbf5805 MA |
1712 | @var{service}, @var{path}, @var{interface} and @var{signal} can be |
1713 | @code{nil}. This is interpreted as a wildcard for the respective | |
1714 | argument. | |
22d8ac3a MA |
1715 | |
1716 | @var{handler} is a Lisp function to be called when the @var{signal} is | |
1717 | received. It must accept as arguments the output parameters | |
9b7993b4 MA |
1718 | @var{signal} is sending. |
1719 | ||
dcbf5805 MA |
1720 | The remaining arguments @var{args} can be keywords or keyword string |
1721 | pairs.@footnote{For backward compatibility, the arguments @var{args} | |
1722 | can also be just strings. They stand for the respective arguments of | |
1723 | @var{signal} in their order, and are used for filtering as well. A | |
1724 | @code{nil} argument might be used to preserve the order.} The meaning | |
1725 | is as follows: | |
1726 | ||
1727 | @itemize | |
1728 | @item @code{:argN} @var{string}:@* | |
1729 | @code{:pathN} @var{string}:@* | |
1730 | This stands for the Nth argument of the signal. @code{:pathN} | |
1731 | arguments can be used for object path wildcard matches as specified by | |
0ba2624f | 1732 | D-Bus, while an @code{:argN} argument requires an exact match. |
dcbf5805 MA |
1733 | |
1734 | @item @code{:arg-namespace} @var{string}:@* | |
1735 | Register for the signals, which first argument defines the service or | |
1736 | interface namespace @var{string}. | |
1737 | ||
1738 | @item @code{:path-namespace} @var{string}:@* | |
1739 | Register for the object path namespace @var{string}. All signals sent | |
1740 | from an object path, which has @var{string} as the preceding string, | |
1741 | are matched. This requires @var{path} to be @code{nil}. | |
1742 | ||
1743 | @item @code{:eavesdrop}:@* | |
1744 | Register for unicast signals which are not directed to the D-Bus | |
1745 | object Emacs is registered at D-Bus BUS, if the security policy of BUS | |
1746 | allows this. Otherwise, this argument is ignored. | |
1747 | @end itemize | |
9b7993b4 MA |
1748 | |
1749 | @code{dbus-register-signal} returns a Lisp object, which can be used | |
1750 | as argument in @code{dbus-unregister-object} for removing the | |
1751 | registration for @var{signal}. Example: | |
22d8ac3a | 1752 | |
06c0751a | 1753 | @lisp |
22d8ac3a MA |
1754 | (defun my-dbus-signal-handler (device) |
1755 | (message "Device %s added" device)) | |
1756 | ||
0ce574ef MA |
1757 | @result{} my-dbus-signal-handler |
1758 | ||
22d8ac3a | 1759 | (dbus-register-signal |
0ce574ef MA |
1760 | :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" |
1761 | "org.freedesktop.Hal.Manager" "DeviceAdded" | |
22d8ac3a MA |
1762 | 'my-dbus-signal-handler) |
1763 | ||
dcbf5805 | 1764 | @result{} ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded") |
cd71c3ef MA |
1765 | ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" |
1766 | my-signal-handler)) | |
06c0751a | 1767 | @end lisp |
22d8ac3a | 1768 | |
cd71b9ae MA |
1769 | As we know from the introspection data of interface |
1770 | @samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded} | |
22d8ac3a MA |
1771 | provides one single parameter, which is mapped into a Lisp string. |
1772 | The callback function @code{my-dbus-signal-handler} must define one | |
1773 | single string argument therefore. Plugging an USB device to your | |
cd71b9ae | 1774 | machine, when registered for signal @samp{DeviceAdded}, will show you |
22d8ac3a | 1775 | which objects the GNU/Linux @code{hal} daemon adds. |
dcbf5805 MA |
1776 | |
1777 | Some of the match rules have been added to a later version of D-Bus. | |
1778 | In order to test the availability of such features, you could register | |
1779 | for a dummy signal, and check the result: | |
1780 | ||
1781 | @lisp | |
1782 | (dbus-ignore-errors | |
1783 | (dbus-register-signal | |
1784 | :system nil nil nil nil 'ignore :path-namespace "/invalid/path")) | |
1785 | ||
1786 | @result{} nil | |
1787 | @end lisp | |
22d8ac3a MA |
1788 | @end defun |
1789 | ||
22d8ac3a | 1790 | |
7457f7b6 | 1791 | @node Alternative Buses |
dcbf5805 | 1792 | @chapter Alternative buses and environments. |
7457f7b6 MA |
1793 | @cindex bus names |
1794 | @cindex UNIX domain socket | |
dcbf5805 | 1795 | @cindex TCP/IP socket |
7457f7b6 MA |
1796 | |
1797 | Until now, we have spoken about the system and the session buses, | |
1798 | which are the default buses to be connected to. However, it is | |
1799 | possible to connect to any bus, from which the address is known. This | |
dcbf5805 MA |
1800 | is a UNIX domain or TCP/IP socket. Everywhere, where a @var{bus} is |
1801 | mentioned as argument of a function (the symbol @code{:system} or the | |
1802 | symbol @code{:session}), this address can be used instead. The | |
1803 | connection to this bus must be initialized first. | |
7457f7b6 | 1804 | |
dcbf5805 | 1805 | @defun dbus-init-bus bus &optional private |
7457f7b6 MA |
1806 | Establish the connection to D-Bus @var{bus}. |
1807 | ||
1808 | @var{bus} can be either the symbol @code{:system} or the symbol | |
1809 | @code{:session}, or it can be a string denoting the address of the | |
301b181a | 1810 | corresponding bus. For the system and session buses, this function |
7457f7b6 MA |
1811 | is called when loading @file{dbus.el}, there is no need to call it |
1812 | again. | |
1813 | ||
dcbf5805 MA |
1814 | The function returns a number, which counts the connections this Emacs |
1815 | session has established to the @var{bus} under the same unique name | |
1816 | (see @code{dbus-get-unique-name}). It depends on the libraries Emacs | |
1817 | is linked with, and on the environment Emacs is running. For example, | |
1818 | if Emacs is linked with the gtk toolkit, and it runs in a GTK-aware | |
1819 | environment like Gnome, another connection might already be | |
1820 | established. | |
7457f7b6 | 1821 | |
dcbf5805 MA |
1822 | When @var{private} is non-@code{nil}, a new connection is established |
1823 | instead of reusing an existing one. It results in a new unique name | |
1824 | at the bus. This can be used, if it is necessary to distinguish from | |
1825 | another connection used in the same Emacs process, like the one | |
1826 | established by GTK+. It should be used with care for at least the | |
1827 | @code{:system} and @code{:session} buses, because other Emacs Lisp | |
1828 | packages might already use this connection to those buses. | |
7457f7b6 | 1829 | |
dcbf5805 | 1830 | Example: You initialize a connection to the AT-SPI bus on your host: |
7457f7b6 MA |
1831 | |
1832 | @lisp | |
1833 | (setq my-bus | |
dcbf5805 MA |
1834 | (dbus-call-method |
1835 | :session "org.a11y.Bus" "/org/a11y/bus" | |
1836 | "org.a11y.Bus" "GetAddress")) | |
7457f7b6 | 1837 | |
dcbf5805 | 1838 | @result{} "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f" |
7457f7b6 | 1839 | |
dcbf5805 MA |
1840 | ;; If Emacs is built with gtk support, and you run in a GTK enabled |
1841 | ;; environment (like a GNOME session), the initialization reuses the | |
1842 | ;; connection established by GTK's atk bindings. | |
7457f7b6 MA |
1843 | (dbus-init-bus my-bus) |
1844 | ||
dcbf5805 | 1845 | @result{} 2 |
7457f7b6 MA |
1846 | |
1847 | (dbus-get-unique-name my-bus) | |
1848 | ||
dcbf5805 MA |
1849 | @result{} ":1.19" |
1850 | ||
1851 | ;; Open a new connection to the same bus. This obsoletes the | |
1852 | ;; previous one. | |
1853 | (dbus-init-bus my-bus 'private) | |
1854 | ||
1855 | @result{} 1 | |
1856 | ||
1857 | (dbus-get-unique-name my-bus) | |
1858 | ||
1859 | @result{} ":1.20" | |
1860 | @end lisp | |
1861 | ||
1862 | D-Bus addresses can specify different transport. A possible address | |
1863 | could be based on TCP/IP sockets, see next example. However, it | |
1864 | depends on the bus daemon configuration, which transport is supported. | |
1865 | @end defun | |
1866 | ||
1867 | @defun dbus-setenv bus variable value | |
1868 | Set the value of the @var{bus} environment variable @var{variable} to | |
1869 | @var{value}. | |
1870 | ||
1871 | @var{bus} is either a Lisp symbol, @code{:system} or @code{:session}, | |
1872 | or a string denoting the bus address. Both @var{variable} and | |
1873 | @var{value} should be strings. | |
1874 | ||
1875 | Normally, services inherit the environment of the bus daemon. This | |
1876 | function adds to or modifies that environment when activating services. | |
1877 | ||
1878 | Some bus instances, such as @code{:system}, may disable setting the | |
1879 | environment. In such cases, or if this feature is not available in | |
1880 | older D-Bus versions, a @code{dbus-error} error is raised. | |
1881 | ||
1882 | As an example, it might be desirable to start X11 enabled services on | |
1883 | a remote host's bus on the same X11 server the local Emacs is | |
1884 | running. This could be achieved by | |
1885 | ||
1886 | @lisp | |
1887 | (setq my-bus "unix:host=example.gnu.org,port=4711") | |
1888 | ||
1889 | @result{} "unix:host=example.gnu.org,port=4711" | |
1890 | ||
1891 | (dbus-init-bus my-bus) | |
1892 | ||
1893 | @result{} 1 | |
1894 | ||
1895 | (dbus-setenv my-bus "DISPLAY" (getenv "DISPLAY")) | |
1896 | ||
1897 | @result{} nil | |
7457f7b6 MA |
1898 | @end lisp |
1899 | @end defun | |
1900 | ||
1901 | ||
22d8ac3a MA |
1902 | @node Errors and Events |
1903 | @chapter Errors and events. | |
5bd55c3c | 1904 | @cindex debugging |
22d8ac3a MA |
1905 | @cindex errors |
1906 | @cindex events | |
1907 | ||
5bd55c3c MA |
1908 | The internal actions can be traced by running in a debug mode. |
1909 | ||
1910 | @defvar dbus-debug | |
1911 | If this variable is non-@code{nil}, D-Bus specific debug messages are raised. | |
1912 | @end defvar | |
1913 | ||
21956b56 | 1914 | Input parameters of @code{dbus-call-method}, |
dcbf5805 MA |
1915 | @code{dbus-call-method-asynchronously}, @code{dbus-send-signal}, |
1916 | @code{dbus-register-method}, @code{dbus-register-property} and | |
6a31c819 MA |
1917 | @code{dbus-register-signal} are checked for correct D-Bus types. If |
1918 | there is a type mismatch, the Lisp error @code{wrong-type-argument} | |
1919 | @code{D-Bus ARG} is raised. | |
1920 | ||
22d8ac3a | 1921 | All errors raised by D-Bus are signaled with the error symbol |
d2e4a6c9 MA |
1922 | @code{dbus-error}. If possible, error messages from D-Bus are |
1923 | appended to the @code{dbus-error}. | |
1924 | ||
1925 | @defspec dbus-ignore-errors forms@dots{} | |
1926 | This executes @var{forms} exactly like a @code{progn}, except that | |
1927 | @code{dbus-error} errors are ignored during the @var{forms}. These | |
5bd55c3c | 1928 | errors can be made visible when @code{dbus-debug} is set to @code{t}. |
d2e4a6c9 | 1929 | @end defspec |
22d8ac3a | 1930 | |
5794c2a5 MA |
1931 | Incoming D-Bus messages are handled as Emacs events, see @pxref{Misc |
1932 | Events, , , elisp}. They are retrieved only, when Emacs runs in | |
1933 | interactive mode. The generated event has this form: | |
22d8ac3a | 1934 | |
06c0751a | 1935 | @lisp |
21956b56 MA |
1936 | (dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} |
1937 | &rest @var{args}) | |
06c0751a | 1938 | @end lisp |
22d8ac3a | 1939 | |
21956b56 | 1940 | @var{bus} identifies the D-Bus the message is coming from. It is |
a4397af9 | 1941 | either the symbol @code{:system} or the symbol @code{:session}. |
22d8ac3a | 1942 | |
21956b56 MA |
1943 | @var{type} is the D-Bus message type which has caused the event. It |
1944 | can be @code{dbus-message-type-invalid}, | |
1945 | @code{dbus-message-type-method-call}, | |
1946 | @code{dbus-message-type-method-return}, | |
1947 | @code{dbus-message-type-error}, or @code{dbus-message-type-signal}. | |
1948 | @var{serial} is the serial number of the received D-Bus message. | |
addb7f2e | 1949 | |
22d8ac3a | 1950 | @var{service} and @var{path} are the unique name and the object path |
addb7f2e MA |
1951 | of the D-Bus object emitting the message. @var{interface} and |
1952 | @var{member} denote the message which has been sent. | |
22d8ac3a | 1953 | |
0ce574ef | 1954 | @var{handler} is the callback function which has been registered for |
addb7f2e | 1955 | this message (see @pxref{Signals}). When a @code{dbus-event} event |
0ce574ef MA |
1956 | arrives, @var{handler} is called with @var{args} as arguments. |
1957 | ||
22d8ac3a MA |
1958 | In order to inspect the @code{dbus-event} data, you could extend the |
1959 | definition of the callback function in @ref{Signals}: | |
1960 | ||
06c0751a | 1961 | @lisp |
22d8ac3a MA |
1962 | (defun my-dbus-signal-handler (&rest args) |
1963 | (message "my-dbus-signal-handler: %S" last-input-event)) | |
06c0751a | 1964 | @end lisp |
22d8ac3a MA |
1965 | |
1966 | There exist convenience functions which could be called inside a | |
1967 | callback function in order to retrieve the information from the event. | |
1968 | ||
1969 | @defun dbus-event-bus-name event | |
22d8ac3a MA |
1970 | Returns the bus name @var{event} is coming from. |
1971 | The result is either the symbol @code{:system} or the symbol @code{:session}. | |
1972 | @end defun | |
1973 | ||
21956b56 MA |
1974 | @defun dbus-event-message-type event |
1975 | Returns the message type of the corresponding D-Bus message. The | |
5bd55c3c | 1976 | result is a natural number. |
21956b56 MA |
1977 | @end defun |
1978 | ||
addb7f2e MA |
1979 | @defun dbus-event-serial-number event |
1980 | Returns the serial number of the corresponding D-Bus message. | |
5bd55c3c | 1981 | The result is a natural number. |
addb7f2e MA |
1982 | @end defun |
1983 | ||
22d8ac3a | 1984 | @defun dbus-event-service-name event |
22d8ac3a MA |
1985 | Returns the unique name of the D-Bus object @var{event} is coming from. |
1986 | @end defun | |
1987 | ||
1988 | @defun dbus-event-path-name event | |
22d8ac3a MA |
1989 | Returns the object path of the D-Bus object @var{event} is coming from. |
1990 | @end defun | |
1991 | ||
1992 | @defun dbus-event-interface-name event | |
74fc5047 | 1993 | Returns the interface name of the D-Bus object @var{event} is coming from. |
22d8ac3a MA |
1994 | @end defun |
1995 | ||
1996 | @defun dbus-event-member-name event | |
74fc5047 | 1997 | Returns the member name of the D-Bus object @var{event} is coming |
22d8ac3a MA |
1998 | from. It is either a signal name or a method name. |
1999 | @end defun | |
2000 | ||
c9ecb5a7 MA |
2001 | D-Bus errors are not propagated during event handling, because it is |
2002 | usually not desired. D-Bus errors in events can be made visible by | |
e7433508 MA |
2003 | setting the variable @code{dbus-debug} to @code{t}. They can also be |
2004 | handled by a hook function. | |
2005 | ||
d1069532 | 2006 | @defvar dbus-event-error-functions |
e7433508 MA |
2007 | This hook variable keeps a list of functions, which are called when a |
2008 | D-Bus error happens in the event handler. Every function must accept | |
333f9019 | 2009 | two arguments, the event and the error variable caught in |
74fc5047 MA |
2010 | @code{condition-case} by @code{dbus-error}. |
2011 | ||
2012 | Such functions can be used the adapt the error signal to be raised. | |
2013 | Example: | |
e7433508 MA |
2014 | |
2015 | @lisp | |
74fc5047 | 2016 | (defun my-dbus-event-error-handler (event error) |
dcbf5805 | 2017 | (when (string-equal (concat dbus-interface-emacs ".FileManager") |
74fc5047 MA |
2018 | (dbus-event-interface-name event)) |
2019 | (message "my-dbus-event-error-handler: %S %S" event error) | |
2020 | (signal 'file-error (cdr error)))) | |
e7433508 | 2021 | |
d1069532 | 2022 | (add-hook 'dbus-event-error-functions 'my-dbus-event-error-handler) |
e7433508 MA |
2023 | @end lisp |
2024 | @end defvar | |
c9ecb5a7 | 2025 | |
74fc5047 MA |
2026 | Hook functions shall take into account, that there might be other |
2027 | D-Bus applications running. Therefore, they shall check carefully, | |
2028 | whether a given D-Bus error is related to them. | |
2029 | ||
22d8ac3a | 2030 | |
5bd55c3c MA |
2031 | @node Index |
2032 | @unnumbered Index | |
2033 | ||
2034 | @printindex cp | |
2035 | ||
2036 | ||
22d8ac3a MA |
2037 | @node GNU Free Documentation License |
2038 | @appendix GNU Free Documentation License | |
2039 | @include doclicense.texi | |
2040 | ||
22d8ac3a | 2041 | @bye |