.\" 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::Binding::Iterator 3pm"
.TH Net::DBus::Binding::Iterator 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::Binding::Iterator \- Reading and writing message parameters
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Creating a new message
.PP
.Vb 2
\&  my $msg = new Net::DBus::Binding::Message::Signal;
\&  my $iterator = $msg\->iterator;
\&
\&  $iterator\->append_boolean(1);
\&  $iterator\->append_byte(123);
.Ve
.PP
Reading from a message
.PP
.Vb 2
\&  my $msg = ...get it from somewhere...
\&  my $iter = $msg\->iterator();
\&
\&  my $i = 0;
\&  while ($iter\->has_next()) {
\&    $iter\->next();
\&    $i++;
\&    if ($i == 1) {
\&       my $val = $iter\->get_boolean();
\&    } elsif ($i == 2) {
\&       my $val = $iter\->get_byte();
\&    }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides an iterator for reading or writing message
fields. This module provides a Perl \s-1API\s0 to access the
dbus_message_iter_XXX methods in the C \s-1API.\s0 The array
and dictionary types are not yet supported, and there
are bugs in the Quad support (ie it always returns \-1!).
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$res = $iter\->\fIhas_next()\fR" 4
.el .IP "\f(CW$res\fR = \f(CW$iter\fR\->\fIhas_next()\fR" 4
.IX Item "$res = $iter->has_next()"
Determines if there are any more fields in the message
itertor to be read. Returns a positive value if there
are more fields, zero otherwise.
.ie n .IP "$success = $iter\->\fInext()\fR" 4
.el .IP "\f(CW$success\fR = \f(CW$iter\fR\->\fInext()\fR" 4
.IX Item "$success = $iter->next()"
Skips the iterator onto the next field in the message.
Returns a positive value if the current field pointer
was successfully advanced, zero otherwise.
.ie n .IP "my $val = $iter\->\fIget_boolean()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_boolean()\fR" 4
.IX Item "my $val = $iter->get_boolean()"
.PD 0
.ie n .IP "$iter\->append_boolean($val);" 4
.el .IP "\f(CW$iter\fR\->append_boolean($val);" 4
.IX Item "$iter->append_boolean($val);"
.PD
Read or write a boolean value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_byte()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_byte()\fR" 4
.IX Item "my $val = $iter->get_byte()"
.PD 0
.ie n .IP "$iter\->append_byte($val);" 4
.el .IP "\f(CW$iter\fR\->append_byte($val);" 4
.IX Item "$iter->append_byte($val);"
.PD
Read or write a single byte value from/to the
message iterator.
.ie n .IP "my $val = $iter\->\fIget_string()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_string()\fR" 4
.IX Item "my $val = $iter->get_string()"
.PD 0
.ie n .IP "$iter\->append_string($val);" 4
.el .IP "\f(CW$iter\fR\->append_string($val);" 4
.IX Item "$iter->append_string($val);"
.PD
Read or write a \s-1UTF\-8\s0 string value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_object_path()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_object_path()\fR" 4
.IX Item "my $val = $iter->get_object_path()"
.PD 0
.ie n .IP "$iter\->append_object_path($val);" 4
.el .IP "\f(CW$iter\fR\->append_object_path($val);" 4
.IX Item "$iter->append_object_path($val);"
.PD
Read or write a \s-1UTF\-8\s0 string value, whose contents is
a valid object path, from/to the message iterator
.ie n .IP "my $val = $iter\->\fIget_signature()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_signature()\fR" 4
.IX Item "my $val = $iter->get_signature()"
.PD 0
.ie n .IP "$iter\->append_signature($val);" 4
.el .IP "\f(CW$iter\fR\->append_signature($val);" 4
.IX Item "$iter->append_signature($val);"
.PD
Read or write a \s-1UTF\-8\s0 string, whose contents is a
valid type signature, value from/to the message iterator
.ie n .IP "my $val = $iter\->\fIget_int16()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_int16()\fR" 4
.IX Item "my $val = $iter->get_int16()"
.PD 0
.ie n .IP "$iter\->append_int16($val);" 4
.el .IP "\f(CW$iter\fR\->append_int16($val);" 4
.IX Item "$iter->append_int16($val);"
.PD
Read or write a signed 16 bit value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_uint16()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_uint16()\fR" 4
.IX Item "my $val = $iter->get_uint16()"
.PD 0
.ie n .IP "$iter\->append_uint16($val);" 4
.el .IP "\f(CW$iter\fR\->append_uint16($val);" 4
.IX Item "$iter->append_uint16($val);"
.PD
Read or write an unsigned 16 bit value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_int32()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_int32()\fR" 4
.IX Item "my $val = $iter->get_int32()"
.PD 0
.ie n .IP "$iter\->append_int32($val);" 4
.el .IP "\f(CW$iter\fR\->append_int32($val);" 4
.IX Item "$iter->append_int32($val);"
.PD
Read or write a signed 32 bit value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_uint32()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_uint32()\fR" 4
.IX Item "my $val = $iter->get_uint32()"
.PD 0
.ie n .IP "$iter\->append_uint32($val);" 4
.el .IP "\f(CW$iter\fR\->append_uint32($val);" 4
.IX Item "$iter->append_uint32($val);"
.PD
Read or write an unsigned 32 bit value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fIget_int64()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_int64()\fR" 4
.IX Item "my $val = $iter->get_int64()"
.PD 0
.ie n .IP "$iter\->append_int64($val);" 4
.el .IP "\f(CW$iter\fR\->append_int64($val);" 4
.IX Item "$iter->append_int64($val);"
.PD
Read or write a signed 64 bit value from/to the
message iterator. An error will be raised if this
build of Perl does not support 64 bit integers
.ie n .IP "my $val = $iter\->\fIget_uint64()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_uint64()\fR" 4
.IX Item "my $val = $iter->get_uint64()"
.PD 0
.ie n .IP "$iter\->append_uint64($val);" 4
.el .IP "\f(CW$iter\fR\->append_uint64($val);" 4
.IX Item "$iter->append_uint64($val);"
.PD
Read or write an unsigned 64 bit value from/to the
message iterator. An error will be raised if this
build of Perl does not support 64 bit integers
.ie n .IP "my $val = $iter\->\fIget_double()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_double()\fR" 4
.IX Item "my $val = $iter->get_double()"
.PD 0
.ie n .IP "$iter\->append_double($val);" 4
.el .IP "\f(CW$iter\fR\->append_double($val);" 4
.IX Item "$iter->append_double($val);"
.PD
Read or write a double precision floating point value
from/to the message iterator
.ie n .IP "my $val = $iter\->\fIget_unix_fd()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fIget_unix_fd()\fR" 4
.IX Item "my $val = $iter->get_unix_fd()"
.PD 0
.ie n .IP "$iter\->append_unix_fd($val);" 4
.el .IP "\f(CW$iter\fR\->append_unix_fd($val);" 4
.IX Item "$iter->append_unix_fd($val);"
.PD
Read or write a unix_fd value from/to the
message iterator
.ie n .IP "my $value = $iter\->\fIget()\fR" 4
.el .IP "my \f(CW$value\fR = \f(CW$iter\fR\->\fIget()\fR" 4
.IX Item "my $value = $iter->get()"
.PD 0
.ie n .IP "my $value = $iter\->get($type);" 4
.el .IP "my \f(CW$value\fR = \f(CW$iter\fR\->get($type);" 4
.IX Item "my $value = $iter->get($type);"
.PD
Get the current value pointed to by this iterator. If the optional
\&\f(CW$type\fR parameter is supplied, the wire type will be compared with
the desired type & a warning output if their differ. The \f(CW$type\fR
value must be one of the \f(CW\*(C`Net::DBus::Binding::Message::TYPE*\*(C'\fR
constants.
.ie n .IP "my $hashref = $iter\->\fIget_dict()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fIget_dict()\fR" 4
.IX Item "my $hashref = $iter->get_dict()"
If the iterator currently points to a dictionary value, unmarshalls
and returns the value as a hash reference.
.ie n .IP "my $hashref = $iter\->\fIget_array()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fIget_array()\fR" 4
.IX Item "my $hashref = $iter->get_array()"
If the iterator currently points to an array value, unmarshalls
and returns the value as a array reference.
.ie n .IP "my $hashref = $iter\->\fIget_variant()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fIget_variant()\fR" 4
.IX Item "my $hashref = $iter->get_variant()"
If the iterator currently points to a variant value, unmarshalls
and returns the value contained in the variant.
.ie n .IP "my $hashref = $iter\->\fIget_struct()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fIget_struct()\fR" 4
.IX Item "my $hashref = $iter->get_struct()"
If the iterator currently points to an struct value, unmarshalls
and returns the value as a array reference. The values in the array
correspond to members of the struct.
.ie n .IP "$iter\->append($value)" 4
.el .IP "\f(CW$iter\fR\->append($value)" 4
.IX Item "$iter->append($value)"
.PD 0
.ie n .IP "$iter\->append($value, $type)" 4
.el .IP "\f(CW$iter\fR\->append($value, \f(CW$type\fR)" 4
.IX Item "$iter->append($value, $type)"
.PD
Appends a value to the message associated with this iterator. The
value is marshalled into wire format, according to the following
rules.
.Sp
If the \f(CW$value\fR is an instance of Net::DBus::Binding::Value,
the embedded data type is used.
.Sp
If the \f(CW$type\fR parameter is supplied, that is taken to represent
the data type. The type must be one of the \f(CW\*(C`Net::DBus::Binding::Message::TYPE_*\*(C'\fR
constants.
.Sp
Otherwise, the data type is chosen to be a string, dict or array
according to the perl data types \s-1SCALAR, HASH\s0 or \s-1ARRAY.\s0
.ie n .IP "my $type = $iter\->guess_type($value)" 4
.el .IP "my \f(CW$type\fR = \f(CW$iter\fR\->guess_type($value)" 4
.IX Item "my $type = $iter->guess_type($value)"
Make a best guess at the on the wire data type to use for
marshalling \f(CW$value\fR. If the value is a hash reference,
the dictionary type is returned; if the value is an array
reference the array type is returned; otherwise the string
type is returned.
.ie n .IP "my $sig = $iter\->format_signature($type)" 4
.el .IP "my \f(CW$sig\fR = \f(CW$iter\fR\->format_signature($type)" 4
.IX Item "my $sig = $iter->format_signature($type)"
Given a data type representation, construct a corresponding
signature string
.ie n .IP "$iter\->append_array($value, $type)" 4
.el .IP "\f(CW$iter\fR\->append_array($value, \f(CW$type\fR)" 4
.IX Item "$iter->append_array($value, $type)"
Append an array of values to the message. The \f(CW$value\fR parameter
must be an array reference, whose elements all have the same data
type specified by the \f(CW$type\fR parameter.
.ie n .IP "$iter\->append_struct($value, $type)" 4
.el .IP "\f(CW$iter\fR\->append_struct($value, \f(CW$type\fR)" 4
.IX Item "$iter->append_struct($value, $type)"
Append a struct to the message. The \f(CW$value\fR parameter
must be an array reference, whose elements correspond to
members of the structure. The \f(CW$type\fR parameter encodes
the type of each member of the struct.
.ie n .IP "$iter\->append_dict($value, $type)" 4
.el .IP "\f(CW$iter\fR\->append_dict($value, \f(CW$type\fR)" 4
.IX Item "$iter->append_dict($value, $type)"
Append a dictionary to the message. The \f(CW$value\fR parameter
must be an hash reference.The \f(CW$type\fR parameter encodes
the type of the key and value of the hash.
.ie n .IP "$iter\->append_variant($value)" 4
.el .IP "\f(CW$iter\fR\->append_variant($value)" 4
.IX Item "$iter->append_variant($value)"
Append a value to the message, encoded as a variant type. The
\&\f(CW$value\fR can be of any type, however, the variant will be
encoded as either a string, dictionary or array according to
the rules of the \f(CW\*(C`guess_type\*(C'\fR method.
.ie n .IP "my $type = $iter\->get_arg_type" 4
.el .IP "my \f(CW$type\fR = \f(CW$iter\fR\->get_arg_type" 4
.IX Item "my $type = $iter->get_arg_type"
Retrieves the type code of the value pointing to by this iterator.
The returned code will correspond to one of the constants
\&\f(CW\*(C`Net::DBus::Binding::Message::TYPE_*\*(C'\fR
.ie n .IP "my $type = $iter\->get_element_type" 4
.el .IP "my \f(CW$type\fR = \f(CW$iter\fR\->get_element_type" 4
.IX Item "my $type = $iter->get_element_type"
If the iterator points to an array, retrieves the type code of
array elements. The returned code will correspond to one of the
constants \f(CW\*(C`Net::DBus::Binding::Message::TYPE_*\*(C'\fR
.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::Binding::Message