.\" 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::Test::MockIterator 3pm"
.TH Net::DBus::Test::MockIterator 3pm "2011-06-30" "perl v5.20.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 mesage
.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 \*(L"mock\*(R" 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\->\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 $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 "BUGS"
.IX Header "BUGS"
It doesn't completely replicate the \s-1API\s0 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>