.\" 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::BaseObject 3pm"
.TH Net::DBus::BaseObject 3pm "2015-06-14" "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::BaseObject \- base class for exporting objects to the bus
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # We\*(Aqre going to be a DBus object
\&  use base qw(Net::DBus::BaseObject);
\&
\&  # Export a \*(AqGreeting\*(Aq signal taking a stringl string parameter
\&  dbus_signal("Greeting", ["string"]);
\&
\&  # Export \*(AqHello\*(Aq as a method accepting a single string
\&  # parameter, and returning a single string value
\&  dbus_method("Hello", ["string"], ["string"]);
\&
\&  sub new {
\&      my $class = shift;
\&      my $service = shift;
\&      my $self = $class\->SUPER::new($service, "/org/demo/HelloWorld");
\&
\&      bless $self, $class;
\&
\&      return $self;
\&  }
\&
\&  sub _dispatch_object {
\&      my $self = shift;
\&      my $connection = shift;
\&      my $message = shift;
\&
\&      if (....$message refers to a object\*(Aqs method ... ) {
\&         ...dispatch this object\*(Aqs interfaces/methods...
\&         return $reply;
\&      }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This the base of all objects which are exported to the
message bus. It provides the core support for type introspection
required for objects exported to the message. When sub-classing
this object, the \f(CW\*(C`_dispatch\*(C'\fR object should be implemented to
handle processing of incoming messages. The Net::DBus::Exporter
module is used to declare which methods (and signals) are being
exported to the message bus.
.PP
All packages inheriting from this, will automatically have the
interface \f(CW\*(C`org.freedesktop.DBus.Introspectable\*(C'\fR registered
with Net::DBus::Exporter, and the \f(CW\*(C`Introspect\*(C'\fR method within
this exported.
.PP
Application developers will rarely want to use this class directly,
instead either Net::DBus::Object or \f(CW\*(C`Net::DBus::ProxyObject\*(C'\fR
are the common choices. This class will only be used if wanting to
write a new approach to dispatching incoming method calls.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "my $object = Net::DBus::BaseObject\->new($service, $path)" 4
.el .IP "my \f(CW$object\fR = Net::DBus::BaseObject\->new($service, \f(CW$path\fR)" 4
.IX Item "my $object = Net::DBus::BaseObject->new($service, $path)"
This creates a new DBus object with an path of \f(CW$path\fR
registered within the service \f(CW$service\fR. The \f(CW$path\fR
parameter should be a string complying with the usual
DBus requirements for object paths, while the \f(CW$service\fR
parameter should be an instance of Net::DBus::Service.
The latter is typically obtained by calling the \f(CW\*(C`export_service\*(C'\fR
method on the Net::DBus object.
.ie n .IP "my $object = Net::DBus::BaseObject\->new($parentobj, $subpath)" 4
.el .IP "my \f(CW$object\fR = Net::DBus::BaseObject\->new($parentobj, \f(CW$subpath\fR)" 4
.IX Item "my $object = Net::DBus::BaseObject->new($parentobj, $subpath)"
This creates a new DBus child object with an path of \f(CW$subpath\fR
relative to its parent \f(CW$parentobj\fR. The \f(CW$subpath\fR
parameter should be a string complying with the usual
DBus requirements for object paths, while the \f(CW$parentobj\fR
parameter should be an instance of Net::DBus::BaseObject.
.ie n .IP "$object\->\fIdisconnect()\fR;" 4
.el .IP "\f(CW$object\fR\->\fIdisconnect()\fR;" 4
.IX Item "$object->disconnect();"
This method disconnects the object from the bus, such that it
will no longer receive messages sent by other clients. Any
child objects will be recursively disconnected too. After an
object has been disconnected, it is possible for Perl to
garbage collect the object instance. It will also make it
possible to connect a newly created object to the same path.
.ie n .IP "my $bool = $object\->is_connected" 4
.el .IP "my \f(CW$bool\fR = \f(CW$object\fR\->is_connected" 4
.IX Item "my $bool = $object->is_connected"
Returns a true value if the object is connected to the bus,
and thus capable of being accessed by remote clients. Returns
false if the object is disconnected & thus ready for garbage
collection. All objects start off in the connected state, and
will only transition if the \f(CW\*(C`disconnect\*(C'\fR method is called.
.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 the Net::DBus::Service object within which this
object is exported.
.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 path under which this object is exported
.ie n .IP "$object\->emit_signal_in($name, $interface, $client, @args);" 4
.el .IP "\f(CW$object\fR\->emit_signal_in($name, \f(CW$interface\fR, \f(CW$client\fR, \f(CW@args\fR);" 4
.IX Item "$object->emit_signal_in($name, $interface, $client, @args);"
Emits a signal from the object, with a name of \f(CW$name\fR. If the
\&\f(CW$interface\fR parameter is defined, the signal will be scoped
within that interface. If the \f(CW$client\fR parameter is defined,
the signal will be unicast to that client on the bus. The
signal and the data types of the arguments \f(CW@args\fR must have
been registered with Net::DBus::Exporter by calling the
\&\f(CW\*(C`dbus_signal\*(C'\fR method.
.ie n .IP "$self\->emit_signal_to($name, $client, @args);" 4
.el .IP "\f(CW$self\fR\->emit_signal_to($name, \f(CW$client\fR, \f(CW@args\fR);" 4
.IX Item "$self->emit_signal_to($name, $client, @args);"
Emits a signal from the object, with a name of \f(CW$name\fR. The
signal and the data types of the arguments \f(CW@args\fR must have
been registered with Net::DBus::Exporter by calling the
\&\f(CW\*(C`dbus_signal\*(C'\fR method. The signal will be sent only to the
client named by the \f(CW$client\fR parameter.
.ie n .IP "$self\->emit_signal($name, @args);" 4
.el .IP "\f(CW$self\fR\->emit_signal($name, \f(CW@args\fR);" 4
.IX Item "$self->emit_signal($name, @args);"
Emits a signal from the object, with a name of \f(CW$name\fR. The
signal and the data types of the arguments \f(CW@args\fR must have
been registered with Net::DBus::Exporter by calling the
\&\f(CW\*(C`dbus_signal\*(C'\fR method. The signal will be broadcast to all
clients on the bus.
.ie n .IP "$object\->connect_to_signal_in($name, $interface, $coderef);" 4
.el .IP "\f(CW$object\fR\->connect_to_signal_in($name, \f(CW$interface\fR, \f(CW$coderef\fR);" 4
.IX Item "$object->connect_to_signal_in($name, $interface, $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. The \f(CW$interface\fR
parameter is used to specify the explicit interface defining the
signal to connect to.
.ie n .IP "$object\->connect_to_signal($name, $coderef);" 4
.el .IP "\f(CW$object\fR\->connect_to_signal($name, \f(CW$coderef\fR);" 4
.IX Item "$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.
.ie n .IP "$reply = $object\->_dispatch_object($connection, $message);" 4
.el .IP "\f(CW$reply\fR = \f(CW$object\fR\->_dispatch_object($connection, \f(CW$message\fR);" 4
.IX Item "$reply = $object->_dispatch_object($connection, $message);"
The \f(CW\*(C`_dispatch_object\*(C'\fR method is to be used to handle dispatch of
methods implemented by the object. The default implementation is
a no-op and should be overridden by subclasses todo whatever
processing is required. If the \f(CW$message\fR could be handled then
another \f(CW\*(C`Net::DBus::Binding::Message\*(C'\fR instance should be returned
for the reply. If \f(CW\*(C`undef\*(C'\fR is returned, then a generic error will
be returned to the caller.
.ie n .IP "$currvalue = $object\->_dispatch_property($name); =item $object\->_dispatch_property($name, $newvalue);" 4
.el .IP "\f(CW$currvalue\fR = \f(CW$object\fR\->_dispatch_property($name); =item \f(CW$object\fR\->_dispatch_property($name, \f(CW$newvalue\fR);" 4
.IX Item "$currvalue = $object->_dispatch_property($name); =item $object->_dispatch_property($name, $newvalue);"
The \f(CW\*(C`_dispatch_property\*(C'\fR method is to be used to handle dispatch
of property reads and writes. The \f(CW$name\fR parameter is the name
of the property being accessed. If \f(CW$newvalue\fR is supplied then
the property is to be updated, otherwise the current value is to
be returned. The default implementation will simply raise an
error, so must be overridden in subclasses.
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel P. Berrange
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2005\-2011 Daniel P. Berrange
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus, Net::DBus::Service, Net::DBus::Object,
Net::DBus::ProxyObject, Net::DBus::Exporter,
Net::DBus::RemoteObject