.\" -*- 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::Test::MockIterator 3"
.TH Net::DBus::Test::MockIterator 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::Test::MockIterator \- Iterator over a mock message
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Creating a new message
.PP
.Vb 2
\&  my $msg = new Net::DBus::Test::MockMessage
\&  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"
This module provides a "mock" counterpart to the Net::DBus::Binding::Iterator
object which is capable of iterating over mock message objects. Instances of this
module are not created directly, instead they are obtained via the \f(CW\*(C`iterator\*(C'\fR
method on the Net::DBus::Test::MockMessage module.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "$res = $iter\->\fBhas_next()\fR" 4
.el .IP "\f(CW$res\fR = \f(CW$iter\fR\->\fBhas_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\->\fBnext()\fR" 4
.el .IP "\f(CW$success\fR = \f(CW$iter\fR\->\fBnext()\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\->\fBget_boolean()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_byte()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_string()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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 UTF\-8 string value from/to the
message iterator
.ie n .IP "my $val = $iter\->\fBget_object_path()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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 UTF\-8 string value, whose contents is
a valid object path, from/to the message iterator
.ie n .IP "my $val = $iter\->\fBget_signature()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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 UTF\-8 string, whose contents is a
valid type signature, value from/to the message iterator
.ie n .IP "my $val = $iter\->\fBget_int16()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_uint16()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_int32()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_uint32()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_int64()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_uint64()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_double()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_unix_fd()\fR" 4
.el .IP "my \f(CW$val\fR = \f(CW$iter\fR\->\fBget_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\->\fBget()\fR" 4
.el .IP "my \f(CW$value\fR = \f(CW$iter\fR\->\fBget()\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\->\fBget_dict()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_array()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_variant()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fBget_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\->\fBget_struct()\fR" 4
.el .IP "my \f(CW$hashref\fR = \f(CW$iter\fR\->\fBget_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 SCALAR, HASH or ARRAY.
.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 BUGS
.IX Header "BUGS"
It doesn't completely replicate the API of Net::DBus::Binding::Iterator,
merely enough to make the high level bindings work in a test scenario.
.SH AUTHOR
.IX Header "AUTHOR"
Daniel P. Berrange
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2005\-2009 Daniel P. Berrange
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::DBus::Test::MockMessage, Net::DBus::Binding::Iterator,
<http://www.mockobjects.com/Faq.html>