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

NAME

6       Net::DBus - Perl extension for the DBus message system
7

SYNOPSIS

9         ####### Attaching to the bus ###########
10
11         use Net::DBus;
12
13         # Find the most appropriate bus
14         my $bus = Net::DBus->find;
15
16         # ... or explicitly go for the session bus
17         my $bus = Net::DBus->session;
18
19         # .... or explicitly go for the system bus
20         my $bus = Net::DBus->system
21
22
23         ######## Accessing remote services #########
24
25         # Get a handle to the HAL service
26         my $hal = $bus->get_service("org.freedesktop.Hal");
27
28         # Get the device manager
29         my $manager = $hal->get_object("/org/freedesktop/Hal/Manager",
30                                        "org.freedesktop.Hal.Manager");
31
32         # List devices
33         foreach my $dev (@{$manager->GetAllDevices}) {
34             print $dev, "\n";
35         }
36
37
38         ######### Providing services ##############
39
40         # Register a service known as 'org.example.Jukebox'
41         my $service = $bus->export_service("org.example.Jukebox");
42

DESCRIPTION

44       Net::DBus provides a Perl API for the DBus message system.  The DBus
45       Perl interface is currently operating against the 0.32 development
46       version of DBus, but should work with later versions too, providing the
47       API changes have not been too drastic.
48
49       Users of this package are either typically, service providers in which
50       case the Net::DBus::Service and Net::DBus::Object modules are of most
51       relevance, or are client consumers, in which case
52       Net::DBus::RemoteService and Net::DBus::RemoteObject are of most
53       relevance.
54

METHODS

56       my $bus = Net::DBus->find(%params);
57           Search for the most appropriate bus to connect to and return a
58           connection to it. The heuristic used for the search is
59
60             - If DBUS_STARTER_BUS_TYPE is set to 'session' attach
61               to the session bus
62
63             - Else If DBUS_STARTER_BUS_TYPE is set to 'system' attach
64               to the system bus
65
66             - Else If DBUS_SESSION_BUS_ADDRESS is set attach to the
67               session bus
68
69             - Else attach to the system bus
70
71           The optional "params" hash can contain be used to specify
72           connection options. The only support option at this time is
73           "nomainloop" which prevents the bus from being automatically
74           attached to the main Net::DBus::Reactor event loop.
75
76       my $bus = Net::DBus->system(%params);
77           Return a handle for the system message bus. Note that the system
78           message bus is locked down by default, so unless appropriate access
79           control rules are added in /etc/dbus/system.d/, an application may
80           access services, but won't be able to export services.
81
82           The optional "params" hash can be used to specify the following
83           options:
84
85           nomainloop
86               If true, prevents the bus from being automatically attached to
87               the main Net::DBus::Reactor event loop.
88
89           private
90               If true, the socket opened is private; any existing socket will
91               be ignored and any future attempts to open the same bus will
92               return a different existing socket or open a fresh one.
93
94       my $bus = Net::DBus->session(%params);
95           Return a handle for the session message bus.
96
97           The optional "params" hash can be used to specify the following
98           options:
99
100           nomainloop
101               If true, prevents the bus from being automatically attached to
102               the main Net::DBus::Reactor event loop.
103
104           private
105               If true, the socket opened is private; any existing socket will
106               be ignored and any future attempts to open the same bus will
107               return a different existing socket or open a fresh one.
108
109       my $bus = Net::DBus->test(%params);
110           Returns a handle for a virtual bus for use in unit tests. This bus
111           does not make any network connections, but rather has an in-memory
112           message pipeline. Consult Net::DBus::Test::MockConnection for
113           further details of how to use this special bus.
114
115       my $bus = Net::DBus->new($address, %params);
116           Return a connection to a specific message bus.  The $address
117           parameter must contain the address of the message bus to connect
118           to. An example address for a session bus might look like
119           "unix:abstract=/tmp/dbus-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500",
120           while one for a system bus would look like
121           "unix:/var/run/dbus/system_bus_socket".  The optional "params" hash
122           can contain be used to specify connection options. The only support
123           option at this time is "nomainloop" which prevents the bus from
124           being automatically attached to the main Net::DBus::Reactor event
125           loop.
126
127       my $connection = $bus->get_connection;
128           Return a handle to the underlying, low level connection object
129           associated with this bus. The returned object will be an instance
130           of the Net::DBus::Binding::Bus class. This method is not intended
131           for use by (most!) application developers, so if you don't
132           understand what this is for, then you don't need to be calling it!
133
134       my $service = $bus->get_service($name);
135           Retrieves a handle for the remote service identified by the service
136           name $name. The returned object will be an instance of the
137           Net::DBus::RemoteService class.
138
139       my $service = $bus->export_service($name);
140           Registers a service with the bus, returning a handle to the
141           service. The returned object is an instance of the
142           Net::DBus::Service class.
143
144       my $object = $bus->get_bus_object;
145           Retrieves a handle to the bus object, "/org/freedesktop/DBus",
146           provided by the service "org.freedesktop.DBus". The returned object
147           is an instance of Net::DBus::RemoteObject
148
149       my $name = $bus->get_unique_name;
150           Retrieves the unique name of this client's connection to the bus.
151
152       my $name = $bus->get_service_owner($service);
153           Retrieves the unique name of the client on the bus owning the
154           service named by the $service parameter.
155
156       my $timeout = $bus->timeout(60 * 1000);
157           Sets or retrieves the timeout value which will be used for DBus
158           requests belongs to this bus connection. The timeout should be
159           specified in milliseconds, with the default value being 60 seconds.
160

DATA TYPING METHODS

162       These methods are not usually used, since most services provide
163       introspection data to inform clients of their data typing requirements.
164       If introspection data is incomplete, however, it may be necessary for a
165       client to mark values with specific data types. In such a case, the
166       following methods can be used. They are not, however, exported by
167       default so must be requested at import time by specifying 'use
168       Net::DBus qw(:typing)'
169
170       $typed_value = dbus_int16($value);
171           Mark a value as being a signed, 16-bit integer.
172
173       $typed_value = dbus_uint16($value);
174           Mark a value as being an unsigned, 16-bit integer.
175
176       $typed_value = dbus_int32($value);
177           Mark a value as being a signed, 32-bit integer.
178
179       $typed_value = dbus_uint32($value);
180           Mark a value as being an unsigned, 32-bit integer.
181
182       $typed_value = dbus_int64($value);
183           Mark a value as being an unsigned, 64-bit integer.
184
185       $typed_value = dbus_uint64($value);
186           Mark a value as being an unsigned, 64-bit integer.
187
188       $typed_value = dbus_double($value);
189           Mark a value as being a double precision IEEE floating point.
190
191       $typed_value = dbus_byte($value);
192           Mark a value as being an unsigned, byte.
193
194       $typed_value = dbus_string($value);
195           Mark a value as being a UTF-8 string. This is not usually required
196           since 'string' is the default data type for any Perl scalar value.
197
198       $typed_value = dbus_signature($value);
199           Mark a value as being a UTF-8 string, whose contents is a valid
200           type signature
201
202       $typed_value = dbus_object_path($value);
203           Mark a value as being a UTF-8 string, whose contents is a valid
204           object path.
205
206       $typed_value = dbus_boolean($value);
207           Mark a value as being an boolean
208
209       $typed_value = dbus_array($value);
210           Mark a value as being an array
211
212       $typed_value = dbus_struct($value);
213           Mark a value as being a structure
214
215       $typed_value = dbus_dict($value);
216           Mark a value as being a dictionary
217
218       $typed_value = dbus_variant($value);
219           Mark a value as being a variant
220
221       $typed_value = dbus_unix_fd($value);
222           Mark a value as being a unix file descriptor
223

SEE ALSO

225       Net::DBus, Net::DBus::RemoteService, Net::DBus::Service,
226       Net::DBus::RemoteObject, Net::DBus::Object, Net::DBus::Exporter,
227       Net::DBus::Dumper, Net::DBus::Reactor, "dbus-monitor(1)",
228       "dbus-daemon-1(1)", "dbus-send(1)", <http://dbus.freedesktop.org>,
229

AUTHOR

231       Daniel Berrange <dan@berrange.com>
232
234       Copyright 2004-2011 by Daniel Berrange
235
236
237
238perl v5.28.0                      2015-03-16                      Net::DBus(3)
Impressum