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 #########
23 # Get a handle to the HAL service
25 my $hal = $bus->get_service("org.freedesktop.Hal");
26 # Get the device manager
28 my $manager = $hal->get_object("/org/freedesktop/Hal/Manager",
29 "org.freedesktop.Hal.Manager");
30 # List devices
32 foreach my $dev (@{$manager->GetAllDevices}) {
33 print $dev, "\n";
34 }
35 ######### Providing services ##############
37 # Register a service known as 'org.example.Jukebox'
39 my $service = $bus->export_service("org.example.Jukebox");
40
42 Net::DBus provides a Perl API for the DBus message system. The DBus
43 Perl interface is currently operating against the 0.32 development ver‐
44 sion of DBus, but should work with later versions too, providing the
45 API changes have not been too drastic.
46 Users of this package are either typically, service providers in which
48 case the Net::DBus::Service and Net::DBus::Object modules are of most
49 relevance, or are client consumers, in which case Net::DBus::RemoteSer‐
50 vice and Net::DBus::RemoteObject are of most relevance.
51
53 my $bus = Net::DBus->find(%params);
54 Search for the most appropriate bus to connect to and return a con‐
55 nection to it. The heuristic used for the search is
56 - If DBUS_STARTER_BUS_TYPE is set to 'session' attach
58 to the session bus
59 - Else If DBUS_STARTER_BUS_TYPE is set to 'system' attach
61 to the system bus
62 - Else If DBUS_SESSION_BUS_ADDRESS is set attach to the
64 session bus
65 - Else attach to the system bus
67 The optional "params" hash can contain be used to specify connec‐
69 tion options. The only support option at this time is "nomainloop"
70 which prevents the bus from being automatically attached to the
71 main Net::DBus::Reactor event loop.
72 my $bus = Net::DBus->system(%params);
74 Return a handle for the system message bus. Note that the system
75 message bus is locked down by default, so unless appropriate access
76 control rules are added in /etc/dbus/system.d/, an application may
77 access services, but won't be able to export services. The
78 optional "params" hash can contain be used to specify connection
79 options. The only support option at this time is "nomainloop" which
80 prevents the bus from being automatically attached to the main
81 Net::DBus::Reactor event loop.
82 my $bus = Net::DBus->session(%params);
84 Return a handle for the session message bus. The optional "params"
85 hash can contain be used to specify connection options. The only
86 support option at this time is "nomainloop" which prevents the bus
87 from being automatically attached to the main Net::DBus::Reactor
88 event loop.
89 my $bus = Net::DBus->test(%params);
91 Returns a handle for a virtual bus for use in unit tests. This bus
92 does not make any network connections, but rather has an in-memory
93 message pipeline. Consult Net::DBus::Test::MockConnection for fur‐
94 ther details of how to use this special bus.
95 my $bus = Net::DBus->new($address, %params);
97 Return a connection to a specific message bus. The $address param‐
98 eter must contain the address of the message bus to connect to. An
99 example address for a session bus might look like
100 "unix:abstract=/tmp/dbus-PBFyyu‐
101 UiVb,guid=191e0a43c3efc222e0818be556d67500", while one for a system
102 bus would look like "unix:/var/run/dbus/system_bus_socket". The
103 optional "params" hash can contain be used to specify connection
104 options. The only support option at this time is "nomainloop" which
105 prevents the bus from being automatically attached to the main
106 Net::DBus::Reactor event loop.
107 my $connection = $bus->get_connection;
109 Return a handle to the underlying, low level connection object
110 associated with this bus. The returned object will be an instance
111 of the Net::DBus::Binding::Bus class. This method is not intended
112 for use by (most!) application developers, so if you don't under‐
113 stand what this is for, then you don't need to be calling it!
114 my $service = $bus->get_service($name);
116 Retrieves a handle for the remote service identified by the service
117 name $name. The returned object will be an instance of the
118 Net::DBus::RemoteService class.
119 my $service = $bus->export_service($name);
121 Registers a service with the bus, returning a handle to the ser‐
122 vice. The returned object is an instance of the Net::DBus::Service
123 class.
124 my $object = $bus->get_bus_object;
126 Retrieves a handle to the bus object, "/org/freedesktop/DBus", pro‐
127 vided by the service "org.freedesktop.DBus". The returned object is
128 an instance of Net::DBus::RemoteObject
129 my $name = $bus->get_unique_name;
131 Retrieves the unique name of this client's connection to the bus.
132 my $name = $bus->get_service_owner($service);
134 Retrieves the unique name of the client on the bus owning the ser‐
135 vice named by the $service parameter.
136
138 These methods are not usually used, since most services provide intro‐
139 spection data to inform clients of their data typing requirements. If
140 introspection data is incomplete, however, it may be neccessary for a
141 client to mark values with specific data types. In such a case, the
142 following methods can be used. They are not, however, exported by
143 default so must be requested at import time by specifying 'use
144 Net::DBus qw(:typing)'
145 $typed_value = dbus_int16($value);
147 Mark a value as being a signed, 16-bit integer.
148 $typed_value = dbus_uint16($value);
150 Mark a value as being an unsigned, 16-bit integer.
151 $typed_value = dbus_int32($value);
153 Mark a value as being a signed, 32-bit integer.
154 $typed_value = dbus_uint32($value);
156 Mark a value as being an unsigned, 32-bit integer.
157 $typed_value = dbus_int64($value);
159 Mark a value as being an unsigned, 64-bit integer.
160 $typed_value = dbus_uint64($value);
162 Mark a value as being an unsigned, 64-bit integer.
163 $typed_value = dbus_double($value);
165 Mark a value as being a double precision IEEE floating point.
166 $typed_value = dbus_byte($value);
168 Mark a value as being an unsigned, byte.
169 $typed_value = dbus_string($value);
171 Mark a value as being a UTF-8 string. This is not usually required
172 since 'string' is the default data type for any Perl scalar value.
173 $typed_value = dbus_signature($value);
175 Mark a value as being a UTF-8 string, whose contents is a valid
176 type signature
177 $typed_value = dbus_object_path($value);
179 Mark a value as being a UTF-8 string, whose contents is a valid
180 object path.
181 $typed_value = dbus_boolean($value);
183 Mark a value as being an boolean
184 $typed_value = dbus_array($value);
186 Mark a value as being an array
187 $typed_value = dbus_struct($value);
189 Mark a value as being a structure
190 $typed_value = dbus_dict($value);
192 Mark a value as being a dictionary
193 $typed_value = dbus_variant($value);
195 Mark a value as being a variant
196
198 Net::DBus, Net::DBus::RemoteService, Net::DBus::Service,
199 Net::DBus::RemoteObject, Net::DBus::Object, Net::DBus::Exporter,
200 Net::DBus::Dumper, Net::DBus::Reactor, "dbus-monitor(1)", "dbus-dae‐
201 mon-1(1)", "dbus-send(1)", <http://dbus.freedesktop.org>,
202
204 Daniel Berrange <dan@berrange.com>
205
207 Copyright 2004-2005 by Daniel Berrange
208perl v5.8.8 2008-02-20 Net::DBus(3)