1Net::DBus::Exporter(3)User Contributed Perl DocumentationNet::DBus::Exporter(3)
2
3
4

NAME

6       Net::DBus::Exporter - Export object methods and signals to the bus
7

SYNOPSIS

9         # Define a new package for the object we're going
10         # to export
11         package Demo::HelloWorld;
12
13         # Specify the main interface provided by our object
14         use Net::DBus::Exporter qw(org.example.demo.Greeter);
15
16         # We're going to be a DBus object
17         use base qw(Net::DBus::Object);
18
19         # Export a 'Greeting' signal taking a stringl string parameter
20         dbus_signal("Greeting", ["string"]);
21
22         # Export 'Hello' as a method accepting a single string
23         # parameter, and returning a single string value
24         dbus_method("Hello", ["string"], ["string"]);
25
26         # 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

DESCRIPTION

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
39       When importing this package, an optional argument can be supplied to
40       specify the default interface name to associate with methods and
41       signals, 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

SCALAR TYPES

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
49       represented as the Perl SCALAR data type (see perldata).
50
51       "string"
52           A UTF-8 string of characters
53
54       "int16"
55           A 16-bit signed integer
56
57       "uint16"
58           A 16-bit unsigned integer
59
60       "int32"
61           A 32-bit signed integer
62
63       "uint32"
64           A 32-bit unsigned integer
65
66       "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
71       "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
76       "byte"
77           A single 8-bit byte
78
79       "bool"
80           A boolean value
81
82       "double"
83           An IEEE double-precision floating point
84

COMPOUND TYPES

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
90       ["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
99               $object->hello(["John", "Doe"])
100
101       ["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
104           dictionary keys. The "VALUE-TYPE" is the name of the scalar, or
105           compound data type used for the dictionary values. When values
106           corresponding to the dict type are (un)marshalled, they are
107           represented as the Perl HASH data type (see perldata). If, for
108           example, a method was declared to have a single parameter with the
109           type ["dict", "string", "string"], then when calling the method one
110           would provide a hash reference of strings,
111
112              $object->hello({forename => "John", surname => "Doe"});
113
114       ["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"],
121           corresponding to the C structure
122
123               struct {
124                 char *forename;
125                 char *surname;
126               } name;
127
128           then, when calling the method one would provide an array refernce
129           with the values orded to match the structure
130
131              $object->hello(["John", "Doe"]);
132

MAGIC TYPES

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
137       automatically by the server side bindings. One use of magic types is to
138       get an extra parameter passed with the unique name of the caller
139       invoking the method.
140
141       "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
144           connections by the bus daemon, for example ':1.15'
145
146       "serial"
147           The value passed in is an integer within the scope of a caller,
148           which increments on every method call.
149

ANNOTATIONS

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
155       annotations are currently supported
156
157       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
162       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
166           method/signal/property is used.
167
168       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
172       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

METHODS

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
184           parameter should be an array reference with each element defining
185           the 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
191       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
196           calling package is used.
197
198       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
205           parameter should be an array reference with each element defining
206           the data type of a parameter to the signal. Signals do not have
207           return values. It not possible to export a signal which has a
208           variable number of parameters.
209

EXAMPLES

211       No paramters, no return values
212           A method which simply prints "Hello World" each time its called
213
214              sub Hello {
215                  my $self = shift;
216                  print "Hello World\n";
217              }
218
219              dbus_method("Hello", [], []);
220
221       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
224           successful.
225
226              sub KillAll {
227                  my $self = shift;
228                  my $processname = shift;
229                  my $ret  = system("killall $processname");
230                  return $ret == 0 ? 1 : 0;
231              }
232
233              dbus_method("KillAll", ["string"], ["bool"]);
234
235       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
239               sub LastModified {
240                  my $self = shift;
241                  my $files = shift;
242
243                  my %mods;
244                  foreach my $file (@{$files}) {
245                     $mods{$file} = (stat $file)[9];
246                  }
247                  return \%mods;
248               }
249
250               dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
251
252       Annotating methods with metdata
253           A method which is targetted for removal, and also does not return
254           any value
255
256               sub PlayMP3 {
257                   my $self = shift;
258                   my $track = shift;
259
260                   system "mpg123 $track &";
261               }
262
263               dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
264
265           Or giving names to input parameters:
266
267               sub PlayMP3 {
268                   my $self = shift;
269                   my $track = shift;
270
271                   system "mpg123 $track &";
272               }
273
274               dbus_method("PlayMP3", ["string"], [], { param_names => ["track"] });
275

SEE ALSO

277       Net::DBus::Object, Net::DBus::Binding::Introspector
278

AUTHORS

280       Daniel P. Berrange <dan@berrange.com>
281
282
283
284perl v5.12.0                      2008-02-21            Net::DBus::Exporter(3)
Impressum