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           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
148       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
153       my $name = $bus->get_unique_name;
154           Retrieves the unique name of this client's connection to the bus.
155
156       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
160       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

DATA TYPING METHODS

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
174       $typed_value = dbus_int16($value);
175           Mark a value as being a signed, 16-bit integer.
176
177       $typed_value = dbus_uint16($value);
178           Mark a value as being an unsigned, 16-bit integer.
179
180       $typed_value = dbus_int32($value);
181           Mark a value as being a signed, 32-bit integer.
182
183       $typed_value = dbus_uint32($value);
184           Mark a value as being an unsigned, 32-bit integer.
185
186       $typed_value = dbus_int64($value);
187           Mark a value as being an unsigned, 64-bit integer.
188
189       $typed_value = dbus_uint64($value);
190           Mark a value as being an unsigned, 64-bit integer.
191
192       $typed_value = dbus_double($value);
193           Mark a value as being a double precision IEEE floating point.
194
195       $typed_value = dbus_byte($value);
196           Mark a value as being an unsigned, byte.
197
198       $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
202       $typed_value = dbus_signature($value);
203           Mark a value as being a UTF-8 string, whose contents is a valid
204           type signature
205
206       $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
210       $typed_value = dbus_boolean($value);
211           Mark a value as being an boolean
212
213       $typed_value = dbus_array($value);
214           Mark a value as being an array
215
216       $typed_value = dbus_struct($value);
217           Mark a value as being a structure
218
219       $typed_value = dbus_dict($value);
220           Mark a value as being a dictionary
221
222       $typed_value = dbus_variant($value);
223           Mark a value as being a variant
224
225       $typed_value = dbus_unix_fd($value);
226           Mark a value as being a unix file descriptor
227

SEE ALSO

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

AUTHOR

235       Daniel Berrange <dan@berrange.com>
236
238       Copyright 2004-2011 by Daniel Berrange
239
240
241
242perl v5.36.0                      2023-01-20                      Net::DBus(3)
Impressum