NAME

       Net::DBus::Binding::Iterator - Reading and writing message parameters

SYNOPSIS

       Creating a new message

         my $msg = new Net::DBus::Binding::Message::Signal;
         my $iterator = $msg->iterator;

         $iterator->append_boolean(1);
         $iterator->append_byte(123);

       Reading from a message

         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();
           }
         }

DESCRIPTION

       Provides an iterator for reading or writing message fields. This module provides a Perl
       API to access the dbus_message_iter_XXX methods in the C API. The array and dictionary
       types are not yet supported, and there are bugs in the Quad support (ie it always returns
       -1!).

METHODS

       $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.

       $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.

       my $val = $iter->get_boolean()
       $iter->append_boolean($val);
           Read or write a boolean value from/to the message iterator

       my $val = $iter->get_byte()
       $iter->append_byte($val);
           Read or write a single byte value from/to the message iterator.

       my $val = $iter->get_string()
       $iter->append_string($val);
           Read or write a UTF-8 string value from/to the message iterator

       my $val = $iter->get_object_path()
       $iter->append_object_path($val);
           Read or write a UTF-8 string value, whose contents is a valid object path, from/to the
           message iterator

       my $val = $iter->get_signature()
       $iter->append_signature($val);
           Read or write a UTF-8 string, whose contents is a valid type signature, value from/to
           the message iterator

       my $val = $iter->get_int16()
       $iter->append_int16($val);
           Read or write a signed 16 bit value from/to the message iterator

       my $val = $iter->get_uint16()
       $iter->append_uint16($val);
           Read or write an unsigned 16 bit value from/to the message iterator

       my $val = $iter->get_int32()
       $iter->append_int32($val);
           Read or write a signed 32 bit value from/to the message iterator

       my $val = $iter->get_uint32()
       $iter->append_uint32($val);
           Read or write an unsigned 32 bit value from/to the message iterator

       my $val = $iter->get_int64()
       $iter->append_int64($val);
           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

       my $val = $iter->get_uint64()
       $iter->append_uint64($val);
           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

       my $val = $iter->get_double()
       $iter->append_double($val);
           Read or write a double precision floating point value from/to the message iterator

       my $val = $iter->get_unix_fd()
       $iter->append_unix_fd($val);
           Read or write a unix_fd value from/to the message iterator

       my $value = $iter->get()
       my $value = $iter->get($type);
           Get the current value pointed to by this iterator. If the optional $type parameter is
           supplied, the wire type will be compared with the desired type & a warning output if
           their differ. The $type value must be one of the "Net::DBus::Binding::Message::TYPE*"
           constants.

       my $hashref = $iter->get_dict()
           If the iterator currently points to a dictionary value, unmarshalls and returns the
           value as a hash reference.

       my $hashref = $iter->get_array()
           If the iterator currently points to an array value, unmarshalls and returns the value
           as a array reference.

       my $hashref = $iter->get_variant()
           If the iterator currently points to a variant value, unmarshalls and returns the value
           contained in the variant.

       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.

       $iter->append($value)
       $iter->append($value, $type)
           Appends a value to the message associated with this iterator. The value is marshalled
           into wire format, according to the following rules.

           If the $value is an instance of Net::DBus::Binding::Value, the embedded data type is
           used.

           If the $type parameter is supplied, that is taken to represent the data type. The type
           must be one of the "Net::DBus::Binding::Message::TYPE_*" constants.

           Otherwise, the data type is chosen to be a string, dict or array according to the perl
           data types SCALAR, HASH or ARRAY.

       my $type = $iter->guess_type($value)
           Make a best guess at the on the wire data type to use for marshalling $value. 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.

       my $sig = $iter->format_signature($type)
           Given a data type representation, construct a corresponding signature string

       $iter->append_array($value, $type)
           Append an array of values to the message. The $value parameter must be an array
           reference, whose elements all have the same data type specified by the $type
           parameter.

       $iter->append_struct($value, $type)
           Append a struct to the message. The $value parameter must be an array reference, whose
           elements correspond to members of the structure. The $type parameter encodes the type
           of each member of the struct.

       $iter->append_dict($value, $type)
           Append a dictionary to the message. The $value parameter must be an hash reference.The
           $type parameter encodes the type of the key and value of the hash.

       $iter->append_variant($value)
           Append a value to the message, encoded as a variant type. The $value can be of any
           type, however, the variant will be encoded as either a string, dictionary or array
           according to the rules of the "guess_type" method.

       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 "Net::DBus::Binding::Message::TYPE_*"

       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
           "Net::DBus::Binding::Message::TYPE_*"

AUTHOR

       Daniel P. Berrange

COPYRIGHT

       Copyright (C) 2004-2011 Daniel P. Berrange

SEE ALSO

       Net::DBus::Binding::Message