annotate doc/misc/dbus.texi @ 92265:9d5f4925c981

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