1Net::DBus::Exporter(3)User Contributed Perl DocumentationNet::DBus::Exporter(3)
2
6 Net::DBus::Exporter - Export object methods and signals to the bus
7
9 # Define a new package for the object we're going
10 # to export
11 package Demo::HelloWorld;
12 # Specify the main interface provided by our object
14 use Net::DBus::Exporter qw(org.example.demo.Greeter);
15 # We're going to be a DBus object
17 use base qw(Net::DBus::Object);
18 # Ensure only explicitly exported methods can be invoked
20 dbus_strict_exports;
21 # Export a 'Greeting' signal taking a stringl string parameter
23 dbus_signal("Greeting", ["string"]);
24 # Export 'Hello' as a method accepting a single string
26 # parameter, and returning a single string value
27 dbus_method("Hello", ["string"], ["string"]);
28 # Export 'Goodbye' as a method accepting a single string
30 # parameter, and returning a single string, but put it
31 # in the 'org.exaple.demo.Farewell' interface
32 dbus_method("Goodbye", ["string"], ["string"], "org.example.demo.Farewell");
33
35 The "Net::DBus::Exporter" module is used to export methods and signals
36 defined in an object to the message bus. Since Perl is a loosely typed
37 language it is not possible to automatically determine correct type
38 information for methods to be exported. Thus when sub-classing
39 Net::DBus::Object, this package will provide the type information for
40 methods and signals.
41 When importing this package, an optional argument can be supplied to
43 specify the default interface name to associate with methods and
44 signals, for which an explicit interface is not specified. Thus in the
45 common case of objects only providing a single interface, this removes
46 the need to repeat the interface name against each method exported.
47
49 When specifying scalar data types for parameters and return values, the
50 following string constants must be used to denote the data type. When
51 values corresponding to these types are (un)marshalled they are
52 represented as the Perl SCALAR data type (see perldata).
53 "string"
55 A UTF-8 string of characters
56 "int16"
58 A 16-bit signed integer
59 "uint16"
61 A 16-bit unsigned integer
62 "int32"
64 A 32-bit signed integer
65 "uint32"
67 A 32-bit unsigned integer
68 "int64"
70 A 64-bit signed integer. NB, this type is not supported by many
71 builds of Perl on 32-bit platforms, so if used, your data is liable
72 to be truncated at 32-bits.
73 "uint64"
75 A 64-bit unsigned integer. NB, this type is not supported by many
76 builds of Perl on 32-bit platforms, so if used, your data is liable
77 to be truncated at 32-bits.
78 "byte"
80 A single 8-bit byte
81 "bool"
83 A boolean value
84 "double"
86 An IEEE double-precision floating point
87
89 When specifying compound data types for parameters and return values,
90 an array reference must be used, with the first element being the name
91 of the compound type.
92 ["array", ARRAY-TYPE]
94 An array of values, whose type os "ARRAY-TYPE". The "ARRAY-TYPE"
95 can be either a scalar type name, or a nested compound type. When
96 values corresponding to the array type are (un)marshalled, they are
97 represented as the Perl ARRAY data type (see perldata). If, for
98 example, a method was declared to have a single parameter with the
99 type, ["array", "string"], then when calling the method one would
100 provide a array reference of strings:
101 $object->hello(["John", "Doe"])
103 ["dict", KEY-TYPE, VALUE-TYPE]
105 A dictionary of values, more commonly known as a hash table. The
106 "KEY-TYPE" is the name of the scalar data type used for the
107 dictionary keys. The "VALUE-TYPE" is the name of the scalar, or
108 compound data type used for the dictionary values. When values
109 corresponding to the dict type are (un)marshalled, they are
110 represented as the Perl HASH data type (see perldata). If, for
111 example, a method was declared to have a single parameter with the
112 type ["dict", "string", "string"], then when calling the method one
113 would provide a hash reference of strings,
114 $object->hello({forename => "John", surname => "Doe"});
116 ["struct", VALUE-TYPE-1, VALUE-TYPE-2]
118 A structure of values, best thought of as a variation on the array
119 type where the elements can vary. Many languages have an explicit
120 name associated with each value, but since Perl does not have a
121 native representation of structures, they are represented by the
122 LIST data type. If, for exaple, a method was declared to have a
123 single parameter with the type ["struct", "string", "string"],
124 corresponding to the C structure
125 struct {
127 char *forename;
128 char *surname;
129 } name;
130 then, when calling the method one would provide an array reference
132 with the values orded to match the structure
133 $object->hello(["John", "Doe"]);
135
137 When specifying introspection data for an exported service, there are a
138 couple of so called "magic" types. Parameters declared as magic types
139 are not visible to clients, but instead their values are provided
140 automatically by the server side bindings. One use of magic types is to
141 get an extra parameter passed with the unique name of the caller
142 invoking the method.
143 "caller"
145 The value passed in is the unique name of the caller of the method.
146 Unique names are strings automatically assigned to client
147 connections by the bus daemon, for example ':1.15'
148 "serial"
150 The value passed in is an integer within the scope of a caller,
151 which increments on every method call.
152
154 When exporting methods, signals & properties, in addition to the core
155 data typing information, a number of metadata annotations are possible.
156 These are specified by passing a hash reference with the desired keys
157 as the last parameter when defining the export. The following
158 annotations are currently supported
159 no_return
161 Indicate that this method does not return any value, and thus no
162 reply message should be sent over the wire, likewise informing the
163 clients not to expect / wait for a reply message
164 deprecated
166 Indicate that use of this method/signal/property is discouraged,
167 and it may disappear altogether in a future release. Clients will
168 typically print out a warning message when a deprecated
169 method/signal/property is used.
170 param_names
172 An array of strings specifying names for the input parameters of
173 the method or signal. If omitted, no names will be assigned.
174 return_names
176 An array of strings specifying names for the return parameters of
177 the method. If omitted, no names will be assigned.
178 strict_exceptions
180 Exceptions thrown by this method which are not of type
181 Net::DBus::Error will not be caught and converted to D-Bus errors.
182 They will be rethrown and continue up the stack until something
183 else catches them (or the process dies).
184
186 dbus_method($name, $params, $returns, [\%annotations]);
187 dbus_method($name, $params, $returns, $interface, [\%annotations]);
188 Exports a method called $name, having parameters whose types are
189 defined by $params, and returning values whose types are defined by
190 $returns. If the $interface parameter is provided, then the method
191 is associated with that interface, otherwise the default interface
192 for the calling package is used. The value for the $params
193 parameter should be an array reference with each element defining
194 the data type of a parameter to the method. Likewise, the $returns
195 parameter should be an array reference with each element defining
196 the data type of a return value. If it not possible to export a
197 method which accepts a variable number of parameters, or returns a
198 variable number of values.
199 dbus_no_strict_exports();
201 If a object is using the Exporter to generate DBus introspection
202 data, the default behaviour is to only allow invocation of methods
203 which have been explicitly exported.
204 To allow clients to access methods which have not been explicitly
206 exported, call "dbus_no_strict_exports". NB, doing this may be a
207 security risk if you have methods considered to be "private" for
208 internal use only. As such this method should not normally be used.
209 It is here only to allow switching export behaviour to match
210 earlier releases.
211 dbus_property($name, $type, $access, [\%attributes]);
213 dbus_property($name, $type, $access, $interface, [\%attributes]);
214 Exports a property called $name, whose data type is $type. If the
215 $interface parameter is provided, then the property is associated
216 with that interface, otherwise the default interface for the
217 calling package is used.
218 dbus_signal($name, $params, [\%attributes]);
220 dbus_signal($name, $params, $interface, [\%attributes]);
221 Exports a signal called $name, having parameters whose types are
222 defined by $params. If the $interface parameter is provided, then
223 the signal is associated with that interface, otherwise the default
224 interface for the calling package is used. The value for the
225 $params parameter should be an array reference with each element
226 defining the data type of a parameter to the signal. Signals do not
227 have return values. It not possible to export a signal which has a
228 variable number of parameters.
229
231 No parameters, no return values
232 A method which simply prints "Hello World" each time its called
233 sub Hello {
235 my $self = shift;
236 print "Hello World\n";
237 }
238 dbus_method("Hello", [], []);
240 One string parameter, returning an boolean value
242 A method which accepts a process name, issues the killall command
243 on it, and returns a boolean value to indicate whether it was
244 successful.
245 sub KillAll {
247 my $self = shift;
248 my $processname = shift;
249 my $ret = system("killall $processname");
250 return $ret == 0 ? 1 : 0;
251 }
252 dbus_method("KillAll", ["string"], ["bool"]);
254 One list of strings parameter, returning a dictionary
256 A method which accepts a list of files names, stats them, and
257 returns a dictionary containing the last modification times.
258 sub LastModified {
260 my $self = shift;
261 my $files = shift;
262 my %mods;
264 foreach my $file (@{$files}) {
265 $mods{$file} = (stat $file)[9];
266 }
267 return \%mods;
268 }
269 dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
271 Annotating methods with metdata
273 A method which is targeted for removal, and also does not return
274 any value
275 sub PlayMP3 {
277 my $self = shift;
278 my $track = shift;
279 system "mpg123 $track &";
281 }
282 dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
284 Or giving names to input parameters:
286 sub PlayMP3 {
288 my $self = shift;
289 my $track = shift;
290 system "mpg123 $track &";
292 }
293 dbus_method("PlayMP3", ["string"], [], { param_names => ["track"] });
295
297 Daniel P. Berrange <dan@berrange.com>
298
300 Copright (C) 2004-2011, Daniel Berrange.
301
303 Net::DBus::Object, Net::DBus::Binding::Introspector
304perl v5.38.0 2023-07-21 Net::DBus::Exporter(3)