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 # Export a 'Greeting' signal taking a stringl string parameter
20 dbus_signal("Greeting", ["string"]);
21 # Export 'Hello' as a method accepting a single string
23 # parameter, and returning a single string value
24 dbus_method("Hello", ["string"], ["string"]);
25 # Export 'Goodbye' as a method accepting a single string
27 # parameter, and returning a single string, but put it
28 # in the 'org.exaple.demo.Farewell' interface
29 dbus_method("Goodbye", ["string"], ["string"], "org.example.demo.Farewell");
30
32 The "Net::DBus::Exporter" module is used to export methods and signals
33 defined in an object to the message bus. Since Perl is a loosely typed
34 language it is not possible to automatically determine correct type
35 information for methods to be exported. Thus when sub-classing
36 Net::DBus::Object, this package will provide the type information for
37 methods and signals.
38 When importing this package, an optional argument can be supplied to
40 specify the default interface name to associate with methods and sig‐
41 nals, for which an explicit interface is not specified. Thus in the
42 common case of objects only providing a single interface, this removes
43 the need to repeat the interface name against each method exported.
44
46 When specifying scalar data types for parameters and return values, the
47 following string constants must be used to denote the data type. When
48 values corresponding to these types are (un)marshalled they are repre‐
49 sented as the Perl SCALAR data type (see perldata).
50 "string"
52 A UTF-8 string of characters
53 "int16"
55 A 16-bit signed integer
56 "uint16"
58 A 16-bit unsigned integer
59 "int32"
61 A 32-bit signed integer
62 "uint32"
64 A 32-bit unsigned integer
65 "int64"
67 A 64-bit signed integer. NB, this type is not supported by many
68 builds of Perl on 32-bit platforms, so if used, your data is liable
69 to be truncated at 32-bits.
70 "uint64"
72 A 64-bit unsigned integer. NB, this type is not supported by many
73 builds of Perl on 32-bit platforms, so if used, your data is liable
74 to be truncated at 32-bits.
75 "byte"
77 A single 8-bit byte
78 "bool"
80 A boolean value
81 "double"
83 An IEEE double-precision floating point
84
86 When specifying compound data types for parameters and return values,
87 an array reference must be used, with the first element being the name
88 of the compound type.
89 ["array", ARRAY-TYPE]
91 An array of values, whose type os "ARRAY-TYPE". The "ARRAY-TYPE"
92 can be either a scalar type name, or a nested compound type. When
93 values corresponding to the array type are (un)marshalled, they are
94 represented as the Perl ARRAY data type (see perldata). If, for
95 example, a method was declared to have a single parameter with the
96 type, ["array", "string"], then when calling the method one would
97 provide a array reference of strings:
98 $object->hello(["John", "Doe"])
100 ["dict", KEY-TYPE, VALUE-TYPE]
102 A dictionary of values, more commonly known as a hash table. The
103 "KEY-TYPE" is the name of the scalar data type used for the dictio‐
104 nary keys. The "VALUE-TYPE" is the name of the scalar, or compound
105 data type used for the dictionary values. When values corresponding
106 to the dict type are (un)marshalled, they are represented as the
107 Perl HASH data type (see perldata). If, for example, a method was
108 declared to have a single parameter with the type ["dict",
109 "string", "string"], then when calling the method one would provide
110 a hash reference of strings,
111 $object->hello({forename => "John", surname => "Doe"});
113 ["struct", VALUE-TYPE-1, VALUE-TYPE-2]
115 A structure of values, best thought of as a variation on the array
116 type where the elements can vary. Many languages have an explicit
117 name associated with each value, but since Perl does not have a
118 native representation of structures, they are represented by the
119 LIST data type. If, for exaple, a method was declared to have a
120 single parameter with the type ["struct", "string", "string"], cor‐
121 responding to the C structure
122 struct {
124 char *forename;
125 char *surname;
126 } name;
127 then, when calling the method one would provide an array refernce
129 with the values orded to match the structure
130 $object->hello(["John", "Doe"]);
132
134 When specifying introspection data for an exported service, there are a
135 couple of so called "magic" types. Parameters declared as magic types
136 are not visible to clients, but instead their values are provided auto‐
137 matically by the server side bindings. One use of magic types is to get
138 an extra parameter passed with the unique name of the caller invoking
139 the method.
140 "caller"
142 The value passed in is the unique name of the caller of the method.
143 Unique names are strings automatically assigned to client connec‐
144 tions by the bus daemon, for example ':1.15'
145 "serial"
147 The value passed in is an integer within the scope of a caller,
148 which increments on every method call.
149
151 When exporting methods, signals & properties, in addition to the core
152 data typing information, a number of metadata annotations are possible.
153 These are specified by passing a hash reference with the desired keys
154 as the last parameter when defining the export. The following annota‐
155 tions are currently supported
156 no_return
158 Indicate that this method does not return any value, and thus no
159 reply message should be sent over the wire, likewise informing the
160 clients not to expect / wait for a reply message
161 deprecated
163 Indicate that use of this method/signal/property is discouraged,
164 and it may disappear altogether in a future release. Clients will
165 typically print out a warning message when a deprecated method/sig‐
166 nal/property is used.
167 param_names
169 An array of strings specifying names for the input parameters of
170 the method or signal. If omitted, no names will be assigned.
171 return_names
173 An array of strings specifying names for the return parameters of
174 the method. If omitted, no names will be assigned.
175
177 dbus_method($name, $params, $returns, [\%annotations]);
178 dbus_method($name, $params, $returns, $interface, [\%annotations]);
179 Exports a method called $name, having parameters whose types are
180 defined by $params, and returning values whose types are defined by
181 $returns. If the $interface parameter is provided, then the method
182 is associated with that interface, otherwise the default interface
183 for the calling package is used. The value for the $params parame‐
184 ter should be an array reference with each element defining the
185 data type of a parameter to the method. Likewise, the $returns
186 parameter should be an array reference with each element defining
187 the data type of a return value. If it not possible to export a
188 method which accepts a variable number of parameters, or returns a
189 variable number of values.
190 dbus_property($name, $type, $access, [\%attributes]);
192 dbus_property($name, $type, $access, $interface, [\%attributes]);
193 Exports a property called $name, whose data type is $type. If the
194 $interface parameter is provided, then the property is associated
195 with that interface, otherwise the default interface for the call‐
196 ing package is used.
197 dbus_signal($name, $params, [\%attributes]);
199 dbus_signal($name, $params, $interface, [\%attributes]);
200 Exports a signal called $name, having parameters whose types are
201 defined by $params, and returning values whose types are defined by
202 $returns. If the $interface parameter is provided, then the signal
203 is associated with that interface, otherwise the default interface
204 for the calling package is used. The value for the $params parame‐
205 ter should be an array reference with each element defining the
206 data type of a parameter to the signal. Signals do not have return
207 values. It not possible to export a signal which has a variable
208 number of parameters.
209
211 No paramters, no return values
212 A method which simply prints "Hello World" each time its called
213 sub Hello {
215 my $self = shift;
216 print "Hello World\n";
217 }
218 dbus_method("Hello", [], []);
220 One string parameter, returning an boolean value
222 A method which accepts a process name, issues the killall command
223 on it, and returns a boolean value to indicate whether it was suc‐
224 cessful.
225 sub KillAll {
227 my $self = shift;
228 my $processname = shift;
229 my $ret = system("killall $processname");
230 return $ret == 0 ? 1 : 0;
231 }
232 dbus_method("KillAll", ["string"], ["bool"]);
234 One list of strings parameter, returning a dictionary
236 A method which accepts a list of files names, stats them, and
237 returns a dictionary containing the last modification times.
238 sub LastModified {
240 my $self = shift;
241 my $files = shift;
242 my %mods;
244 foreach my $file (@{$files}) {
245 $mods{$file} = (stat $file)[9];
246 }
247 return \%mods;
248 }
249 dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
251 Annotating methods with metdata
253 A method which is targetted for removal, and also does not return
254 any value
255 sub PlayMP3 {
257 my $self = shift;
258 my $track = shift;
259 system "mpg123 $track &";
261 }
262 dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
264 Or giving names to input parameters:
266 sub PlayMP3 {
268 my $self = shift;
269 my $track = shift;
270 system "mpg123 $track &";
272 }
273 dbus_method("PlayMP3", ["string"], [], { param_names => ["track"] });
275
277 Net::DBus::Object, Net::DBus::Binding::Introspector
278
280 Daniel P. Berrange <dan@berrange.com>
281perl v5.8.8 2008-02-20 Net::DBus::Exporter(3)