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         # Ensure only explicitly exported methods can be invoked
20         dbus_strict_exports;
21
22         # Export a 'Greeting' signal taking a stringl string parameter
23         dbus_signal("Greeting", ["string"]);
24
25         # Export 'Hello' as a method accepting a single string
26         # parameter, and returning a single string value
27         dbus_method("Hello", ["string"], ["string"]);
28
29         # 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

DESCRIPTION

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
42       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

SCALAR TYPES

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
54       "string"
55           A UTF-8 string of characters
56
57       "int16"
58           A 16-bit signed integer
59
60       "uint16"
61           A 16-bit unsigned integer
62
63       "int32"
64           A 32-bit signed integer
65
66       "uint32"
67           A 32-bit unsigned integer
68
69       "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
74       "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
79       "byte"
80           A single 8-bit byte
81
82       "bool"
83           A boolean value
84
85       "double"
86           An IEEE double-precision floating point
87

COMPOUND TYPES

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
93       ["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
102               $object->hello(["John", "Doe"])
103
104       ["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
115              $object->hello({forename => "John", surname => "Doe"});
116
117       ["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
126               struct {
127                 char *forename;
128                 char *surname;
129               } name;
130
131           then, when calling the method one would provide an array reference
132           with the values orded to match the structure
133
134              $object->hello(["John", "Doe"]);
135

MAGIC TYPES

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
144       "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
149       "serial"
150           The value passed in is an integer within the scope of a caller,
151           which increments on every method call.
152

ANNOTATIONS

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
160       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
165       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
171       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
175       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
179       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

METHODS

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
200       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
205           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
212       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
219       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

EXAMPLES

231       No parameters, no return values
232           A method which simply prints "Hello World" each time its called
233
234              sub Hello {
235                  my $self = shift;
236                  print "Hello World\n";
237              }
238
239              dbus_method("Hello", [], []);
240
241       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
246              sub KillAll {
247                  my $self = shift;
248                  my $processname = shift;
249                  my $ret  = system("killall $processname");
250                  return $ret == 0 ? 1 : 0;
251              }
252
253              dbus_method("KillAll", ["string"], ["bool"]);
254
255       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
259               sub LastModified {
260                  my $self = shift;
261                  my $files = shift;
262
263                  my %mods;
264                  foreach my $file (@{$files}) {
265                     $mods{$file} = (stat $file)[9];
266                  }
267                  return \%mods;
268               }
269
270               dbus_method("LastModified", ["array", "string"], ["dict", "string", "int32"]);
271
272       Annotating methods with metdata
273           A method which is targeted for removal, and also does not return
274           any value
275
276               sub PlayMP3 {
277                   my $self = shift;
278                   my $track = shift;
279
280                   system "mpg123 $track &";
281               }
282
283               dbus_method("PlayMP3", ["string"], [], { deprecated => 1, no_return => 1 });
284
285           Or giving names to input parameters:
286
287               sub PlayMP3 {
288                   my $self = shift;
289                   my $track = shift;
290
291                   system "mpg123 $track &";
292               }
293
294               dbus_method("PlayMP3", ["string"], [], { param_names => ["track"] });
295

AUTHOR

297       Daniel P. Berrange <dan@berrange.com>
298
300       Copright (C) 2004-2011, Daniel Berrange.
301

SEE ALSO

303       Net::DBus::Object, Net::DBus::Binding::Introspector
304
305
306
307perl v5.36.0                      2023-01-20            Net::DBus::Exporter(3)
Impressum