1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-signature.c Routines for reading recursive type signatures
4 * Copyright (C) 2005 Red Hat, Inc.
6 * Licensed under the Academic Free License version 2.1
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "dbus-signature.h"
25 #include "dbus-marshal-recursive.h"
26 #include "dbus-marshal-basic.h"
27 #include "dbus-internals.h"
28 #include "dbus-test.h"
33 unsigned int finished : 1;
34 unsigned int in_array : 1;
35 } DBusSignatureRealIter;
38 * @addtogroup DBusSignature
43 * Initializes a #DBusSignatureIter for reading a type signature. This
44 * function is not safe to use on invalid signatures; be sure to
45 * validate potentially invalid signatures with dbus_signature_validate
46 * before using this function.
48 * @param iter pointer to an iterator to initialize
49 * @param signature the type signature
52 dbus_signature_iter_init (DBusSignatureIter *iter,
53 const char *signature)
55 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
57 real_iter->pos = signature;
58 real_iter->finished = FALSE;
59 real_iter->in_array = FALSE;
63 * Returns the current type pointed to by the iterator.
64 * If the iterator is pointing at a type code such as 's', then
65 * it will be returned directly.
67 * However, when the parser encounters a container type start
68 * character such as '(' for a structure, the corresponding type for
69 * the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('.
70 * In this case, you should initialize a sub-iterator with
71 * dbus_signature_iter_recurse to parse the container type.
73 * @param iter pointer to an iterator
74 * @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY)
77 dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
79 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
81 return _dbus_first_type_in_signature_c_str (real_iter->pos, 0);
85 * Returns the full type signature represented by the current
86 * iterator as a C string.
88 * @param iter pointer to an iterator
89 * @returns current signature; or NULL on OOM. Should be freed with #dbus_free
92 dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
94 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
99 if (!_dbus_string_init (&str))
103 _dbus_type_signature_next (real_iter->pos, &pos);
105 if (!_dbus_string_append_len (&str, real_iter->pos, pos))
107 if (!_dbus_string_steal_data (&str, &ret))
109 _dbus_string_free (&str);
115 * Convenience function for returning the element type of an array;
116 * This function allows you to avoid initializing a sub-iterator and
117 * getting its current type.
119 * It is an error to invoke this function if the current type of the
120 * iterator is not DBUS_TYPE_ARRAY.
122 * @param iter pointer to an iterator
123 * @returns current array element type
126 dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
128 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
130 _dbus_return_val_if_fail (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
132 return _dbus_first_type_in_signature_c_str (real_iter->pos, 1);
136 * Skip to the next value on this "level". e.g. the next field in a
137 * struct, the next value in an array. Returns FALSE at the end of the
140 * @param iter the iterator
141 * @returns FALSE if nothing more to read at or below this level
144 dbus_signature_iter_next (DBusSignatureIter *iter)
146 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
148 if (real_iter->finished)
154 if (real_iter->in_array)
156 real_iter->finished = TRUE;
161 _dbus_type_signature_next (real_iter->pos, &pos);
162 real_iter->pos += pos;
164 if (*real_iter->pos == DBUS_STRUCT_END_CHAR
165 || *real_iter->pos == DBUS_DICT_ENTRY_END_CHAR)
167 real_iter->finished = TRUE;
171 return *real_iter->pos != DBUS_TYPE_INVALID;
176 * Initialize a new iterator pointing to the first type current
177 * container. It's an error to call this if the current type is a
178 * non-container (i.e. if dbus_type_is_container returns FALSE).
180 * @param iter the current interator
181 * @param subiter an iterator to initialize pointing to the first child
184 dbus_signature_iter_recurse (const DBusSignatureIter *iter,
185 DBusSignatureIter *subiter)
187 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
188 DBusSignatureRealIter *real_sub_iter = (DBusSignatureRealIter *) subiter;
190 _dbus_return_if_fail (dbus_type_is_container (dbus_signature_iter_get_current_type (iter)));
192 *real_sub_iter = *real_iter;
193 real_sub_iter->pos++;
195 if (dbus_signature_iter_get_current_type (subiter) == DBUS_TYPE_ARRAY)
196 real_sub_iter->in_array = TRUE;
200 * Check a type signature for validity.
202 * @param signature a potentially invalid type signature
203 * @error error return
204 * @returns TRUE iif signature is valid
207 dbus_signature_validate (const char *signature,
213 _dbus_string_init_const (&str, signature);
214 if (_dbus_validate_signature (&str, 0, _dbus_string_get_length (&str)))
216 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Corrupt type signature");
221 * Check that a type signature is both valid and contains exactly
224 * @param signature a potentially invalid type signature
225 * @error error return
226 * @returns TRUE iif signature is valid and has exactly one complete type
229 dbus_signature_validate_single (const char *signature,
232 DBusSignatureIter iter;
234 if (!dbus_signature_validate (signature, error))
237 dbus_signature_iter_init (&iter, signature);
238 if (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID)
240 if (!dbus_signature_iter_next (&iter))
243 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Exactly one complete type required in signature");
247 /** macro that checks whether a typecode is a container type */
248 #define TYPE_IS_CONTAINER(typecode) \
249 ((typecode) == DBUS_TYPE_STRUCT || \
250 (typecode) == DBUS_TYPE_DICT_ENTRY || \
251 (typecode) == DBUS_TYPE_VARIANT || \
252 (typecode) == DBUS_TYPE_ARRAY)
255 * A "container type" can contain basic types, or nested
256 * container types. #DBUS_TYPE_INVALID is not a container type.
257 * This function will crash if passed a typecode that isn't
260 * @returns #TRUE if type is a container
263 dbus_type_is_container (int typecode)
265 /* only reasonable (non-line-noise) typecodes are allowed */
266 _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
268 return TYPE_IS_CONTAINER (typecode);
272 * A "basic type" is a somewhat arbitrary concept, but the intent
273 * is to include those types that are fully-specified by a single
274 * typecode, with no additional type information or nested
275 * values. So all numbers and strings are basic types and
276 * structs, arrays, and variants are not basic types.
277 * #DBUS_TYPE_INVALID is not a basic type.
279 * This function will crash if passed a typecode that isn't
282 * @returns #TRUE if type is basic
285 dbus_type_is_basic (int typecode)
287 /* only reasonable (non-line-noise) typecodes are allowed */
288 _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
291 /* everything that isn't invalid or a container */
292 return !(typecode == DBUS_TYPE_INVALID || TYPE_IS_CONTAINER (typecode));
296 * Tells you whether values of this type can change length if you set
297 * them to some other value. For this purpose, you assume that the
298 * first byte of the old and new value would be in the same location,
299 * so alignment padding is not a factor.
301 * This function is useful to determine whether #dbus_message_iter_get_fixed_array
304 * @returns #FALSE if the type can occupy different lengths
307 dbus_type_is_fixed (int typecode)
312 case DBUS_TYPE_BOOLEAN:
313 case DBUS_TYPE_INT16:
314 case DBUS_TYPE_UINT16:
315 case DBUS_TYPE_INT32:
316 case DBUS_TYPE_UINT32:
317 case DBUS_TYPE_INT64:
318 case DBUS_TYPE_UINT64:
319 case DBUS_TYPE_DOUBLE:
326 #ifdef DBUS_BUILD_TESTS
329 * @ingroup DBusSignatureInternals
330 * Unit test for DBusSignature.
332 * @returns #TRUE on success.
335 _dbus_signature_test (void)
337 DBusSignatureIter iter;
338 DBusSignatureIter subiter;
339 DBusSignatureIter subsubiter;
340 DBusSignatureIter subsubsubiter;
343 _dbus_assert (sizeof (DBusSignatureIter) >= sizeof (DBusSignatureRealIter));
346 _dbus_assert (dbus_signature_validate (sig, NULL));
347 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
348 dbus_signature_iter_init (&iter, sig);
349 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID);
351 sig = DBUS_TYPE_STRING_AS_STRING;
352 _dbus_assert (dbus_signature_validate (sig, NULL));
353 _dbus_assert (dbus_signature_validate_single (sig, NULL));
354 dbus_signature_iter_init (&iter, sig);
355 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
357 sig = DBUS_TYPE_STRING_AS_STRING DBUS_TYPE_BYTE_AS_STRING;
358 _dbus_assert (dbus_signature_validate (sig, NULL));
359 dbus_signature_iter_init (&iter, sig);
360 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
361 _dbus_assert (dbus_signature_iter_next (&iter));
362 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_BYTE);
364 sig = DBUS_TYPE_UINT16_AS_STRING
365 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
366 DBUS_TYPE_STRING_AS_STRING
367 DBUS_TYPE_UINT32_AS_STRING
368 DBUS_TYPE_VARIANT_AS_STRING
369 DBUS_TYPE_DOUBLE_AS_STRING
370 DBUS_STRUCT_END_CHAR_AS_STRING;
371 _dbus_assert (dbus_signature_validate (sig, NULL));
372 dbus_signature_iter_init (&iter, sig);
373 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
374 _dbus_assert (dbus_signature_iter_next (&iter));
375 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
376 dbus_signature_iter_recurse (&iter, &subiter);
377 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRING);
378 _dbus_assert (dbus_signature_iter_next (&subiter));
379 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
380 _dbus_assert (dbus_signature_iter_next (&subiter));
381 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_VARIANT);
382 _dbus_assert (dbus_signature_iter_next (&subiter));
383 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_DOUBLE);
385 sig = DBUS_TYPE_UINT16_AS_STRING
386 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
387 DBUS_TYPE_UINT32_AS_STRING
388 DBUS_TYPE_BYTE_AS_STRING
389 DBUS_TYPE_ARRAY_AS_STRING
390 DBUS_TYPE_ARRAY_AS_STRING
391 DBUS_TYPE_DOUBLE_AS_STRING
392 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
393 DBUS_TYPE_BYTE_AS_STRING
394 DBUS_STRUCT_END_CHAR_AS_STRING
395 DBUS_STRUCT_END_CHAR_AS_STRING;
396 _dbus_assert (dbus_signature_validate (sig, NULL));
397 dbus_signature_iter_init (&iter, sig);
398 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
399 _dbus_assert (dbus_signature_iter_next (&iter));
400 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
401 dbus_signature_iter_recurse (&iter, &subiter);
402 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
403 _dbus_assert (dbus_signature_iter_next (&subiter));
404 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_BYTE);
405 _dbus_assert (dbus_signature_iter_next (&subiter));
406 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_ARRAY);
407 _dbus_assert (dbus_signature_iter_get_element_type (&subiter) == DBUS_TYPE_ARRAY);
409 dbus_signature_iter_recurse (&subiter, &subsubiter);
410 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_ARRAY);
411 _dbus_assert (dbus_signature_iter_get_element_type (&subsubiter) == DBUS_TYPE_DOUBLE);
413 dbus_signature_iter_recurse (&subsubiter, &subsubsubiter);
414 _dbus_assert (dbus_signature_iter_get_current_type (&subsubsubiter) == DBUS_TYPE_DOUBLE);
415 _dbus_assert (dbus_signature_iter_next (&subiter));
416 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRUCT);
417 dbus_signature_iter_recurse (&subiter, &subsubiter);
418 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_BYTE);
420 sig = DBUS_TYPE_ARRAY_AS_STRING
421 DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
422 DBUS_TYPE_INT16_AS_STRING
423 DBUS_TYPE_STRING_AS_STRING
424 DBUS_DICT_ENTRY_END_CHAR_AS_STRING
425 DBUS_TYPE_VARIANT_AS_STRING;
426 _dbus_assert (dbus_signature_validate (sig, NULL));
427 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
428 dbus_signature_iter_init (&iter, sig);
429 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_ARRAY);
430 _dbus_assert (dbus_signature_iter_get_element_type (&iter) == DBUS_TYPE_DICT_ENTRY);
432 dbus_signature_iter_recurse (&iter, &subiter);
433 dbus_signature_iter_recurse (&subiter, &subsubiter);
434 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_INT16);
435 _dbus_assert (dbus_signature_iter_next (&subsubiter));
436 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_STRING);
437 _dbus_assert (!dbus_signature_iter_next (&subsubiter));
439 _dbus_assert (dbus_signature_iter_next (&iter));
440 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_VARIANT);
441 _dbus_assert (!dbus_signature_iter_next (&iter));
443 sig = DBUS_TYPE_DICT_ENTRY_AS_STRING;
444 _dbus_assert (!dbus_signature_validate (sig, NULL));
446 sig = DBUS_TYPE_ARRAY_AS_STRING;
447 _dbus_assert (!dbus_signature_validate (sig, NULL));
449 sig = DBUS_TYPE_UINT32_AS_STRING
450 DBUS_TYPE_ARRAY_AS_STRING;
451 _dbus_assert (!dbus_signature_validate (sig, NULL));
453 sig = DBUS_TYPE_ARRAY_AS_STRING
454 DBUS_TYPE_DICT_ENTRY_AS_STRING;
455 _dbus_assert (!dbus_signature_validate (sig, NULL));
457 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING;
458 _dbus_assert (!dbus_signature_validate (sig, NULL));
460 sig = DBUS_DICT_ENTRY_END_CHAR_AS_STRING;
461 _dbus_assert (!dbus_signature_validate (sig, NULL));
463 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
464 DBUS_TYPE_INT32_AS_STRING;
465 _dbus_assert (!dbus_signature_validate (sig, NULL));
467 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
468 DBUS_TYPE_INT32_AS_STRING
469 DBUS_TYPE_STRING_AS_STRING;
470 _dbus_assert (!dbus_signature_validate (sig, NULL));
472 sig = DBUS_STRUCT_END_CHAR_AS_STRING
473 DBUS_STRUCT_BEGIN_CHAR_AS_STRING;
474 _dbus_assert (!dbus_signature_validate (sig, NULL));
476 sig = DBUS_STRUCT_BEGIN_CHAR_AS_STRING
477 DBUS_TYPE_BOOLEAN_AS_STRING;
478 _dbus_assert (!dbus_signature_validate (sig, NULL));
482 _dbus_assert_not_reached ("out of memory");
489 /** @} */ /* end of DBusSignature group */