# -*- perl -*-
#
# Copyright (C) 2004-2011 Daniel P. Berrange
#
# This program is free software; You can redistribute it and/or modify
# it under the same terms as Perl itself. Either:
#
# a) the GNU General Public License as published by the Free
# Software Foundation; either version 2, or (at your option) any
# later version,
#
# or
#
# b) the "Artistic License"
#
# The file "COPYING" distributed along with this file provides full
# details of the terms and conditions of the two licenses.
=pod
=head1 NAME
Net::DBus::Binding::Iterator - Reading and writing message parameters
=head1 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();
}
}
=head1 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!).
=head1 METHODS
=over 4
=cut
package Net::DBus::Binding::Iterator;
use 5.006;
use strict;
use warnings;
use Net::DBus;
=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.
=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.
=item my $val = $iter->get_boolean()
=item $iter->append_boolean($val);
Read or write a boolean value from/to the
message iterator
=item my $val = $iter->get_byte()
=item $iter->append_byte($val);
Read or write a single byte value from/to the
message iterator.
=item my $val = $iter->get_string()
=item $iter->append_string($val);
Read or write a UTF-8 string value from/to the
message iterator
=item my $val = $iter->get_object_path()
=item $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
=item my $val = $iter->get_signature()
=item $iter->append_signature($val);
Read or write a UTF-8 string, whose contents is a
valid type signature, value from/to the message iterator
=item my $val = $iter->get_int16()
=item $iter->append_int16($val);
Read or write a signed 16 bit value from/to the
message iterator
=item my $val = $iter->get_uint16()
=item $iter->append_uint16($val);
Read or write an unsigned 16 bit value from/to the
message iterator
=item my $val = $iter->get_int32()
=item $iter->append_int32($val);
Read or write a signed 32 bit value from/to the
message iterator
=item my $val = $iter->get_uint32()
=item $iter->append_uint32($val);
Read or write an unsigned 32 bit value from/to the
message iterator
=item my $val = $iter->get_int64()
=item $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
=item my $val = $iter->get_uint64()
=item $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
=item my $val = $iter->get_double()
=item $iter->append_double($val);
Read or write a double precision floating point value
from/to the message iterator
=item my $val = $iter->get_unix_fd()
=item $iter->append_unix_fd($val);
Read or write a unix_fd value from/to the
message iterator
=cut
sub get_int64 {
my $self = shift;
return $self->_get_int64;
}
sub get_uint64 {
my $self = shift;
return $self->_get_uint64;
}
sub append_int64 {
my $self = shift;
$self->_append_int64(shift);
}
sub append_uint64 {
my $self = shift;
$self->_append_uint64(shift);
}
=item my $value = $iter->get()
=item my $value = $iter->get($type);
Get the current value pointed to by this iterator. If the optional
C<$type> parameter is supplied, the wire type will be compared with
the desired type & a warning output if their differ. The C<$type>
value must be one of the C<Net::DBus::Binding::Message::TYPE*>
constants.
=cut
sub get {
my $self = shift;
my $type = shift;
if (defined $type) {
if (ref($type)) {
if (ref($type) eq "ARRAY") {
# XXX we should recursively validate types
$type = $type->[0];
if ($type eq &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
$type = &Net::DBus::Binding::Message::TYPE_ARRAY;
}
} else {
die "unsupport type reference $type";
}
}
my $actual = $self->get_arg_type;
if ($actual != $type) {
# "Be strict in what you send, be leniant in what you accept"
# - ie can't rely on python to send correct types, eg int32 vs uint32
# But, don't complain for variants because a number of apps (eg HAL)
# claim to return variants, but in fact don't correctly encode their
# data as variants. Technically a bug in the server, but it does
# 'just work' normally.
warn "requested type '" . chr($type) . "' ($type) did not match wire type '" . chr($actual) . "' ($actual)"
if $type != &Net::DBus::Binding::Message::TYPE_VARIANT;
$type = $actual;
}
} else {
$type = $self->get_arg_type;
}
if ($type == &Net::DBus::Binding::Message::TYPE_STRING) {
return $self->get_string;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_BOOLEAN) {
return $self->get_boolean;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_BYTE) {
return $self->get_byte;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT16) {
return $self->get_int16;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT16) {
return $self->get_uint16;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT32) {
return $self->get_int32;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT32) {
return $self->get_uint32;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT64) {
return $self->get_int64;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT64) {
return $self->get_uint64;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_DOUBLE) {
return $self->get_double;
} elsif ($type == &Net::DBus::Binding::Message::TYPE_ARRAY) {
my $array_type = $self->get_element_type();
if ($array_type == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
return $self->get_dict();
} else {
return $self->get_array($array_type);
}
} elsif ($type == &Net::DBus::Binding::Message::TYPE_STRUCT) {
return $self->get_struct();
} elsif ($type == &Net::DBus::Binding::Message::TYPE_VARIANT) {
return $self->get_variant();
} elsif ($type == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
die "dictionary can only occur as part of an array type";
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INVALID) {
die "cannot handle Net::DBus::Binding::Message::TYPE_INVALID";
} elsif ($type == &Net::DBus::Binding::Message::TYPE_OBJECT_PATH) {
return $self->get_object_path();
} elsif ($type == &Net::DBus::Binding::Message::TYPE_SIGNATURE) {
return $self->get_signature();
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UNIX_FD) {
return $self->get_unix_fd();
} else {
die "unknown argument type '" . chr($type) . "' ($type)";
}
}
=item my $hashref = $iter->get_dict()
If the iterator currently points to a dictionary value, unmarshalls
and returns the value as a hash reference.
=cut
sub get_dict {
my $self = shift;
my $iter = $self->_recurse();
my $type = $iter->get_arg_type();
my $dict = {};
while ($type == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
my $entry = $iter->get_struct();
if ($#{$entry} != 1) {
die "Dictionary entries must be structs of 2 elements. This entry has " . ($#{$entry}+1) ." elements";
}
$dict->{$entry->[0]} = $entry->[1];
$iter->next();
$type = $iter->get_arg_type();
}
return $dict;
}
=item my $hashref = $iter->get_array()
If the iterator currently points to an array value, unmarshalls
and returns the value as a array reference.
=cut
sub get_array {
my $self = shift;
my $array_type = shift;
my $iter = $self->_recurse();
my $type = $iter->get_arg_type();
my $array = [];
while ($type != &Net::DBus::Binding::Message::TYPE_INVALID) {
if ($type != $array_type) {
die "Element $type not of array type $array_type";
}
my $value = $iter->get($type);
push @{$array}, $value;
$iter->next();
$type = $iter->get_arg_type();
}
return $array;
}
=item my $hashref = $iter->get_variant()
If the iterator currently points to a variant value, unmarshalls
and returns the value contained in the variant.
=cut
sub get_variant {
my $self = shift;
my $iter = $self->_recurse();
return $iter->get();
}
=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.
=cut
sub get_struct {
my $self = shift;
my $iter = $self->_recurse();
my $type = $iter->get_arg_type();
my $struct = [];
while ($type != &Net::DBus::Binding::Message::TYPE_INVALID) {
my $value = $iter->get($type);
push @{$struct}, $value;
$iter->next();
$type = $iter->get_arg_type();
}
return $struct;
}
=item $iter->append($value)
=item $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 C<$value> is an instance of L<Net::DBus::Binding::Value>,
the embedded data type is used.
If the C<$type> parameter is supplied, that is taken to represent
the data type. The type must be one of the C<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.
=cut
sub append {
my $self = shift;
my $value = shift;
my $type = shift;
if (ref($value) eq "Net::DBus::Binding::Value" &&
((! defined ref($type)) ||
(ref($type) ne "ARRAY") ||
$type->[0] != &Net::DBus::Binding::Message::TYPE_VARIANT)) {
$type = $value->type;
$value = $value->value;
}
if (!defined $type) {
$type = $self->guess_type($value);
}
if (ref($type) eq "ARRAY") {
my $maintype = $type->[0];
my $subtype = $type->[1];
if ($maintype == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
$self->append_dict($value, $subtype);
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_STRUCT) {
$self->append_struct($value, $subtype);
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_ARRAY) {
$self->append_array($value, $subtype);
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_VARIANT) {
$self->append_variant($value, $subtype);
} else {
die "Unsupported compound type ", $maintype, " ('", chr($maintype), "')";
}
} else {
# XXX is this good idea or not
$value = '' unless defined $value;
if ($type == &Net::DBus::Binding::Message::TYPE_BOOLEAN) {
$self->append_boolean($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_BYTE) {
$self->append_byte($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_STRING) {
$self->append_string($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT16) {
$self->append_int16($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT16) {
$self->append_uint16($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT32) {
$self->append_int32($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT32) {
$self->append_uint32($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_INT64) {
$self->append_int64($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UINT64) {
$self->append_uint64($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_DOUBLE) {
$self->append_double($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_OBJECT_PATH) {
$self->append_object_path($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_SIGNATURE) {
$self->append_signature($value);
} elsif ($type == &Net::DBus::Binding::Message::TYPE_UNIX_FD) {
$self->append_unix_fd($value);
} else {
die "Unsupported scalar type ", $type, " ('", chr($type), "')";
}
}
}
=item my $type = $iter->guess_type($value)
Make a best guess at the on the wire data type to use for
marshalling C<$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.
=cut
sub guess_type {
my $self = shift;
my $value = shift;
if (ref($value)) {
if (UNIVERSAL::isa($value, "Net::DBus::Binding::Value")) {
my $type = $value->type;
if (ref($type) && ref($type) eq "ARRAY") {
my $maintype = $type->[0];
my $subtype = $type->[1];
if (!defined $subtype) {
if ($maintype == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
$subtype = [ $self->guess_type((keys(%{ $value->value }))[0]),
$self->guess_type((values(%{ $value->value }))[0]) ];
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_ARRAY) {
$subtype = [ $self->guess_type(($value->value())[0]->[0]) ];
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_STRUCT) {
$subtype = [ map { $self->guess_type($_) } @{($value->value())[0]} ];
} elsif ($maintype == &Net::DBus::Binding::Message::TYPE_VARIANT) {
$subtype = $self->guess_type($value->value);
} else {
die "Unguessable compound type '$maintype' ('", chr($maintype), "')\n";
}
}
return [$maintype, $subtype];
} else {
return $type;
}
} elsif (ref($value) eq "HASH") {
my $key = (keys %{$value})[0];
my $val = $value->{$key};
# XXX Basically impossible to decide between DICT & STRUCT
return [ &Net::DBus::Binding::Message::TYPE_DICT_ENTRY,
[ &Net::DBus::Binding::Message::TYPE_STRING, $self->guess_type($val)] ];
} elsif (ref($value) eq "ARRAY") {
return [ &Net::DBus::Binding::Message::TYPE_ARRAY,
[$self->guess_type($value->[0])] ];
} else {
die "cannot marshall reference of type " . ref($value);
}
} else {
# XXX Should we bother trying to guess integer & floating point types ?
# I say sod it, because strongly typed languages will support introspection
# and loosely typed languages won't care about the difference
return &Net::DBus::Binding::Message::TYPE_STRING;
}
}
=item my $sig = $iter->format_signature($type)
Given a data type representation, construct a corresponding
signature string
=cut
sub format_signature {
my $self = shift;
my $type = shift;
my ($sig, $t, $i);
$sig = "";
$i = 0;
if (ref($type) eq "ARRAY") {
while ($i <= $#{$type}) {
$t = $$type[$i];
if (ref($t) eq "ARRAY") {
$sig .= $self->format_signature($t);
} elsif ($t == &Net::DBus::Binding::Message::TYPE_DICT_ENTRY) {
$sig .= chr (&Net::DBus::Binding::Message::TYPE_ARRAY);
$sig .= "{" . $self->format_signature($$type[++$i]) . "}";
} elsif ($t == &Net::DBus::Binding::Message::TYPE_STRUCT) {
$sig .= "(" . $self->format_signature($$type[++$i]) . ")";
} else {
$sig .= chr($t);
if ($t == &Net::DBus::Binding::Message::TYPE_VARIANT)
{
last;
}
}
$i++;
}
} else {
$sig .= chr ($type);
}
return $sig;
}
=item $iter->append_array($value, $type)
Append an array of values to the message. The C<$value> parameter
must be an array reference, whose elements all have the same data
type specified by the C<$type> parameter.
=cut
sub append_array {
my $self = shift;
my $array = shift;
my $type = shift;
if (!defined($type)) {
$type = [$self->guess_type($array->[0])];
}
die "array must only have one type"
if $#{$type} > 0;
my $sig = $self->format_signature($type);
my $iter = $self->_open_container(&Net::DBus::Binding::Message::TYPE_ARRAY, $sig);
foreach my $value (@{$array}) {
$iter->append($value, $type->[0]);
}
$self->_close_container($iter);
}
=item $iter->append_struct($value, $type)
Append a struct to the message. The C<$value> parameter
must be an array reference, whose elements correspond to
members of the structure. The C<$type> parameter encodes
the type of each member of the struct.
=cut
sub append_struct {
my $self = shift;
my $struct = shift;
my $type = shift;
if (defined($type) &&
$#{$struct} != $#{$type}) {
die "number of values does not match type";
}
my $iter = $self->_open_container(&Net::DBus::Binding::Message::TYPE_STRUCT, "");
my @type = defined $type ? @{$type} : ();
foreach my $value (@{$struct}) {
$iter->append($value, shift @type);
}
$self->_close_container($iter);
}
=item $iter->append_dict($value, $type)
Append a dictionary to the message. The C<$value> parameter
must be an hash reference.The C<$type> parameter encodes
the type of the key and value of the hash.
=cut
sub append_dict {
my $self = shift;
my $hash = shift;
my $type = shift;
my $sig;
$sig = "{";
$sig .= $self->format_signature($type);
$sig .= "}";
my $iter = $self->_open_container(&Net::DBus::Binding::Message::TYPE_ARRAY, $sig);
foreach my $key (keys %{$hash}) {
my $value = $hash->{$key};
my $entry = $iter->_open_container(&Net::DBus::Binding::Message::TYPE_DICT_ENTRY, "");
$entry->append($key, $type->[0]);
$entry->append($value, $type->[1]);
$iter->_close_container($entry);
}
$self->_close_container($iter);
}
=item $iter->append_variant($value)
Append a value to the message, encoded as a variant type. The
C<$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 C<guess_type> method.
=cut
sub append_variant {
my $self = shift;
my $value = shift;
my $type = shift;
if (UNIVERSAL::isa($value, "Net::DBus::Binding::Value")) {
$type = [$self->guess_type($value)];
$value = $value->value;
} elsif (!defined $type || !defined $type->[0]) {
$type = [$self->guess_type($value)];
}
die "variant must only have one type"
if defined $type && $#{$type} > 0;
my $sig = $self->format_signature($type->[0]);
my $iter = $self->_open_container(&Net::DBus::Binding::Message::TYPE_VARIANT, $sig);
$iter->append($value, $type->[0]);
$self->_close_container($iter);
}
=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
C<Net::DBus::Binding::Message::TYPE_*>
=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 C<Net::DBus::Binding::Message::TYPE_*>
=cut
1;
=pod
=back
=head1 AUTHOR
Daniel P. Berrange
=head1 COPYRIGHT
Copyright (C) 2004-2011 Daniel P. Berrange
=head1 SEE ALSO
L<Net::DBus::Binding::Message>
=cut