.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
..
.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
.\" ========================================================================
.\"
.IX Title "Net::DBus::RemoteService 3"
.TH Net::DBus::RemoteService 3 2024-09-01 "perl v5.40.0" "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::RemoteService \- Access services provided on the bus
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  my $bus = Net::DBus\->find;
\&  my $service = $bus\->get_service("org.freedesktop.DBus");
\&
\&  my $object = $service\->get_object("/org/freedesktop/DBus");
\&  foreach (@{$object\->ListNames}) {
\&    print "$_\en";
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This object provides a handle to a remote service on the
bus. From this handle it is possible to access objects
associated with the service. If a service is not running,
an attempt will be made to activate it the first time a
method is called against one of its objects.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $service = Net::DBus::RemoteService\->new($bus, $owner, $service_name);" 4
.el .IP "my \f(CW$service\fR = Net::DBus::RemoteService\->new($bus, \f(CW$owner\fR, \f(CW$service_name\fR);" 4
.IX Item "my $service = Net::DBus::RemoteService->new($bus, $owner, $service_name);"
Creates a new handle for a remote service. The \f(CW$bus\fR parameter is an
instance of Net::DBus, \f(CW$owner\fR is the name of the client providing the
service, while \f(CW$service_name\fR is the well known name of the  service on
the bus. Service names consist of two or more tokens, separated
by periods, while the tokens comprise the letters a\-z, A\-Z, 0\-9 and _,
for example \f(CW\*(C`org.freedesktop.DBus\*(C'\fR. There is generally no need to call
this constructor, instead the \f(CW\*(C`get_service\*(C'\fR method on Net::DBus should
be used. This caches handles to remote services, eliminating repeated
retrieval of introspection data.
.ie n .IP "my $bus = $service\->get_bus;" 4
.el .IP "my \f(CW$bus\fR = \f(CW$service\fR\->get_bus;" 4
.IX Item "my $bus = $service->get_bus;"
Retrieves a handle for the bus to which this service is attached.
The returned object will be an instance of Net::DBus.
.ie n .IP "my $service_name = $service\->get_service_name" 4
.el .IP "my \f(CW$service_name\fR = \f(CW$service\fR\->get_service_name" 4
.IX Item "my $service_name = $service->get_service_name"
Retrieves the name of the remote service as known to the bus.
.ie n .IP "my $owner_name = $service\->get_owner_name;" 4
.el .IP "my \f(CW$owner_name\fR = \f(CW$service\fR\->get_owner_name;" 4
.IX Item "my $owner_name = $service->get_owner_name;"
Retrieves the name of the client owning the service at the
time it was connected to.
.ie n .IP "my $object = $service\->get_object($object_path[, $interface]); =item my $object = $service\->get_object($object_path, \e%params);" 4
.el .IP "my \f(CW$object\fR = \f(CW$service\fR\->get_object($object_path[, \f(CW$interface\fR]); =item my \f(CW$object\fR = \f(CW$service\fR\->get_object($object_path, \e%params);" 4
.IX Item "my $object = $service->get_object($object_path[, $interface]); =item my $object = $service->get_object($object_path, %params);"
Retrieves a handle to the remote object provided by the service  with
the name of \f(CW$object_path\fR. If the optional \f(CW$interface\fR parameter is
provided, the object will immediately be cast to the designated
interface. NB, it is only necessary to cast an object to a specific
interface if there are multiple interfaces on the object providing
methods with the same name, or the remote object does support
introspection. The returned object will be an instance of Net::DBus::RemoteObject.
.Sp
An alternate form of the method is available, passing a hash reference
of extra parameters. Valid keys in the hash are \f(CW\*(C`interface\*(C'\fR specifying
the interface name to cast to, and \f(CW\*(C`timeout\*(C'\fR specifying a timeout in
milliseconds
.ie n .IP "my $timeout = $service\->timeout(60 * 1000);" 4
.el .IP "my \f(CW$timeout\fR = \f(CW$service\fR\->timeout(60 * 1000);" 4
.IX Item "my $timeout = $service->timeout(60 * 1000);"
Sets or retrieves the timeout value which will be used for DBus
requests belongs to this service. The value is in milliseconds.
If the timeout for a service is undefined, then the default
timeout from the bus will apply.
.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::RemoteObject, Net::DBus::Service, Net::DBus