1Net::DBus::Binding::IteUrsaetrorC(o3n)tributed Perl DocuNmeetn:t:aDtBiuosn::Binding::Iterator(3)
2
3
4

NAME

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

SYNOPSIS

9       Creating a new message
10
11         my $msg = new Net::DBus::Binding::Message::Signal;
12         my $iterator = $msg->iterator;
13
14         $iterator->append_boolean(1);
15         $iterator->append_byte(123);
16
17       Reading from a mesage
18
19         my $msg = ...get it from somewhere...
20         my $iter = $msg->iterator();
21
22         my $i = 0;
23         while ($iter->has_next()) {
24           $iter->next();
25           $i++;
26           if ($i == 1) {
27              my $val = $iter->get_boolean();
28           } elsif ($i == 2) {
29              my $val = $iter->get_byte();
30           }
31         }
32

DESCRIPTION

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

METHODS

40       $res = $iter->has_next()
41           Determines if there are any more fields in the message itertor to
42           be read. Returns a positive value if there are more fields, zero
43           otherwise.
44
45       $success = $iter->next()
46           Skips the iterator onto the next field in the message.  Returns a
47           positive value if the current field pointer was successfully
48           advanced, zero otherwise.
49
50       my $val = $iter->get_boolean()
51       $iter->append_boolean($val);
52           Read or write a boolean value from/to the message iterator
53
54       my $val = $iter->get_byte()
55       $iter->append_byte($val);
56           Read or write a single byte value from/to the message iterator.
57
58       my $val = $iter->get_string()
59       $iter->append_string($val);
60           Read or write a UTF-8 string value from/to the message iterator
61
62       my $val = $iter->get_object_path()
63       $iter->append_object_path($val);
64           Read or write a UTF-8 string value, whose contents is a valid
65           object path, from/to the message iterator
66
67       my $val = $iter->get_signature()
68       $iter->append_signature($val);
69           Read or write a UTF-8 string, whose contents is a valid type signa‐
70           ture, value from/to the message iterator
71
72       my $val = $iter->get_int16()
73       $iter->append_int16($val);
74           Read or write a signed 16 bit value from/to the message iterator
75
76       my $val = $iter->get_uint16()
77       $iter->append_uint16($val);
78           Read or write an unsigned 16 bit value from/to the message iterator
79
80       my $val = $iter->get_int32()
81       $iter->append_int32($val);
82           Read or write a signed 32 bit value from/to the message iterator
83
84       my $val = $iter->get_uint32()
85       $iter->append_uint32($val);
86           Read or write an unsigned 32 bit value from/to the message iterator
87
88       my $val = $iter->get_int64()
89       $iter->append_int64($val);
90           Read or write a signed 64 bit value from/to the message iterator.
91           An error will be raised if this build of Perl does not support 64
92           bit integers
93
94       my $val = $iter->get_uint64()
95       $iter->append_uint64($val);
96           Read or write an unsigned 64 bit value from/to the message itera‐
97           tor. An error will be raised if this build of Perl does not support
98           64 bit integers
99
100       my $val = $iter->get_double()
101       $iter->append_double($val);
102           Read or write a double precision floating point value from/to the
103           message iterator
104
105       my $value = $iter->get()
106       my $value = $iter->get($type);
107           Get the current value pointed to by this iterator. If the optional
108           $type parameter is supplied, the wire type will be compared with
109           the desired type & a warning output if their differ. The $type
110           value must be one of the "Net::DBus::Binding::Message::TYPE*" con‐
111           stants.
112
113       my $hashref = $iter->get_dict()
114           If the iterator currently points to a dictionary value, unmarshalls
115           and returns the value as a hash reference.
116
117       my $hashref = $iter->get_array()
118           If the iterator currently points to an array value, unmarshalls and
119           returns the value as a array reference.
120
121       my $hashref = $iter->get_variant()
122           If the iterator currently points to a variant value, unmarshalls
123           and returns the value contained in the variant.
124
125       my $hashref = $iter->get_struct()
126           If the iterator currently points to an struct value, unmarshalls
127           and returns the value as a array reference. The values in the array
128           correspond to members of the struct.
129
130       $iter->append($value)
131       $iter->append($value, $type)
132           Appends a value to the message associated with this iterator. The
133           value is marshalled into wire format, according to the following
134           rules.
135
136           If the $value is an instance of Net::DBus::Binding::Value, the
137           embedded data type is used.
138
139           If the $type parameter is supplied, that is taken to represent the
140           data type. The type must be one of the "Net::DBus::Binding::Mes‐
141           sage::TYPE_*" constants.
142
143           Otherwise, the data type is chosen to be a string, dict or array
144           according to the perl data types SCALAR, HASH or ARRAY.
145
146       my $type = $iter->guess_type($value)
147           Make a best guess at the on the wire data type to use for mar‐
148           shalling $value. If the value is a hash reference, the dictionary
149           type is returned; if the value is an array reference the array type
150           is returned; otherwise the string type is returned.
151
152       my $sig = $iter->format_signature($type)
153           Given a data type representation, construct a corresponding signa‐
154           ture string
155
156       $iter->append_array($value, $type)
157           Append an array of values to the message. The $value parameter must
158           be an array reference, whose elements all have the same data type
159           specified by the $type parameter.
160
161       $iter->append_struct($value, $type)
162           Append a struct to the message. The $value parameter must be an
163           array reference, whose elements correspond to members of the struc‐
164           ture. The $type parameter encodes the type of each member of the
165           struct.
166
167       $iter->append_dict($value, $type)
168           Append a dictionary to the message. The $value parameter must be an
169           hash reference.The $type parameter encodes the type of the key and
170           value of the hash.
171
172       $iter->append_variant($value)
173           Append a value to the message, encoded as a variant type. The
174           $value can be of any type, however, the variant will be encoded as
175           either a string, dictionary or array according to the rules of the
176           "guess_type" method.
177
178       my $type = $iter->get_arg_type
179           Retrieves the type code of the value pointing to by this iterator.
180           The returned code will correspond to one of the constants
181           "Net::DBus::Binding::Message::TYPE_*"
182
183       my $type = $iter->get_element_type
184           If the iterator points to an array, retrieves the type code of
185           array elements. The returned code will correspond to one of the
186           constants "Net::DBus::Binding::Message::TYPE_*"
187

SEE ALSO

189       Net::DBus::Binding::Message
190

AUTHOR

192       Daniel Berrange <dan@berrange.com>
193
195       Copyright 2004 by Daniel Berrange
196
197
198
199perl v5.8.8                       2008-02-20   Net::DBus::Binding::Iterator(3)
Impressum