Net::DBus_Binding_Tutorial - Net::DBus Modules and Methods - Net::DBus::Binding::Iterator - Net::DBus::Binding::Iterator Methods

In the following sections there are many references to type codes. For a detailed list of these codes see either;

• DBus Type Codes
• DBus Specifications

It is important to understand what the 'message iterator' is, as this term comes up frequently in the following sections. The 'message iterator' is the queue that handles marshalling data onto and off of the message bus. In this regard, this module acts like a translator; it converts data and data structures between perl formats and syntax into DBus formats and syntax when appending data to the message bus, whereas it does the reverse when getting data off of the message bus. MADI: Confirm this definition/description.

Contents 1 append 2 get 3 has_next 4 next 5 append_boolean 6 get_boolean 7 appent_byte 8 get_byte 9 append_string 10 get_string 11 append_object_path 12 get_object_path 13 append_signature 14 get_signature 15 append_int16 16 get_int16 17 append_uint16 18 get_uint16 19 append_int32 20 get_int32 21 append_uint32 22 get_uint32 23 append_int64 24 get_int64 25 append_uint64 26 get_uint64 27 append_double 28 get_double 29 get_dict 30 get_array 31 get_variant 32 get_struct 33 guess_type 34 format_signature 35 append_array 36 append_struct 37 append_dict 38 append_variant 39 get_arg_type 40 get_element_type

[edit] append

Usage:

$iterator->append($value);

Or:

my $type=""; # This must be one of the 'Net::DBus::Binding::Message::TYPE*' constants.
my $value=$iterator->append($value, $type);

This puts the data in the '$value' onto the message iterator. When used without '$type', the '$value' itself is checked and if it is an instance of Net::DBus::Binding::Value, the embedded type is used. If '$type' is specified, it must be a valid 'Net::DBus::Binding::Message::TYPE*' constants.

[edit] get

Usage:

my $value=$iterator->get();

Or:

my $type=""; # This must be one of the 'Net::DBus::Binding::Message::TYPE*' constants.
my $value=$iterator->get($type);

This gets the current value pointed to from the message iterator. If '$type' is specified, then the type of the message is checked on the wire and compared to that specified in '$type'. If they do not match a warning is raised.

[edit] has_next

Usage:

my $result=$iterator->has_next();

This checks to see if there is another message in the iterator, returning a positive integer if so, '0' if not. MADI: Is the positive integer equal to the number of remaining messages in the iterator? Or is it a key that indicates what type the next message is?

[edit] next

Usage:

my $success=$iterator->next();

This skips the current message in the iterator. If the skip succeeded, it returns '1', returning '0' if it failed.

[edit] append_boolean

Usage:

$iterator->append_boolean($value);

This writes a boolean value to the message interator. MADI: What are valid values for '$value'?

[edit] get_boolean

Usage:

my $value=$iterator->get_boolean();

This reads a boolean value from the message interator. MADI: What are valid values for '$value'?

[edit] appent_byte

Usage:

$iterator->append_byte($value);

This writes a single byte value to the message interator.

[edit] get_byte

Usage:

my $value=$iterator->get_byte();

This reads a single byte value from the message interator.

[edit] append_string

Usage:

$iterator->append_string($value);

This writes a UTF-8 encoded string to the message interator.

[edit] get_string

Usage:

my $value=$iterator->get_string();

This reads a UTF-8 encoded string value from the message interator.

[edit] append_object_path

Usage:

$iterator->append_object_path($value);

This writes a UTF-8 encoded object path to the message interator.

[edit] get_object_path

Usage:

my $value=$iterator->get_object_path();

This reads a UTF-8 encoded object path from the message interator.

[edit] append_signature

Usage:

$iterator->append_signature($value);

This writes a UTF-8 encoded 'type signature' to the message interator.

[edit] get_signature

Usage:

my $value=$iterator->get_signature();

This reads a UTF-8 encoded 'type signature' from the message interator.

[edit] append_int16

Usage:

$iterator->append_int16($value);

This writes a signed 16-bit integer to the message interator.

[edit] get_int16

Usage:

my $value=$iterator->get_int16();

This reads a signed 16-bit integer from the message interator.

[edit] append_uint16

Usage:

$iterator->append_uint16($value);

This writes an unsigned 16-bit integer to the message interator.

[edit] get_uint16

Usage:

my $value=$iterator->get_uint16();

This reads an unsigned 16-bit integer from the message interator.

[edit] append_int32

Usage:

$iterator->append_int32($value);

This writes a signed 32-bit integer to the message interator.

[edit] get_int32

Usage:

my $value=$iterator->get_int32();

This reads a signed 32-bit integer from the message interator.

[edit] append_uint32

Usage:

$iterator->append_uint32($value);

This writes an unsigned 32-bit integer to the message interator.

[edit] get_uint32

Usage:

my $value=$iterator->get_uint32();

This reads an unsigned 32-bit integer from the message interator.

[edit] append_int64

Usage:

$iterator->append_int64($value);

This writes a signed 64-bit integer to the message interator.

NOTE: An error will be raised if the version of Perl in use does not support 64-bit integers.

[edit] get_int64

Usage:

my $value=$iterator->get_int64();

This reads a signed 64-bit integer from the message interator.

NOTE: An error will be raised if the version of Perl in use does not support 64-bit integers.

[edit] append_uint64

Usage:

$iterator->append_uint64($value);

This writes an unsigned 64-bit integer to the message interator.

NOTE: An error will be raised if the version of Perl in use does not support 64-bit integers.

[edit] get_uint64

Usage:

my $value=$iterator->get_uint64();

This reads an unsigned 64-bit integer from the message interator.

NOTE: An error will be raised if the version of Perl in use does not support 64-bit integers.

[edit] append_double

Usage:

$iterator->append_double($value);

This writes a double-precision floating point value to the message interator.

[edit] get_double

Usage:

my $value=$iterator->get_double();

This reads a double-precision floating point value from the message interator.

[edit] get_dict

Usage:

my $hashref=$iterator->get_dict();
foreach my $key (keys %{$hashref})
{
        print "The hash key: [$key] points to the value: [$$hashref{$key}]\n";
}

This takes a dictionary from the message interator and feeds it into a perl hash. Once the hash has been populated, a reference to the hash is returned.

[edit] get_array

Usage:

my $arrayref=$iterator->get_array();
foreach my $value (@{$arrayref})
{
        print "The array position: [$_] contains to the value: [$$arrayref[$_]]\n";
}

This takes an array from the message iterator and feeds it into a perl array. Once the array has been populated. a reference to the array is returned.

[edit] get_variant

Usage:

my $hashref=$iterator->get_variant();
foreach my $key (keys %{$hashref})
{
        print "The hash key: [$key] points to the value: [$$hashref{$key}]\n";
}

If the current currently points to a 'variant' container type, read it from the message iterator and return a hash reference to it.

[edit] get_struct

Usage:

my $hashref=$iterator->get_struct();
foreach my $key (keys %{$hashref})
{
        print "The hash key: [$key] points to the value: [$$hashref{$key}]\n";
}

If the current currently points to a 'struct' container type, read it from the message iterator and return a hash reference to it.

[edit] guess_type

Usage:

my $type=$iterator->guess_type($value);

This looks at the data in '$value' and tries to determine an appropriate wire-type to use for it. It checks to see if it's a 'HASH', in which case 'DICT' is returned. If it's an 'ARRAY' then 'ARRAY</code>' is returned. Failing one of these two types, 'STRING' is returned.

[edit] format_signature

Usage:

my $signature=$iterator->format_signature($type);

This looks at the given '$type' and returns an appropriate signature string.

[edit] append_array

Usage:

$iterator->append_array($arrayref, $type);

This takes a reference to an array whose members are all of the same '$type' and appends it to the message.

[edit] append_struct

Usage:

$iterator->append_struct($value, $type);

This takes the 'struct' contained in '$value' whose members are of '$type' and appends it to the message.

[edit] append_dict

Usage:

$iterator->append_dict($value, $type);

This takes a hash reference contained in '$value' whose key and value are of '$type' and appends it to the message.

[edit] append_variant

Usage:

$iterator->append_variant($value);

This takes a 'variant' type message contained in '$value', uses the 'guess_type' method to determine if 'dict', 'array' or 'string' encoding is most appropriate and then appends it to the message.

[edit] get_arg_type

Usage:

my $type=$iterator->get_arg_type;

This looks at the message currently pointed to by the iterator and tries to determine what type of message it is. The detected type is returned and is one of the 'Net::DBus::Binding::Message::TYPE_*' types.

[edit] get_element_type

Usage:

my $type=$iterator->get_element_type;

When the message currently pointed to is an array, this will look at the elements in the array and tries to determine what type of element they are. The detected type is returned and is one of the 'Net::DBus::Binding::Message::TYPE_*' types.