Commit | Line | Data |
---|---|---|
22d8ac3a MA |
1 | \input texinfo @c -*-texinfo-*- |
2 | @setfilename ../../info/dbus | |
3 | @c %**start of header | |
4 | @settitle Using of D-Bus | |
5 | @c @setchapternewpage odd | |
6 | @c %**end of header | |
7 | ||
8 | @copying | |
4db2806c | 9 | Copyright @copyright{} 2007, 2008 Free Software Foundation, Inc. |
22d8ac3a MA |
10 | |
11 | @quotation | |
12 | Permission is granted to copy, distribute and/or modify this document | |
13 | under the terms of the GNU Free Documentation License, Version 1.2 or | |
14 | any later version published by the Free Software Foundation; with no | |
debf4439 GM |
15 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', |
16 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
17 | is included in the section entitled ``GNU Free Documentation License''. | |
22d8ac3a | 18 | |
6f093307 GM |
19 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
20 | modify this GNU manual. Buying copies from the FSF supports it in | |
21 | developing GNU and promoting software freedom.'' | |
22d8ac3a MA |
22 | @end quotation |
23 | @end copying | |
24 | ||
25 | @dircategory Emacs | |
26 | @direntry | |
27 | * D-Bus: (dbus). Using D-Bus in Emacs. | |
28 | @end direntry | |
29 | ||
30 | @node Top, Overview, (dir), (dir) | |
31 | @top D-Bus integration in Emacs | |
32 | ||
33 | This manual documents an API for usage of D-Bus in | |
34 | Emacs.@footnote{D-Bus is not enabled by default. You must run | |
35 | @command{./configure --with-dbus} in Emacs' top level directory, | |
36 | before you compile Emacs.} D-Bus is a message bus system, a simple | |
37 | way for applications to talk to one another. An overview of D-Bus can | |
38 | be found at @uref{http://dbus.freedesktop.org/}. | |
39 | ||
40 | @insertcopying | |
41 | ||
42 | @menu | |
43 | * Overview:: An overview of D-Bus. | |
44 | * Inspection:: Inspection of the bus names. | |
45 | * Type Conversion:: Mapping Lisp types and D-Bus types. | |
46 | * Synchronous Methods:: Calling methods in a blocking way. | |
addb7f2e | 47 | * Receiving Method Calls:: Offering own methods. |
22d8ac3a MA |
48 | * Signals:: Sending and receiving signals. |
49 | * Errors and Events:: Errors and events. | |
50 | * GNU Free Documentation License:: The license for this documentation. | |
51 | @end menu | |
52 | ||
53 | @node Overview | |
54 | @chapter An overview of D-Bus | |
55 | @cindex overview | |
56 | ||
57 | D-Bus is an inter-process communication mechanism for applications | |
58 | residing on the same host. The communication is based on | |
59 | @dfn{messages}. Data in the messages is carried in a structured way, | |
60 | it is not just a byte stream. | |
61 | ||
62 | The communication is connection oriented to two kinds of message | |
63 | buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a | |
64 | given machine, there is always one single system bus for miscellaneous | |
65 | system-wide communication, like changing of hardware configuration. | |
66 | On the other hand, the session bus is always related to a single | |
67 | user's session. | |
68 | ||
69 | Every client application, which is connected to a bus, registers under | |
70 | a @dfn{unique name} at the bus. This name is used for identifying the | |
71 | client application. Such a unique name starts always with a colon, | |
72 | and looks like @samp{:1.42}. | |
73 | ||
74 | Additionally, a client application can register itself to a so called | |
75 | @dfn{known name}, which is a series of identifiers separated by dots, | |
7ef92bc9 | 76 | as in @samp{org.gnu.Emacs}. If several applications register to the |
22d8ac3a MA |
77 | same known name, these registrations are queued, and only the first |
78 | application which has registered for the known name is reachable via | |
79 | this name. If this application disconnects from the bus, the next | |
80 | queued unique name becomes the owner of this known name. | |
81 | ||
82 | An application can install one or several objects under its name. | |
83 | Such objects are identified by an @dfn{object path}, which looks | |
84 | similar to paths in a filesystem. An example of such an object path | |
85 | could be @samp{/org/gnu/Emacs/}. | |
86 | ||
87 | Applications might send a request to an object, that means sending a | |
88 | message with some data as input parameters, and receiving a message | |
89 | from that object with the result of this message, the output | |
90 | parameters. Such a request is called @dfn{method} in D-Bus. | |
91 | ||
92 | The other form of communication are @dfn{signals}. The underlying | |
93 | message is emitted from an object and will be received by all other | |
94 | applications which have registered for such a signal. | |
95 | ||
96 | All methods and signals an object supports are called @dfn{interface} | |
97 | of the object. Interfaces are specified under a hierarchical name in | |
98 | D-Bus; an object can support several interfaces. Such an interface | |
99 | name could be @samp{org.gnu.Emacs.TextEditor} or | |
100 | @samp{org.gnu.Emacs.FileManager}. | |
101 | ||
102 | ||
103 | @node Inspection | |
104 | @chapter Inspection of the bus names. | |
105 | @cindex inspection | |
106 | ||
107 | There are several basic functions which inspect the buses for | |
108 | registered names. Internally they use the basic interface | |
109 | @samp{org.freedesktop.DBus}, which is supported by all objects of a bus. | |
110 | ||
111 | @defun dbus-list-activatable-names | |
22d8ac3a MA |
112 | This function returns the D-Bus service names, which can be activated. |
113 | An activatable service is described in a service registration file. | |
114 | Under GNU/Linux, such files are located at | |
115 | @file{/usr/share/dbus-1/services/}. | |
116 | ||
117 | The result is a list of strings, which is @code{nil} when there are no | |
118 | activatable service names at all. | |
119 | @end defun | |
120 | ||
121 | @defun dbus-list-names bus | |
22d8ac3a MA |
122 | All service names, which are registered at D-Bus @var{bus}, are |
123 | returned. The result is a list of strings, which is @code{nil} when | |
124 | there are no registered service names at all. Well known names are | |
125 | strings like @samp{org.freedesktop.DBus}. Names starting with | |
126 | @samp{:} are unique names for services. | |
127 | ||
128 | @var{bus} must be either the symbol @code{:system} or the symbol | |
129 | @code{:session}. | |
130 | @end defun | |
131 | ||
132 | @defun dbus-list-known-names bus | |
22d8ac3a MA |
133 | Retrieves all services which correspond to a known name in @var{bus}. |
134 | A service has a known name if it doesn't start with @samp{:}. The | |
135 | result is a list of strings, which is @code{nil} when there are no | |
136 | known names at all. | |
137 | ||
138 | @var{bus} must be either the symbol @code{:system} or the symbol | |
139 | @code{:session}. | |
140 | @end defun | |
141 | ||
142 | @defun dbus-list-queued-owners bus service | |
22d8ac3a MA |
143 | For a given service, registered at D-Bus @var{bus} under the name |
144 | @var{service}, all queued unique names are returned. The result is a | |
145 | list of strings, or @code{nil} when there are no queued names for | |
146 | @var{service} at all. | |
147 | ||
148 | @var{bus} must be either the symbol @code{:system} or the symbol | |
149 | @code{:session}. @var{service} must be a known service name as | |
150 | string. | |
151 | @end defun | |
152 | ||
153 | @defun dbus-get-name-owner bus service | |
22d8ac3a | 154 | For a given service, registered at D-Bus @var{bus} under the name |
06c0751a MA |
155 | @var{service}, the unique name of the name owner is returned. The |
156 | result is a string, or @code{nil} when there exist no name owner of | |
157 | @var{service}. | |
22d8ac3a MA |
158 | |
159 | @var{bus} must be either the symbol @code{:system} or the symbol | |
160 | @code{:session}. @var{service} must be a known service name as | |
161 | string. | |
162 | @end defun | |
163 | ||
06c0751a MA |
164 | @defun dbus-ping bus service |
165 | Check whether the service name @var{service} is registered at D-Bus | |
166 | @var{bus}. @var{service} might not have been started yet. The result | |
167 | is either @code{t} or @code{nil}. | |
168 | ||
169 | @var{bus} must be either the symbol @code{:system} or the symbol | |
170 | @code{:session}. @var{service} must be a string. Example: | |
171 | ||
172 | @lisp | |
173 | (message | |
174 | "%s screensaver on board." | |
175 | (cond | |
176 | ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome") | |
177 | ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE") | |
178 | (t "No"))) | |
179 | @end lisp | |
180 | @end defun | |
181 | ||
22d8ac3a | 182 | @defun dbus-get-unique-name bus |
22d8ac3a MA |
183 | The unique name, under which Emacs is registered at D-Bus @var{bus}, |
184 | is returned as string. | |
185 | ||
186 | @var{bus} must be either the symbol @code{:system} or the symbol | |
187 | @code{:session}. | |
188 | @end defun | |
189 | ||
190 | @defun dbus-introspect bus service path | |
22d8ac3a MA |
191 | Objects can publish there interfaces to the D-Bus. This function |
192 | returns all interfaces of @var{service}, registered at object path | |
193 | @var{path} at bus @var{bus}. | |
194 | ||
195 | @var{bus} must be either the symbol @code{:system} or the symbol | |
196 | @code{:session}. @var{service} must be a known service name, and | |
197 | @var{path} must be a valid object path. The last two parameters are | |
198 | strings. The result, the introspection data, is a string in XML | |
199 | format. Example: | |
200 | ||
06c0751a | 201 | @lisp |
22d8ac3a MA |
202 | (dbus-introspect |
203 | :system "org.freedesktop.Hal" | |
204 | "/org/freedesktop/Hal/devices/computer") | |
205 | ||
d9e21158 MA |
206 | @result{} "<!DOCTYPE node PUBLIC |
207 | \"-//freedesktop//DTD D-BUS Object Introspection 1.0//EN\" | |
208 | \"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd\"> | |
209 | <node> | |
210 | <interface name=\"org.freedesktop.Hal.Device\"> | |
211 | <method name=\"GetAllProperties\"> | |
212 | <arg name=\"properties\" direction=\"out\" type=\"a@{sv@}\"/> | |
213 | </method> | |
c9ecb5a7 | 214 | @dots{} |
d9e21158 MA |
215 | <signal name=\"PropertyModified\"> |
216 | <arg name=\"num_updates\" type=\"i\"/> | |
217 | <arg name=\"updates\" type=\"a(sbb)\"/> | |
218 | </signal> | |
219 | </interface> | |
c9ecb5a7 | 220 | @dots{} |
d9e21158 | 221 | </node>" |
06c0751a | 222 | @end lisp |
22d8ac3a MA |
223 | |
224 | This example informs us, that the service @code{org.freedesktop.Hal} | |
225 | at object path @code{/org/freedesktop/Hal/devices/computer} offers the | |
226 | interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces | |
227 | not documented here). This interface contains the method | |
228 | @code{GetAllProperties}, which needs no input parameters, but returns | |
229 | as output parameter an array of dictionary entries (key-value pairs). | |
230 | Every dictionary entry has a string as key, and a variant as value. | |
231 | ||
232 | The interface offers also a signal, which returns 2 parameters: an | |
233 | integer, and an array consisting of elements which are a struct of a | |
234 | string and 2 boolean values. | |
235 | ||
236 | Such type descriptions are called @dfn{signature} in D-Bus. For a | |
237 | discussion of D-Bus types and their Lisp representation see @ref{Type | |
238 | Conversion}.@footnote{D-Bus signatures are explained in the D-Bus | |
239 | specification | |
240 | @uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}. | |
241 | The interfaces of the service @code{org.freedesktop.Hal} are described | |
242 | at | |
243 | @uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.} | |
244 | @end defun | |
245 | ||
246 | ||
247 | @node Type Conversion | |
248 | @chapter Mapping Lisp types and D-Bus types. | |
249 | @cindex type conversion | |
250 | ||
251 | D-Bus method calls and signals accept usually several arguments as | |
252 | parameters, either as input parameter, or as output parameter. Every | |
253 | argument belongs to a D-Bus type. | |
254 | ||
6a31c819 | 255 | Such arguments must be mapped between the value encoded as a D-Bus |
22d8ac3a MA |
256 | type, and the corresponding type of Lisp objects. The mapping is |
257 | applied Lisp object @expansion{} D-Bus type for input parameters, and | |
258 | D-Bus type @expansion{} Lisp object for output parameters. | |
259 | ||
260 | ||
261 | @section Input parameters. | |
262 | ||
263 | Input parameters for D-Bus methods and signals occur as arguments of a | |
6a31c819 | 264 | Lisp function call. The following mapping to D-Bus types is |
22d8ac3a MA |
265 | applied, when the corresponding D-Bus message is created: |
266 | ||
267 | @example | |
268 | @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN} | |
269 | @item Lisp type @tab @tab D-Bus type | |
270 | @item | |
271 | @item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN | |
272 | @item number @tab @expansion{} @tab DBUS_TYPE_UINT32 | |
273 | @item integer @tab @expansion{} @tab DBUS_TYPE_INT32 | |
274 | @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE | |
275 | @item string @tab @expansion{} @tab DBUS_TYPE_STRING | |
6a31c819 | 276 | @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY |
22d8ac3a MA |
277 | @end multitable |
278 | @end example | |
279 | ||
6a31c819 MA |
280 | Other Lisp objects, like symbols or hash tables, are not accepted as |
281 | input parameter. | |
282 | ||
283 | If it is necessary to use another D-Bus type, a corresponding type | |
284 | symbol can be preceeded to the corresponding Lisp object. Basic D-Bus | |
d4e67bc5 MA |
285 | types are represented by the type symbols @code{:byte}, |
286 | @code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, | |
287 | @code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, | |
288 | @code{:string}, @code{:object-path} and @code{:signature}. | |
6a31c819 | 289 | |
22d8ac3a | 290 | @noindent |
6a31c819 MA |
291 | Example: |
292 | ||
293 | @lisp | |
c9ecb5a7 | 294 | (dbus-call-method @dots{} @var{NUMBER} @var{STRING}) |
6a31c819 MA |
295 | @end lisp |
296 | ||
297 | is equivalent to | |
298 | ||
299 | @lisp | |
c9ecb5a7 | 300 | (dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING}) |
6a31c819 MA |
301 | @end lisp |
302 | ||
303 | but different to | |
304 | ||
305 | @lisp | |
c9ecb5a7 | 306 | (dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING}) |
6a31c819 MA |
307 | @end lisp |
308 | ||
4db2806c MA |
309 | The value for a byte D-Bus type can be any integer in the range 0 |
310 | through 255. If a character is used as argument, modifiers | |
311 | represented outside this range are stripped of. For example, | |
312 | @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to | |
313 | @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. | |
c9ecb5a7 | 314 | |
4db2806c MA |
315 | A D-Bus compound type is always represented as a list. The @sc{car} |
316 | of this list can be the type symbol @code{:array}, @code{:variant}, | |
d4e67bc5 MA |
317 | @code{:struct} or @code{:dict-entry}, which would result in a |
318 | corresponding D-Bus container. @code{:array} is optional, because | |
4db2806c | 319 | this is the default compound D-Bus type for a list. |
6a31c819 MA |
320 | |
321 | The objects being elements of the list are checked according to the | |
322 | D-Bus compound type rules. | |
323 | ||
324 | @itemize | |
4db2806c MA |
325 | @item An array must contain only elements of the same D-Bus type. It |
326 | can be empty. | |
327 | ||
6a31c819 | 328 | @item A variant must contain only one single element. |
4db2806c | 329 | |
6a31c819 | 330 | @item A dictionary entry must be element of an array, and it must |
4db2806c MA |
331 | contain only a key-value pair of two elements, with a basic D-Bus type |
332 | key. | |
333 | ||
6a31c819 MA |
334 | @item There is no restriction for structs. |
335 | @end itemize | |
336 | ||
4db2806c MA |
337 | If an empty array needs an element D-Bus type other than string, it |
338 | can contain exactly one element of D-Bus type @code{:signature}. The | |
339 | value of this element (a string) is used as the signature of the | |
340 | elements of this array. Example: | |
6a31c819 MA |
341 | |
342 | @lisp | |
4db2806c MA |
343 | (dbus-call-method |
344 | :session "org.freedesktop.Notifications" | |
345 | "/org/freedesktop/Notifications" | |
346 | "org.freedesktop.Notifications" "Notify" | |
347 | "GNU Emacs" ;; Application name. | |
348 | 0 ;; No replacement of other notifications. | |
349 | "" ;; No icon. | |
350 | "Notification summary" ;; Summary. | |
351 | (format ;; Body. | |
352 | "This is a test notification, raised from %s" (emacs-version)) | |
353 | '(:array) ;; No actions (empty array of strings). | |
354 | '(:array :signature "@{sv@}") ;; No hints | |
355 | ;; (empty array of dictionary entries). | |
356 | ':int32 -1) ;; Default timeout. | |
357 | ||
358 | @result{} 3 | |
6a31c819 | 359 | @end lisp |
22d8ac3a MA |
360 | |
361 | ||
362 | @section Output parameters. | |
363 | ||
364 | Output parameters of D-Bus methods and signals are mapped to Lisp | |
6a31c819 | 365 | objects. |
22d8ac3a MA |
366 | |
367 | @example | |
368 | @multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}} | |
369 | @item D-Bus type @tab @tab Lisp type | |
370 | @item | |
371 | @item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} | |
d4e67bc5 | 372 | @item DBUS_TYPE_BYTE @tab @expansion{} @tab number |
6a31c819 | 373 | @item DBUS_TYPE_UINT16 @tab @expansion{} @tab number |
d4e67bc5 MA |
374 | @item DBUS_TYPE_INT16 @tab @expansion{} @tab number |
375 | @item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float | |
376 | @item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float | |
377 | @item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float | |
378 | @item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float | |
22d8ac3a MA |
379 | @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float |
380 | @item DBUS_TYPE_STRING @tab @expansion{} @tab string | |
381 | @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string | |
6a31c819 | 382 | @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string |
22d8ac3a MA |
383 | @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list |
384 | @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list | |
385 | @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list | |
386 | @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list | |
387 | @end multitable | |
388 | @end example | |
389 | ||
d4e67bc5 MA |
390 | A float object in case of @code{DBUS_TYPE_UINT32}, |
391 | @code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and | |
392 | @code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the | |
393 | Emacs number size range. | |
394 | ||
22d8ac3a MA |
395 | The resulting list of the last 4 D-Bus compound types contains as |
396 | elements the elements of the D-Bus container, mapped according to the | |
397 | same rules. | |
398 | ||
399 | The signal @code{PropertyModified}, discussed as example in | |
400 | @ref{Inspection}, would offer as Lisp data the following object | |
401 | (@var{BOOL} stands here for either @code{nil} or @code{t}): | |
402 | ||
403 | @lisp | |
c9ecb5a7 | 404 | (@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) |
22d8ac3a MA |
405 | @end lisp |
406 | ||
407 | ||
408 | @node Synchronous Methods | |
409 | @chapter Calling methods in a blocking way. | |
410 | @cindex method calls, synchronous | |
411 | @cindex synchronous method calls | |
412 | ||
413 | Methods can be called synchronously (@dfn{blocking}) or asynchronously | |
414 | (@dfn{non-blocking}). Currently, just synchronous methods are | |
415 | implemented. | |
416 | ||
417 | At D-Bus level, a method call consist of two messages: one message | |
418 | which carries the input parameters to the object owning the method to | |
419 | be called, and a reply message returning the resulting output | |
420 | parameters from the object. | |
421 | ||
134ce16c | 422 | @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args |
22d8ac3a MA |
423 | This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is |
424 | either the symbol @code{:system} or the symbol @code{:session}. | |
425 | ||
426 | @var{service} is the D-Bus service name to be used. @var{path} is the | |
427 | D-Bus object path, @var{service} is registered at. @var{interface} is | |
428 | an interface offered by @var{service}. It must provide @var{method}. | |
429 | ||
134ce16c MA |
430 | If the parameter @code{:timeout} is given, the following integer |
431 | @var{timeout} specifies the maximun number of milliseconds the method | |
432 | call must return. The default value is 25.000. If the method call | |
433 | doesn't return in time, a D-Bus error is raised (@pxref{Errors and | |
434 | Events}). | |
435 | ||
22d8ac3a MA |
436 | All other arguments args are passed to @var{method} as arguments. |
437 | They are converted into D-Bus types as described in @ref{Type | |
438 | Conversion}. | |
439 | ||
440 | The function returns the resulting values of @var{method} as a list of | |
441 | Lisp objects, according to the type conversion rules described in | |
442 | @ref{Type Conversion}. Example: | |
443 | ||
06c0751a | 444 | @lisp |
22d8ac3a | 445 | (dbus-call-method |
0ce574ef MA |
446 | :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" |
447 | "org.gnome.seahorse.Keys" "GetKeyField" | |
22d8ac3a MA |
448 | "openpgp:657984B8C7A966DD" "simple-name") |
449 | ||
450 | @result{} (t ("Philip R. Zimmermann")) | |
06c0751a | 451 | @end lisp |
22d8ac3a MA |
452 | |
453 | If the result of the method call is just one value, the converted Lisp | |
454 | object is returned instead of a list containing this single Lisp | |
455 | object. Example: | |
456 | ||
06c0751a | 457 | @lisp |
22d8ac3a | 458 | (dbus-call-method |
0ce574ef MA |
459 | :system "org.freedesktop.Hal" |
460 | "/org/freedesktop/Hal/devices/computer" | |
461 | "org.freedesktop.Hal.Device" "GetPropertyString" | |
22d8ac3a MA |
462 | "system.kernel.machine") |
463 | ||
464 | @result{} "i686" | |
06c0751a | 465 | @end lisp |
22d8ac3a MA |
466 | |
467 | With the @code{dbus-introspect} function it is possible to explore the | |
468 | interfaces of @samp{org.freedesktop.Hal} service. It offers the | |
469 | interfaces @samp{org.freedesktop.Hal.Manager} for the object at the | |
470 | path @samp{/org/freedesktop/Hal/Manager} as well as the interface | |
471 | @samp{org.freedesktop.Hal.Device} for all objects prefixed with the | |
472 | path @samp{/org/freedesktop/Hal/devices}. With the methods | |
473 | @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to | |
474 | emulate the @code{lshal} command on GNU/Linux systems: | |
475 | ||
06c0751a | 476 | @lisp |
22d8ac3a MA |
477 | (dolist (device |
478 | (dbus-call-method | |
0ce574ef | 479 | :system "org.freedesktop.Hal" |
22d8ac3a | 480 | "/org/freedesktop/Hal/Manager" |
0ce574ef | 481 | "org.freedesktop.Hal.Manager" "GetAllDevices")) |
22d8ac3a MA |
482 | (message "\nudi = %s" device) |
483 | (dolist (properties | |
484 | (dbus-call-method | |
0ce574ef MA |
485 | :system "org.freedesktop.Hal" device |
486 | "org.freedesktop.Hal.Device" "GetAllProperties")) | |
22d8ac3a MA |
487 | (message " %s = %S" |
488 | (car properties) (or (caar (cdr properties)) "")))) | |
489 | ||
7b13a0f2 | 490 | @print{} "udi = /org/freedesktop/Hal/devices/computer |
d9e21158 MA |
491 | info.addons = (\"hald-addon-acpi\") |
492 | info.bus = \"unknown\" | |
493 | info.product = \"Computer\" | |
494 | info.subsystem = \"unknown\" | |
495 | info.udi = \"/org/freedesktop/Hal/devices/computer\" | |
496 | linux.sysfs_path_device = \"(none)\" | |
497 | power_management.acpi.linux.version = \"20051216\" | |
498 | power_management.can_suspend_to_disk = t | |
499 | power_management.can_suspend_to_ram = \"\" | |
500 | power_management.type = \"acpi\" | |
501 | smbios.bios.release_date = \"11/07/2001\" | |
502 | system.chassis.manufacturer = \"COMPAL\" | |
503 | system.chassis.type = \"Notebook\" | |
504 | system.firmware.release_date = \"03/19/2005\" | |
c9ecb5a7 | 505 | @dots{}" |
06c0751a | 506 | @end lisp |
22d8ac3a MA |
507 | @end defun |
508 | ||
509 | ||
addb7f2e MA |
510 | @node Receiving Method Calls |
511 | @chapter Offering own methods. | |
512 | @cindex method calls, returning | |
513 | @cindex returning method calls | |
514 | ||
515 | Emacs can also offer own methods, which can be called by other | |
516 | applications. These methods could be an implementation of an | |
517 | interface of a well known service, like @code{org.freedesktop.TextEditor}. | |
518 | ||
519 | It could be also an implementation of an own interface. In this case, | |
520 | the service name must be @code{org.gnu.Emacs}. The object path shall | |
521 | begin with @code{/org/gnu/Emacs/@strong{Application}/}, and the | |
522 | interface name shall be @code{org.gnu.Emacs.@strong{Application}}. | |
523 | @code{@strong{Application}} is the name of the application which | |
524 | provides the interface. | |
525 | ||
526 | @defun dbus-register-method bus service path interface method handler | |
527 | With this function, an application registers @var{method} on the D-Bus | |
528 | @var{bus}. | |
529 | ||
530 | @var{bus} is either the symbol @code{:system} or the symbol | |
531 | @code{:session}. | |
532 | ||
533 | @var{service} is the D-Bus service name of the D-Bus object | |
534 | @var{method} is registered for. It must be a known name. | |
535 | ||
536 | @var{path} is the D-Bus object path @var{service} is | |
537 | registered. | |
538 | ||
539 | @var{interface} is the interface offered by @var{service}. It must | |
540 | provide @var{method}. | |
541 | ||
542 | @var{handler} is a Lisp function to be called when when a @var{method} | |
543 | call is is received. It must accept as arguments the input arguments | |
544 | of @var{method}. @var{handler} must return a list, which elements are | |
545 | used as arguments for the reply message of @var{method}. This list | |
546 | can be composed like the input parameters in @ref{Type Conversion}. | |
547 | ||
4a7c4c40 | 548 | The default D-Bus timeout when waiting for a message reply is 25 |
134ce16c MA |
549 | seconds. This value could be even smaller, depending on the calling |
550 | client. Therefore, @var{handler} shall not last longer than | |
4a7c4c40 MA |
551 | absolutely necessary. |
552 | ||
addb7f2e MA |
553 | @code{dbus-register-method} returns a Lisp symbol, which can be used |
554 | as argument in @code{dbus-unregister-object} for removing the | |
555 | registration for @var{method}. Example: | |
556 | ||
06c0751a | 557 | @lisp |
addb7f2e MA |
558 | (defun my-dbus-method-handler (filename) |
559 | (let (result) | |
560 | (if (find-file filename) | |
561 | (setq result '(:boolean t)) | |
562 | (setq result '(:boolean nil))) | |
563 | result)) | |
564 | ||
565 | @result{} my-dbus-method-handler | |
566 | ||
567 | (dbus-register-method | |
568 | :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
569 | "org.freedesktop.TextEditor" "OpenFile" | |
570 | 'my-dbus-method-handler) | |
571 | ||
572 | @result{} ((:system "org.freedesktop.TextEditor" "OpenFile") | |
573 | ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" | |
574 | my-method-handler)) | |
06c0751a | 575 | @end lisp |
addb7f2e MA |
576 | |
577 | If you invoke the method @code{org.freedesktop.TextEditor.OpenFile} | |
578 | from another D-Bus application with a filename as parameter, the file | |
579 | is opened in Emacs, and the method returns either @var{true} or | |
580 | @var{false}, indicating the success if the method. As test tool one | |
581 | could use the command line tool @code{dbus-send} in a shell: | |
582 | ||
583 | @example | |
584 | # dbus-send --session --print-reply \ | |
585 | --dest="org.freedesktop.TextEditor" \ | |
586 | "/org/freedesktop/TextEditor" \ | |
587 | "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" | |
588 | ||
589 | @print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 | |
590 | boolean true | |
591 | @end example | |
592 | @end defun | |
593 | ||
594 | ||
22d8ac3a MA |
595 | @node Signals |
596 | @chapter Sending and receiving signals. | |
597 | @cindex signals | |
598 | ||
599 | Signals are broadcast messages. They carry input parameters, which | |
600 | are received by all objects which have registered for such a signal. | |
601 | ||
0ce574ef | 602 | @defun dbus-send-signal bus service path interface signal &rest args |
22d8ac3a MA |
603 | This function is similar to @code{dbus-call-method}. The difference |
604 | is, that there are no returning output parameters. | |
605 | ||
606 | The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is | |
607 | either the symbol @code{:system} or the symbol @code{:session}. It | |
608 | doesn't matter whether another object has registered for @var{signal}. | |
609 | ||
610 | @var{service} is the D-Bus service name of the object the signal is | |
611 | emitted from. @var{path} is the corresponding D-Bus object path, | |
612 | @var{service} is registered at. @var{interface} is an interface | |
613 | offered by @var{service}. It must provide @var{signal}. | |
614 | ||
615 | All other arguments args are passed to @var{signal} as arguments. | |
616 | They are converted into D-Bus types as described in @ref{Type | |
617 | Conversion}. Example: | |
618 | ||
06c0751a | 619 | @lisp |
22d8ac3a | 620 | (dbus-send-signal |
0ce574ef MA |
621 | :session "org.gnu.Emacs" "/org/gnu/Emacs" |
622 | "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs") | |
06c0751a | 623 | @end lisp |
22d8ac3a MA |
624 | @end defun |
625 | ||
0ce574ef | 626 | @defun dbus-register-signal bus service path interface signal handler |
22d8ac3a MA |
627 | With this function, an application registers for @var{signal} on the |
628 | D-Bus @var{bus}. | |
629 | ||
630 | @var{bus} is either the symbol @code{:system} or the symbol | |
631 | @code{:session}. | |
632 | ||
a4397af9 MA |
633 | @var{service} is the D-Bus service name used by the sending D-Bus |
634 | object. It can be either a known name or the unique name of the D-Bus | |
635 | object sending the signal. In case of a unique name, signals won't be | |
636 | received any longer once the object owning this unique name has | |
637 | disappeared, and a new queued object has replaced it. | |
638 | ||
639 | When @var{service} is @code{nil}, related signals from all D-Bus | |
640 | objects shall be accepted. | |
641 | ||
642 | @var{path} is the corresponding D-Bus object path, @var{service} is | |
643 | registered at. It can also be @code{nil} if the path name of incoming | |
644 | signals shall not be checked. | |
645 | ||
646 | @var{interface} is an interface offered by @var{service}. It must | |
647 | provide @var{signal}. | |
22d8ac3a MA |
648 | |
649 | @var{handler} is a Lisp function to be called when the @var{signal} is | |
650 | received. It must accept as arguments the output parameters | |
651 | @var{signal} is sending. Example: | |
652 | ||
06c0751a | 653 | @lisp |
22d8ac3a MA |
654 | (defun my-dbus-signal-handler (device) |
655 | (message "Device %s added" device)) | |
656 | ||
0ce574ef MA |
657 | @result{} my-dbus-signal-handler |
658 | ||
22d8ac3a | 659 | (dbus-register-signal |
0ce574ef MA |
660 | :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" |
661 | "org.freedesktop.Hal.Manager" "DeviceAdded" | |
22d8ac3a MA |
662 | 'my-dbus-signal-handler) |
663 | ||
cd71c3ef MA |
664 | @result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded") |
665 | ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" | |
666 | my-signal-handler)) | |
06c0751a | 667 | @end lisp |
22d8ac3a MA |
668 | |
669 | As we know from the inspection data of interface | |
670 | @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded} | |
671 | provides one single parameter, which is mapped into a Lisp string. | |
672 | The callback function @code{my-dbus-signal-handler} must define one | |
673 | single string argument therefore. Plugging an USB device to your | |
674 | machine, when registered for signal @code{DeviceAdded}, will show you | |
675 | which objects the GNU/Linux @code{hal} daemon adds. | |
676 | ||
677 | @code{dbus-register-signal} returns a Lisp symbol, which can be used | |
c9ecb5a7 | 678 | as argument in @code{dbus-unregister-object} for removing the |
22d8ac3a MA |
679 | registration for @var{signal}. |
680 | @end defun | |
681 | ||
c9ecb5a7 | 682 | @defun dbus-unregister-object object |
22d8ac3a | 683 | Unregister @var{object} from the the D-Bus. @var{object} must be the |
c9ecb5a7 MA |
684 | result of a preceding @code{dbus-register-signal} or |
685 | @code{dbus-register-method} call. It returns @code{t} if @var{object} | |
686 | has been unregistered, @code{nil} otherwise. | |
22d8ac3a MA |
687 | @end defun |
688 | ||
689 | ||
690 | @node Errors and Events | |
691 | @chapter Errors and events. | |
692 | @cindex errors | |
693 | @cindex events | |
694 | ||
6a31c819 MA |
695 | Input parameters of @code{dbus-call-method} and |
696 | @code{dbus-register-signal} are checked for correct D-Bus types. If | |
697 | there is a type mismatch, the Lisp error @code{wrong-type-argument} | |
698 | @code{D-Bus ARG} is raised. | |
699 | ||
22d8ac3a | 700 | All errors raised by D-Bus are signaled with the error symbol |
d2e4a6c9 MA |
701 | @code{dbus-error}. If possible, error messages from D-Bus are |
702 | appended to the @code{dbus-error}. | |
703 | ||
704 | @defspec dbus-ignore-errors forms@dots{} | |
705 | This executes @var{forms} exactly like a @code{progn}, except that | |
706 | @code{dbus-error} errors are ignored during the @var{forms}. These | |
707 | errors can be made visible when variable @code{dbus-debug} is set to | |
708 | @code{t}. | |
709 | @end defspec | |
22d8ac3a | 710 | |
a4397af9 | 711 | Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc |
22d8ac3a MA |
712 | Events, , , elisp}). The generated event has this form: |
713 | ||
06c0751a | 714 | @lisp |
addb7f2e | 715 | (dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} &rest @var{args}) |
06c0751a | 716 | @end lisp |
22d8ac3a | 717 | |
a4397af9 MA |
718 | @var{bus} identifies the D-Bus the signal is coming from. It is |
719 | either the symbol @code{:system} or the symbol @code{:session}. | |
22d8ac3a | 720 | |
addb7f2e MA |
721 | @var{serial} is the serial number of the received D-Bus message if it |
722 | is a method call, or @code{nil}. | |
723 | ||
22d8ac3a | 724 | @var{service} and @var{path} are the unique name and the object path |
addb7f2e MA |
725 | of the D-Bus object emitting the message. @var{interface} and |
726 | @var{member} denote the message which has been sent. | |
22d8ac3a | 727 | |
0ce574ef | 728 | @var{handler} is the callback function which has been registered for |
addb7f2e | 729 | this message (see @pxref{Signals}). When a @code{dbus-event} event |
0ce574ef MA |
730 | arrives, @var{handler} is called with @var{args} as arguments. |
731 | ||
22d8ac3a MA |
732 | In order to inspect the @code{dbus-event} data, you could extend the |
733 | definition of the callback function in @ref{Signals}: | |
734 | ||
06c0751a | 735 | @lisp |
22d8ac3a MA |
736 | (defun my-dbus-signal-handler (&rest args) |
737 | (message "my-dbus-signal-handler: %S" last-input-event)) | |
06c0751a | 738 | @end lisp |
22d8ac3a MA |
739 | |
740 | There exist convenience functions which could be called inside a | |
741 | callback function in order to retrieve the information from the event. | |
742 | ||
743 | @defun dbus-event-bus-name event | |
22d8ac3a MA |
744 | Returns the bus name @var{event} is coming from. |
745 | The result is either the symbol @code{:system} or the symbol @code{:session}. | |
746 | @end defun | |
747 | ||
addb7f2e MA |
748 | @defun dbus-event-serial-number event |
749 | Returns the serial number of the corresponding D-Bus message. | |
750 | The result is a number in case the D-Bus message is a method | |
751 | call, or @code{nil} for all other mesage types. | |
752 | @end defun | |
753 | ||
22d8ac3a | 754 | @defun dbus-event-service-name event |
22d8ac3a MA |
755 | Returns the unique name of the D-Bus object @var{event} is coming from. |
756 | @end defun | |
757 | ||
758 | @defun dbus-event-path-name event | |
22d8ac3a MA |
759 | Returns the object path of the D-Bus object @var{event} is coming from. |
760 | @end defun | |
761 | ||
762 | @defun dbus-event-interface-name event | |
22d8ac3a MA |
763 | Returns the interface name of of the D-Bus object @var{event} is coming from. |
764 | @end defun | |
765 | ||
766 | @defun dbus-event-member-name event | |
22d8ac3a MA |
767 | Returns the member name of of the D-Bus object @var{event} is coming |
768 | from. It is either a signal name or a method name. | |
769 | @end defun | |
770 | ||
c9ecb5a7 MA |
771 | D-Bus errors are not propagated during event handling, because it is |
772 | usually not desired. D-Bus errors in events can be made visible by | |
773 | setting the variable @code{dbus-debug} to @code{t}. | |
774 | ||
22d8ac3a MA |
775 | |
776 | @node GNU Free Documentation License | |
777 | @appendix GNU Free Documentation License | |
778 | @include doclicense.texi | |
779 | ||
780 | @contents | |
781 | @c End of dbus.texi | |
782 | @bye | |
79f10da0 MB |
783 | |
784 | @ignore | |
785 | arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 | |
786 | @end ignore |