annotate doc/misc/dbus.texi @ 88015:7b54e553ca0b

Sync ERC 5.3 release.
author Michael Olson <mwolson@gnu.org>
date Sat, 26 Jan 2008 21:49:41 +0000
parents af599a62c634
children 6834ec860aff
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
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
161 @var{service}, the unique name of the name owner is returned. The result is a
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
162 string, or @code{nil} when there exist no name owner of @var{service}.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
163
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
164 @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
165 @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
166 string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
167 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
168
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
169 @defun dbus-get-unique-name bus
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
170 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
171 is returned as string.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
172
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
173 @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
174 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
175 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
176
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
177 @defun dbus-introspect bus service path
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
178 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
179 returns all interfaces of @var{service}, registered at object path
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
180 @var{path} at bus @var{bus}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
181
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
182 @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
183 @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
184 @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
185 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
186 format. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
187
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
188 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
189 (dbus-introspect
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
190 :system "org.freedesktop.Hal"
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
191 "/org/freedesktop/Hal/devices/computer")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
192
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
193 @result{} "<!DOCTYPE node PUBLIC
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
194 \"-//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
195 \"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
196 <node>
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
197 <interface name=\"org.freedesktop.Hal.Device\">
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
198 <method name=\"GetAllProperties\">
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
199 <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
200 </method>
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
201 @dots{}
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
202 <signal name=\"PropertyModified\">
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
203 <arg name=\"num_updates\" type=\"i\"/>
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
204 <arg name=\"updates\" type=\"a(sbb)\"/>
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
205 </signal>
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
206 </interface>
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
207 @dots{}
86944
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
208 </node>"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
209 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
210
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
211 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
212 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
213 interface @code{org.freedesktop.Hal.Device} (and 2 other interfaces
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
214 not documented here). This interface contains the method
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
215 @code{GetAllProperties}, which needs no input parameters, but returns
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
216 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
217 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
218
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
219 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
220 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
221 string and 2 boolean values.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
222
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
223 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
224 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
225 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
226 specification
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
227 @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
228 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
229 at
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
230 @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
231 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
232
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
233
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
234 @node Type Conversion
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
235 @chapter Mapping Lisp types and D-Bus types.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
236 @cindex type conversion
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 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
239 parameters, either as input parameter, or as output parameter. Every
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
240 argument belongs to a D-Bus type.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
241
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
242 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
243 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
244 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
245 D-Bus type @expansion{} Lisp object for output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
246
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
247
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
248 @section Input parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
249
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
250 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
251 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
252 applied, when the corresponding D-Bus message is created:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
253
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
254 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
255 @multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN}
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
256 @item Lisp type @tab @tab D-Bus type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
257 @item
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
258 @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
259 @item number @tab @expansion{} @tab DBUS_TYPE_UINT32
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
260 @item integer @tab @expansion{} @tab DBUS_TYPE_INT32
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
261 @item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
262 @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
263 @item list @tab @expansion{} @tab DBUS_TYPE_ARRAY
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
264 @end multitable
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
265 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
266
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
267 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
268 input parameter.
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
269
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
270 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
271 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
272 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
273 @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
274 @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
275 @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
276
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
277 @noindent
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
278 Example:
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
279
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
280 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
281 (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
282 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
283
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
284 is equivalent to
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
285
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
286 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
287 (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
288 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
289
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
290 but different to
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
291
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
292 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
293 (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
294 @end lisp
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
295
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
296 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
297 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
298 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
299 @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
300 @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
301
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
302 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
303 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
304 @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
305 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
306 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
307
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
308 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
309 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
310
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
311 @itemize
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
312 @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
313 can be empty.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
314
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
315 @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
316
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
317 @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
318 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
319 key.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
320
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
321 @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
322 @end itemize
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
323
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
324 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
325 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
326 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
327 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
328
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
329 @lisp
87540
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
330 (dbus-call-method
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
331 :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
332 "/org/freedesktop/Notifications"
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
333 "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
334 "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
335 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
336 "" ;; No icon.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
337 "Notification summary" ;; Summary.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
338 (format ;; Body.
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
339 "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
340 '(: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
341 '(: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
342 ;; (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
343 ':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
344
084340c0bd27 * dbus.texi (Type Conversion): Explain the type specification for empty
Michael Albinus <michael.albinus@gmx.de>
parents: 87491
diff changeset
345 @result{} 3
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
346 @end lisp
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
347
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
348
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
349 @section Output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
350
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
351 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
352 objects.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
353
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
354 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
355 @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
356 @item D-Bus type @tab @tab Lisp type
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
357 @item
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
358 @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
359 @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
360 @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
361 @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
362 @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
363 @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
364 @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
365 @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
366 @item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
367 @item DBUS_TYPE_STRING @tab @expansion{} @tab string
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
368 @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
369 @item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
370 @item DBUS_TYPE_ARRAY @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
371 @item DBUS_TYPE_VARIANT @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
372 @item DBUS_TYPE_STRUCT @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
373 @item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
374 @end multitable
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
375 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
376
87365
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
377 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
378 @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
379 @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
380 Emacs number size range.
7744259cbbc0 * dbus.texi (Type Conversion): Correct input parameters mapping.
Michael Albinus <michael.albinus@gmx.de>
parents: 87362
diff changeset
381
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
382 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
383 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
384 same rules.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
385
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
386 The signal @code{PropertyModified}, discussed as example in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
387 @ref{Inspection}, would offer as Lisp data the following object
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
388 (@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
389
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
390 @lisp
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
391 (@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
392 @end lisp
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
393
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
394
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
395 @node Synchronous Methods
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
396 @chapter Calling methods in a blocking way.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
397 @cindex method calls, synchronous
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
398 @cindex synchronous method calls
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
399
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
400 Methods can be called synchronously (@dfn{blocking}) or asynchronously
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
401 (@dfn{non-blocking}). Currently, just synchronous methods are
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
402 implemented.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
403
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
404 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
405 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
406 be called, and a reply message returning the resulting output
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
407 parameters from the object.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
408
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
409 @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
410 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
411 either the symbol @code{:system} or the symbol @code{:session}.
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 @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
414 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
415 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
416
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
417 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
418 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
419 Conversion}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
420
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
421 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
422 Lisp objects, according to the type conversion rules described in
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
423 @ref{Type Conversion}. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
424
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
425 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
426 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
427 :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
428 "org.gnome.seahorse.Keys" "GetKeyField"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
429 "openpgp:657984B8C7A966DD" "simple-name")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
430
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
431 @result{} (t ("Philip R. Zimmermann"))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
432 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
433
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
434 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
435 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
436 object. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
437
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
438 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
439 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
440 :system "org.freedesktop.Hal"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
441 "/org/freedesktop/Hal/devices/computer"
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
442 "org.freedesktop.Hal.Device" "GetPropertyString"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
443 "system.kernel.machine")
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
444
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
445 @result{} "i686"
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
446 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
447
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
448 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
449 interfaces of @samp{org.freedesktop.Hal} service. It offers the
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
450 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
451 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
452 @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
453 path @samp{/org/freedesktop/Hal/devices}. With the methods
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
454 @samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
455 emulate the @code{lshal} command on GNU/Linux systems:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
456
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
457 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
458 (dolist (device
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
459 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
460 :system "org.freedesktop.Hal"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
461 "/org/freedesktop/Hal/Manager"
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
462 "org.freedesktop.Hal.Manager" "GetAllDevices"))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
463 (message "\nudi = %s" device)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
464 (dolist (properties
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
465 (dbus-call-method
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
466 :system "org.freedesktop.Hal" device
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
467 "org.freedesktop.Hal.Device" "GetAllProperties"))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
468 (message " %s = %S"
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
469 (car properties) (or (caar (cdr properties)) ""))))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
470
87004
0877a1d16074 * Makefile.in (INFO_TARGETS, DVI_TARGETS): Apply dbus and dbus.dvi
Michael Albinus <michael.albinus@gmx.de>
parents: 86972
diff changeset
471 @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
472 info.addons = (\"hald-addon-acpi\")
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
473 info.bus = \"unknown\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
474 info.product = \"Computer\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
475 info.subsystem = \"unknown\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
476 info.udi = \"/org/freedesktop/Hal/devices/computer\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
477 linux.sysfs_path_device = \"(none)\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
478 power_management.acpi.linux.version = \"20051216\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
479 power_management.can_suspend_to_disk = t
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
480 power_management.can_suspend_to_ram = \"\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
481 power_management.type = \"acpi\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
482 smbios.bios.release_date = \"11/07/2001\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
483 system.chassis.manufacturer = \"COMPAL\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
484 system.chassis.type = \"Notebook\"
9ae2c39a9be6 * dbus.texi: Applying comments from RMS.
Michael Albinus <michael.albinus@gmx.de>
parents: 86942
diff changeset
485 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
486 @dots{}"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
487 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
488 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
489
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
490
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
491 @node Receiving Method Calls
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
492 @chapter Offering own methods.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
493 @cindex method calls, returning
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
494 @cindex returning method calls
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
495
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
496 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
497 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
498 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
499
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
500 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
501 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
502 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
503 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
504 @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
505 provides the interface.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
506
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
507 @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
508 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
509 @var{bus}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
510
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
511 @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
512 @code{:session}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
513
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
514 @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
515 @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
516
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
517 @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
518 registered.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
519
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
520 @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
521 provide @var{method}.
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
522
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
523 @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
524 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
525 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
526 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
527 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
528
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
529 @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
530 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
531 registration for @var{method}. Example:
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 @example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
534 (defun my-dbus-method-handler (filename)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
535 (let (result)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
536 (if (find-file filename)
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
537 (setq result '(:boolean t))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
538 (setq result '(:boolean nil)))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
539 result))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
540
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
541 @result{} my-dbus-method-handler
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
542
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
543 (dbus-register-method
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
544 :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
545 "org.freedesktop.TextEditor" "OpenFile"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
546 'my-dbus-method-handler)
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 @result{} ((:system "org.freedesktop.TextEditor" "OpenFile")
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
549 ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
550 my-method-handler))
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
551 @end example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
552
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
553 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
554 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
555 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
556 @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
557 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
558
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
559 @example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
560 # dbus-send --session --print-reply \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
561 --dest="org.freedesktop.TextEditor" \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
562 "/org/freedesktop/TextEditor" \
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
563 "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
564
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
565 @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
566 boolean true
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
567 @end example
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
568 @end defun
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
569
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
570
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
571 @node Signals
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
572 @chapter Sending and receiving signals.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
573 @cindex signals
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
574
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
575 Signals are broadcast messages. They carry input parameters, which
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
576 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
577
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
578 @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
579 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
580 is, that there are no returning output parameters.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
581
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
582 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
583 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
584 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
585
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
586 @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
587 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
588 @var{service} is registered at. @var{interface} is an interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
589 offered by @var{service}. It must provide @var{signal}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
590
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
591 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
592 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
593 Conversion}. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
594
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
595 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
596 (dbus-send-signal
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
597 :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
598 "org.gnu.Emacs.FileManager" "FileModified" "/home/albinus/.emacs")
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
599 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
600 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
601
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
602 @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
603 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
604 D-Bus @var{bus}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
605
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
606 @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
607 @code{:session}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
608
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
609 @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
610 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
611 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
612 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
613 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
614
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
615 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
616 objects shall be accepted.
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
617
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
618 @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
619 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
620 signals shall not be checked.
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
621
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
622 @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
623 provide @var{signal}.
86942
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{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
626 received. It must accept as arguments the output parameters
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
627 @var{signal} is sending. Example:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
628
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
629 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
630 (defun my-dbus-signal-handler (device)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
631 (message "Device %s added" device))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
632
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
633 @result{} my-dbus-signal-handler
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
634
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
635 (dbus-register-signal
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
636 :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
637 "org.freedesktop.Hal.Manager" "DeviceAdded"
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
638 'my-dbus-signal-handler)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
639
87309
44eebe469b1f * dbus.texi (Signals): Fix example in dbus-register-signal.
Michael Albinus <michael.albinus@gmx.de>
parents: 87158
diff changeset
640 @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
641 ("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
642 my-signal-handler))
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
643 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
644
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
645 As we know from the inspection data of interface
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
646 @code{org.freedesktop.Hal.Manager}, the signal @code{DeviceAdded}
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
647 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
648 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
649 single string argument therefore. Plugging an USB device to your
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
650 machine, when registered for signal @code{DeviceAdded}, will show you
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
651 which objects the GNU/Linux @code{hal} daemon adds.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
652
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
653 @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
654 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
655 registration for @var{signal}.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
656 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
657
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
658 @defun dbus-unregister-object object
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
659 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
660 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
661 @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
662 has been unregistered, @code{nil} otherwise.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
663 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
664
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
665
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
666 @node Errors and Events
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
667 @chapter Errors and events.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
668 @cindex errors
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
669 @cindex events
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
670
87362
85cef0528c37 * dbus.texi (Type Conversion): Extend for D-Bus compound types.
Michael Albinus <michael.albinus@gmx.de>
parents: 87309
diff changeset
671 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
672 @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
673 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
674 @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
675
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
676 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
677 @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
678 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
679
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
680 @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
681 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
682 @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
683 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
684 @code{t}.
af599a62c634 * dbus.texi (Errors and Events): New macro dbus-ignore-errors.
Michael Albinus <michael.albinus@gmx.de>
parents: 87585
diff changeset
685 @end defspec
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
686
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
687 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
688 Events, , , elisp}). The generated event has this form:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
689
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
690 @example
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
691 (dbus-event @var{bus} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} &rest @var{args})
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
692 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
693
87049
cbcfa9b4201e * dbus.texi (Signals): Precise `dbus-register-signal'.
Michael Albinus <michael.albinus@gmx.de>
parents: 87004
diff changeset
694 @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
695 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
696
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
697 @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
698 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
699
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
700 @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
701 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
702 @var{member} denote the message which has been sent.
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
703
87158
f10e4cb7d001 * dbus.texi (Synchronous Methods): Adapt dbus-call-method.
Michael Albinus <michael.albinus@gmx.de>
parents: 87053
diff changeset
704 @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
705 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
706 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
707
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
708 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
709 definition of the callback function in @ref{Signals}:
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
710
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
711 @example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
712 (defun my-dbus-signal-handler (&rest args)
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
713 (message "my-dbus-signal-handler: %S" last-input-event))
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
714 @end example
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
715
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
716 There exist convenience functions which could be called inside a
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
717 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
718
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
719 @defun dbus-event-bus-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
720 Returns the bus name @var{event} is coming from.
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
721 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
722 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
723
87585
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
724 @defun dbus-event-serial-number event
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
725 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
726 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
727 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
728 @end defun
072778cd2f17 * dbus.texi (Receiving Method Calls): New chapter.
Michael Albinus <michael.albinus@gmx.de>
parents: 87540
diff changeset
729
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
730 @defun dbus-event-service-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
731 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
732 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
733
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
734 @defun dbus-event-path-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
735 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
736 @end defun
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-interface-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
739 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
740 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
741
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
742 @defun dbus-event-member-name event
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
743 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
744 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
745 @end defun
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
746
87491
dd7c58c2342a * dbus.texi (all): Replace "..." by @dots{}.
Michael Albinus <michael.albinus@gmx.de>
parents: 87365
diff changeset
747 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
748 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
749 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
750
86942
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
751
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
752 @node GNU Free Documentation License
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
753 @appendix GNU Free Documentation License
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
754 @include doclicense.texi
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
755
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
756 @contents
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
757 @c End of dbus.texi
2fa0494ae318 * dbus.texi: New file.
Michael Albinus <michael.albinus@gmx.de>
parents:
diff changeset
758 @bye
87053
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
759
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
760 @ignore
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
761 arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8
f767f1ba8301 Add arch tagline
Miles Bader <miles@gnu.org>
parents: 87049
diff changeset
762 @end ignore