.\" -*- 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::Binding::Introspector 3"
.TH Net::DBus::Binding::Introspector 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::Binding::Introspector \- Handler for object introspection data
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # Create an object populating with info from an
\&  # XML doc containing introspection data.
\&
\&  my $ins = Net::DBus::Binding::Introspector\->new(xml => $data);
\&
\&  # Create an object, defining introspection data
\&  # programmatically
\&  my $ins = Net::DBus::Binding::Introspector\->new(object_path => $object\->get_object_path);
\&  $ins\->add_method("DoSomething", ["string"], [], "org.example.MyObject");
\&  $ins\->add_method("TestSomething", ["int32"], [], "org.example.MyObject");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This class is responsible for managing introspection data, and
answering questions about it. This is not intended for use by
application developers, whom should instead consult the higher
level API in Net::DBus::Exporter.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $ins = Net::DBus::Binding::Introspector\->new(object_path => $object_path, xml => $xml);" 4
.el .IP "my \f(CW$ins\fR = Net::DBus::Binding::Introspector\->new(object_path => \f(CW$object_path\fR, xml => \f(CW$xml\fR);" 4
.IX Item "my $ins = Net::DBus::Binding::Introspector->new(object_path => $object_path, xml => $xml);"
Creates a new introspection data manager for the object registered
at the path specified for the \f(CW\*(C`object_path\*(C'\fR parameter. The optional
\&\f(CW\*(C`xml\*(C'\fR parameter can be used to pre-load the manager with introspection
metadata from an XML document.
.ie n .IP $ins\->add_interface($name) 4
.el .IP \f(CW$ins\fR\->add_interface($name) 4
.IX Item "$ins->add_interface($name)"
Register the object as providing an interface with the name \f(CW$name\fR
.ie n .IP "my $bool = $ins\->has_interface($name)" 4
.el .IP "my \f(CW$bool\fR = \f(CW$ins\fR\->has_interface($name)" 4
.IX Item "my $bool = $ins->has_interface($name)"
Return a true value if the object is registered as providing
an interface with the name \f(CW$name\fR; returns false otherwise.
.ie n .IP "my @interfaces = $ins\->has_method($name, [$interface])" 4
.el .IP "my \f(CW@interfaces\fR = \f(CW$ins\fR\->has_method($name, [$interface])" 4
.IX Item "my @interfaces = $ins->has_method($name, [$interface])"
Return a list of all interfaces provided by the object, which
contain a method called \f(CW$name\fR. This may be an empty list.
The optional \f(CW$interface\fR parameter can restrict the check to
just that one interface.
.ie n .IP "my $boolean = $ins\->is_method_allowed($name[, $interface])" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->is_method_allowed($name[, \f(CW$interface\fR])" 4
.IX Item "my $boolean = $ins->is_method_allowed($name[, $interface])"
Checks according to whether the remote caller is allowed to invoke
the method \f(CW$name\fR on the object associated with this introspector.
If this object has 'strict exports' enabled, then only explicitly
exported methods will be allowed. The optional \f(CW$interface\fR parameter
can restrict the check to just that one interface. Returns a non-zero
value if the method should be allowed.
.ie n .IP "my @interfaces = $ins\->has_signal($name)" 4
.el .IP "my \f(CW@interfaces\fR = \f(CW$ins\fR\->has_signal($name)" 4
.IX Item "my @interfaces = $ins->has_signal($name)"
Return a list of all interfaces provided by the object, which
contain a signal called \f(CW$name\fR. This may be an empty list.
.ie n .IP "my @interfaces = $ins\->has_property($name)" 4
.el .IP "my \f(CW@interfaces\fR = \f(CW$ins\fR\->has_property($name)" 4
.IX Item "my @interfaces = $ins->has_property($name)"
Return a list of all interfaces provided by the object, which
contain a property called \f(CW$name\fR. This may be an empty list.
The optional \f(CW$interface\fR parameter can restrict the check to
just that one interface.
.ie n .IP "$ins\->add_method($name, $params, $returns, $interface, $attributes, $paramnames, $returnnames);" 4
.el .IP "\f(CW$ins\fR\->add_method($name, \f(CW$params\fR, \f(CW$returns\fR, \f(CW$interface\fR, \f(CW$attributes\fR, \f(CW$paramnames\fR, \f(CW$returnnames\fR);" 4
.IX Item "$ins->add_method($name, $params, $returns, $interface, $attributes, $paramnames, $returnnames);"
Register the object as providing a method called \f(CW$name\fR accepting parameters
whose types are declared by \f(CW$params\fR and returning values whose type
are declared by \f(CW$returns\fR. The method will be scoped to the interface
named by \f(CW$interface\fR. The \f(CW$attributes\fR parameter is a hash reference
for annotating the method. The \f(CW$paramnames\fR and \f(CW$returnames\fR parameters
are a list of argument and return value names.
.ie n .IP "$ins\->add_signal($name, $params, $interface, $attributes);" 4
.el .IP "\f(CW$ins\fR\->add_signal($name, \f(CW$params\fR, \f(CW$interface\fR, \f(CW$attributes\fR);" 4
.IX Item "$ins->add_signal($name, $params, $interface, $attributes);"
Register the object as providing a signal called \f(CW$name\fR with parameters
whose types are declared by \f(CW$params\fR. The signal will be scoped to the interface
named by \f(CW$interface\fR. The \f(CW$attributes\fR parameter is a hash reference
for annotating the signal.
.ie n .IP "$ins\->add_property($name, $type, $access, $interface, $attributes);" 4
.el .IP "\f(CW$ins\fR\->add_property($name, \f(CW$type\fR, \f(CW$access\fR, \f(CW$interface\fR, \f(CW$attributes\fR);" 4
.IX Item "$ins->add_property($name, $type, $access, $interface, $attributes);"
Register the object as providing a property called \f(CW$name\fR with a type
of \f(CW$type\fR. The \f(CW$access\fR parameter can be one of \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`write\*(C'\fR,
or \f(CW\*(C`readwrite\*(C'\fR. The property will be scoped to the interface
named by \f(CW$interface\fR. The \f(CW$attributes\fR parameter is a hash reference
for annotating the signal.
.ie n .IP "my $boolean = $ins\->is_method_deprecated($name, $interface)" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->is_method_deprecated($name, \f(CW$interface\fR)" 4
.IX Item "my $boolean = $ins->is_method_deprecated($name, $interface)"
Returns a true value if the method called \f(CW$name\fR in the interface
\&\f(CW$interface\fR is marked as deprecated
.ie n .IP "my $boolean = $ins\->is_signal_deprecated($name, $interface)" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->is_signal_deprecated($name, \f(CW$interface\fR)" 4
.IX Item "my $boolean = $ins->is_signal_deprecated($name, $interface)"
Returns a true value if the signal called \f(CW$name\fR in the interface
\&\f(CW$interface\fR is marked as deprecated
.ie n .IP "my $boolean = $ins\->is_property_deprecated($name, $interface)" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->is_property_deprecated($name, \f(CW$interface\fR)" 4
.IX Item "my $boolean = $ins->is_property_deprecated($name, $interface)"
Returns a true value if the property called \f(CW$name\fR in the interface
\&\f(CW$interface\fR is marked as deprecated
.ie n .IP "my $boolean = $ins\->does_method_reply($name, $interface)" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->does_method_reply($name, \f(CW$interface\fR)" 4
.IX Item "my $boolean = $ins->does_method_reply($name, $interface)"
Returns a true value if the method called \f(CW$name\fR in the interface
\&\f(CW$interface\fR will generate a reply. Returns a false value otherwise.
.ie n .IP "my $boolean = $ins\->method_has_strict_exceptions($name, $interface)" 4
.el .IP "my \f(CW$boolean\fR = \f(CW$ins\fR\->method_has_strict_exceptions($name, \f(CW$interface\fR)" 4
.IX Item "my $boolean = $ins->method_has_strict_exceptions($name, $interface)"
Returns true if the method called \f(CW$name\fR in the interface \f(CW$interface\fR has
the strict_exceptions attribute; that is any exceptions which aren't
Net::DBus::Error objects should not be caught and allowed to travel up the
stack.
.ie n .IP "my @names = $ins\->list_interfaces" 4
.el .IP "my \f(CW@names\fR = \f(CW$ins\fR\->list_interfaces" 4
.IX Item "my @names = $ins->list_interfaces"
Returns a list of all interfaces registered as being provided
by the object.
.ie n .IP "my @names = $ins\->list_methods($interface)" 4
.el .IP "my \f(CW@names\fR = \f(CW$ins\fR\->list_methods($interface)" 4
.IX Item "my @names = $ins->list_methods($interface)"
Returns a list of all methods registered as being provided
by the object, within the interface \f(CW$interface\fR.
.ie n .IP "my @names = $ins\->list_signals($interface)" 4
.el .IP "my \f(CW@names\fR = \f(CW$ins\fR\->list_signals($interface)" 4
.IX Item "my @names = $ins->list_signals($interface)"
Returns a list of all signals registered as being provided
by the object, within the interface \f(CW$interface\fR.
.ie n .IP "my @names = $ins\->list_properties($interface)" 4
.el .IP "my \f(CW@names\fR = \f(CW$ins\fR\->list_properties($interface)" 4
.IX Item "my @names = $ins->list_properties($interface)"
Returns a list of all properties registered as being provided
by the object, within the interface \f(CW$interface\fR.
.ie n .IP "my @paths = $self\->list_children;" 4
.el .IP "my \f(CW@paths\fR = \f(CW$self\fR\->list_children;" 4
.IX Item "my @paths = $self->list_children;"
Returns a list of object paths representing all the children
of this node.
.ie n .IP "my $path = $ins\->get_object_path" 4
.el .IP "my \f(CW$path\fR = \f(CW$ins\fR\->get_object_path" 4
.IX Item "my $path = $ins->get_object_path"
Returns the path of the object associated with this introspection
data
.ie n .IP "my @types = $ins\->get_method_params($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_method_params($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_method_params($interface, $name)"
Returns a list of declared data types for parameters of the
method called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my @types = $ins\->get_method_param_names($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_method_param_names($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_method_param_names($interface, $name)"
Returns a list of declared names for parameters of the
method called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my @types = $ins\->get_method_returns($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_method_returns($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_method_returns($interface, $name)"
Returns a list of declared data types for return values of the
method called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my @types = $ins\->get_method_return_names($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_method_return_names($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_method_return_names($interface, $name)"
Returns a list of declared names for return values of the
method called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my @types = $ins\->get_signal_params($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_signal_params($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_signal_params($interface, $name)"
Returns a list of declared data types for values associated with the
signal called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my @types = $ins\->get_signal_param_names($interface, $name)" 4
.el .IP "my \f(CW@types\fR = \f(CW$ins\fR\->get_signal_param_names($interface, \f(CW$name\fR)" 4
.IX Item "my @types = $ins->get_signal_param_names($interface, $name)"
Returns a list of declared names for values associated with the
signal called \f(CW$name\fR within the interface \f(CW$interface\fR.
.ie n .IP "my $type = $ins\->get_property_type($interface, $name)" 4
.el .IP "my \f(CW$type\fR = \f(CW$ins\fR\->get_property_type($interface, \f(CW$name\fR)" 4
.IX Item "my $type = $ins->get_property_type($interface, $name)"
Returns the declared data type for property called \f(CW$name\fR within
the interface \f(CW$interface\fR.
.ie n .IP "my $bool = $ins\->is_property_readable($interface, $name);" 4
.el .IP "my \f(CW$bool\fR = \f(CW$ins\fR\->is_property_readable($interface, \f(CW$name\fR);" 4
.IX Item "my $bool = $ins->is_property_readable($interface, $name);"
Returns a true value if the property called \f(CW$name\fR within the
interface \f(CW$interface\fR can have its value read.
.ie n .IP "my $bool = $ins\->is_property_writable($interface, $name);" 4
.el .IP "my \f(CW$bool\fR = \f(CW$ins\fR\->is_property_writable($interface, \f(CW$name\fR);" 4
.IX Item "my $bool = $ins->is_property_writable($interface, $name);"
Returns a true value if the property called \f(CW$name\fR within the
interface \f(CW$interface\fR can have its value written to.
.ie n .IP "my $xml = $ins\->format([$obj])" 4
.el .IP "my \f(CW$xml\fR = \f(CW$ins\fR\->format([$obj])" 4
.IX Item "my $xml = $ins->format([$obj])"
Return a string containing an XML document representing the
state of the introspection data. The optional \f(CW$obj\fR parameter
can be an instance of Net::DBus::Object to include object
specific information in the XML (eg child nodes).
.ie n .IP "my $xml_fragment = $ins\->to_xml" 4
.el .IP "my \f(CW$xml_fragment\fR = \f(CW$ins\fR\->to_xml" 4
.IX Item "my $xml_fragment = $ins->to_xml"
Returns a string containing an XML fragment representing the
state of the introspection data. This is basically the same
as the \f(CW\*(C`format\*(C'\fR method, but without the leading doctype
declaration.
.ie n .IP "$type = $ins\->to_xml_type($type)" 4
.el .IP "\f(CW$type\fR = \f(CW$ins\fR\->to_xml_type($type)" 4
.IX Item "$type = $ins->to_xml_type($type)"
Takes a text-based representation of a data type and returns
the compact representation used in XML introspection data.
.ie n .IP "$ins\->encode($message, $type, $name, $direction, @args)" 4
.el .IP "\f(CW$ins\fR\->encode($message, \f(CW$type\fR, \f(CW$name\fR, \f(CW$direction\fR, \f(CW@args\fR)" 4
.IX Item "$ins->encode($message, $type, $name, $direction, @args)"
Append a set of values <@args> to a message object \f(CW$message\fR.
The \f(CW$type\fR parameter is either \f(CW\*(C`signal\*(C'\fR or \f(CW\*(C`method\*(C'\fR and
\&\f(CW$direction\fR is either \f(CW\*(C`params\*(C'\fR or \f(CW\*(C`returns\*(C'\fR. The introspection
data will be queried to obtain the declared data types & the
argument marshalling accordingly.
.ie n .IP "my @args = $ins\->decode($message, $type, $name, $direction)" 4
.el .IP "my \f(CW@args\fR = \f(CW$ins\fR\->decode($message, \f(CW$type\fR, \f(CW$name\fR, \f(CW$direction\fR)" 4
.IX Item "my @args = $ins->decode($message, $type, $name, $direction)"
Unmarshalls the contents of a message object \f(CW$message\fR.
The \f(CW$type\fR parameter is either \f(CW\*(C`signal\*(C'\fR or \f(CW\*(C`method\*(C'\fR and
\&\f(CW$direction\fR is either \f(CW\*(C`params\*(C'\fR or \f(CW\*(C`returns\*(C'\fR. The introspection
data will be queried to obtain the declared data types & the
arguments unmarshalled accordingly.
.SH AUTHOR
.IX Header "AUTHOR"
Daniel P. Berrange
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2004\-2011 Daniel P. Berrange
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus::Exporter, Net::DBus::Binding::Message