1Net::DBus(3) User Contributed Perl Documentation Net::DBus(3)
2
6 Net::DBus - Perl extension for the DBus message system
7
9 ####### Attaching to the bus ###########
10 use Net::DBus;
12 # Find the most appropriate bus
14 my $bus = Net::DBus->find;
15 # ... or explicitly go for the session bus
17 my $bus = Net::DBus->session;
18 # .... or explicitly go for the system bus
20 my $bus = Net::DBus->system
21 ######## Accessing remote services #########
24 # Get a handle to the HAL service
26 my $hal = $bus->get_service("org.freedesktop.Hal");
27 # Get the device manager
29 my $manager = $hal->get_object("/org/freedesktop/Hal/Manager",
30 "org.freedesktop.Hal.Manager");
31 # List devices
33 foreach my $dev (@{$manager->GetAllDevices}) {
34 print $dev, "\n";
35 }
36 ######### Providing services ##############
39 # Register a service known as 'org.example.Jukebox'
41 my $service = $bus->export_service("org.example.Jukebox");
42
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 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
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 - If DBUS_STARTER_BUS_TYPE is set to 'session' attach
61 to the session bus
62 - Else If DBUS_STARTER_BUS_TYPE is set to 'system' attach
64 to the system bus
65 - Else If DBUS_SESSION_BUS_ADDRESS is set attach to the
67 session bus
68 - Else attach to the system bus
70 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 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 The optional "params" hash can be used to specify the following
83 options:
84 nomainloop
86 If true, prevents the bus from being automatically attached to
87 the main Net::DBus::Reactor event loop.
88 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 my $bus = Net::DBus->session(%params);
95 Return a handle for the session message bus.
96 The optional "params" hash can be used to specify the following
98 options:
99 nomainloop
101 If true, prevents the bus from being automatically attached to
102 the main Net::DBus::Reactor event loop.
103 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 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 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 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 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 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 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 my $name = $bus->get_unique_name;
150 Retrieves the unique name of this client's connection to the bus.
151 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 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
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 $typed_value = dbus_int16($value);
171 Mark a value as being a signed, 16-bit integer.
172 $typed_value = dbus_uint16($value);
174 Mark a value as being an unsigned, 16-bit integer.
175 $typed_value = dbus_int32($value);
177 Mark a value as being a signed, 32-bit integer.
178 $typed_value = dbus_uint32($value);
180 Mark a value as being an unsigned, 32-bit integer.
181 $typed_value = dbus_int64($value);
183 Mark a value as being an unsigned, 64-bit integer.
184 $typed_value = dbus_uint64($value);
186 Mark a value as being an unsigned, 64-bit integer.
187 $typed_value = dbus_double($value);
189 Mark a value as being a double precision IEEE floating point.
190 $typed_value = dbus_byte($value);
192 Mark a value as being an unsigned, byte.
193 $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 $typed_value = dbus_signature($value);
199 Mark a value as being a UTF-8 string, whose contents is a valid
200 type signature
201 $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 $typed_value = dbus_boolean($value);
207 Mark a value as being an boolean
208 $typed_value = dbus_array($value);
210 Mark a value as being an array
211 $typed_value = dbus_struct($value);
213 Mark a value as being a structure
214 $typed_value = dbus_dict($value);
216 Mark a value as being a dictionary
217 $typed_value = dbus_variant($value);
219 Mark a value as being a variant
220 $typed_value = dbus_unix_fd($value);
222 Mark a value as being a unix file descriptor
223
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
231 Daniel Berrange <dan@berrange.com>
232
234 Copyright 2004-2011 by Daniel Berrange
235perl v5.30.0 2019-07-26 Net::DBus(3)