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 When $name is not specified or is "undef" then returned handle to
145 the service is identified only by the unique name of client's
146 connection to the bus.
147 my $object = $bus->get_bus_object;
149 Retrieves a handle to the bus object, "/org/freedesktop/DBus",
150 provided by the service "org.freedesktop.DBus". The returned object
151 is an instance of Net::DBus::RemoteObject
152 my $name = $bus->get_unique_name;
154 Retrieves the unique name of this client's connection to the bus.
155 my $name = $bus->get_service_owner($service);
157 Retrieves the unique name of the client on the bus owning the
158 service named by the $service parameter.
159 my $timeout = $bus->timeout(60 * 1000);
161 Sets or retrieves the timeout value which will be used for DBus
162 requests belongs to this bus connection. The timeout should be
163 specified in milliseconds, with the default value being 60 seconds.
164
166 These methods are not usually used, since most services provide
167 introspection data to inform clients of their data typing requirements.
168 If introspection data is incomplete, however, it may be necessary for a
169 client to mark values with specific data types. In such a case, the
170 following methods can be used. They are not, however, exported by
171 default so must be requested at import time by specifying 'use
172 Net::DBus qw(:typing)'
173 $typed_value = dbus_int16($value);
175 Mark a value as being a signed, 16-bit integer.
176 $typed_value = dbus_uint16($value);
178 Mark a value as being an unsigned, 16-bit integer.
179 $typed_value = dbus_int32($value);
181 Mark a value as being a signed, 32-bit integer.
182 $typed_value = dbus_uint32($value);
184 Mark a value as being an unsigned, 32-bit integer.
185 $typed_value = dbus_int64($value);
187 Mark a value as being an unsigned, 64-bit integer.
188 $typed_value = dbus_uint64($value);
190 Mark a value as being an unsigned, 64-bit integer.
191 $typed_value = dbus_double($value);
193 Mark a value as being a double precision IEEE floating point.
194 $typed_value = dbus_byte($value);
196 Mark a value as being an unsigned, byte.
197 $typed_value = dbus_string($value);
199 Mark a value as being a UTF-8 string. This is not usually required
200 since 'string' is the default data type for any Perl scalar value.
201 $typed_value = dbus_signature($value);
203 Mark a value as being a UTF-8 string, whose contents is a valid
204 type signature
205 $typed_value = dbus_object_path($value);
207 Mark a value as being a UTF-8 string, whose contents is a valid
208 object path.
209 $typed_value = dbus_boolean($value);
211 Mark a value as being an boolean
212 $typed_value = dbus_array($value);
214 Mark a value as being an array
215 $typed_value = dbus_struct($value);
217 Mark a value as being a structure
218 $typed_value = dbus_dict($value);
220 Mark a value as being a dictionary
221 $typed_value = dbus_variant($value);
223 Mark a value as being a variant
224 $typed_value = dbus_unix_fd($value);
226 Mark a value as being a unix file descriptor
227
229 Net::DBus, Net::DBus::RemoteService, Net::DBus::Service,
230 Net::DBus::RemoteObject, Net::DBus::Object, Net::DBus::Exporter,
231 Net::DBus::Dumper, Net::DBus::Reactor, "dbus-monitor(1)",
232 "dbus-daemon-1(1)", "dbus-send(1)", <http://dbus.freedesktop.org>,
233
235 Daniel Berrange <dan@berrange.com>
236
238 Copyright 2004-2011 by Daniel Berrange
239perl v5.32.1 2021-01-27 Net::DBus(3)