.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::DBus 3pm"
.TH Net::DBus 3pm "2015-03-16" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::DBus \- Perl extension for the DBus message system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  ####### Attaching to the bus ###########
\&
\&  use Net::DBus;
\&
\&  # Find the most appropriate bus
\&  my $bus = Net::DBus\->find;
\&
\&  # ... or explicitly go for the session bus
\&  my $bus = Net::DBus\->session;
\&
\&  # .... or explicitly go for the system bus
\&  my $bus = Net::DBus\->system
\&
\&
\&  ######## Accessing remote services #########
\&
\&  # Get a handle to the HAL service
\&  my $hal = $bus\->get_service("org.freedesktop.Hal");
\&
\&  # Get the device manager
\&  my $manager = $hal\->get_object("/org/freedesktop/Hal/Manager",
\&                                 "org.freedesktop.Hal.Manager");
\&
\&  # List devices
\&  foreach my $dev (@{$manager\->GetAllDevices}) {
\&      print $dev, "\en";
\&  }
\&
\&
\&  ######### Providing services ##############
\&
\&  # Register a service known as \*(Aqorg.example.Jukebox\*(Aq
\&  my $service = $bus\->export_service("org.example.Jukebox");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::DBus provides a Perl \s-1API\s0 for the DBus message system.
The DBus Perl interface is currently operating against
the 0.32 development version of DBus, but should work with
later versions too, providing the \s-1API\s0 changes have not been
too drastic.
.PP
Users of this package are either typically, service providers
in which case the Net::DBus::Service and Net::DBus::Object
modules are of most relevance, or are client consumers, in which
case Net::DBus::RemoteService and Net::DBus::RemoteObject
are of most relevance.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $bus = Net::DBus\->find(%params);" 4
.el .IP "my \f(CW$bus\fR = Net::DBus\->find(%params);" 4
.IX Item "my $bus = Net::DBus->find(%params);"
Search for the most appropriate bus to connect to and
return a connection to it. The heuristic used for the
search is
.Sp
.Vb 2
\&  \- If DBUS_STARTER_BUS_TYPE is set to \*(Aqsession\*(Aq attach
\&    to the session bus
\&
\&  \- Else If DBUS_STARTER_BUS_TYPE is set to \*(Aqsystem\*(Aq attach
\&    to the system bus
\&
\&  \- Else If DBUS_SESSION_BUS_ADDRESS is set attach to the
\&    session bus
\&
\&  \- Else attach to the system bus
.Ve
.Sp
The optional \f(CW\*(C`params\*(C'\fR hash can contain be used to specify
connection options. The only support option at this time
is \f(CW\*(C`nomainloop\*(C'\fR which prevents the bus from being automatically
attached to the main Net::DBus::Reactor event loop.
.ie n .IP "my $bus = Net::DBus\->system(%params);" 4
.el .IP "my \f(CW$bus\fR = Net::DBus\->system(%params);" 4
.IX Item "my $bus = Net::DBus->system(%params);"
Return a handle for the system message bus. Note that the
system message bus is locked down by default, so unless appropriate
access control rules are added in /etc/dbus/system.d/, an application
may access services, but won't be able to export services.
.Sp
The optional \f(CW\*(C`params\*(C'\fR hash can be used to specify the following options:
.RS 4
.IP "nomainloop" 4
.IX Item "nomainloop"
If true, prevents the bus from being automatically attached to the main
Net::DBus::Reactor event loop.
.IP "private" 4
.IX Item "private"
If true, the socket opened is private; any existing socket will be ignored and
any future attempts to open the same bus will return a different existing socket
or open a fresh one.
.RE
.RS 4
.RE
.ie n .IP "my $bus = Net::DBus\->session(%params);" 4
.el .IP "my \f(CW$bus\fR = Net::DBus\->session(%params);" 4
.IX Item "my $bus = Net::DBus->session(%params);"
Return a handle for the session message bus.
.Sp
The optional \f(CW\*(C`params\*(C'\fR hash can be used to specify the following options:
.RS 4
.IP "nomainloop" 4
.IX Item "nomainloop"
If true, prevents the bus from being automatically attached to the main
Net::DBus::Reactor event loop.
.IP "private" 4
.IX Item "private"
If true, the socket opened is private; any existing socket will be ignored and
any future attempts to open the same bus will return a different existing socket
or open a fresh one.
.RE
.RS 4
.RE
.ie n .IP "my $bus = Net::DBus\->test(%params);" 4
.el .IP "my \f(CW$bus\fR = Net::DBus\->test(%params);" 4
.IX Item "my $bus = Net::DBus->test(%params);"
Returns a handle for a virtual bus for use in unit tests. This bus does
not make any network connections, but rather has an in-memory message
pipeline. Consult Net::DBus::Test::MockConnection for further details
of how to use this special bus.
.ie n .IP "my $bus = Net::DBus\->new($address, %params);" 4
.el .IP "my \f(CW$bus\fR = Net::DBus\->new($address, \f(CW%params\fR);" 4
.IX Item "my $bus = Net::DBus->new($address, %params);"
Return a connection to a specific message bus.  The \f(CW$address\fR
parameter must contain the address of the message bus to connect
to. An example address for a session bus might look like
\&\f(CW\*(C`unix:abstract=/tmp/dbus\-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500\*(C'\fR,
while one for a system bus would look like \f(CW\*(C`unix:/var/run/dbus/system_bus_socket\*(C'\fR.
The optional \f(CW\*(C`params\*(C'\fR hash can contain be used to specify
connection options. The only support option at this time
is \f(CW\*(C`nomainloop\*(C'\fR which prevents the bus from being automatically
attached to the main Net::DBus::Reactor event loop.
.ie n .IP "my $connection = $bus\->get_connection;" 4
.el .IP "my \f(CW$connection\fR = \f(CW$bus\fR\->get_connection;" 4
.IX Item "my $connection = $bus->get_connection;"
Return a handle to the underlying, low level connection object
associated with this bus. The returned object will be an instance
of the Net::DBus::Binding::Bus class. This method is not intended
for use by (most!) application developers, so if you don't understand
what this is for, then you don't need to be calling it!
.ie n .IP "my $service = $bus\->get_service($name);" 4
.el .IP "my \f(CW$service\fR = \f(CW$bus\fR\->get_service($name);" 4
.IX Item "my $service = $bus->get_service($name);"
Retrieves a handle for the remote service identified by the
service name \f(CW$name\fR. The returned object will be an instance
of the Net::DBus::RemoteService class.
.ie n .IP "my $service = $bus\->export_service($name);" 4
.el .IP "my \f(CW$service\fR = \f(CW$bus\fR\->export_service($name);" 4
.IX Item "my $service = $bus->export_service($name);"
Registers a service with the bus, returning a handle to
the service. The returned object is an instance of the
Net::DBus::Service class.
.ie n .IP "my $object = $bus\->get_bus_object;" 4
.el .IP "my \f(CW$object\fR = \f(CW$bus\fR\->get_bus_object;" 4
.IX Item "my $object = $bus->get_bus_object;"
Retrieves a handle to the bus object, \f(CW\*(C`/org/freedesktop/DBus\*(C'\fR,
provided by the service \f(CW\*(C`org.freedesktop.DBus\*(C'\fR. The returned
object is an instance of Net::DBus::RemoteObject
.ie n .IP "my $name = $bus\->get_unique_name;" 4
.el .IP "my \f(CW$name\fR = \f(CW$bus\fR\->get_unique_name;" 4
.IX Item "my $name = $bus->get_unique_name;"
Retrieves the unique name of this client's connection to
the bus.
.ie n .IP "my $name = $bus\->get_service_owner($service);" 4
.el .IP "my \f(CW$name\fR = \f(CW$bus\fR\->get_service_owner($service);" 4
.IX Item "my $name = $bus->get_service_owner($service);"
Retrieves the unique name of the client on the bus owning
the service named by the \f(CW$service\fR parameter.
.ie n .IP "my $timeout = $bus\->timeout(60 * 1000);" 4
.el .IP "my \f(CW$timeout\fR = \f(CW$bus\fR\->timeout(60 * 1000);" 4
.IX Item "my $timeout = $bus->timeout(60 * 1000);"
Sets or retrieves the timeout value which will be used for DBus
requests belongs to this bus connection. The timeout should be
specified in milliseconds, with the default value being 60 seconds.
.SH "DATA TYPING METHODS"
.IX Header "DATA TYPING METHODS"
These methods are not usually used, since most services provide introspection
data to inform clients of their data typing requirements. If introspection data
is incomplete, however, it may be necessary for a client to mark values with
specific data types. In such a case, the following methods can be used. They
are not, however, exported by default so must be requested at import time by
specifying 'use Net::DBus qw(:typing)'
.ie n .IP "$typed_value = dbus_int16($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_int16($value);" 4
.IX Item "$typed_value = dbus_int16($value);"
Mark a value as being a signed, 16\-bit integer.
.ie n .IP "$typed_value = dbus_uint16($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_uint16($value);" 4
.IX Item "$typed_value = dbus_uint16($value);"
Mark a value as being an unsigned, 16\-bit integer.
.ie n .IP "$typed_value = dbus_int32($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_int32($value);" 4
.IX Item "$typed_value = dbus_int32($value);"
Mark a value as being a signed, 32\-bit integer.
.ie n .IP "$typed_value = dbus_uint32($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_uint32($value);" 4
.IX Item "$typed_value = dbus_uint32($value);"
Mark a value as being an unsigned, 32\-bit integer.
.ie n .IP "$typed_value = dbus_int64($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_int64($value);" 4
.IX Item "$typed_value = dbus_int64($value);"
Mark a value as being an unsigned, 64\-bit integer.
.ie n .IP "$typed_value = dbus_uint64($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_uint64($value);" 4
.IX Item "$typed_value = dbus_uint64($value);"
Mark a value as being an unsigned, 64\-bit integer.
.ie n .IP "$typed_value = dbus_double($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_double($value);" 4
.IX Item "$typed_value = dbus_double($value);"
Mark a value as being a double precision \s-1IEEE\s0 floating point.
.ie n .IP "$typed_value = dbus_byte($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_byte($value);" 4
.IX Item "$typed_value = dbus_byte($value);"
Mark a value as being an unsigned, byte.
.ie n .IP "$typed_value = dbus_string($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_string($value);" 4
.IX Item "$typed_value = dbus_string($value);"
Mark a value as being a \s-1UTF\-8\s0 string. This is not usually required
since 'string' is the default data type for any Perl scalar value.
.ie n .IP "$typed_value = dbus_signature($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_signature($value);" 4
.IX Item "$typed_value = dbus_signature($value);"
Mark a value as being a \s-1UTF\-8\s0 string, whose contents is a valid
type signature
.ie n .IP "$typed_value = dbus_object_path($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_object_path($value);" 4
.IX Item "$typed_value = dbus_object_path($value);"
Mark a value as being a \s-1UTF\-8\s0 string, whose contents is a valid
object path.
.ie n .IP "$typed_value = dbus_boolean($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_boolean($value);" 4
.IX Item "$typed_value = dbus_boolean($value);"
Mark a value as being an boolean
.ie n .IP "$typed_value = dbus_array($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_array($value);" 4
.IX Item "$typed_value = dbus_array($value);"
Mark a value as being an array
.ie n .IP "$typed_value = dbus_struct($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_struct($value);" 4
.IX Item "$typed_value = dbus_struct($value);"
Mark a value as being a structure
.ie n .IP "$typed_value = dbus_dict($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_dict($value);" 4
.IX Item "$typed_value = dbus_dict($value);"
Mark a value as being a dictionary
.ie n .IP "$typed_value = dbus_variant($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_variant($value);" 4
.IX Item "$typed_value = dbus_variant($value);"
Mark a value as being a variant
.ie n .IP "$typed_value = dbus_unix_fd($value);" 4
.el .IP "\f(CW$typed_value\fR = dbus_unix_fd($value);" 4
.IX Item "$typed_value = dbus_unix_fd($value);"
Mark a value as being a unix file descriptor
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus, Net::DBus::RemoteService, Net::DBus::Service,
Net::DBus::RemoteObject, Net::DBus::Object,
Net::DBus::Exporter, Net::DBus::Dumper, Net::DBus::Reactor,
\&\f(CW\*(C`dbus\-monitor(1)\*(C'\fR, \f(CW\*(C`dbus\-daemon\-1(1)\*(C'\fR, \f(CW\*(C`dbus\-send(1)\*(C'\fR, <http://dbus.freedesktop.org>,
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Berrange <dan@berrange.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2011 by Daniel Berrange