.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::DBus::RemoteObject 3pm"
.TH Net::DBus::RemoteObject 3pm "2016-07-08" "perl v5.24.1" "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::RemoteObject \- Access objects provided on the bus
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $service = $bus\->get_service("org.freedesktop.DBus");
\&  my $object = $service\->get_object("/org/freedesktop/DBus");
\&
\&  print "Names on the bus {\en";
\&  foreach my $name (sort @{$object\->ListNames}) {
\&      print "  ", $name, "\en";
\&  }
\&  print "}\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the \s-1API\s0 for accessing remote objects available
on the bus. It uses the autoloader to fake the presence of methods
based on the \s-1API\s0 of the remote object. There is also support for
setting callbacks against signals, and accessing properties of the
object.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $object = Net::DBus::RemoteObject\->new($service, $object_path[, $interface], \e%params);" 4
.el .IP "my \f(CW$object\fR = Net::DBus::RemoteObject\->new($service, \f(CW$object_path\fR[, \f(CW$interface\fR], \e%params);" 4
.IX Item "my $object = Net::DBus::RemoteObject->new($service, $object_path[, $interface], %params);"
Creates a new handle to a remote object. The \f(CW$service\fR parameter is an instance
of the Net::DBus::RemoteService method, and \f(CW$object_path\fR is the identifier of
an object exported by this service, for example \f(CW\*(C`/org/freedesktop/DBus\*(C'\fR. For remote
objects which implement more than one interface it is possible to specify an optional
name of an interface as the third parameter. This is only really required, however, if
two interfaces in the object provide methods with the same name, since introspection
data can be used to automatically resolve the correct interface to call cases where
method names are unique. Rather than using this constructor directly, it is preferable
to use the \f(CW\*(C`get_object\*(C'\fR method on Net::DBus::RemoteService, since this caches handles
to remote objects, eliminating unnecessary introspection data lookups.
.Sp
The \f(CW%params\fR parameter contains extra configuration parameters for the object. Currently
a single parameter is supported, \f(CW\*(C`timeout\*(C'\fR which takes a value in milliseconds to use as
the timeout for method calls on the object.
.ie n .IP "my $object = $object\->as_interface($interface);" 4
.el .IP "my \f(CW$object\fR = \f(CW$object\fR\->as_interface($interface);" 4
.IX Item "my $object = $object->as_interface($interface);"
Casts the object to a specific interface, returning a new instance of the
Net::DBus::RemoteObject specialized to the desired interface. It is only
necessary to cast objects to a specific interface, if two interfaces
export methods or signals with the same name, or the remote object does not
support introspection.
.ie n .IP "my $service = $object\->get_service" 4
.el .IP "my \f(CW$service\fR = \f(CW$object\fR\->get_service" 4
.IX Item "my $service = $object->get_service"
Retrieves a handle for the remote service on which this object is
attached. The returned object is an instance of Net::DBus::RemoteService
.ie n .IP "my $path = $object\->get_object_path" 4
.el .IP "my \f(CW$path\fR = \f(CW$object\fR\->get_object_path" 4
.IX Item "my $path = $object->get_object_path"
Retrieves the unique path identifier for this object within the
service.
.ie n .IP "my $object = $object\->get_child_object($subpath, [$interface])" 4
.el .IP "my \f(CW$object\fR = \f(CW$object\fR\->get_child_object($subpath, [$interface])" 4
.IX Item "my $object = $object->get_child_object($subpath, [$interface])"
Retrieves a handle to a child of this object, identified
by the relative path \f(CW$subpath\fR. The returned object
is an instance of \f(CW\*(C`Net::DBus::RemoteObject\*(C'\fR. The optional
\&\f(CW$interface\fR parameter can be used to immediately cast
the object to a specific type.
.ie n .IP "my $sigid = $object\->connect_to_signal($name, $coderef);" 4
.el .IP "my \f(CW$sigid\fR = \f(CW$object\fR\->connect_to_signal($name, \f(CW$coderef\fR);" 4
.IX Item "my $sigid = $object->connect_to_signal($name, $coderef);"
Connects a callback to a signal emitted by the object. The \f(CW$name\fR
parameter is the name of the signal within the object, and \f(CW$coderef\fR
is a reference to an anonymous subroutine. When the signal \f(CW$name\fR
is emitted by the remote object, the subroutine \f(CW$coderef\fR will be
invoked, and passed the parameters from the signal. A unique \f(CW$sigid\fR
will be returned, which can be later passed to \f(CW\*(C`disconnect_from_signal\*(C'\fR
to remove the handler
.ie n .IP "$object\->disconnect_from_signal($name, $sigid);" 4
.el .IP "\f(CW$object\fR\->disconnect_from_signal($name, \f(CW$sigid\fR);" 4
.IX Item "$object->disconnect_from_signal($name, $sigid);"
Disconnects from a signal emitted by the object. The \f(CW$name\fR
parameter is the name of the signal within the object. The
\&\f(CW$sigid\fR must be the unique signal handler \s-1ID\s0 returned by
a previous \f(CW\*(C`connect_to_signal\*(C'\fR method call.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Berrange <dan@berrange.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copright (C) 2004\-2011, Daniel Berrange.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus::RemoteService, Net::DBus::Object, Net::DBus::Annotation