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. The
81 optional "params" hash can contain be used to specify connection
82 options. The only support option at this time is "nomainloop" which
83 prevents the bus from being automatically attached to the main
84 Net::DBus::Reactor event loop.
85 my $bus = Net::DBus->session(%params);
87 Return a handle for the session message bus. The optional "params"
88 hash can contain be used to specify connection options. The only
89 support option at this time is "nomainloop" which prevents the bus
90 from being automatically attached to the main Net::DBus::Reactor
91 event loop.
92 my $bus = Net::DBus->test(%params);
94 Returns a handle for a virtual bus for use in unit tests. This bus
95 does not make any network connections, but rather has an in-memory
96 message pipeline. Consult Net::DBus::Test::MockConnection for
97 further details of how to use this special bus.
98 my $bus = Net::DBus->new($address, %params);
100 Return a connection to a specific message bus. The $address
101 parameter must contain the address of the message bus to connect
102 to. An example address for a session bus might look like
103 "unix:abstract=/tmp/dbus-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500",
104 while one for a system bus would look like
105 "unix:/var/run/dbus/system_bus_socket". The optional "params" hash
106 can contain be used to specify connection options. The only support
107 option at this time is "nomainloop" which prevents the bus from
108 being automatically attached to the main Net::DBus::Reactor event
109 loop.
110 my $connection = $bus->get_connection;
112 Return a handle to the underlying, low level connection object
113 associated with this bus. The returned object will be an instance
114 of the Net::DBus::Binding::Bus class. This method is not intended
115 for use by (most!) application developers, so if you don't
116 understand what this is for, then you don't need to be calling it!
117 my $service = $bus->get_service($name);
119 Retrieves a handle for the remote service identified by the service
120 name $name. The returned object will be an instance of the
121 Net::DBus::RemoteService class.
122 my $service = $bus->export_service($name);
124 Registers a service with the bus, returning a handle to the
125 service. The returned object is an instance of the
126 Net::DBus::Service class.
127 my $object = $bus->get_bus_object;
129 Retrieves a handle to the bus object, "/org/freedesktop/DBus",
130 provided by the service "org.freedesktop.DBus". The returned object
131 is an instance of Net::DBus::RemoteObject
132 my $name = $bus->get_unique_name;
134 Retrieves the unique name of this client's connection to the bus.
135 my $name = $bus->get_service_owner($service);
137 Retrieves the unique name of the client on the bus owning the
138 service named by the $service parameter.
139
141 These methods are not usually used, since most services provide
142 introspection data to inform clients of their data typing requirements.
143 If introspection data is incomplete, however, it may be neccessary for
144 a client to mark values with specific data types. In such a case, the
145 following methods can be used. They are not, however, exported by
146 default so must be requested at import time by specifying 'use
147 Net::DBus qw(:typing)'
148 $typed_value = dbus_int16($value);
150 Mark a value as being a signed, 16-bit integer.
151 $typed_value = dbus_uint16($value);
153 Mark a value as being an unsigned, 16-bit integer.
154 $typed_value = dbus_int32($value);
156 Mark a value as being a signed, 32-bit integer.
157 $typed_value = dbus_uint32($value);
159 Mark a value as being an unsigned, 32-bit integer.
160 $typed_value = dbus_int64($value);
162 Mark a value as being an unsigned, 64-bit integer.
163 $typed_value = dbus_uint64($value);
165 Mark a value as being an unsigned, 64-bit integer.
166 $typed_value = dbus_double($value);
168 Mark a value as being a double precision IEEE floating point.
169 $typed_value = dbus_byte($value);
171 Mark a value as being an unsigned, byte.
172 $typed_value = dbus_string($value);
174 Mark a value as being a UTF-8 string. This is not usually required
175 since 'string' is the default data type for any Perl scalar value.
176 $typed_value = dbus_signature($value);
178 Mark a value as being a UTF-8 string, whose contents is a valid
179 type signature
180 $typed_value = dbus_object_path($value);
182 Mark a value as being a UTF-8 string, whose contents is a valid
183 object path.
184 $typed_value = dbus_boolean($value);
186 Mark a value as being an boolean
187 $typed_value = dbus_array($value);
189 Mark a value as being an array
190 $typed_value = dbus_struct($value);
192 Mark a value as being a structure
193 $typed_value = dbus_dict($value);
195 Mark a value as being a dictionary
196 $typed_value = dbus_variant($value);
198 Mark a value as being a variant
199
201 Net::DBus, Net::DBus::RemoteService, Net::DBus::Service,
202 Net::DBus::RemoteObject, Net::DBus::Object, Net::DBus::Exporter,
203 Net::DBus::Dumper, Net::DBus::Reactor, "dbus-monitor(1)",
204 "dbus-daemon-1(1)", "dbus-send(1)", <http://dbus.freedesktop.org>,
205
207 Daniel Berrange <dan@berrange.com>
208
210 Copyright 2004-2005 by Daniel Berrange
211perl v5.12.0 2008-02-21 Net::DBus(3)