1 """Service-side D-Bus decorators."""
3 # Copyright (C) 2003, 2004, 2005, 2006 Red Hat Inc. <http://www.redhat.com/>
4 # Copyright (C) 2003 David Zeuthen
5 # Copyright (C) 2004 Rob Taylor
6 # Copyright (C) 2005, 2006 Collabora Ltd. <http://www.collabora.co.uk/>
8 # Licensed under the Academic Free License version 2.1
10 # This program is free software; you can redistribute it and/or modify
11 # it under the terms of the GNU General Public License as published by
12 # the Free Software Foundation; either version 2 of the License, or
13 # (at your option) any later version.
15 # This program is distributed in the hope that it will be useful,
16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 # GNU General Public License for more details.
20 # You should have received a copy of the GNU General Public License
21 # along with this program; if not, write to the Free Software
22 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 __all__
= ('method', 'signal')
25 __docformat__
= 'restructuredtext'
31 from dbus
.exceptions
import DBusException
34 def method(dbus_interface
, in_signature
=None, out_signature
=None,
36 sender_keyword
=None, path_keyword
=None, destination_keyword
=None,
37 message_keyword
=None, connection_keyword
=None,
38 utf8_strings
=False, byte_arrays
=False):
39 """Factory for decorators used to mark methods of a `dbus.service.Object`
40 to be exported on the D-Bus.
42 The decorated method will be exported over D-Bus as the method of the
43 same name on the given D-Bus interface.
46 `dbus_interface` : str
47 Name of a D-Bus interface
48 `in_signature` : str or None
49 If not None, the signature of the method parameters in the usual
51 `out_signature` : str or None
52 If not None, the signature of the return value in the usual
54 `async_callbacks` : tuple containing (str,str), or None
55 If None (default) the decorated method is expected to return
56 values matching the `out_signature` as usual, or raise
57 an exception on error. If not None, the following applies:
59 `async_callbacks` contains the names of two keyword arguments to
60 the decorated function, which will be used to provide a success
61 callback and an error callback (in that order).
63 When the decorated method is called via the D-Bus, its normal
64 return value will be ignored; instead, a pair of callbacks are
65 passed as keyword arguments, and the decorated method is
66 expected to arrange for one of them to be called.
68 On success the success callback must be called, passing the
69 results of this method as positional parameters in the format
70 given by the `out_signature`.
72 On error the decorated method may either raise an exception
73 before it returns, or arrange for the error callback to be
74 called with an Exception instance as parameter.
76 `sender_keyword` : str or None
77 If not None, contains the name of a keyword argument to the
78 decorated function, conventionally ``'sender'``. When the
79 method is called, the sender's unique name will be passed as
80 this keyword argument.
82 `path_keyword` : str or None
83 If not None (the default), the decorated method will receive
84 the destination object path as a keyword argument with this
85 name. Normally you already know the object path, but in the
86 case of "fallback paths" you'll usually want to use the object
87 path in the method's implementation.
89 `destination_keyword` : str or None
90 If not None (the default), the decorated method will receive
91 the destination bus name as a keyword argument with this name.
92 Included for completeness - you shouldn't need this.
94 `message_keyword` : str or None
95 If not None (the default), the decorated method will receive
96 the `dbus.lowlevel.MethodCallMessage` as a keyword argument
99 `connection_keyword` : str or None
100 If not None (the default), the decorated method will receive
101 the `dbus.connection.Connection` as a keyword argument
102 with this name. This is generally only useful for objects
103 that are available on more than one connection.
105 `utf8_strings` : bool
106 If False (default), D-Bus strings are passed to the decorated
107 method as objects of class dbus.String, a unicode subclass.
109 If True, D-Bus strings are passed to the decorated method
110 as objects of class dbus.UTF8String, a str subclass guaranteed
111 to be encoded in UTF-8.
113 This option does not affect object-paths and signatures, which
114 are always 8-bit strings (str subclass) encoded in ASCII.
117 If False (default), a byte array will be passed to the decorated
118 method as an `Array` (a list subclass) of `Byte` objects.
120 If True, a byte array will be passed to the decorated method as
121 a `ByteArray`, a str subclass. This is usually what you want,
122 but is switched off by default to keep dbus-python's API
125 _dbus_bindings
.validate_interface_name(dbus_interface
)
128 args
= inspect
.getargspec(func
)[0]
132 if type(async_callbacks
) != tuple:
133 raise TypeError('async_callbacks must be a tuple of (keyword for return callback, keyword for error callback)')
134 if len(async_callbacks
) != 2:
135 raise ValueError('async_callbacks must be a tuple of (keyword for return callback, keyword for error callback)')
136 args
.remove(async_callbacks
[0])
137 args
.remove(async_callbacks
[1])
140 args
.remove(sender_keyword
)
142 args
.remove(path_keyword
)
143 if destination_keyword
:
144 args
.remove(destination_keyword
)
146 args
.remove(message_keyword
)
147 if connection_keyword
:
148 args
.remove(connection_keyword
)
151 in_sig
= tuple(_dbus_bindings
.Signature(in_signature
))
153 if len(in_sig
) > len(args
):
154 raise ValueError, 'input signature is longer than the number of arguments taken'
155 elif len(in_sig
) < len(args
):
156 raise ValueError, 'input signature is shorter than the number of arguments taken'
158 func
._dbus
_is
_method
= True
159 func
._dbus
_async
_callbacks
= async_callbacks
160 func
._dbus
_interface
= dbus_interface
161 func
._dbus
_in
_signature
= in_signature
162 func
._dbus
_out
_signature
= out_signature
163 func
._dbus
_sender
_keyword
= sender_keyword
164 func
._dbus
_path
_keyword
= path_keyword
165 func
._dbus
_destination
_keyword
= destination_keyword
166 func
._dbus
_message
_keyword
= message_keyword
167 func
._dbus
_connection
_keyword
= connection_keyword
168 func
._dbus
_args
= args
169 func
._dbus
_get
_args
_options
= {'byte_arrays': byte_arrays
,
170 'utf8_strings': utf8_strings
}
176 def signal(dbus_interface
, signature
=None, path_keyword
=None,
177 connection_keyword
=None):
178 """Factory for decorators used to mark methods of a `dbus.service.Object`
179 to emit signals on the D-Bus.
181 Whenever the decorated method is called in Python, after the method
182 body is executed, a signal with the same name as the decorated method,
183 with the given D-Bus interface, will be emitted from this object.
186 `dbus_interface` : str
187 The D-Bus interface whose signal is emitted
189 The signature of the signal in the usual D-Bus notation
191 `path_keyword` : str or None
192 A keyword argument to the decorated method. If not None,
193 that argument will not be emitted as an argument of
194 the signal, and when the signal is emitted, it will appear
195 to come from the object path given by the keyword argument.
197 Note that when calling the decorated method, you must always
198 pass in the object path as a keyword argument, not as a
201 `connection_keyword` : str or None
202 Similar to `path_keyword`, but this gives the Connection on
203 which the signal should be emitted. If given, and the path_keyword
204 is also given, the signal will be emitted at that path on that
205 connection; if given, but the path_keyword is not, the signal
206 will be emitted from every path at which this object is available
209 If not given, the signal is emitted on every Connection on which
210 the object is available: if the `path_keyword` is given, it will
211 be emitted at that path on each Connection, otherwise it will be
212 emitted once per (Connection, path) pair.
214 _dbus_bindings
.validate_interface_name(dbus_interface
)
216 member_name
= func
.__name
__
217 _dbus_bindings
.validate_member_name(member_name
)
219 def emit_signal(self
, *args
, **keywords
):
220 func(self
, *args
, **keywords
)
224 object_path
= keywords
.pop(path_keyword
, None)
226 if connection_keyword
:
227 connection
= keywords
.pop(connection_keyword
, None)
229 if connection
is None:
230 if object_path
is None:
232 locations
= self
.locations
234 # any conn, specified path
236 for location
in self
.locations
:
237 connections
.add(connection
)
238 locations
= [(connection
, object_path
)
239 for connection
in connections
]
240 elif object_path
is None:
241 # specified conn, any path
242 locations
= [L
for L
in self
.locations
if L
[0] is connection
]
244 # specified conn, specified path
245 locations
= ((connection
, object_path
),)
247 for location
in locations
:
248 message
= _dbus_bindings
.SignalMessage(location
[1],
251 if signature
is not None:
252 message
.append(signature
=signature
, *args
)
254 message
.append(*args
)
256 location
[0].send_message(message
)
258 args
= inspect
.getargspec(func
)[0]
262 sig
= tuple(_dbus_bindings
.Signature(signature
))
264 if len(sig
) > len(args
):
265 raise ValueError, 'signal signature is longer than the number of arguments provided'
266 elif len(sig
) < len(args
):
267 raise ValueError, 'signal signature is shorter than the number of arguments provided'
269 emit_signal
.__name
__ = func
.__name
__
270 emit_signal
.__doc
__ = func
.__doc
__
271 emit_signal
._dbus
_is
_signal
= True
272 emit_signal
._dbus
_interface
= dbus_interface
273 emit_signal
._dbus
_signature
= signature
274 emit_signal
._dbus
_args
= args