Digimer: Created page with '{{dbtut_header}} In the following sections there are many references to type codes. For a detailed list of these codes see either; * DBus Type Codes * [http://dbus.freedeskt…'

2009-10-12T02:45:47Z

Created page with '{{dbtut_header}} In the following sections there are many references to type codes. For a detailed list of these codes see either; * DBus Type Codes * [http://dbus.freedeskt…'

Páàjì titun

{{dbtut_header}}

In the following sections there are many references to type codes. For a detailed list of these codes see either;
* [[DBus Type Codes]]
* [http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures 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.

= append =

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

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 Tutorial#Net::DBus::Binding::Value|Net::DBus::Binding::Value]], the embedded type is used. If '$type' is specified, it must be a valid 'Net::DBus::Binding::Message::TYPE*' constants.

= get =

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

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.

= has_next =

Usage:
<source lang="perl">my $result=$iterator->has_next();</source>

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?

= next =

Usage:
<source lang="perl">my $success=$iterator->next();</source>

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

= append_boolean =

Usage:
<source lang="perl">$iterator->append_boolean($value);</source>

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

= get_boolean =

Usage:
<source lang="perl">my $value=$iterator->get_boolean();</source>

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

= appent_byte =

Usage:
<source lang="perl">$iterator->append_byte($value);</source>

This writes a single byte value to the message interator.

= get_byte =

Usage:
<source lang="perl">my $value=$iterator->get_byte();</source>

This reads a single byte value from the message interator.

= append_string =

Usage:
<source lang="perl">$iterator->append_string($value);</source>

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

= get_string =

Usage:
<source lang="perl">my $value=$iterator->get_string();</source>

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

= append_object_path =

Usage:
<source lang="perl">$iterator->append_object_path($value);</source>

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

= get_object_path =

Usage:
<source lang="perl">my $value=$iterator->get_object_path();</source>

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

= append_signature =

Usage:
<source lang="perl">$iterator->append_signature($value);</source>

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

= get_signature =

Usage:
<source lang="perl">my $value=$iterator->get_signature();</source>

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

= append_int16 =

Usage:
<source lang="perl">$iterator->append_int16($value);</source>

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

= get_int16 =

Usage:
<source lang="perl">my $value=$iterator->get_int16();</source>

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

= append_uint16 =

Usage:
<source lang="perl">$iterator->append_uint16($value);</source>

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

= get_uint16 =

Usage:
<source lang="perl">my $value=$iterator->get_uint16();</source>

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

= append_int32 =

Usage:
<source lang="perl">$iterator->append_int32($value);</source>

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

= get_int32 =

Usage:
<source lang="perl">my $value=$iterator->get_int32();</source>

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

= append_uint32 =

Usage:
<source lang="perl">$iterator->append_uint32($value);</source>

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

= get_uint32 =

Usage:
<source lang="perl">my $value=$iterator->get_uint32();</source>

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

= append_int64 =

Usage:
<source lang="perl">$iterator->append_int64($value);</source>

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.

= get_int64 =

Usage:
<source lang="perl">my $value=$iterator->get_int64();</source>

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.

= append_uint64 =

Usage:
<source lang="perl">$iterator->append_uint64($value);</source>

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.

= get_uint64 =

Usage:
<source lang="perl">my $value=$iterator->get_uint64();</source>

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.

= append_double =

Usage:
<source lang="perl">$iterator->append_double($value);</source>

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

= get_double =

Usage:
<source lang="perl">my $value=$iterator->get_double();</source>

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

= get_dict =

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

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.

= get_array =

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

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.

= get_variant =

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

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

= get_struct =

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

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

= guess_type =

Usage:
<source lang="perl">my $type=$iterator->guess_type($value);</source>

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.

= format_signature =

Usage:
<source lang="perl">my $signature=$iterator->format_signature($type);</source>

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

= append_array =

Usage:
<source lang="perl">$iterator->append_array($arrayref, $type);</source>

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

= append_struct =

Usage:
<source lang="perl">$iterator->append_struct($value, $type);</source>

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

= append_dict =

Usage:
<source lang="perl">$iterator->append_dict($value, $type);</source>

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

= append_variant =

Usage:
<source lang="perl">$iterator->append_variant($value);</source>

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

= get_arg_type =

Usage:
<source lang="perl">my $type=$iterator->get_arg_type;</source>

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.

= get_element_type =

Usage:
<source lang="perl">my $type=$iterator->get_element_type;</source>

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.

{{footer}}

Net::DBus::Binding::Iterator Methods - Revision history

Digimer: Created page with '{{dbtut_header}} In the following sections there are many references to type codes. For a detailed list of these codes see either; * DBus Type Codes * [http://dbus.freedeskt…'